Skip to content

Version 2 Implementation and Changes

Jump to bottom Edit New page
AdrianP edited this page Apr 19, 2023 · 15 revisions

Signal K Server Version 2 Implementation

PR#1477 build of Signal K server introduces some significant changes on the journey towards version 2 of the specification.

Signal K v1 defined a Common Data Model which resulted in the full data model schema providing a hierarchy of paths in which values are held. These paths are available to be populated by any device, sensor or client and relied on these to correctly maintain the values in a group of related paths.

Signal K v2 introduces APIs as HTTP endpoints that complete specific operations (e.g. set destination, advance to next point, etc) rather than expose some well known paths in the underlying data model.

Invoking a v2 API to perform an operation will result in values being set in all the related SK paths ensuring a cohesive data set that can be reliably used for navigation, etc.

The new API endpoints are mounted under /signalk/v2/api so they can coexist with /signalk/v1/api paths.

They are defined as OpenApi documents.

The work has ensured that the v1 and v2 paths co-exist to maintain backwards compatibility.

Course API

The Course API provides HTTP endpoints course operations which populate values under the new path /signalk/v2/api/vessels/self/navigation/course.

See the Course API definition for details.

The Course API maintains values in the following v1 paths to maintain backward compatibility:

  • /signalk/v1/api/vessels/self/navigation/courseGreatCircle
  • /signalk/v1/api/vessels/self/navigation/courseRhumbline

The Course API has consolidated all operations and calculated course values under one path /signalk/v2/api/vessels/self/navigation/course.

Current course details are set using either the activeRoute (navigate a route) or destination (navigate to a position) API operations.

Example: Navigate to specified location

HTTP PUT "/signalk/v2/api/vessels/self/navigation/course/destination" {
    "position": {
        "latitude": 65.4567,
	"longitude": 3.3452
    }
}

This operation will set values for startTime, nextPoint.Position, nextPoint.type and previousPoint.Position enabling valid calculated values to be populated under calcValues.

These course details can be retrieved using HTTP GET "/signalk/v2/api/vessels/self/navigation/course" which returns all relevant information about the active route / destination.

{
	"startTime":  "2022-04-22T05:02:56.484Z",
        "targetArrivalTime": "2022-04-22T15:02:56.484Z",
	"arrivalCircle": 2000
	"activeRoute": {
            "href":  null,
	    "pointIndex":  null,
	    "pointTotal":  null,
	    "reverse": null,
            "name": null,
            "waypoints": null
	},
	"nextPoint": {
	    "href": null,
	    "position": {
		"latitude": 65.4567,
		"longitude": 3.3452
            }
	    "type": "Location"
	},
	"previousPoint": {
	    "position": {   // vessel position when destination was set.
		"latitude": 65.0,
		"longitude": 3.754
             },
	    "type": "VesselPosition"
	}
}

Calculated data relating to the active course are available at the path /signalk/v2/api/vessels/self/navigation/course/calcValues. These paths are for use by a course computer, etc to populate the calculated values based on the active destination and identify the type of calculation used (i.e. Great Circle or Rhumbline).

{
    "calcMethod":  "..",
    "bearingTrackTrue":  ...
    "bearingTrackMagnetic":  ...,
    "crossTrackError":  ...,
    "distance":  ...,
    "bearingTrue":  ...,
    "bearingMagnetic":  ...,
    "velocityMadeGood":  ...,
    "timeToGo":  ...,
    "estimatedTimeOfArrival":  ...,
    "previousPoint": {
        "distance":  ...
    }
}

NMEA0183 / NMEA2000 message processing:

As stated previously the Course API ensures a cohesive data set by ensuring values are set in ALL related SK paths for the given operation.

An NMEA data stream is also a source of course data which has traditionally been used to populate various Signal K paths via the n2k-signalk and nmea0183-signalk plugins.

In order to align with V2 API course operations, it is proposed that plugins processing incoming data streams (i.e. NMEA, SEATALK, etc) populate course data by invoking the V2 Course API endpoints.

In practise this would mean collecting and processing data received from the relevant sentences / pgns to compose a Course API request.

Example 1: Vessel is navigating to a location

  1. Retrieve the destination location (lat/lon) from the NMEA data stream
  2. Create a request containing the loaction lat/lon
  3. Issue a request to signalk/v2/api/vessels/self/navigation/course/destination 
HTTP PUT '/signalk/v2/api/vessels/self/navigation/course/destination' {"position": {"latitude": -60.5, "longitude": -166.7}}

Example 2: Vessel is navigating a route

  1. Retrieve the route details and points from the NMEA data stream
  2. Compile route information into a Signal K Route record
  3. Create a Signal K route resource by issuing a POST request to signalk/v2/api/resources/routes and record the route_id in the response
  4. Issue a request to signalk/v2/api/vessels/self/navigation/course/activeRoute 
HTTP PUT '/signalk/v2/api/vessels/self/navigation/course/activeRoute' {"href": "/resources/routes/5242d307-fbe8-4c65-9059-1f9df1ee126f"}

Conflicting course information from connected devices.

See signalk-server Issue 1522 regarding options for addressing the situation where the course data being received from a connected NMEA device in in conflict with that set via the Course API.

Course Computer (Course Provider Plugin)

Whilst not part of the installation of Signal K server, the Course Provider Plugin has been created in support of the Course API to populate values under the calcValues path.

As well as calculating values it raises the following notifications:

  • notifications.navigation.course.arrivalCircleEntered: upon vessel entering the arrival circle area around nextPoint.position
  • notifications.navigation.course.perpendicularPassed: when the vessel passes a line from nextPoint.position that is perpendicular to a line between nextPoint.position and previousPoint.position

Resources API

The Resources API provides HTTP endpoints for creating, updating and deleting resources (e.g. waypoints, routes, etc.) under the path /signalk/v2/api/resources. It also defines an interface to pass the data to plugins registered as "resource providers" to store and retrieve resources. Delegating the storage of resource data in this way facilitates the ability to use a storage type most suitable for the implementation.

In order to provide out-of-the-box resource storage and retrieval Signal K server v2 includes a built-in resources-provider plugin for saving and retrieving resources using the server file system.

See the following documents for more details:

Connection with v1 Full Data Model

In the current implementation of the v2 API there is only a single stream endpoint and all values emitted as deltas will appear there, but deltas sent as v2 will not appear the full data model. This means that these values will only be available under the equivalent /signalk/v2/api path.

Stream updates

The v2 implementation emits values in the deltas that are object valued. For example, a course is activated and deltas will be emitted for navigation.course.previousPoint, navigation.course.nextPoint and navigation.course.activeRoute where the value is an object.

e.g. navigation.course.previousPoint

{
    "path": "navigation.course.previousPoint",
    "value": {
        "position": {
           "latitude": 65.0,
           "longitude": 3.754
        },
        "type": "Location",
        "href": null
    }
}

and not values sent separately.

{
    "path": "navigation.course.previousPoint.type",
    "value": "Location"
},
{
    "path": "navigation.course.previousPoint.href",
    "value": null
},
{
    "path": "navigation.course.previousPoint.position",
    "value": {
        "latitude": 65.0,
        "longitude": 3.754
    }
}

Deprecations:

Resource IDs prefix

The version 1 specification defined defined resource Ids with the following format urn:mrn:signalk:uuid:<UUIDv4>.

e.g. urn:mrn:signalk:uuid:18592f80-3425-43c2-937b-0be64b6be68c

Version 2 has dropped the use the prefix and are now just a uuidv4 value.

e.g. 18592f80-3425-43c2-937b-0be64b6be68c

This format should be used for both accessing a resource e.g. /signalk/v1/api/resources/waypoints/18592f80-3425-43c2-937b-0be64b6be68c as well as value for the href attribute.

Example:

{
   "name": "...",
   "descripton": "...",
   "href": "/resources/waypoints/18592f80-3425-43c2-937b-0be64b6be68c",
   ...
}

v1 paths

The introduction of the new APIs has resulted in the opportunity to deprecate some paths.

Deprecation of these paths will break compatibility with v1 and will impact applications and plugins that use these paths.

Details are provided in each of the following sections as to the necessary actions required to successfully deprecate the v1 paths.

Course

The v1 paths are flagged for deprecation:

  • /signalk/v1/api/vessels/self/navigation/courseGreatCircle
  • /signalk/v1/api/vessels/self/navigation/courseRhumbline

Applications and plugins that reference these paths should use the equivalent paths under /signalk/v2/api/vessels/self/navigation/course.

Known Issues / impacts

The following plugins have been identified as requiring updates to support v2:

  • @signalk/signalk-to-nmea0183

  • @signalk/signalk-to-nmea2000

  • @signalk/n2k-signalk

  • signalk-derived-data (navigation calculations can be replaced by use of new @signalk/course-provider plugin)

  • freeboard-sk (update to v2 compatible version required: npm i freeboard-sk@beta)

  • freeboard-sk-helper (no longer required with freeboard-sk v2)

  • @signalk/charts-plugin (Updated to support both v1 & v2 paths. PR #20)

  • sk-resources-fs (deprecated - use @signalk/resources-provider plugin instead)

  • ca-reports

Resources

The Resources API has updated the definition of the following resources:

  • routes: removed the start, end properties.
  • waypoints: removed position attribute, added name, description and type attributes.
  • regions: removed geohash attribute, added name and description properties.
  • notes: removed geohash and region attributes, added href and properties attributes.
  • charts: There has been a significant changes to include support for WMS, WMTS and TileJSON sources. Please see the Resources API definition for details.

Please consult Resources API definition for details.

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