sailkick-boat 0.23.3 → 0.23.7

package/README.md

@@ -341,6 +341,52 @@ at all. The raw channels are always recorded regardless, so the cloud can recomp
 history if the maths ever changes: the recorded channel is a materialisation, not the only
 truth.
 
+## Two paths, one reading
+
+Source priorities solve *several devices on one path*. There is a second, separate case:
+**several paths that mean the same thing**. Signal K publishes active-waypoint course data
+under three prefixes — `navigation.courseGreatCircle.nextPoint.*`,
+`navigation.courseRhumbline.nextPoint.*` and `navigation.course.calcValues.*` — and the
+app maps all three onto the same readouts. A boat publishing more than one gets whichever
+delta arrived last, so the waypoint distance alternates: measured on this boat, 2049.48 nm
+from great circle against 2050.86 nm from the course provider, several times a second.
+
+`sourcePriorities` cannot fix that — it arbitrates sources on ONE path, and these are
+different paths, each legitimately sourced. The plugin therefore applies the precedence
+the app already documents on its history side (great circle primary, the other two
+`fallback: true`): a lower-priority prefix is ignored while a better one is publishing,
+and takes over if that one goes quiet for 10 s.
+
+An audit of the mapper found exactly one other case: **depth**, fed by both
+`environment.depth.belowSurface` and `belowTransducer`. On a boat publishing both they
+differ by the transducer offset (0.3 m here), so the reading would oscillate in shallow
+water where the sounder streams. Same rule, with `belowSurface` preferred — the honest
+"how much water is under me" figure, and what the mapper itself calls preferred.
+
+## Heading: the boat's own true heading
+
+Two ways to know true heading — the boat publishes `navigation.headingTrue`, or it is
+derived from `headingMagnetic + magneticVariation`. The plugin uses the **published**
+value.
+
+The vendored mapper prefers the derivation, citing a heading frozen at 151° while the
+compass read true ~293° — but that came from another vessel's AIS data, not from a boat's
+own instruments, so it is weak grounds for distrusting your own.
+
+A cross-check is still worth having against a genuinely stuck publisher, and it runs
+**only when variation is on the bus**, comparing two *true* headings. That condition
+matters: without variation the derivation is raw magnetic, so comparing against it would
+just measure the variation — 16° on this boat, over 20° in places — and reject a perfectly
+good `headingTrue`, reporting magnetic as true. The check would have caused the very error
+it exists to prevent. When variation is absent the boat is simply taken at its word.
+
+With both available a healthy boat sits near zero (0.5° here); a gap over 10° falls back
+to the compass and says so once, and recovers automatically.
+
+This also lines the boat up with the cloud's history provider, which takes `headingTrue`
+first. (Its fallback converts `headingMagnetic` **without** adding variation, so a boat
+publishing only magnetic gets raw magnetic in Trends — an upstream bug, flagged.)
+
 ## Several devices publishing the same value
 
 A real N2K network usually has more than one device announcing a given path, and they do

package/lib/telemetry/index.js

@@ -30,6 +30,8 @@ const { signalkValuesToPatch, resolveHeadingDeg } = require('./signalk-map')
 
 const WS_GUID = '258EAFA5-E914-47DA-95CA-C5AB0DC85B11'
 const SUBPROTOCOL = 'sailkick.telemetry.v1'
+const wrap360d = (d) => ((d % 360) + 360) % 360
+const wrap180 = (d) => { const w = wrap360d(d); return w > 180 ? w - 360 : w }
 const SEED = { sogKt: 0, cogDeg: 0, headingDeg: 0, awsKt: null, awaDeg: null }
 
 function encodeTextFrame (str) {
@@ -41,9 +43,68 @@ function encodeTextFrame (str) {
   return Buffer.concat([header, payload])
 }
 
+// Signal K publishes active-waypoint course data under THREE prefixes, and
+// signalk-map.js maps all of them onto the same BoatState fields (wptDistNm and friends)
+// — see COURSE_RE there. On a boat that publishes more than one, whichever delta arrives
+// last wins and the readout flip-flops: measured here, courseGreatCircle said 2049.48 nm
+// while course.calcValues said 2050.86 nm, alternating several times a second.
+//
+// Signal K's own sourcePriorities cannot fix this. It arbitrates between SOURCES on ONE
+// path; here the competing values are on DIFFERENT paths, each legitimately sourced.
+//
+// The app already states the intended order on its history side: great circle is primary,
+// the other two are `fallback: true` (server/history/influx-provider.js). Its LIVE mapper
+// simply never implemented that, which does not show up in the cloud because that
+// deployment reads history rather than live Signal K. So this applies the app's own
+// documented precedence to the live stream.
+//
+// Deliberately NOT patched into lib/telemetry/signalk-map.js: that file is vendored
+// verbatim from the app and must stay byte-comparable. Handed upstream so the rule can
+// move into COURSE_RE and this can be deleted.
+// The boat's PUBLISHED navigation.headingTrue is preferred over deriving true heading
+// from magnetic + variation.
+//
+// The vendored mapper's resolveHeadingDeg() does the opposite. The case it cites — a
+// heading frozen at 151° while the compass read true ~293° — came from ANOTHER vessel's
+// AIS data, not from self telemetry, so it is weak evidence for distrusting a boat's own
+// instruments. This boat's headingTrue is healthy and agrees to 0.52°.
+//
+// A cross-check is still worth having against a genuinely broken publisher, but ONLY when
+// there is something valid to check against. resolveHeadingDeg() returns RAW MAGNETIC
+// when no variation is published, and comparing a true heading against raw magnetic just
+// measures the variation — 16° here, more elsewhere. A guard built on that would reject a
+// perfectly good headingTrue on every boat that does not publish variation, and report
+// magnetic as if it were true: a 16° error introduced by the safety check itself. So the
+// comparison runs only when variation is on the bus, and both sides are true headings.
+// Both sides are TRUE headings, so a healthy boat sits near zero (0.52° here). This is
+// sized to catch a stuck publisher, not to police variation error.
+const HEADING_DISAGREE_DEG = 10
+
+// Each group is one BoatState field fed by several paths, most-preferred first.
+const PRECEDENCE_GROUPS = [
+  // Active waypoint: wptBrgDeg / wptDistNm / wptVmgKt / wptTtgSec (COURSE_RE).
+  ['navigation.courseGreatCircle.nextPoint.',
+    'navigation.courseRhumbline.nextPoint.',
+    'navigation.course.calcValues.'],
+  // depthM. Both are published by the same transducer here, 0.3 m apart — that gap IS
+  // environment.depth.surfaceToTransducer. belowSurface is the honest "how much water is
+  // under me" number and is what signalk-map.js calls preferred, so it wins.
+  //
+  // NOTE for the re-vendor: the app's two implementations disagree here. Its live mapper
+  // comments belowSurface "preferred" and belowTransducer "fallback", while its history
+  // provider (influx-provider.js MAP) has belowTransducer primary and belowSurface
+  // `fallback: true` — the opposite. So live and Trends can differ by the transducer
+  // offset for the same instant. Flagged upstream; this follows the live mapper.
+  ['environment.depth.belowSurface', 'environment.depth.belowTransducer']
+]
+// How long a higher-priority path stays "live" after its last value. Long enough to
+// cover a slow publisher, short enough that a genuinely stopped source hands over.
+const PRECEDENCE_STALE_MS = 10000
+
 function createTelemetry (app, options = {}) {
   const log = (m) => (app.debug ? app.debug('[telemetry] ' + m) : console.log('[sailkick-boat:telemetry]', m))
   let state = null
+  const pathSeen = new Map() // 'group:index' -> last ms, for the precedence above
   const clients = new Set()
   const unsubscribes = []
 
@@ -55,13 +116,68 @@ function createTelemetry (app, options = {}) {
     for (const s of clients) { try { s.write(frame) } catch { clients.delete(s) } }
   }
 
+  // Drop a value whose path is covered by a higher-priority sibling that is currently
+  // publishing. Anything outside PRECEDENCE_GROUPS passes through untouched.
+  function applyPrecedence (values) {
+    const hit = (path) => {
+      for (let g = 0; g < PRECEDENCE_GROUPS.length; g++) {
+        const i = PRECEDENCE_GROUPS[g].findIndex((p) => path === p || path.startsWith(p))
+        if (i >= 0) return { g, i }
+      }
+      return null
+    }
+    let touched = false
+    for (const v of values) {
+      if (!v || !v.path) continue
+      const h = hit(v.path)
+      if (h) { pathSeen.set(`${h.g}:${h.i}`, Date.now()); touched = true }
+    }
+    if (!touched) return values
+    const now = Date.now()
+    return values.filter((v) => {
+      if (!v || !v.path) return true
+      const h = hit(v.path)
+      if (!h || h.i === 0) return true // not grouped, or already the top choice
+      for (let j = 0; j < h.i; j++) {
+        const seen = pathSeen.get(`${h.g}:${j}`)
+        if (seen && now - seen < PRECEDENCE_STALE_MS) return false
+      }
+      return true
+    })
+  }
+
+  // See HEADING_DISAGREE_DEG. Returns true heading in degrees, or undefined.
+  let headingWarned = false
+  function resolveHeading (st) {
+    const derived = resolveHeadingDeg(st) // magnetic + variation, per the vendored mapper
+    const published = st.hdgTrueDeg
+    if (!Number.isFinite(published)) return derived
+    if (!Number.isFinite(derived)) return published
+    // Without variation, `derived` is raw MAGNETIC and the comparison would just measure
+    // the variation. Nothing to corroborate against — take the boat at its word.
+    if (!Number.isFinite(st.magVarDeg)) return published
+    const gap = Math.abs(wrap180(published - derived))
+    if (gap > HEADING_DISAGREE_DEG) {
+      if (!headingWarned) {
+        headingWarned = true
+        const warn = app.error ? (m) => app.error('[sailkick-boat:telemetry] ' + m) : log
+        warn(`navigation.headingTrue (${published.toFixed(1)}°) disagrees with the compass + variation ` +
+          `(${derived.toFixed(1)}°) by ${gap.toFixed(1)}° — using the compass. A headingTrue that is ` +
+          'stale or static is a known failure mode; check which device publishes it.')
+      }
+      return derived
+    }
+    if (headingWarned) { headingWarned = false; log('navigation.headingTrue agrees with the compass again — using it') }
+    return published
+  }
+
   function onDelta (delta) {
     if (!delta || !Array.isArray(delta.updates)) return
     const patch = {}
     let ts = null
     for (const u of delta.updates) {
       if (!u || !Array.isArray(u.values)) continue
-      Object.assign(patch, signalkValuesToPatch(u.values))
+      Object.assign(patch, signalkValuesToPatch(applyPrecedence(u.values)))
       if (u.timestamp) ts = u.timestamp
     }
     if (Object.keys(patch).length === 0) return
@@ -70,7 +186,7 @@ function createTelemetry (app, options = {}) {
       state = { ...SEED }
     }
     state = { ...state, ...patch, updatedAt: ts || new Date().toISOString() }
-    const hd = resolveHeadingDeg(state)
+    const hd = resolveHeading(state)
     state.headingDeg = Number.isFinite(hd) ? hd : (state.headingDeg || state.cogDeg || 0)
     broadcast({ type: 'telemetry/update', state })
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sailkick-boat",
-  "version": "0.23.3",
+  "version": "0.23.7",
   "description": "Run the sailkick app on board with no internet: charts, weather, climatology, trends and AIS all served from the boat itself. With a sailkick account it also syncs your metrics to the cloud in real time. Alpha, invite-only \u2014 info@sailkick.io",
   "main": "index.js",
   "scripts": {