sailkick-boat 0.23.3 → 0.23.8

package/README.md

@@ -341,6 +341,62 @@ 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.
+
+Both are TRUE headings and on this boat they agree to 0.12°, so correctness does not
+separate them. **Resolution does:**
+
+| | rate | resolution |
+|---|---|---|
+| `navigation.headingTrue` (AIS transponder) | 1 Hz | whole degrees |
+| `navigation.headingMagnetic` (Precision-9) | 20 Hz | 0.006° |
+
+AIS transmits heading as an integer, so the transponder rounds before publishing. The
+compass is the same underlying sensor without that rounding, so using it costs nothing in
+accuracy and gains 20× the rate — a display that flows instead of stepping once a second.
+
+The published value is still used, as an **independent check**: if the two disagree by
+more than 10° something is broken and the log says so, naming both numbers. The displayed
+value does not change on the strength of that.
+
+The comparison runs **only when variation is on the bus** — without it the compass yields
+raw magnetic, which is wrong by the local declination (16° here), so there is no valid
+compass option at all and the boat's own `headingTrue` is used instead.
+
+> This is a deliberate divergence from the app, which makes `headingTrue` authoritative on
+> correctness grounds without weighing transmission rounding. Handed back upstream; if it
+> ever prefers the higher-resolution source when both are true, this can be dropped.
+
+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/index.js

@@ -45,7 +45,12 @@ const SYNC_TUNING = {
   retryMinMs: 1000,
   retryMaxMs: 60000
 }
-const PROXY_TUNING = { requestTimeoutMs: 20000, localPaths: ['/signalk'], telemetryPath: '/ws/telemetry' }
+// requestTimeoutMs is for CACHED fetches (tiles, assets) where 20s is generous.
+// relayTimeoutMs is for the transparent non-GET relay, which carries requests that are
+// legitimately slow: /api/isochrone is weather routing and the app itself allows 120s for
+// it (FETCH_TIMEOUT_MS in public/engine/wind-client.js). Applying the tile timeout to the
+// relay killed every route that took longer and returned 502.
+const PROXY_TUNING = { requestTimeoutMs: 20000, relayTimeoutMs: 180000, localPaths: ['/signalk'], telemetryPath: '/ws/telemetry' }
 const MANIFEST = { enabled: true, path: '/api/cache-manifest', pollIntervalSec: 300 }
 const SEED_TUNING = { coastlineMaxZoom: 8, seabedMaxZoom: 6, concurrency: 4 }
 const PREFETCH_TUNING = { concurrency: 4 }
@@ -286,6 +291,7 @@ module.exports = function (app) {
         localPaths: (p.localPaths && p.localPaths.length) ? p.localPaths : PROXY_TUNING.localPaths,
         telemetryPath: p.telemetryPath || PROXY_TUNING.telemetryPath,
         requestTimeoutMs: p.requestTimeoutMs || PROXY_TUNING.requestTimeoutMs,
+        relayTimeoutMs: p.relayTimeoutMs || PROXY_TUNING.relayTimeoutMs,
         openAccess: p.openAccess !== false, // single-tenant boat: the cloud login gate can't work over plain HTTP
         manifest: MANIFEST, // always on — freshness comes from the cloud announcing bakes
         seed: {

package/lib/proxy/index.js

@@ -88,6 +88,8 @@ function createProxy (app, options) {
       upstream: options.sailkickUrl.replace(/\/+$/, ''),
       storeDir: options.storeDir || path.join(dataDir, 'store'),
       timeoutMs: options.requestTimeoutMs || 20000,
+      // The relay carries slow work: /api/isochrone routing budgets 120s app-side.
+      relayTimeoutMs: options.relayTimeoutMs || 180000,
       localSignalk: (options.localSignalkUrl || 'http://127.0.0.1:3000').replace(/\/+$/, ''),
       localPaths: (options.localPaths && options.localPaths.length) ? options.localPaths : ['/signalk'],
       telemetryPath: options.telemetryPath || '/ws/telemetry',
@@ -339,8 +341,23 @@ function createProxy (app, options) {
     }
     let r
     try {
-      r = await request(target, { method: req.method, headers: fwd, body: chunks.length ? Buffer.concat(chunks) : undefined, timeoutMs: cfg.timeoutMs })
-    } catch (e) { res.statusCode = 502; res.end('upstream unreachable'); return }
+      r = await request(target, {
+        method: req.method,
+        headers: fwd,
+        body: chunks.length ? Buffer.concat(chunks) : undefined,
+        timeoutMs: cfg.relayTimeoutMs
+      })
+    } catch (e) {
+      // Say WHICH failure. A timeout on a long computation and an unreachable host need
+      // different fixes, and a bare 'upstream unreachable' claimed to know which it was.
+      const timedOut = e.code === 'ETIMEDOUT'
+      log(`relay ${req.method} ${req.url.split('?')[0]} failed — ${e.code || e.message}`)
+      res.statusCode = timedOut ? 504 : 502
+      res.end(timedOut
+        ? `upstream timed out after ${Math.round(cfg.relayTimeoutMs / 1000)}s`
+        : `upstream unreachable (${e.code || 'error'})`)
+      return
+    }
     res.statusCode = r.status
     r.headers.forEach((v, k) => {
       const kl = k.toLowerCase()

package/lib/telemetry/contract.js

@@ -24,7 +24,7 @@
 // sha256(app public/engine/signalk-map.js)[0..12] as ported in v0.18.6
 const { request } = require('../net') // owned connection pool + real error codes
 
-const PINNED_APP_HASH = '2015ae986cd8'
+const PINNED_APP_HASH = '3e42369c002b'
 
 function createContractCheck (app, options = {}) {
   const warn = (m) => (app.error ? app.error('[sailkick-boat:contract] ' + m) : console.error('[sailkick-boat:contract]', m))

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,86 @@ 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.
+// DELIBERATE DIVERGENCE FROM UPSTREAM, at the owner's request.
+//
+// resolveHeadingDeg() in the vendored mapper now returns navigation.headingTrue when it is
+// present (348c3d9, "true heading is authoritative"). That is right on CORRECTNESS — raw
+// magnetic would be wrong by the local variation — but on this boat both candidates are
+// true headings that agree to 0.12°, so correctness is not what separates them. Resolution
+// is, and by a wide margin:
+//
+//   navigation.headingTrue      NMEA.31 NAIS 500      1 Hz,  quantised to 1°
+//   navigation.headingMagnetic  NMEA.23 Precision-9  20 Hz,  0.006° steps
+//
+// The AIS transponder rounds heading to a whole degree before transmitting — normal for
+// AIS, but it makes the display step once a second. The Precision-9 is the same underlying
+// compass the transponder derives from, so taking it directly costs nothing in accuracy
+// and gains 20x the rate.
+//
+// The published value is still used, as an INDEPENDENT check: if the two disagree
+// materially something is broken, and the log says so. The displayed value never changes
+// on the strength of that, because falling back to a 1 Hz 1° source would trade a
+// suspected problem for a certainly worse reading.
+//
+// Handed upstream: the app's choice is about correctness and does not weigh transmission
+// rounding. If it ever prefers the higher-resolution source when both are true, this whole
+// block can go.
+const HEADING_DISAGREE_DEG = 10
+
+// Cross-delta precedence for fields fed by several paths.
+//
+// Upstream now ranks these inside signalkValuesToPatch (b519a9f) — but `courseRank` and
+// `depthRank` are declared per CALL, so that ranking only orders values within ONE delta.
+// On this boat the competing publishers are different sources sending SEPARATE deltas
+// (courseGreatCircle from NMEA.24, course.calcValues from course-provider), so last one
+// in still wins and the readout flip-flops between the two solves. Measured: 2049.48 nm
+// against 2050.86 nm, several times a second.
+//
+// This layer remembers which path last spoke and for how long, so the precedence survives
+// across deltas. It is complementary to the upstream fix, not a duplicate — delete it only
+// if the ranking upstream ever becomes stateful.
+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 +134,76 @@ 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 published = Number.isFinite(st.hdgTrueDeg) ? st.hdgTrueDeg : undefined
+    // Compass-derived TRUE heading. Only valid when variation is known — without it this
+    // would be RAW MAGNETIC, wrong by the local declination (16° here), which is exactly
+    // what upstream's 348c3d9 set out to eliminate. So no variation, no compass option.
+    const compass = (Number.isFinite(st.hdgMagDeg) && Number.isFinite(st.magVarDeg))
+      ? wrap360d(st.hdgMagDeg + st.magVarDeg)
+      : undefined
+
+    // Neither of ours applies — let the vendored mapper decide (it handles the remaining
+    // cases, including magnetic-without-variation, however upstream judges best).
+    if (compass === undefined) return published !== undefined ? published : resolveHeadingDeg(st)
+
+    if (published !== undefined) {
+      const gap = Math.abs(wrap180(published - compass))
+      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 ` +
+            `(${compass.toFixed(1)}°) by ${gap.toFixed(1)}° — displaying the compass. Check which device ` +
+            'publishes headingTrue, and the variation in use.')
+        }
+      } else if (headingWarned) {
+        headingWarned = false
+        log('navigation.headingTrue agrees with the compass again')
+      }
+    }
+    return compass
+  }
+
   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 +212,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/lib/telemetry/signalk-map.js

@@ -1,136 +1,195 @@
-'use strict'
+// VENDORED from sailkick/public/engine/signalk-map.js @ dc57057  sha256:3e42369c002b7cb7
+// Do not edit here — fix upstream and re-vendor. One SignalK -> BoatState mapping, or
+// the boat and the app quietly disagree (it has drifted twice; both times silently).
+//
+// Converted ESM -> CommonJS ONLY. No logic changed.
+//
+// Re-vendored after b519a9f (course + depth precedence) and 348c3d9 (heading true
+// authoritative) — both of which came from findings handed over from this repo.
 
-// SignalK -> BoatState mapping. Ported VERBATIM from the sailkick app
-// (public/engine/signalk-map.js) so the plugin's /ws/telemetry is identical to
-// the server's SignalKSource. SignalK emits SI units (m/s, radians); BoatState
-// uses knots + degrees. Keep in sync with the app copy.
+// SignalK → BoatState mapping — pure, dependency-free, so it's shared by both
+// the client provider (public/ui/boat-panel.js, browser WebSocket) and the
+// server-side SignalKSource (server/telemetry/signalk.js, ws). No imports.
+// SignalK emits SI units (m/s, radians); BoatState uses knots + degrees.
 
-const MS_TO_KT = 1.94384
-const RAD2DEG = 180 / Math.PI
-const wrap360 = (d) => ((d % 360) + 360) % 360
-const wrap180 = (d) => { const w = wrap360(d); return w > 180 ? w - 360 : w }
+const MS_TO_KT = 1.94384;
+const RAD2DEG = 180 / Math.PI;
+const wrap360 = (d) => ((d % 360) + 360) % 360;
+const wrap180 = (d) => { const w = wrap360(d); return w > 180 ? w - 360 : w; };
 
 // Active-waypoint course data. SignalK publishes it under three prefixes
 // depending on server version/config (v1 courseGreatCircle/courseRhumbline,
-// v2 course.calcValues) — all carry the same SI values (rad, m, m/s, s).
-const COURSE_RE = /^navigation\.(?:course(?:GreatCircle|Rhumbline)\.nextPoint|course\.calcValues)\.(bearingTrue|distance|velocityMadeGood|timeToGo)$/
+// v2 course.calcValues) — all carry the same SI values (rad, m, m/s, s). A boat
+// commonly publishes SEVERAL of them in the same delta; great-circle is PRIMARY
+// and the others only fill a field it left empty (mirrors the primary/fallback
+// ordering in server/history/influx-provider.js). Group 1 = source prefix,
+// group 2 = value suffix.
+const COURSE_RE = /^navigation\.(courseGreatCircle\.nextPoint|courseRhumbline\.nextPoint|course\.calcValues)\.(bearingTrue|distance|velocityMadeGood|timeToGo)$/;
+const COURSE_FIELD = { bearingTrue: 'wptBrgDeg', distance: 'wptDistNm', velocityMadeGood: 'wptVmgKt', timeToGo: 'wptTtgSec' };
 
-function signalkValuesToPatch (values) {
-  const patch = {}
-  if (!Array.isArray(values)) return patch
+// A SignalK delta `values` array → a partial BoatState patch. Skips
+// null / missing / non-finite values (SignalK sends null when a sensor is absent).
+function signalkValuesToPatch(values) {
+  const patch = {};
+  if (!Array.isArray(values)) return patch;
+  const courseRank = {};   // wpt field → rank of the source that set it (great-circle 2, fallback 1)
+  let depthRank = 0;       // rank of the depth source that set patch.depthM (belowSurface 2, transducer 1)
   for (const v of values) {
-    if (!v || !v.path) continue
+    if (!v || !v.path) continue;
     // Course paths first: unlike sensors, a null here MEANS something — the
     // destination was cleared — so propagate it instead of skipping, or the
     // ribbon would show stale waypoint numbers forever.
-    const course = v.path.match(COURSE_RE)
+    const course = v.path.match(COURSE_RE);
     if (course) {
-      const suffix = course[1]
-      if (suffix === 'bearingTrue') patch.wptBrgDeg = Number.isFinite(v.value) ? wrap360(v.value * RAD2DEG) : null
-      else if (suffix === 'distance') patch.wptDistNm = Number.isFinite(v.value) ? Math.max(0, v.value / 1852) : null
-      else if (suffix === 'velocityMadeGood') patch.wptVmgKt = Number.isFinite(v.value) ? v.value * MS_TO_KT : null
-      else patch.wptTtgSec = Number.isFinite(v.value) && v.value >= 0 ? v.value : null
-      continue
+      const [, src, suffix] = course;
+      // Great-circle wins; rhumbline / calcValues only fill a field it left empty
+      // this delta. Without this, a boat publishing several course prefixes would
+      // last-writer-win and flip-flop the waypoint readouts between the two solves.
+      const rank = src === 'courseGreatCircle.nextPoint' ? 2 : 1;
+      if ((courseRank[COURSE_FIELD[suffix]] || 0) > rank) continue;   // a stronger source already set it
+      courseRank[COURSE_FIELD[suffix]] = rank;
+      if (suffix === 'bearingTrue') patch.wptBrgDeg = Number.isFinite(v.value) ? wrap360(v.value * RAD2DEG) : null;
+      else if (suffix === 'distance') patch.wptDistNm = Number.isFinite(v.value) ? Math.max(0, v.value / 1852) : null;
+      else if (suffix === 'velocityMadeGood') patch.wptVmgKt = Number.isFinite(v.value) ? v.value * MS_TO_KT : null;
+      else patch.wptTtgSec = Number.isFinite(v.value) && v.value >= 0 ? v.value : null;
+      continue;
     }
-    if (v.value == null) continue
+    if (v.value == null) continue;
     switch (v.path) {
       case 'navigation.position': {
-        const { latitude, longitude } = v.value || {}
+        const { latitude, longitude } = v.value || {};
         if (Number.isFinite(latitude) && Number.isFinite(longitude)) {
-          patch.lat = latitude
-          patch.lon = longitude
+          patch.lat = latitude;
+          patch.lon = longitude;
         }
-        break
+        break;
       }
       case 'navigation.speedOverGround':
-        if (Number.isFinite(v.value)) patch.sogKt = Math.max(0, v.value * MS_TO_KT)
-        break
+        if (Number.isFinite(v.value)) patch.sogKt = Math.max(0, v.value * MS_TO_KT);
+        break;
       case 'navigation.speedThroughWater':
-        if (Number.isFinite(v.value)) patch.stwKt = Math.max(0, v.value * MS_TO_KT)
-        break
+        if (Number.isFinite(v.value)) patch.stwKt = Math.max(0, v.value * MS_TO_KT);
+        break;
       case 'navigation.courseOverGroundTrue':
-        if (Number.isFinite(v.value)) patch.cogDeg = wrap360(v.value * RAD2DEG)
-        break
+        if (Number.isFinite(v.value)) patch.cogDeg = wrap360(v.value * RAD2DEG);
+        break;
+      // Heading: emit the RAW components (deg). Resolution happens in
+      // resolveHeadingDeg() against the ACCUMULATED state, so a heading-only
+      // message still uses the last-known variation instead of flip-flopping
+      // between true-heading and raw-magnetic.
       case 'navigation.headingTrue':
-        if (Number.isFinite(v.value)) patch.hdgTrueDeg = wrap360(v.value * RAD2DEG)
-        break
+        if (Number.isFinite(v.value)) patch.hdgTrueDeg = wrap360(v.value * RAD2DEG);
+        break;
       case 'navigation.headingMagnetic':
-        if (Number.isFinite(v.value)) patch.hdgMagDeg = v.value * RAD2DEG
-        break
+        if (Number.isFinite(v.value)) patch.hdgMagDeg = v.value * RAD2DEG;   // wrapped after variation
+        break;
       case 'navigation.magneticVariation':
-        if (Number.isFinite(v.value) && v.value !== 0) patch.magVarDeg = v.value * RAD2DEG
-        break
+        // Skip a 0 sentinel (a common "no-data" value): applying 0 is a no-op
+        // anyway, and retaining the last real variation avoids a heading
+        // flip-flop when the source intermittently reports 0.
+        if (Number.isFinite(v.value) && v.value !== 0) patch.magVarDeg = v.value * RAD2DEG;  // east positive
+        break;
       case 'environment.wind.speedApparent':
-        if (Number.isFinite(v.value)) patch.awsKt = Math.max(0, v.value * MS_TO_KT)
-        break
+        if (Number.isFinite(v.value)) patch.awsKt = Math.max(0, v.value * MS_TO_KT);
+        break;
       case 'environment.wind.angleApparent':
-        if (Number.isFinite(v.value)) patch.awaDeg = wrap180(v.value * RAD2DEG)
-        break
+        if (Number.isFinite(v.value)) patch.awaDeg = wrap180(v.value * RAD2DEG);
+        break;
       case 'environment.wind.speedTrue':
-        if (Number.isFinite(v.value)) patch.twsKt = Math.max(0, v.value * MS_TO_KT)
-        break
-      case 'environment.wind.directionTrue': // absolute compass direction (not off-bow)
-        if (Number.isFinite(v.value)) patch.twdDeg = wrap360(v.value * RAD2DEG)
-        break
-      case 'environment.wind.angleTrueWater': // true wind ANGLE off the bow, port negative
-        if (Number.isFinite(v.value)) patch.twaDeg = wrap180(v.value * RAD2DEG)
-        break
-      case 'performance.velocityMadeGood': // signed: negative = losing ground to windward
-        if (Number.isFinite(v.value)) patch.vmgKt = v.value * MS_TO_KT
-        break
-      case 'environment.depth.belowSurface':
-      case 'environment.depth.belowTransducer':
-        if (Number.isFinite(v.value)) patch.depthM = v.value
-        break
+        if (Number.isFinite(v.value)) patch.twsKt = Math.max(0, v.value * MS_TO_KT);
+        break;
+      case 'environment.wind.directionTrue':   // absolute compass direction (not off-bow)
+        if (Number.isFinite(v.value)) patch.twdDeg = wrap360(v.value * RAD2DEG);
+        break;
+      case 'environment.wind.angleTrueWater':  // true wind ANGLE off the bow, port negative
+        if (Number.isFinite(v.value)) patch.twaDeg = wrap180(v.value * RAD2DEG);
+        break;
+      case 'performance.velocityMadeGood':     // signed: negative = losing ground to windward
+        if (Number.isFinite(v.value)) patch.vmgKt = v.value * MS_TO_KT;
+        break;
+      case 'environment.depth.belowSurface':      // primary: actual water depth (transducer offset applied)
+      case 'environment.depth.belowTransducer': { // fallback: raw sounder reading (offset not applied)
+        // belowSurface is authoritative; the transducer reading only fills in when
+        // belowSurface is absent. Without the rank guard, a boat publishing both
+        // would last-writer-win and jump by the transducer offset.
+        const rank = v.path === 'environment.depth.belowSurface' ? 2 : 1;
+        if (rank >= depthRank && Number.isFinite(v.value)) { patch.depthM = v.value; depthRank = rank; }
+        break;
+      }
       // (active-waypoint course paths are handled above via COURSE_RE — all three
       //  publish prefixes, with nulls propagated so a cleared goto clears the values)
-      case 'environment.water.temperature': // sea temperature, K → °C
-        if (Number.isFinite(v.value)) patch.seaTempC = v.value - 273.15
-        break
-      case 'environment.outside.temperature': // air temperature, K → °C
-        if (Number.isFinite(v.value)) patch.airTempC = v.value - 273.15
-        break
-      case 'propulsion.port.revolutions': // engine speed, Hz → rpm
-        if (Number.isFinite(v.value)) patch.rpmPort = Math.max(0, v.value * 60)
-        break
+      case 'environment.water.temperature':       // sea temperature, K → °C
+        if (Number.isFinite(v.value)) patch.seaTempC = v.value - 273.15;
+        break;
+      case 'environment.outside.temperature':     // air temperature, K → °C
+        if (Number.isFinite(v.value)) patch.airTempC = v.value - 273.15;
+        break;
+      case 'propulsion.port.revolutions':         // engine speed, Hz → rpm
+        if (Number.isFinite(v.value)) patch.rpmPort = Math.max(0, v.value * 60);
+        break;
       case 'propulsion.starboard.revolutions':
-        if (Number.isFinite(v.value)) patch.rpmStbd = Math.max(0, v.value * 60)
-        break
+        if (Number.isFinite(v.value)) patch.rpmStbd = Math.max(0, v.value * 60);
+        break;
       case 'steering.rudderAngle':
-        if (Number.isFinite(v.value)) patch.rudderDeg = v.value * RAD2DEG
-        break
+        if (Number.isFinite(v.value)) patch.rudderDeg = v.value * RAD2DEG;
+        break;
       case 'navigation.rateOfTurn':
-        if (Number.isFinite(v.value)) patch.rotDegMin = v.value * RAD2DEG * 60
-        break
-      case 'navigation.attitude': // object { roll, pitch, yaw } (rad)
-        if (v.value && Number.isFinite(v.value.roll)) patch.heelDeg = v.value.roll * RAD2DEG
-        break
+        if (Number.isFinite(v.value)) patch.rotDegMin = v.value * RAD2DEG * 60;
+        break;
+      case 'navigation.attitude':                 // object { roll, pitch, yaw } (rad)
+        if (Number.isFinite(v.value?.roll)) patch.heelDeg = v.value.roll * RAD2DEG;
+        break;
       case 'steering.autopilot.state':
-        if (typeof v.value === 'string') patch.apState = v.value
-        break
+        if (typeof v.value === 'string') patch.apState = v.value;
+        break;
       case 'steering.autopilot.target.headingTrue':
-        if (Number.isFinite(v.value)) patch.apTargetDeg = wrap360(v.value * RAD2DEG)
-        break
+        if (Number.isFinite(v.value)) patch.apTargetDeg = wrap360(v.value * RAD2DEG);
+        break;
       case 'steering.autopilot.target.windAngleApparent':
-        if (Number.isFinite(v.value)) patch.apTargetAwa = wrap180(v.value * RAD2DEG)
-        break
-      case 'navigation.datetime':
-        if (typeof v.value === 'string') patch.gpsTime = v.value
-        break
+        if (Number.isFinite(v.value)) patch.apTargetAwa = wrap180(v.value * RAD2DEG);
+        break;
+      case 'navigation.datetime':                 // GNSS UTC time (from the satellites)
+        if (typeof v.value === 'string') patch.gpsTime = v.value;
+        break;
       default:
-        break
+        break; // ignore everything else
     }
   }
-  return patch
+  return patch;
 }
 
-function resolveHeadingDeg (state) {
-  if (!state) return undefined
+// Resolve the boat's true heading (deg) from accumulated components: prefer
+// navigation.headingTrue; else navigation.headingMagnetic + the last-known
+// magneticVariation. Because the raw components live in the accumulated state
+// (not resolved per-message), a message carrying only headingMagnetic still
+// gets the retained variation applied — no jumping. Returns undefined if no
+// heading is known yet.
+function resolveHeadingDeg(state) {
+  if (!state) return undefined;
+  // TRUE heading is authoritative. Raw magnetic heading (no variation applied) is
+  // dangerously wrong for sailing — off by the local declination, tens of degrees
+  // in places — so navigation.headingTrue wins. Only when it is absent do we DERIVE
+  // true from the magnetic compass + last-known variation; that still yields TRUE
+  // (never raw magnetic), so the fallback is safe, not a magnetic readout.
+  // (This boat once published a frozen headingTrue stuck at 151° while truly ~293°,
+  // which is why magnetic was temporarily preferred; verified 2026-08-20 that its
+  // NMEA.31 headingTrue is live at ~1 Hz, tracks the full 0–359° span, and agrees
+  // with magnetic+variation to ~1° — so true is primary again.)
+  if (Number.isFinite(state.hdgTrueDeg)) return state.hdgTrueDeg;
   if (Number.isFinite(state.hdgMagDeg)) {
-    return wrap360(state.hdgMagDeg + (Number.isFinite(state.magVarDeg) ? state.magVarDeg : 0))
+    return wrap360(state.hdgMagDeg + (Number.isFinite(state.magVarDeg) ? state.magVarDeg : 0));
   }
-  if (Number.isFinite(state.hdgTrueDeg)) return state.hdgTrueDeg
-  return undefined
+  return undefined;
+}
+
+// Build the delta-stream URL from a base host/URL. Accepts a bare base
+// (`ws://host:3000`) and appends the self stream path; passes a full
+// `…/signalk/…` URL through untouched. Adds `&token=` only if a token is set.
+function streamUrl(base, token) {
+  let url = String(base || '').trim().replace(/\/+$/, '');
+  if (!/\/signalk\//.test(url)) url += '/signalk/v1/stream?subscribe=self';
+  if (token) url += (url.includes('?') ? '&' : '?') + 'token=' + encodeURIComponent(token);
+  return url;
 }
 
 module.exports = { signalkValuesToPatch, resolveHeadingDeg, MS_TO_KT }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sailkick-boat",
-  "version": "0.23.3",
+  "version": "0.23.8",
   "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": {