Signal K In¶
One single instrument but so important that it deserves its own chapter!
The instrument is no reading one single instrument but it is actually controlling a data streamer which reads data from a Signal K server node. This alternative data source to OpenCPN is feeding DashT and its instruments with Signal K data from a delta channel (delta for changed data). The fast, time stamped data source is an alternative to OpenCPN to get data normally not visible to OpenCPN.
This is how you start Signal K input stream, by creating Signal K In instrument. It is recommend to have its own, dedicated window pane with only one of these single line instuments in it (see below the troubleshooting section to find out why). You can have multiple instances of this instrument type but only the first one is going to do anything else but showing the data rate.
This is what you are going to see when the Signal K In instrument is starting, it means that it is waiting for a connection to a Signal K server node:
Signal K server node¶
As you may have learned by now, if there is no Signal K server node the Signal K In instrument will remain forever in the waiting state.
OpenCPN v5.2 and superior supports Signal K data and therefore also the Signal K server node as data source. If you have set OpenCPN for Signal K data and you still do not get any data in DashT, please read the operation principles below to understand that DashT asks only NMEA-0183 data from OpenCPN but for Signal K data it requires a direct, dedicated connection to a Signal K server node.
NOTE: Signal K is a data format. Signal K server node is a data processing and interchange server which is delivering data in Signal K data format. DashT requires a Signal K server node for Signal K data.
In case you do not have a Signal K server node please read the OpenCPN documentation for supplementary software, which has a section for Signal K server node which gives you the right pointers for your operating system installations.
If there is a Signal K server node available in the local network of your computer, you will see the above heartbeat pulsing on the instrument display. Data is coming in already, at this point.
In case there is an issue with this and you find out that all components are there, please see the troublesoothing section further down of this document for instructions.
Once enough data has been received to make meaningful statistics, the data rate is displayed. It is showing data values received, in average and per second. The value shown is not corresponding the data rate value which one can observe on the Signal K server node dashboard. It counts messages Signal K server node receives but Signal K In streamer counts valid data values it has subscribed to and which it effectively receives.
NOTE: In some of the Signal K data structures there are more than one data value per message, for example in the position data latitude and longitude: Signal K In streamer counts each of the data value since this is the way they are internally streamed to the instruments, one by one. Therefore the value is presenting the effective data rate all the way to the instruments.
While you are all set now, it would be perhaps interesting to understand more about the Signal K data and how it arrives in DashT and how it is used there, so please continue reading.
NMEA-0183 data type¶
As discussed in NMEA-0183 Data chapter, the origin of data in Signal K server node can be also a SignalK data source with NMEA-0183 data type.
In this case the data arrives to your instruments exactly the same way through Signal K In streamer than it would come via the OpenCPN plug-in interface. Only that you get it faster and with timestamps set by the Signal K server node, a feature mandatory for the usage of any time based database or analysis software.
Logically speaking, there is nothing to gain to get this same data via OpenCPN - one would just get an extra delay in the data path. Even if one has a NMEA-0183 based navigation data system, Signal K In streamer is the preferred way to get this data in DashT.
NMEA-2000 data type¶
To get access to a rich and flexible data source is the main motivation for DashT to interface with Signal K server node. If available, it provides much higher data rates and wide variety of new data parameters. The Signal K data format unifies the access to this data source.
NMEA-2000, a derivation of the CAN data bus is the most likely commodity off the shelf (COTS) source for engine and energy data on boats with recent electronics (albeit it may have a different commercial name for © and ® business reasons). Shortly, what the CAN-bus is doing in your car, NMEA-2000 is used to the same in your boat. NMEA-0183 remains, of course a data source for_DashT_instruments but EngineDJG instruments, for example require Signal K data which simply is not available in NMEA-0183 coming from OpenCPN.
Other data types¶
Currently, DashT does not support GPIO, \(I^2C\), BLE or other Signal K data types other than NMEA-0183 and NMEA-2000.
There is no other particular reason for this other than there is not enough information and use cases available for other data formats which would allow testing of them. From the DashT instruments’ point of view the data can be from any source and any type. However, SignalK server node sets, in delta sentence the data source and the type, which also changes the data structure: currently DashT has been taught to parse only NMEA-0183 and NMEA-2000 type of sentences. If a new interesting data source and type emerges, it would be quite straightforward to add parsing of its data structure into Signal K In streamer, for example for energy data and similar.
Signal K data interchange¶
Signal K, a modern and open data format for marine use is a protocol understood by DashT for data interchange over the network. Signal K keys are defined for each data source, called below data paths. A DashT EngineDJG instrument, for example subscribes to the data coming from one of the data path using a Signal K key.
NOTE: Unlike with OpenCPN, where all data is pushed to everybody who has asked for NMEA-0183, with Signal K server node and DashT support for it, the instruments are subcribing to data. In other words, if you have only one instrument, showing one data value, Signal K server node needs to send only that data to DashT, nothing else. This, obviously reduces the power consumption and allows your computer to run more efficiently.
How it works¶
(1). NMEA-2000 databus is the source of the engine and energy data for the EngineDJG instrument.
There may be other, potential data sources which can be enabled in the future, such as IoT capable sensors, Bluetooth Low Energy (BLE), \(I^2C\) and General Purpose I/O pins (GPIO). For now, only NMEA-2000 is discussed as data source and type but DashT does not require NMEA-2000 in particular, just Signal K data.
(2). In case the NMEA-2000 databus does not provide navigational data, needed by OpenCPN and displayed by other DashT instruments, your boat probably sports also a classic NMEA-0183 wired sensors and instruments. They end up, typically into a multiplexer (MUX), which interfaces simply with the Signal K server node either by a USB connection, Ethernet connection or WiFi.
(3). Signal K server node, or a commercial Signal K data enabled router / multiplexer is entirely network enabled and can locate anywhere in your boat, not necessarily on the same computer where one is running OpenCPN and DashT.
Signal K data format is a standard for data interchange. A server implements and a client uses that data format. For example “Signal K server node” is not “Signal K”, it is one of its implementations but there are others. See this list of open source and commercial products available.
(4). For example, one can have immediately access from the cockpit tablet to the rich set of instruments, plug-ins and features Signal K server node provides
(5). Signal K standard defines and a server node provides, among its other networked data interchange interfaces, so-called Delta-channel, where all the changes in the boat data is available. When the boat has a NMEA-2000 databus this usually means a lot of data and many Signal K keys. Clients can subscribe to all of this data or to some selected keys only.
(6). OpenCPN has developed an interface to Signal K data, using a different interface than DashT is using. Of course, OpenCPN is not a consumer of the engine data, and it is not even remotely interested in knowing if the ice cube machine is still working. But it needs the time, position and other navigational data for its routing and map functions. Also, it needs to feed the majority of its plug-ins with NMEA-0183 or Signal K data. For that it is using a internal (i.e. fast) multiplexer gateway.
NOTE: Even if you decide not to use Signal K data in OpenCPN but NMEA-0183, please be aware that a Signal K server node is able to provide all the NMEA-0183/AIS data to the chartplotter (and other clients) also in NMEA-0183 format - and still continue to feed DashT with Signal K data only for those values DashT subscribes to.
(7). DashT is a plug-in for OpenCPN chartplotter, containing an efficient, built-in Signal K data streamer. It subscribes to all data a Signal K server sends over the Delta channel to start with, then asks the instruments what of this data available they are interested in, subscribing to those data keys only. When data arrives, it is distributed to subscribers over a C++ method call-back mechanism (i.e. very efficiently). This way, DashT is making gain in speed and lowers the number of network connections to the Signal K server node, reducing its workload as well as that of your computer.
(8). The DashT EngineDJG instrument comes only in one flavour, unlike other DashT “traditional” OpenCPN Dashboard instruments which are hard-coded for their intended usage. An EngineDJG instrument is configured after its creation. The user of the instrument is provided with a list of available Signal K keys. Only one of the keys can be selected per instrument. The origin of the data is not required to be NMEA-2000 data source, but it most probably is. Once set, the instrument is subscribed to a Signal K key and show, say port engine rotation speed in r.p.m. There is no limitation other than the screen size for the number of these instruments.
(9). The traditional Dashboard instruments, such as wind data and similar are subscribed automatically to the corresponding Signal K key. If it is not available, they will receive the data as before, from the OpenCPN’s NMEA-0183 distribution channel.
Configuration¶
The default configuration file is in JSON-format (like Signal K data). The default values are good for normal, local-only operation. It may require changes in case when things are not working. It is located:
Windows \ProgramData\opencpn\plugins\dashoard_tactics_pi\streamin-sk.json
Linux ~/.opencpnplugins/dashboard_tactics_pi/streamin-sk.json
Typical changes would be to change port or the location of your Signal K server node and its delta channel.
"streaminsk" : {
"source" : "localhost:8375", // not limited to localhost
"api" : "v1.20.0", // version of Signal K server
"connectionretry" : 5, // [s](min.=1s to reduce CPU load)
"timestamps" : "server", // Signal K "server" or "local"
"verbosity" : 1 //0=no,1=events,2=verbose,3+=debug
NOTE: The configuration file is read only in during the startup so you would need to restart OpenCPN after modifying this file.
Troubleshooting¶
When debugging or searching for a probable communication issue you would set the verbosity parameter to a value between 2… 5, the 5 being really verbose; so talkative that it would actually affect the performance and the OpenCPN log file will get really big, really fast.
Typically, you would stop OpenCPN, set the debug value and, before starting OpenCPN you would set a line-by line observation to its log file. With grep command you can further reduce the filtering if it is too verbose.
On Windows using PowerShell:
PS C:\ProgramData\opencpn>
Get-Content ./opencpn.log -Wait -Tail 20
On *nix systems:
tail -f ~.opencpn/opencpn.log
or with filtering
tail -f ~.opencpn/opencpn.log | grep dashboard_tactics_pi
No connection¶
If the arrows keep on moving forever from right to left, it indicates that the TCP/IP cannot get connection. Check the configuration file’s parameter, which is by default:
"source" : "localhost:8375", // not limited to localhost
If your Signal K server node is located in another computer, replace the localhost with the computer’s name or if that does not work, with its IP-address (numerical).
In case the remote Signal K server is still not answering it may be that it does not implement the delta service in the port 8375, or on any other port perhaps; it is not a mandatory requirement for a Signal K server to provide this service.
NOTE: the implementation of Signal K data delta channel is the reason why only Signal K server node is supported in DashT - other servers have simply never been tested.
If you know that the local Signal K server node is there, that it is based on Node.js and it is equal of greater to version 1.19, there is indeed no reason why the port 8375 would not be served. In this case you may try simply to use IP-address 127.0.0.1 instead of loccalhost, maybe there is an issue with your systems’ Domain Name Service (DNS) settings.
No data¶
This is indicated by the following condition in the Signal K In throughput display:
First, see the Signal K server node’s dashboard and verify that it gets indeed some data in - if not, nothing will come out either…
If all looks good both for Signal K server node’s input and also the Dashboard’s instruments keep hopping around as they normally do, there is perhaps simply no data available in 8375 port. See above, that’s not a mandatory requirement for a Signal K server, maybe you are using some commercial implementation of it?
HALT state¶
The message indicates that the continously running communication thread has been stopped. There is no other remedy for this condition but to stop gracefully OpenCPN and restart it.
To avoid this to happen one should keep both the Signal K input stream instrument and the Influx DB output stream instrument both in their own, distinct instrument windows. In other words, they shall be separated from other instruments but also from each other. This is to avoid that the communication thread would get orphan when instrument windows get reorganized.
If one attempts to change the orientation of the Signal K In input stream’s carrying instrument display pane, the communication thread will be detached from it and the instrument itself indicates halted state. If you absolutely need to change the orientation of the single Signal K In instrument pane (perhaps you want to dock it - otherwise the orientation has no meaning for a single instrument), you need to remove it from the list of instruments and create a new one with the desired orientation.
Confusing timestamps¶
One may experience difficulties to find recorded data from InfluxDB v2 which, as a time series database requires that you know at what time range your data was recorded. There is one, potential source for this and that is the clocks not running the same time!
For NMEA-0183 data coming form OpenCPN, timestamps are generated by DashT on-the fly at the reception using the local, CPU clock.
For any data coming from Signal K server node the timestamps coming with the data are used. If you are repeating a recording, or if your CPU’s time is different than that of the Signal K server node there is a chance that you get quickly confused.
If not, this is what DashT will do: if there is more than five seconds difference between the GNSS (GPS) data provided by the navigation.datetime and your CPU (computer) time, DashT starts to use exclusively that GNSS (GPS) originated time, also for the Tactics’ generated regatta processor data, but with offset from the local CPU clock. This, because the navigation.datetime messages do not arrive with frequency high enough for the very fast Tactics regatta processor. Without this
measure, one would never be able to match the derived performance data with the input data.
Briefly, if you can, synchronize your CPU (computer) clock with the GNSS (GPS) when underway and over the network when not.