sailkick-boat 0.23.7 → 0.23.8

package/README.md

@@ -369,19 +369,29 @@ Two ways to know true heading — the boat publishes `navigation.headingTrue`, o
 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.
+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

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

@@ -61,26 +61,44 @@ function encodeTextFrame (str) {
 // 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.
+// DELIBERATE DIVERGENCE FROM UPSTREAM, at the owner's request.
 //
-// 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°.
+// 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:
 //
-// 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.
+//   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
 
-// Each group is one BoatState field fed by several paths, most-preferred first.
+// 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.',
@@ -146,29 +164,37 @@ function createTelemetry (app, options = {}) {
     })
   }
 
-  // See HEADING_DISAGREE_DEG. Returns true heading in degrees, or undefined.
+  // 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.')
+    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 derived
     }
-    if (headingWarned) { headingWarned = false; log('navigation.headingTrue agrees with the compass again — using it') }
-    return published
+    return compass
   }
 
   function onDelta (delta) {

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.7",
+  "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": {