Skip to content

Extending autopilot related paths 2020

Jump to bottom Edit New page
AdrianP edited this page Jan 10, 2025 · 24 revisions

This doc is a draft for extending Signal K autopilot related paths to improve integration with different autopilots.

Contents:

Autopilot paths:

List of relevant paths, proposed extensions in italic

  • autopilot/state
    • enum: enabled disabled error
  • autopilot/mode
    • current mode: e.g. compass
  • autopilot/availableModes
    • array of modes supported by the Auto-pilot e.g. [compass, gps, windApparent, windTrue]
  • autopilot/target/windAngleApparent (Q: should the path just be _autopilot/target_ which is a numeric value (-179 -> 359) as the mode will dtermine what the value represents?)
  • autopilot/target/windAngleTrue
  • autopilot/target/headingTrue
  • autopilot/target/headingMagnetic
  • autopilot/target/courseTrue
  • autopilot/target/courseMagnetic (not really relevant?)
  • autopilot/deadZone
  • autopilot/backlash
  • autopilot/gain
    • what subkeys should we have here?
  • autopilot/maxDriveCurrent
  • autopilot/maxDriveRate
  • autopilot/portLock
  • autopilot/starboardLock
  • _ slew speeds ??_

Course paths:

Autopilot operation is interlinked with course information so outlined below are the relevant course paths.

Ref: Signal K Server Course API

V1 specification:

  • navigation/courseGreatCircle/crossTrackError
  • navigation/courseGreatCircle/bearingTrackTrue
  • navigation/courseGreatCircle/bearingTrackMagnetic
  • navigation/courseGreatCircle/activeRoute
  • navigation/courseGreatCircle/activeRoute/estimatedTimeOfArrival
  • navigation/courseGreatCircle/activeRoute/startTime
  • navigation/courseGreatCircle/nextPoint {type + href}
  • navigation/courseGreatCircle/nextPoint/distance (tkurki: no idea why these are missing)
  • navigation/courseGreatCircle/nextPoint/position
  • navigation/courseGreatCircle/nextPoint/arrivalCircle (size in m)
  • navigation/courseGreatCircle/previousPoint {type + href}
  • navigation/courseGreatCircle/previousPoint/distance
  • navigation/courseGreatCircle/previousPoint/position

V2 specification:

  • navigation/course/calcValues/calcMethod {great circle | rhumbline}
  • navigation/course/calcValues/crossTrackError
  • navigation/course/calcValues/bearingTrackTrue
  • navigation/course/calcValues/bearingTrackMagnetic
  • navigation/course/calcValues/estimatedTimeOfArrival
  • navigation/course/calcValues/distance
  • navigation/course/calcValues/bearingTrue
  • navigation/course/calcValues/bearingMagnetic
  • navigation/course/calcValues/velocityMadeGood
  • navigation/course/calcValues/timeToGo

Autopilot API:

Ref: Signal K Server Autopilot API

Signal K Server 2.13.0 implements an Autopilot API that:

  1. Accepts requests via HTTP for performing common autopilot operations
  2. Defines an interface for AutopilotProvider plugins to process requests and provide updates from autopilot devices

The Signal K Server handles AutoPilot API requests, validates the supplied data and then passes the request to an AutopilotProvider plugin which manages communication with the autopilot device.

Autopilot API endpoints are available at the path /signalk/v2/api/vessels/self/autopilots

Example: Retrieve autopilot configuration options from the default provider:

// Request:
HTTP GET /signalk/v2/api/vessels/self/autopilots/_default

// Response:
{
   states: [  // valid values for state
      {
         "name": "auto",
         "engaged": true
      },
      {
         "name": "standby",
         "engaged": false
      },
   ],    
      modes: ['gps', 'compass', 'wind']   // valid values for mode
}

Common Autopilot Operations

  • Engage / Disengage`
  • Set State
  • Set Mode
  • Set / Adjust Target
  • Tack / Gybe

Notifications

  • What well defined notification/* paths should there be?

Control vs informing about a state

Data pertaining to the current value of the autopilot should be sent as a delta update message where it can be retrieved via the server published endpoints.

Control / command is performed via the proposed Autopilot API using HTTP PUT requests.

SK Server Network Plugin CAN / serial / IP Autopilot
/stream
context: self		 <------------ status ----------------------
steering.autopilot.state
steering.autopilot.mode 		N2K to SK
websocket 		<------
<------
 NMEA Pilot
SK aware pilot
/stream
context: self		 <------------ target details ------------
steering.autopilot.target 		N2K to SK
websocket 		<------
<------
 NMEA Pilot
SK aware pilot
/stream
context: self		 --------------- course data ------------>
navigation.course.nextPoint
navigation.course.calcValues 		SK to 0183
SK to N2K
websocket 		---------->
RMB, APB, XTE
---------->
PGN 12928x
---------->		 NMEA0183 Pilot
NMEA2000 Pilot
SK aware pilot
HTTP GET <---------------- config / options -------------------
./autopilots/{id}/options 		AP Plugin <------
HTTP PUT --------------- engage / activate ------------>
POST ./autopilots/{id}/engage 		AP Plugin ------>
HTTP PUT --------------- disengage / deactivate ------------>
POST ./autopilots/{id}/disengage 		AP Plugin ------>
HTTP PUT --------------- set state ------------>
PUT ./autopilots/{id}/state {value: string}		 AP Plugin ------>
HTTP PUT --------------- set mode ------------>
PUT ./autopilots/{id}/mode {value: string}		 AP Plugin ------>
HTTP PUT --------------- set target ------------>
PUT ./autopilots/{id}/target {value: number, units: 'deg' or 'rad'}		 AP Plugin ------>
HTTP PUT --------------- adjust target ------------>
PUT ./autopilots/{id}/target/adjust {value: number, units: 'deg' or 'rad'}		 AP Plugin ------>
HTTP PUT --------------- tack port ------------>
POST ./autopilots/{id}/tack/port 		AP Plugin ------>
HTTP PUT --------------- tack starboard ------------>
POST ./autopilots/{id}/tack/starboard 		AP Plugin ------>

Operation / Usage:

Assumption: Autopilot is a standalone device operating autonomously. It can accept commands and course settings via:

  • Direct input on the device / built-in UI
  • NMEA0183, NMEA200, SeaTalk messages
  • Signal K delta messages

Signal K Course API: Signal K Server implements a course API that provides operations for setting an active route or destination point and facilitates the maintenance of navigation.course path values.

Assumption: navigation.courseGreatCircle and/or navigation.courseRhumbline (v1 specification), navigation.course.calculations (v2 specification) path values are populated through the use of a course data provider plugin.

Action Signal K aware Autopilot Plugin/Provider
1. SK Server startup Send status in steering/autopilot/mode path(s) to server. Connect to autopilot and retrieve status. Send steering/autopilotdeltas with retrieved values.
2. Autopilot engaged (autopilot UI) Send deltas containing updated autopilot path values. Detect change in autopilot status, retrieve status from autopilot, send deltas containing updated autopilot path values.
3. Changes to Autopilot status (autopilot UI) Send deltas containing updated autopilot path values. Detect change in autopilot status, retrieve status from autopilot, send deltas containing updated autopilot path values.
4. Destination set via Signal K Course API Receives course/nextPoint, course/calcValues deltas and uses values to set course to steer. Receives course/nextPoint, course/calcValues deltas and sends values to autopilot to set course to steer.
5. Send command to autopilot via Signal K Autopilot API Receives steering/autopilot deltas and adjusts operation based on received values. Receives steering/autopilot deltas and sends values to autopilot to adjust operation based on values supplied.

Real World setups

How about describing some real world setups to get context and depth.

A start point would be current NMEA0183 and N2K systems and OpenCpn & pypilot, then we could construct a "pure" Signal K system.

Related resources:

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