search

SignalK / signalk-server

An implementation of a Signal K central server for boats.
http://signalk.org
Apache License 2.0
318 stars 155 forks source link
signalk

readme

Signal K Server

Signal K logo

npm version npm license PRs Welcome

Open Collective backers and sponsors

Contents

Introduction

Signal K Server is a server application that runs on a central hub in a boat. If you use or develop marine electronics, Signal K Server has something to offer for you.

Boaters and Boat Owners

For boaters, Signal K Server runs in the background and makes functionality and data available to other apps and devices. One of its most used features is to be a wireless AIS and navigation server for popular apps like Navionics, iSailor, iNavX, Aqua Map and WilhelmSK on your phones and tablets.

Signal K Server can also take care of the anchor watch, be a weather station or an automatic logbook for you. A different example, it can turn your boat into a MarineTraffic station which may give free access to the MarineTraffic professional plans. These are all just examples: there is far more to Signal K Server.

If you are a boat owner, you can easily run Signal K Server on a Victron Cerbo GX, RaspberryPi or similar hardware. To take full advantage, you will probably want to connect it to your boat network via NMEA 0183 or NMEA 2000 but it is not a requirement.

Marine Vendors

For Marine vendors who build marine hardware and software, for example those developing navigation, monitoring and tracking systems, Signal K Server is an opportunity to accelerate development and decrease time to market, by taking advantage of a proven, modern and extensible software platform that is open source and available with a permissive Apache 2.0 license. Signal K Server is implemented in Node.js and is easy to integrate into modern systems that run Linux derivatives.

Signal K Server is already running inside products developed by Victron Energy, Airmar Technology and others.

Software Developers & Boat Electronics Hobbyists

There are many boaters who happen to be highly skilled software developers and engineers, who want to build software for themselves and share with others. If you are one of them, Signal K offers you a free, modern and open platform developed by boaters for other boaters like you. Signal K Server features an extensible plugin framework, web applications as well as a rich set of REST and Streaming APIs.

Signal K Server takes care of all the complicated parts of protocol decode, and conversions to and from NMEA2000, NMEA0183 and many more protocols. It can also act as data hub for additional sensors, see the Signal K SensESP project for ESP32.

Signal K Server makes the data available in JSON format according to the Signal K standard specification. This allows developers to bypass all the hurdles typically encountered when wanting to implement something for a boat. Getting started with a plugin is surprisingly easy.

Signal K Platform

Signal K is more than just the Signal K Server, it is a comprehensive platform that encompasses three major components:

  1. The Signal K Data Standard: an open marine data standard. It is a modern data format for marine use, suitable for WiFi, cellphones, tablets and the internet. It is built on standard web technologies including JSON, WebSockets and HTTP. More information on https://signalk.org.
  2. Signal K Server: Software in this GitHub repository and described in this document. Signal K server is a full stack application developed in Node.js. Its back-end multiplexes data from and to NMEA0183, NMEA 2000, Signal K and other marine protocols, as well as WiFi, LAN and Internet, and provides APIs and websockets for access and control. Its front-end provides an extensible web-based application allowing easy configuration and management of server functions and capabilities.
  3. Signal K Plugins and Webapps: Built using the extensibility of Signal K Server with a plugin framework, allows developers to develop applications that easily integrate with Signal K server, extend its capabilities and publish them through npm. All published plugins become available in all existing Signal K server installations, which provides an easy distribution mechanism.

Documentation, Community & Support

Documentation for Signal K Server.

See Github Discussions and Discord (chat).

There is a Signal K Server FAQ Frequently Asked Questions on the Wiki, including How do I integrate with NMEA2000 (CAN bus).

How to get Signal K Server?

For the typical boater, not being a software developer nor electrical engineer, the best option is to get a (commercially available) product that already has Signal K Server inside. These are the currently available devices:

For a more technical DIY oriented boater, a RaspberryPi based setup offers a very cost-attractive alternative. Read this FAQ entry to learn how to connect a RaspberryPi to an NMEA2000 network.

These prebuilt images for RaspberryPis take away most of the complexity involved from the software side:

You can run Signal K Server in Docker:

And an installer for Windows:

Another level up, this document explains how to install Signal K Server, as well as its dependencies, on a RaspberryPi that is already running Raspberry Pi OS:

Last, here is how to install the Signal K Server application from NPM:

Prerequisites:

Now you can start the server with sample data:

To generate your own vessel settings file and configure the server to start automatically, run:

$ sudo signalk-server-setup

Configuration and use

Opening the Signal K Server Admin UI

For all described options of running Signal K Server, ie. on an Airmar Smartboat, a Victron Cerbo GX or a RaspberryPi, the way to configure it is via the Admin UI. Open the Admin UI by navigating to http://[ipaddress]:3000/. Here is what it will look like when opened up on a Victron Cerbo GX:

image

The top of the screen shows some actual stats. Below that is a pane showing all configured Connections & Plugins. These are the plugins shown in above screenshot:

Creating an admin account

The first thing to do is create an admin account. This is done in the Settings -> Users page:

image

Besides recommended from a security point of view, setting an admin account also enables the Restart button.

After creating the account, the server needs to be restarted. How to do that depends on how you are using Signal K Server: self installed from NPM, embedded on a commercial device or otherwise. Power cycling the device that Signal K Server is running on will always work.

Setting up data connections

This screenshot shows how to setup an NMEA0183 connection:

image

Installing Plugins and Webapps

The Appstore menu is where to add, update and remove Plugins and Webapps:

image

The entries with the blue icons are Webapps. The entries with the green icons are Plugins. An internet connection is required for Signal K Server to fetch information about availble Plugins and webapps.

Typically, plugins make for functionality such as protocol conversion. And Webapps provide a user interface, up to a fully featured Chartplotter that runs in a web browser:

image

To install Plugins and Webapps, click the "Available" menu on the left. It will show a categorised list of all available Plugins:

image

It is also possible to search for and browse Plugins and Webapps in the NPM registry:

Restart after Configuration Changes and Plugin/Webapp Installation

Most configuration changes and installing add-ons from the App store require a server restart to take effect. See Restart button at the top right or restart the server manually (details depend on your setup). If the restart button is not showing, that is usually because security is not activate and there is no Admin user.

Configuring Plugins

After the restart, the new Plugin needs to be enabled and configured. See the Server -> Plugin Config menu:

image

Vessel Base Data and Server Settings

image

image

You can change the admin application's top left logo by placing a SVG file named logo.svg in the settings directory (default: $HOME/.signalk/).

Server Log

If the Admin UI is available, go to Server -> Server Log to see the server's log. Different errors are logged there, so in case of trouble make sure to check not only the Admin UI but also the server log.

To activate more details debug logging enter the the names of the components you want to debug. Some of the debug keys are listed with toggles to activate them.

With the Remember debug setting enabled, the configured debug keys parameter is stored in a settings file, ie. survives a server restart.

image

To enable debugging without going through the Admin UI, see the file ~/.signalk/debug and add the required debug keys there. For example: @signalk/aisreporter,signalk-server:udp-provider.

Supported PGNs, sentences and more

Development

Further reading

The documents provide more details about developing Webapps or Plugings for Signal K Server, as well as working on the server itself:

Install from git

git clone https://github.com/SignalK/signalk-server.git
cd signalk-server
npm install
npm run build:all

Start the server with sample data:

This will start the server with a sample configuration file and the server will start playing back data from a sample file under samples/. The data is available immediately via the REST interface at https://localhost:3000/signalk/v1/api/.

This small demo shows how to connect the Signal K Server WebSocket interface from the command line:

npm install -g wscat2
wscat 'ws://localhost:3000/signalk/v1/stream?subscribe=all'

Sponsoring Signal K

See Signal K on Open Collective.

License

Copyright [2015] [Fabian Tollenaar, Teppo Kurki and Signal K committers]

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.