Skip to content

Latest commit

 

History

History
89 lines (59 loc) · 4.91 KB

README.md

File metadata and controls

89 lines (59 loc) · 4.91 KB
Raw

Signal K to InfluxDb Plugin

Signal K Node server plugin to write all simple numeric Signal K values to InfluxDB 1.x, a time series database.

Note: If you're interested in using InfluxDB 2.x, see the signalk-to-influxdb2 repository instead. This is the preferred approach for new installations.

Once the data is in InfluxDb you can use for example Grafana to draw pretty graphs of your data.

The plugin assumes that the database you specify exists. You can create one with

curl -X POST http://localhost:8086/query?q=CREATE+DATABASE+boatdata

The plugin writes only self data. It converts Signal K paths to InfluxDb measurement keys in CamelCase format, eg. navigationPosition.

Adding support for non-self data would be pretty easy by adding context as InfluxDB tags.

Position handling and tracks

If enabled by black/whitelist configuration navigation.position updates are written to the db no more frequently than once per second. More frequent updates are simply ignored.

The coordinates are written as [lon, lat] strings for minimal postprocessing in GeoJSON conversion. Optionally, coordinates can be written separately to database. This enable location data to be used in various ways e.g. in Grafana (mapping, functions, ...).

The plugin creates /signalk/vX/api/self/track endpoint that accepts three parameters and returns GeoJSON MultiLineString.

Parameters:

  • timespan: in the format xxxY (e.g. 1h), where xxx is a Number and Y one of:

    • s (seconds)
    • m (minutes)
    • h (hours)
    • d (days)
    • w (weeks)

  • resolution: (in the same format) specifies the time interval between each point returned. For example http://localhost:3000/signalk/v1/api/self/track?timespan=1d&resolution=1h will return the data for the last 1 day (24 hours) with one position per hour. The data is simply sampled with InfluxDB's first() function.

  • timespanOffset: (number) Without timespanOffset defined the end time of the returned data is the current time. Supplying a timespanOffset value changes the end time to be current time - timespanOffset. The timespanOffset value is considered to have the same "Y" as timespan.

Examples: where current time is 14:00

http://localhost:3000/signalk/v1/api/self/track?timespan=12h&resolution=1m returns data in the time window 2:00 - 14:00

http://localhost:3000/signalk/v1/api/self/track?timespan=12h&resolution=1m&timespanOffset=1 returns data in the time window 1:00 - 13:00.

Sources

If you have multiple sources generating the same data / same Signal K paths you can distinguish between them by specifying source in the query:

image

To get persistent source data in data from NMEA 2000 networks use Use Can NAME in source data in connection settings. This way all sources will get a unique identity that does not change the NMEA 2000 bus addresses change.

Time Series API

This plugin implements an HTTP API for retrieving historical / time series values with urls like http://localhost:3000/signalk/v1/history/values?from=2021-05-25T20:00:00.001Z&to=2021-05-25T23:00:00.561Z&paths=navigation.speedOverGround,navigation.speedOverGround

  • from and to are date-times with a time offset and/or a time zone in the ISO-8601 calendar system
  • paths is a comma delimited list of Signal K paths
  • resolution is how many seconds between entries, given as integer
  • context

Additionally you can retrieve the contexts that the db has data for with query like http://localhost:3000/signalk/v1/history/contexts?from=2021-05-25T20:00:00.001Z&to=2021-05-25T23:00:00.561Z and paths with http://localhost:3000/signalk/v1/history/paths?from=2021-05-25T20:00:00.001Z&to=2021-05-25T23:00:00.561Z

Provider

If you want to import log files to InfluxDb this plugin provides also a provider interface that you can include in your input pipeline. First configure your log playback, then stop the server and insert the following entry in your settings.json:

        {
          "type": "signalk-to-influxdb/provider",
          "options": {
            "host": "localhost",
            "port": 8086,
            "database": "signalk",
            "selfId": <your self id here>,
            "batchSize": 1000
          }
        }

Try it out / Development setup

A quick way to get started / try things out / set things up for development is to start InfluxDb and Grafana withdocker-compose up. Then you need to configure the plugin to write to localhost:8086 and Grafana to use InfluxDb data.

For a real world setup you probably want to install these locally, see for example Seabits step by step instructions.