Skip to content

Version 2 Implementation and Changes

Jump to bottom Edit New page
AdrianP edited this page Jun 1, 2022 · 15 revisions

Signal K Server Version 2 Implementation

PR#1381 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.

Breaking Changes

The introduction of the new APIs has triggered a review of path definitions and some changes have resulted.

Some of these changes are significant and break compatibility with v1 and will impact applications and plugins that use these paths.

Details of breaking changes will be provided in each of the following sections.

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.

BREAKING CHANGES

The Course API deprecates the use of the v1 paths:

  • /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

The following plugins have been identified as requiring an update to work with v2:

  • @signalk/signalk-to-nmea0183 (PR #91)
  • @signalk/signalk-to-nmea2000 (PR #63)
  • signalk-derived-data (navigation calculations can be replaced by use of new @signalk/course-provider plugin)
  • freeboard-sk-helper (remove arrivalCircleEntered notification generation)

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"
	},
	"activeRoute": {
		"href":  null,
		"pointIndex":  null,
		"pointTotal":  null,
		"reverse": null
	},
	"nextPoint": {
		"href": null,
		"position": {
			"latitude": 65.4567,
			"longitude": 3.3452
        }
		"type": "Location",
		"arrivalCircle": ...    // value is unchanged
	},
	"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":  ...
    }
}

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:

BREAKING CHANGES

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

  • routes: removed the start, end properties.
  • waypoints: removed position attribute, added name and description 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.

POST operations to the routes, waypoints and regions paths no longer use a resource record object as a payload. POST operations can facilitate resource creation with only a minimal number of details supplied. Please consult Resources API definition for details.

Known Issues

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

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

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 in the full data model regardless of whether the path is v2. This means that these values will be available under the equivalent /signalk/v1/api path as well as /signalk/v2/api.

Example: Course data will be available under both /signalk/v2/api/vessels/self/navigation/course and /signalk/v1/api/vessels/self/navigation/course.

This may change with future implementations of the v2 API and therefore should not be relied on in future.

Stream updates

The current v2 implementation emits values in the deltas that are object valued. For example, a course is activated the navigation.course.previousPoint.position value is a object

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

and not values sent separately.

{
    "path": "navigation.course.previousPoint.position.latitude",
	"value": 65.0,
},
{
    "path": "navigation.course.previousPoint.position.longitude",
	"value": 3.754
}
Add a custom footer
Add a custom sidebar
Clone this wiki locally