Extending autopilot related paths 2020

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

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
• 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 ??_

"Navigation computer" related paths:

• 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

Todo

• Dodging - what does it mean in real life?
• Tacking
• +/- adjustments
• • what well defined notification/* paths should there be?

Control vs informing about a state

In Signal K control/command is usually separate from "sensor data", eg. data about the current value of something. Control messages are HTTP PUTs or (ws) messages with put syntax: https://github.com/SignalK/specification/blob/master/gitbook-docs/put.md

Usage Scenarios

Note: signalk-server PR #1381 adds a course API that handles the setting of ALL the appropriate navigation.course path attribute values when setting an active route or destination point.

Signal K App User Actions:

1: Set Active Route

• User selects a route
• User marks Route as Active
• SKApp submits a request to navigation/course/activeRoute
• SK server processes request and sets navigation.course attribute values.

---

2: Set Next Point in route

• SKApp submits a request to navigation/course/activeRoute/nextPoint
• SK server processes request and sets navigation.course attribute values.

---

3: Set Destination

• SKApp submits a request to navigation/course/destination
• SK server processes request and sets navigation.course attribute values.

---

4: Steer to Destination (Autopilot)

• pre-requisite: 1: Set Active Route or 3: Set Destination operation has been performed
• pre-requisite: Calculate Nav Data
• SKApp reads list of available autopilot modes from steering.autopilot.availableModes`
• SKApp selects desired mode by PUT of one of the availableModes entries to steering.autopilot.mode
• SKApp enables Autopilot operation by PUTting enabled to steering.autopilot.state
• triggers: Send data to AutoPilot

---

SK Server / Nav Computer Actions:

Calculate Nav Data

Note: signalk-server plugin required.

• Calculate and place values in appropriate paths under navigation.courseGreatCircle and/or navigation.courseRhumline
• optionally: emit nmea2000, nmea0183

---

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:

• https://github.com/SignalK/signalk-autopilot