Events and Outputting Data

Signal K server uses a mechanism called events internally to make data available to different parts of the server, including the data connections and plugins.

Events have a mandatory name and optional arguments. An example of an event without any arguments is nmea2000OutAvailable, that is emitted when a connection that can output NMEA2000 is available. A plugin can use it to detect that NMEA2000 output can be used. nmea0183 is an example of an event with an argument/payload: every time the server receives an NMEA 0183 input sentence it is emitted as the event's payload.

Events can be used to connect certain data to an output. The server's built in NMEA 0183 over TCP service listens for events nmea0183 and nmea0183out and whenever it receives these events the payload data is sent to connected TCP clients (terminated with the CR LF characters, that are not part of the payload). nmea0183out event is emitted by signalk-to-nmea0183 plugin. Using two event names here allows distinguishing between original and derived/generated data.

NMEA0183 serial connections work by default as inputs into the server and as outputs from the server. To activate the output you need to configure the connection to listen for an event. For example if you want to direct the output of the signalk-to-nmea0183 plugin into a serial connection you enter nmea0183out in the Output events field.

Events provide no backpressure mechanism: the event emitter does not know if another part of the system is listening nor if it has the capacity to consume all the events that the emitter produces. A practical example would be having incoming AIS data at 38400 bps and configuring a 4800 bps output to listen for nmea0183 events. The serial output buffer will overflow and emit only part of the data, with error messages in the log, but the system will keep working, albeit suboptimally. This is why signalk-to-nmea0183 has a configuration option to control the output rate of each sentence.

You can monitor the flow of events in the Server Log page by activating debug logging for one or more events.

You often need to filter or include some of the events when routing data from one input into another. This can be achieved with nmea0183-to-nmea1038 plugin. It can be used to listen for one event with NMEA 0183 data and output some of the sentences as another event, that can be in turn configured as the output event for the other connection.

If you need more complex logic you can use the Node-RED plugin and its Signal K related nodes, that allow you to listen for server's events and emit your own. Another alternative is a custom plugin, where you can use events to create your logic. With the event mechanism it is very easy to tap into the server's non-Signal K data streams.

For Signal K data processing plugins should use the available Signal K data streams implemented with Bacon JS.