Skip to content

FAQ: Frequently Asked Questions

Jump to bottom Edit New page
mpvader edited this page Mar 21, 2023 · 56 revisions

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

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 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

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 and mobile apps like WilhelmSK can not retrieve the unit for display and conversions.

You can add the missing units to your baseDeltas.json file. The known units are defined in the schema files.
If you don't have a baseDeltas.json file, please update your SignalK server version, it is too old and not supported anymore.

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

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.

Add a custom footer
Add a custom sidebar
Clone this wiki locally