Skip to content

Extending autopilot related paths 2020

Jump to bottom Edit New page
AdrianP edited this page Apr 11, 2022 · 24 revisions

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:

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/calculations/calcMethod
  • navigation/course/calculations/crossTrackError
  • navigation/course/calculations/bearingTrackTrue
  • navigation/course/calculations/bearingTrackMagnetic
  • navigation/course/calculations/estimatedTimeOfArrival
  • navigation/course/calculations/distance
  • navigation/course/calculations/bearingTrue
  • navigation/course/calculations/bearingMagnetic
  • navigation/course/calculations/velocityMadeGood
  • navigation/course/calculations/timeToGo

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

Signal K Client App (via Course API):

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.

1: Set Active Route

  • User selects a route
  • User marks Route as Active
  • SKApp submits a request to course api (navigation/course/activeRoute)
  • SK server processes request and sets navigation.course path values
  • Course computer plugin populates navigation.course.calculations.

2: Set Next Point in route

  • SKApp submits a request to course api (navigation/course/activeRoute/nextPoint)
  • SK server processes request and sets navigation.course path values
  • Course computer plugin populates navigation.course.calculations.

3: Set Destination

  • SKApp submits a request to navigation/course/destination
  • SK server processes request and sets navigation.course path values
  • Course computer plugin populates navigation.course.calculations.

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

Autopilot API:

Note: Consideration should be given to implementation of an Autopilot API to provide a consistent way to perform common operations in a similar manner to the Course and Resources APIs.

Examples:

  • GET /steering/autopilot (retrieve autopilot status)

  • GET /steering/autopilot/modes (retrieve available autopilot modes)

  • PUT /steering/autopilot/mode { "value": "compass"}` (set autopilot mode to compass)

  • PUT /steering/autopilot/enable (set autopilot to active i.e. steer a course)

  • PUT /steering/autopilot/disable (stop autopilot from steering a course)

  • PUT /steering/autopilot/tack/port (perform a port tack)

  • PUT /steering/autopilot/tack/starboard (perform a starboard tack)

  • PUT /steering/autopilot/tack/port (perform a port tack)

  • PUT /steering/autopilot/tack/starboard (perform a starboard tack)

  • PUT /steering/autopilot/adjust { value: 10 } (increment heading / wind angle) value by 10)

SK Server / Nav Computer Actions:

Calculate Nav Data (signalk-server plugin required)

  • Calculate and place values in appropriate paths under: navigation.courseGreatCircle and/or navigation.courseRhumbline (v1 specification), navigation.course.calculations (v2 specification)
  • 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:

Device Operation:

Action Signal K aware Autopilot Plugin/Provider
1. SK Server startup Send status in steering/autopilot 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/calculations deltas and uses values to set course to steer. Receives course/nextPoint, course/calculations 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.
Add a custom footer
Add a custom sidebar
Clone this wiki locally