Skip to content

FAQ: Frequently Asked Questions

Jump to bottom Edit New page
gregsyoung edited this page Oct 26, 2024 · 56 revisions

Please, feel free to add new entries, if you can include the answer. Questions without answers in Discord Signal K or as Github Issues.

Something's wrong, I need to reinstall / reset my system

On a Linux system the server is installed with the -g global option at /usr/lib/node_modules/signalk-server. Check that this is the case from the command line with ls /usr/lib/node_modules/signalk-server, which should produce a list of files. Remove that directory with sudo rm -rf /usr/lib/node_modules/signalk-server and the server installation is removed. You can then reinstall with sudo npm install -g signalk-server and optionally run signalk-server-setup.

Your own settings, the plugins that you've installed and their settings and data are stored under $HOME/.signalk. If you have trouble with plugins' code you can reinstall all plugins by first removing $HOME/.signalk/node_modules and then running npm install in $HOME/.signalk, which will install all the plugins listed in $HOME/.signalk/package.json. Finalise the reinstall with server restart.

The plugins' settings and data are stored in files under $HOME/.signalk/plugin-config-data, so you can disable all plugins and just one acting up but removing or manually editing files there.

Migrating the Signal K(SK) server to a new server with settings and plugins

On the source SK server update the server and all plugins. The following objects are needed on the target SK server

  • $HOME/.signalk/package.json, file
  • $HOME/.signalk/settings.json, file
  • $HOME/.signalk/plugin-config-data, directory

Create a target server installing Signal K, logon and then remove/rename

  • $HOME/.signalk/node_modules (Will disable the installed plugins)
  • $HOME/.signalk/settings.json (SK server settings)
  • $HOME/.signalk/package.json (Node.js metadata)

Restore the files settings.json and package.json, from the source server, to target server in folder $HOME/.signalk/

In $HOME/.signalk/ run npm install which will install all the plugins listed in package.json

Remove/rename $HOME/.signalk/plugin-config-data (Plugin settings)

Restore the plugin-config-data folder, from the source server, to target server in folder $HOME/.signalk/

Restart the SK target server and check the result.

Server update not updating the server version

Symptoms: server update proceeds without errors, but after restart the server is still running the previous version.

The reason is that a Node.js update has changed the location of global node_modules directory. The server startup script is pointing to the old location but server update installs the new version in the new location.

You can check if you have both /usr/lib/node_modules and /usr/local/lib/node_modules directories and which one $HOME/.signalk/signalk-server is using. Change it to use /usr/local/lib/node_modules and restart the server from the admin UI or with sudo systemctl restart signalk.service.

Incorrect nodejs version

Installing versions of nodejs higher than V18.x are known to cause problems with some plugins and CAN adaptors. Care should be taken when installing other applications (example Grafana) that can (depending on method of install) automatically update nodejs to V19 or higher. If this occurs, the best solution is to uninstall nodejs, & then reinstall nodejs V18 , followed by reinstall of signalk-server (for both these actions, refer Signalk Server installation instructions for more detail) To check the version of nodejs installed, use command node -v from a terminal command line.

How do I send data to the server?

PUT is for making changes that have some real world consequences, like turning on the anchor light. For PUT requests to work there must be a PUT handler registered for the path in question, that carries out the action, like turning the light on or off. There are also plugins that interface with external systems, like NMEA 2000 controlled switches, that register corresponding PUT handlers.

Sensor data / new values for something are sent as delta messages over the WebSocket connection. The simplest delta is {"updates":[{"values": [{"path":"a.b", "value":3.14}]}]}.

How to send data from a script to Node-Red?

Node-Red can be an HTTP end-point listening for incoming requests. This can be done with the node "http in" with "Method = PUT" and "URL = /SomeThing". Now you can send an HTTP 'PUT' with data as '{"value": data}'. This can be done from a script with curl like so: curl -X PUT -H "Authorization: JWT YourToken" -H "Content-Type: application/json" -d '{"status": $SomeVAR}' http://ip:3000/plugins/signalk-node-red/redApi/SomeThing, but first we need to create YourToken for authentication. This is documented here. But as an example: pi@raspberrypi:~/.signalk $ signalk-generate-token -u admin -e 5y -s ~/.signalk/security.json. Maybe first create another user instead of using 'admin'. The Node-Red flow needs one other node, to finish the open connection curl created. It is just a simple "http response node" which needs no further configuration. As an example that works with above curl-command you can copy and import this: [{"id":"ddbadbfbb6ed48b9","type":"http in","z":"85fb2be4229c3180","name":"SomeThing","url":"/SomeThing","method":"put","upload":false,"swaggerDoc":"","x":320,"y":940,"wires":[["741f04c747171fe5","7d19519a8c98ea10"]]},{"id":"7d19519a8c98ea10","type":"http response","z":"85fb2be4229c3180","name":"","statusCode":"","headers":{},"x":530,"y":900,"wires":[]}] What can it be used for:

  • have systemd init files send the status of the process in the 'service '-block with ExecStart and ExecStop which can be used with KIP buttons for status feedback.
  • have a script collect data and send it into SignalK via Node-Red

How do I output data via a serial connection?

See Events and Outputting data.

Where is the server’s log?

On Raspberry Pi the log is at /var/log/syslog and under Server => Server Log in the admin webapp.

How to disable security? OR I have lost my admin password, what do I do?

Remove this section from your settings.json (that is usually located at $HOME/.signalk/settings.json)

  "security": {
    "strategy": "./tokensecurity"
  },

If your server is started with --securityenabled argument you need to remove that to disable security.

WebSocket connections are being dropped and syslog shows "Send buffer overflow, terminating connection"

Some WebSocket client connects with a url that causes the server to send it data continuously, but the client never reads the data. The outgoing buffer on the server grows and eventually the server cuts the connection to safeguard its wellbeing. The client should connect with subscribe=none query parameter, if it does not care for the data stream.

How do I integrate with NMEA2000 (CAN bus)?

Receiving NMEA2000 data requires a CAN bus transceiver to be connected to your system. There is a multitude of chips, devices, HATs, adapters and other solutions out there that roughly be divided into two categories: NMEA 2000 Gateways and Socketcan-compatible hardware. The Node.js Signal K server supports all socketcan-compatible hardware (some are well tested by other community members, others less so) and a few NMEA 2000 gateways.

Supported NMEA 2000 gateways

Node.js Signal K server gateway support is determined by the devices supported by canboat(js). At the time of writing, the following gateways are supported:

Socketcan-compatible CAN transceivers

Socketcan is a Linux kernel extension that publishes a compatible CAN transceiver as a network interface, allowing programs to open sockets to the CAN bus. Unlike the NMEA2000 Gateways, some configuration may be necessary (such as setting up the network interface to be set up at boot, with the right bitrate). The amount of configuration and correct settings depend on the transceiver and firmware used. These solutions are usually cheaper than an NMEA2000 Gateway, but require more DIY to get up and running, and carry no NMEA certification.

To set-up a socketcan device for NMEA 2000, you run the command: sudo ip link set up can0 type can bitrate 250000. However, that only persists until the next reboot. Consult the internet for instructions for your Linux distro and CAN transceiver on how to configure your system to enable the CAN interface at boot time.

The socketcan devices are divided in two categories: those that have galvanic signal isolation and those that do not. Galvanic isolation is important for removing ground loops and for improving signal noise immunity. Without galvanic isolation, ground loops (like the 50/60 Hz hum in badly designed audio systems) can cause significant voltage potential differences and disrupt the communication signal. Galvanic isolation is a mandatory requirement in both NMEA 2000 and NMEA 0183 specifications and should always be used when connecting to essential navigation equipment.

CAN interface devices with galvanic isolation, in alphabetical order:

*Note: PEAK provides SLCAN drivers, but they should not be necessary on Linux. When using SLCAN the CAN adapters shows up as a serial device instead of a socketcan device.

CAN interface devices without galvanic isolation, in alphabetical order:

These lists are incomplete. Most other socketcan-compatible boards and chips will work, but have not been tested yet.

Are you using a CAN transceiver not on this list? Please add!

How do I configure a Yacht Devices Wi-Fi Gateway as a NMEA 2000 source?

Go to the "NMEA Server" page on the YD gateway and add a new server. Use Network Protocol TCP, Data Protocol RAW, Port 1457 and Direction BOTH.

Now you can configure, at the Signal K server, a NMEA 2000 connection as "Yacht Devices RAW TCP(canboatjs)".

Tested with YDWG-02, YDNR-02

How do I configure a Actisense W2K-1 as a NMEA 2000 source?

Configure a Server on W2K-1 with format N2K ASCII, direction Both, protocol TCP.

Now you can configure, at the Signal K server, a NMEA 2000 connection as "W2K-1 N2K ASCII (canboatjs)".

How can I use CAN interface when running Signal K Server in a Docker container?

As Socketcan exposes the CAN bus to the operating system as a network interface (to enable multiple applications to consume the bus), the interface is not available in any container within a bridge (default) network mode. There are basically two methods for making your CAN transceiver available within the Docker container:

  1. The simplest option is to run the container in host network mode. The downside is that Docker's fundamental intention of running applications in isolation from the host doesn't happen with host networking. Also, the feature is only available on Linux hosts. Several other considerations should be taken into account, more can be read in Docker documentation. An example Ansible configuration of this setup can be found here: https://github.com/tkurki/marinepi-provisioning/blob/master/roles/signalk-docker/templates/docker-compose.j2
  2. In order to preserve isolation, Docker container needs to be configured in bridged network mode where host network interfaces are not available. However, this limitation can be overcome by configuring a virtual can network device pair with vxcan kernel module and moving the other end of the virtual network to the container's network namespace. To route the actual N2K communication to the virtual CAN network, a bi-directional gateway is configured using cangw kernel module from canutils. The solution walkthrough is described in a blog post from Lagerdata. An example Ansible configuration can be found here: https://github.com/plektra/vega-ansible/blob/main/roles/signalk/tasks/main.yml

One challenge with the second solution is that Signal K Server establishes NMEA2000 connections in the startup and if the connection fails to initialize, it won't be retried. This is particularly relevant, as the vxcan interface must be moved to a running container's network namespace, meaning that the container must be running before the interface can be made available within the container runtime. This issue has been addressed in canboatjs project. It also seems that if the interface is made available as soon as the container is started, canboatjs is able to pick it up. See the above Ansible example for a Systemd script that listens to Docker events and attaches the virtual network automatically to the container when it's started.

NMEA 2000 inputs are not working

Get a log of your NMEA2000 bus data with something like /usr/lib/node_modules/signalk-server/node_modules/canboatjs/bin/actisense-serialjs /dev/ttyUSB0 > /tmp/actisense.log.

Share the resulting file, preferably via Dropbox, Google Drive, Github Gist or something similar so that you can just share the url.

How to add missing units and static data (e.g.: displayName)

The metadata are provided by the Signal K schema on the server. If they do not appear in the original schema, server's Data Browser, webapps like InstrumentPanel, KIP and mobile apps like WilhelmSK can not retrieve the unit for display and conversions.

Since v2.8.0 you can add metadata fields in Data Browser:

Metadata Editing

Metadata is persisted in baseDeltas.json file where you can edit it manually. The known units are defined in the schema files.

Locate the ~/.signalk/baseDeltas.json file

  • Add your static value inside the updates/values section
  • Add your metadata (units, displayName,...) inside the updates/meta section

In the example below, we will add :

  • A static value -0.191986 in the navigation.magneticVariation path
  • Some metadata value (units, displayName, description, ...) in the environment.cpu.temperature 
[
  {
    "context": "vessels.self",
    "updates": [
      {
        "values": [
          {
            "path": "navigation.magneticVariation",
            "value": -0.191986
          },
          {
            "path": "",
            "value": {
              "name": "MyBoat",
              "mmsi": "1234556",
              "communication": {
                "callsignVhf": "Test"
              }
            }
          }
        ]
      }
    ]
  },
  {
    "context": "vessels.self",
    "updates": [
      {
        "meta": [
          {
            "path": "environment.cpu.temperature",
            "value": {
              "description": "Raspberry Pi cpu temperature",
              "units": "K",
              "displayName": "CPU temp",
              "timeout": 30
            }
          }
        ]
      }
    ]
  }
]

You can also add other missing static data, like environment.depth.transducerToKeel used by the Derived Data plugin, in the same file.

  • Double check your json file content with a json validator
  • Loading changes requires a server restart
  • Verify if unit is present in Signal K Data Browser (Wait at least 30 seconds for the plugin to send data)

How can I get remote access to Signal K?

The following solutions provide direct access to your server.

[systemctl] How to add ENV variable

https://www.freedesktop.org/software/systemd/man/systemd.service.html#Command%20lines
see the example below for the variable PORT

[systemctl] How to change the server listen port (e.g. 3000 to 3030)

edit /etc/systemd/system/signalk.service
add: Environment=PORT=3030 in [service] section

edit /etc/systemd/system/signalk.socket
change: ListenStream=3030 in [Socket] section

then run:
sudo systemctl daemon-reload
sudo systemctl restart signalk

How to expose signalk through a nginx proxy

server {
  root /var/www/<site>/html;
  index index.html index.htm index.nginx-debian.html;

  server_name <site> www.<site>;

  location / {
    proxy_pass http://localhost:3000;
    proxy_set_header Host $host;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
  }

  listen [::]:443 ssl ipv6only=on; # managed by Certbot
  listen 443 ssl; # managed by Certbot
  ssl_certificate /etc/letsencrypt/live/<site>/fullchain.pem; # managed by Certbot
  ssl_certificate_key /etc/letsencrypt/live/<site>/privkey.pem; # managed by Certbot
  include /etc/letsencrypt/options-ssl-nginx.conf; # managed by Certbot
  ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem; # managed by Certbot
}

https://www.nginx.com/blog/websocket-nginx/

How do I develop a plugin or webapp so that I can run it in the server?

Use npm link to link the module you are developing to the server and run the server from a git clone, not as a real install.

$ mkdir work && cd work
$ git clone [email protected]:SignalK/set-system-time.git && pushd set-system-time && npm link && popd
$ git clone [email protected]:SignalK/signalk-server.git && pushd signalk-server && npm install && npm link @signalk/set-system-time
$ bin/n2k-from-file
Add a custom footer
Add a custom sidebar
Clone this wiki locally