Kees Verruijt edited this page Oct 21, 2018 · 2 revisions

The n2kd program reads parsed output from analyzer in json format, stores it and then sends it on to TCP clients, still in json format, and also converts some PGNs to a NMEA0183 data stream accessible over TCP.

It provides three distinct TCP servers:

  1. A caching JSON server that provides a single snapshot of the latest received data of all PGNs, in fully valid JSON format. The default port number is 2597 and can be overruled with -p.
  2. A streaming JSON server. The client continuously receives JSON messages as they are received by n2kd. The port number is always one higher than the AJAX server. This server is useful for clients that are able to keep an open TCP socket and are interested in changes in values and need to respond immediately.
  3. A NMEA0183 stream. Certain PGNs received are translated into NMEA0183 ASCII stream. The port number is always two higher than the AJAX server.

To be more useful it generates a (complete) JSON object that contains a 2 dimensional array.

The first dimension is indexed by PRN (the PGN id). This makes it easy for clients to ignore PGNS that they are not interested in.

The second dimension is indexed by key. The key is that what is deemed a useful key. Normally it will be the source device ID, a number between 0 and 254. For some PGNs that is not sufficient because there may be many datagrams received over time that all have a different meaning or source.

For instance the apparent and true wind data are datagrams arriving several times a second from the source. If the daemon just stored the last datagram it would be random chance which one the client would receive. The same holds for AIS messages, you'd see only one MMSI (ship ID). So the code contains heuristics that attempt to make sure that a unique key is generated for each such message.

You can see this in the following example stream:

{   "130311": 
    {"description":"Environmental Parameters"
    ,"35_Sea":{"timestamp":"2012-11-22-12:24:03.000","prio":"5","src":"35","dst":"255","pgn":"130311","description":"Environmental Parameters","fields":{"SID":"31","Temperature Instance":"Sea","Temperature":"19.44"}}
    }
}

Here the water temperature gets a key "35_Sea" instead of "35" (source device) so that a potential air temperature would be distinguished as "35_Air".

The caching JSON server

This server has been developed as a backend for HTTP servers that fulfill AJAX requests. I personally use a small PHP script that opens a connection to this server and just passes everything on.

This server does the following for every incoming client connection:

  • Wait for 500 ms
  • Send the latest message from all sources received within the last 120 seconds and AIS and SonicHub data received within the last 6 minutes.
  • Close the connection.

The streaming JSON server

This server does not do any processing on the incoming data received from analyze. It just passes on each record as it is received. Thus this can be used to provide a 2nd (or 3rd... etc) consumer of the JSON messages.

I personally use this with small scripts that monitor a particular value and then send alarms, switch off consumers etc. -- for instance, when the battery voltage goes below 24V all consumers are switched off.

The NMEA0183 server

This server also streams -- ie. it never closes the connection itself. As NMEA 2000 messages are received it will check if it knows the NMEA0183 equivalent and if so it converts it and sends it out.

The NMEA0183 messages that can be generated are:

  • Compass heading sentence HDG, HDM or HDT from PGN 127250.
  • Wind data sentence MWV from PGN 130306.
  • Depth sentence DBK, DBS or DBT from PGN 128267.

There is an option to only send on data coming from particular N2K sources (--src-limit <filter>), for instance --src-filter 2,13 will only send data coming from addresses 2 and 13, or --src-limit '!35' will send data coming from all addresses except 35.

If you intend to send the NMEA0183 stream to a real NMEA serial port at 4800 baud you can use the --rate-limit option which will make the server only pass one message per source per type per second.

This is a recent addition and likely to improve and change, over time.

TODO: Add support for GPS and AIS data.

Usage

usage: n2kd [-d] [-q] [-o] [-r] [--src-filter <srclist>] [--rate-limit] [-p <port>]

  -d                      debug mode
  -q                      quiet mode
  -o                      output mode, send all TCP client data to stdout (as well as stdin)
  -r                      restrict mode, send no data to stdout
  --src-filter <srclist>  restrict NMEA0183 stream to particular N2K sources
  --rate-limit            restrict NMEA0183 stream to one message per source per second
  -p <port>               Start servers at <port> instead of 2597
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.