sailkick-boat 0.22.2 → 0.23.0

package/README.md

@@ -292,6 +292,78 @@ Items are matched by **name**, since ids are assigned independently on each side
 polar you refined in the web app appears as *cloud only* — or *differs* if the boat has an
 older one of the same name — and one click brings it aboard.
 
+## Live polar performance, computed on board
+
+The plugin computes **percentage of polar target** (boat speed ÷ what the polar says you
+should be doing) and emits it as two ordinary SignalK deltas:
+
+```
+performance.polarSpeed        target boat speed, m/s
+performance.polarSpeedRatio   achieved / target, 0–1
+```
+
+Because they are deltas, everything downstream gets them for nothing: telemetry sync
+forwards them to the cloud through the same store-and-forward spool as every raw channel
+— so an offline passage replays them **gapless** rather than leaving a hole — NMEA
+displays and other plugins can read them natively, and the local history ring records the
+rounded percentage as a `perf` channel for offline Trends.
+
+The maths is **vendored verbatim** from the app (`shared/engine/perf-live.js` and the pure
+`Polar` evaluator), each file carrying its upstream commit and sha256. There is one
+definition of "the %" — the boat and the screens must not quietly disagree — and
+`test/perf.test.js` replays the upstream test suite against the vendored copy to prove it.
+Fix the maths upstream and re-vendor; never edit the copy.
+
+**Nothing is emitted unless the guards pass.** In irons (inside the no-go angle), under
+2 kt of wind, or against a near-zero target, the channel simply stops. A gap is the honest
+representation; a zero would be a lie that drags down every average drawn over it.
+
+**No paddlewheel?** The percentage falls back to SOG, which the screens do too — but SOG
+is polluted by current, so the status line says `(from SOG — current-polluted)` rather
+than presenting it as a through-water figure.
+
+**Polar staleness.** The percentage is computed against whichever polar the boat has. If
+you refine your polar ashore, the boat keeps using its own copy until you bring it across
+on the **Sync polars & routes** page — this is a manual copy, not background sync. And a
+catalogue polar has to have been fetched at least once while online before it can be used
+at all. The raw channels are always recorded regardless, so the cloud can recompute the
+history if the maths ever changes: the recorded channel is a materialisation, not the only
+truth.
+
+## Several devices publishing the same value
+
+A real N2K network usually has more than one device announcing a given path, and they do
+not always agree. On the boat this was developed against: three sources for
+`navigation.speedThroughWater`, one of them reporting a constant **0**; and two compasses
+on `navigation.headingMagnetic` **7.5° apart**. Whichever delta arrived last won, so speed
+dropped to zero intermittently and heading — which the app derives from magnetic heading
+plus variation, and which feeds the true-wind calculation — wandered.
+
+**The plugin does not arbitrate this, and deliberately so.** Signal K already resolves it
+from `sourcePriorities` in `settings.json`, applied in its delta pipeline *before* any
+consumer sees the value, so one setting fixes the app, KIP, the instruments, the local
+history ring and the telemetry going to the cloud all at once. Set it under
+**Server → Settings → Source Priorities**:
+
+```json
+"navigation.speedThroughWater": [{ "sourceRef": "NMEA.27", "timeout": "" }],
+"navigation.headingMagnetic":   [{ "sourceRef": "NMEA.23", "timeout": "" }]
+```
+
+To find the culprit, compare sources on one path:
+
+```bash
+curl -s http://<boat>:3000/signalk/v1/api/vessels/self/navigation/speedThroughWater
+```
+
+`values` lists every source and what each is reporting; `$source` is whichever last won.
+A path where they disagree is worth pinning. Where a cross-check exists it settles which
+is right — magnetic heading plus variation should equal the reported true heading, and on
+that boat one compass matched to 0.25° while the other was 7.5° out.
+
+Note that a de-prioritised source still appears **once** when a client subscribes: Signal K
+replays current values on subscription. That is a single stale sample, not a live feed.
+
 ## Local history (offline Trends + track)
 **One source: a live ring**, sampled from the same BoatState that feeds `/ws/telemetry`
 — no database, works on a Victron GX with nothing else installed. `historyAvailable` is

package/index.js

@@ -10,6 +10,7 @@ const { createBackfill } = require('./lib/backfill')
 const { createAis } = require('./lib/ais')
 const { createAisTargets } = require('./lib/ais/targets')
 const { createProfile } = require('./lib/profile')
+const { createPerf } = require('./lib/perf')
 const { createCloud } = require('./lib/cloud')
 const { resolveAccountConfig } = require('./lib/account')
 
@@ -100,6 +101,7 @@ module.exports = function (app) {
   let aisTargets = null
   let profile = null
   let cloud = null
+  let perf = null
   let proxyPort = null // what the launcher page needs to build its links
   let pairedSlug = null
   let statusTimer = null
@@ -356,12 +358,31 @@ module.exports = function (app) {
           telemetry = null
         }
       }
+      // Live polar performance, computed here so it becomes a RECORDED channel: it rides
+      // the same spool as everything else, so an offline passage replays it gapless.
+      // Needs telemetry (it samples BoatState) and must exist before history (which
+      // samples it), hence the position.
+      if (telemetry) {
+        try {
+          perf = createPerf(app, {
+            source: telemetry,
+            pluginId: plugin.id,
+            storeDir: store,
+            profileFile: path.join((app.getDataDirPath && app.getDataDirPath()) || '.', 'profile.json')
+          })
+          perf.start()
+        } catch (e) {
+          (app.error || console.error)('[sailkick-boat] performance start failed: ' + e.message)
+          perf = null
+        }
+      }
+
       if (pOpts.history.enabled !== false) {
         try {
           // ringSource = the telemetry module: when no local InfluxDB token is set
           // (the common case, e.g. a Victron GX), history serves a DB-less ring from
           // live telemetry. storeDir puts the persistent ring log on the SSD.
-          history = createHistory(app, { ...pOpts.history, ringSource: telemetry, storeDir: store })
+          history = createHistory(app, { ...pOpts.history, ringSource: telemetry, perfSource: perf, storeDir: store })
           history.start()
           pOpts.history = history // proxy dispatches /api/history to it when available()
         } catch (e) {
@@ -459,6 +480,7 @@ module.exports = function (app) {
     if (history) parts.push(history.status())
     if (aisTargets) parts.push(aisTargets.status())
     if (profile) parts.push(profile.status())
+    if (perf) parts.push(perf.status())
     if (ais) parts.push(ais.status())
     if (backfill) parts.push(backfill.status())
     try { app.setPluginStatus(parts.join('   |   ') || 'idle (both features off)') } catch {}
@@ -473,6 +495,7 @@ module.exports = function (app) {
     try { if (aisTargets) aisTargets.stop() } catch {}
     try { if (profile) profile.stop() } catch {}
     try { if (cloud) cloud.stop() } catch {}
+    try { if (perf) perf.stop() } catch {}
     try { if (ais) ais.stop() } catch {}
     try { if (backfill) backfill.stop() } catch {}
     try { if (proxy) proxy.stop() } catch {}
@@ -484,6 +507,7 @@ module.exports = function (app) {
     aisTargets = null
     profile = null
     cloud = null
+    perf = null
     proxyPort = null
     pairedSlug = null
     proxy = null

package/lib/history/ring.js

@@ -36,7 +36,12 @@ const CHANNELS = [
   'tws', 'twd', 'aws', 'awa', 'twa', 'vmg',
   'sog', 'stw', 'cog', 'heading', 'depth',
   'seaTemp', 'airTemp', 'rpmPort', 'rpmStbd',
-  'wptBrg', 'wptDist', 'wptVmg', 'wptTtg'
+  'wptBrg', 'wptDist', 'wptVmg', 'wptTtg',
+  // Computed on the boat (lib/perf) rather than read off the bus: percentage of polar
+  // target. Null whenever the guards do not pass — in irons, under 2 kt, no polar — so
+  // the channel GAPS instead of flat-lining at zero, which would drag every average
+  // drawn over it.
+  'perf'
 ]
 const wrap360 = (d) => ((d % 360) + 360) % 360
 const MAX_SAMPLES = 50000
@@ -66,8 +71,9 @@ function trueWind (s) {
 }
 
 class RingHistoryProvider {
-  constructor ({ source, sampleSec, windowSec, persistFile } = {}) {
+  constructor ({ source, perfSource, sampleSec, windowSec, persistFile } = {}) {
     this._source = source
+    this._perfSource = perfSource || null
     this._ring = [] // [{ t, ...CHANNELS, lat, lon }]
     const win = windowSec || 3600
     this._windowMs = win * 1000
@@ -107,6 +113,7 @@ class RingHistoryProvider {
       // rather than showing a flat line at zero.
       wptBrg: num(s.wptBrgDeg), wptDist: num(s.wptDistNm),
       wptVmg: num(s.wptVmgKt), wptTtg: num(s.wptTtgSec),
+      perf: this._perfSource ? num(this._perfSource.getPerf()) : null,
       lat: num(s.lat), lon: num(s.lon)
     }
     this._ring.push(row)

package/lib/perf/index.js

@@ -0,0 +1,182 @@
+'use strict'
+
+// Live polar performance, computed on the boat.
+//
+// The app already shows a live "% of polar target" on the mobile Polar screen and the
+// desktop ribbon, computed in the browser. Computing it HERE instead makes it a recorded
+// channel: it rides the same store-and-forward spool as every other value, so an offline
+// passage replays it gapless rather than leaving a hole; it sees full-rate SignalK rather
+// than the cloud's 2 s Influx poll; and it keeps working in the boat-served offline mode.
+//
+// The maths is NOT reimplemented — perf-live.js and polar.js are vendored verbatim from
+// the app (see their headers). One definition of "the %", or the boat and the screens
+// would quietly disagree.
+//
+// Output is two ordinary SignalK deltas:
+//   performance.polarSpeed       target boat speed, m/s   (SI, as SignalK expects)
+//   performance.polarSpeedRatio  achieved / target, 0–1
+// Emitting deltas rather than writing our own measurement means everything downstream
+// gets it for free: lib/sync already subscribes to '*' and forwards to the cloud bucket,
+// NMEA displays and other plugins can read it, and the cloud maps
+// performance.polarSpeedRatio -> the `perf` history channel with one line.
+//
+// ONLY when the guards pass. Inside the no-go wedge, in under 2 kt of wind, or against a
+// near-zero target, nothing is emitted at all: a gap is the honest representation, and a
+// zero would be a lie that pollutes every average drawn over it.
+
+const fs = require('fs')
+const path = require('path')
+const { createLivePerf, perfPct } = require('./perf-live')
+const { Polar } = require('./polar')
+
+const OWN_PREFIX = 'own:'
+const MS_TO_KT = 1.94384
+const DEFAULTS = {
+  intervalMs: 1000, // the 5 s EMA makes this cadence-insensitive; 1 s matches the ring
+  polarReloadMs: 60000 // pick up an active-polar change without a restart
+}
+
+function createPerf (app, options = {}) {
+  const log = (m) => (app.debug ? app.debug('[perf] ' + m) : console.log('[sailkick-boat:perf]', m))
+  const warn = (m) => (app.error ? app.error('[sailkick-boat:perf] ' + m) : console.error('[sailkick-boat:perf]', m))
+
+  const cfg = { ...DEFAULTS, ...options }
+  let live = null
+  let polar = null
+  let polarId = null
+  let polarError = null
+  let timer = null
+  let reloadTimer = null
+  let stopped = false
+  let last = null // { pct, target, kind, usingSog }
+  let emitted = 0
+  let skipped = 0
+  let warnedSog = false
+
+  // --- resolving the active polar -------------------------------------------------
+  // The boat has its own profile mirror (lib/profile). `activePolar` is either an
+  // own:<id> — a polar the owner authored, whose CSV is in the profile itself — or a
+  // catalogue id, whose CSV the mirror has cached under store/polars/<id>.csv exactly as
+  // the app fetches it.
+  function readProfile () {
+    try { return JSON.parse(fs.readFileSync(cfg.profileFile, 'utf8')) } catch { return null }
+  }
+
+  function csvFor (id, profile) {
+    if (id.startsWith(OWN_PREFIX)) {
+      const pid = id.slice(OWN_PREFIX.length)
+      const item = (profile.polars || []).find((p) => p && p.id === pid)
+      return item && typeof item.csv === 'string' ? item.csv : null
+    }
+    // Catalogue polar: whatever the mirror cached. Not fetched on demand — this must
+    // work with no uplink, and an unseen polar simply means no % until the app has
+    // opened it once.
+    try { return fs.readFileSync(path.join(cfg.storeDir, 'polars', `${id}.csv`), 'utf8') } catch { return null }
+  }
+
+  function loadPolar () {
+    const profile = readProfile()
+    const id = profile && typeof profile.activePolar === 'string' ? profile.activePolar : null
+    if (!id) {
+      if (polarId !== null) log('no active polar selected — performance is not being computed')
+      polar = null; polarId = null; polarError = 'no active polar selected'
+      return
+    }
+    if (id === polarId && polar) return // unchanged
+    const csv = csvFor(id, profile || {})
+    if (!csv) {
+      polar = null; polarId = id
+      polarError = `the CSV for "${id}" is not on the boat yet`
+      warn(`${polarError} — open the polar once in the app while online, or copy it across on the Sync page`)
+      return
+    }
+    try {
+      polar = Polar.fromCSV(id, csv)
+      polarId = id
+      polarError = null
+      log(`active polar "${polar.name || id}" loaded (no-go ${polar.noGoTwa}°)`)
+    } catch (e) {
+      polar = null; polarId = id
+      polarError = `polar "${id}" will not parse: ${e.message}`
+      warn(polarError)
+    }
+  }
+
+  // --- the computation ------------------------------------------------------------
+  function tick () {
+    if (stopped || !cfg.source || !cfg.source.getState) return
+    const s = cfg.source.getState()
+    if (!s) return
+
+    // The SignalK timestamp, never wall clock: buffered or replayed computation has to
+    // be deterministic, and the EMA is time-weighted.
+    const now = Date.parse(s.updatedAt) || Date.now()
+    const r = live.update(s, now)
+    if (!r) { last = null; return } // wind or speed missing — the EMA reset itself
+
+    const tws = live.avgTws(now)
+    const res = perfPct(polar, tws, r.ema)
+
+    if (live.usingSog && !warnedSog) {
+      warnedSog = true
+      log('no speed through water — the percentage is computed from SOG, so it is polluted by current')
+    }
+
+    if (res.kind !== 'ok') { last = { kind: res.kind }; skipped++; return }
+    last = { kind: 'ok', pct: res.pct, target: res.target, usingSog: live.usingSog }
+    emitted++
+    emit(res, s.updatedAt)
+  }
+
+  // Standard SignalK paths, in SI. round() lives here so the ratio and the percentage
+  // can never disagree: the cloud takes round(ratio * 100).
+  function emit (res, timestamp) {
+    if (!app.handleMessage) return
+    try {
+      app.handleMessage(cfg.pluginId || 'sailkick-boat', {
+        updates: [{
+          timestamp: timestamp || new Date().toISOString(),
+          values: [
+            { path: 'performance.polarSpeed', value: res.target / MS_TO_KT },
+            { path: 'performance.polarSpeedRatio', value: res.pct / 100 }
+          ]
+        }]
+      })
+    } catch (e) { warn('could not emit deltas: ' + e.message) }
+  }
+
+  // --- lifecycle ------------------------------------------------------------------
+  function start () {
+    if (!cfg.source) { log('not started — no telemetry source'); return }
+    live = createLivePerf({})
+    loadPolar()
+    timer = setInterval(tick, cfg.intervalMs)
+    reloadTimer = setInterval(loadPolar, cfg.polarReloadMs)
+    if (timer.unref) timer.unref()
+    if (reloadTimer.unref) reloadTimer.unref()
+    log(`computing performance every ${Math.round(cfg.intervalMs / 1000)}s -> performance.polarSpeed{,Ratio}`)
+  }
+
+  function stop () {
+    stopped = true
+    clearInterval(timer); clearInterval(reloadTimer)
+    timer = reloadTimer = null
+    live = null; polar = null; polarId = null; last = null
+  }
+
+  // What the history ring samples. Null whenever the guards did not pass, so the channel
+  // gaps rather than flat-lining.
+  function getPerf () { return last && last.kind === 'ok' ? last.pct : null }
+
+  function status () {
+    if (!live) return 'perf: off'
+    if (polarError) return `perf: ${polarError}`
+    if (!last) return 'perf: waiting for wind and speed'
+    if (last.kind !== 'ok') return `perf: ${last.kind}`
+    return `perf: ${last.pct}% of "${polarId}"${last.usingSog ? ' (from SOG — current-polluted)' : ''}${skipped ? `; ${skipped} guarded` : ''}`
+  }
+
+  return { start, stop, status, getPerf, _tick: tick, _polar: () => polar, _loadPolar: loadPolar, _counts: () => ({ emitted, skipped }) }
+}
+
+module.exports = { createPerf }

package/lib/perf/perf-live.js

@@ -0,0 +1,80 @@
+// VENDORED from sailkick/shared/engine/perf-live.js @ 128cf97  sha256:7ce83a1df13926f0
+// Do not edit here — fix upstream and re-vendor. One definition of "the %".
+//
+// Converted ESM -> CommonJS ONLY (export keywords removed, module.exports appended). No logic changed: the boat and every app
+// surface must produce the same number, and test/perf.test.js replays the upstream
+// suite's cases against this copy to prove it.
+// Live polar performance — ONE definition of "the %", shared by every surface that
+// shows or will compute it: the mobile Polar screen, the desktop ribbon polar, the
+// cloud server (perfPct on the telemetry stream, when it lands) and — vendored, see
+// the handoff when it happens — the boat plugin. Extracted from polar-screen.js /
+// instrument-polar.js, which had drifted to two copies of the same five constants.
+//
+// Pure: no DOM, no fetch, no Date.now() of its own (callers pass `now` so the cloud
+// can replay history deterministically). The polar object comes from polar.js
+// (`speed(tws, signedTwa)` abs-clamps the angle; `noGoTwa` is the first table row).
+
+const EMA_TAU_S = 5;        // live-point smoothing time constant (s)
+const TWS_AVG_SEC = 60;     // "current wind" = 1-min mean TWS
+const MIN_TWS = 2;          // below this wind the % is noise…
+const MIN_TARGET = 0.5;     // …and below this target it divides by ~zero
+
+const wrap180 = (d) => { const x = ((d % 360) + 360) % 360; return x > 180 ? x - 360 : x; };
+
+// Stateful smoother over the BoatState stream. update() ingests one sample and
+// returns { raw, ema } (raw feeds trails/recorders; ema feeds the % and the dot),
+// or null while wind or speed is missing — which also RESETS the EMA, so a data
+// gap doesn't get smoothed across.
+function createLivePerf({ emaTauS = EMA_TAU_S, twsAvgSec = TWS_AVG_SEC } = {}) {
+  let ema = null, lastT = 0, usingSog = false;
+  let twsHist = [];   // [{t, v}] for the windowed mean
+
+  return {
+    update(s, now) {
+      if (Number.isFinite(s?.twsKt)) twsHist.push({ t: now, v: s.twsKt });
+      // Prefer the boat's own TWA; derive from TWD − HDG until it's published.
+      const twa = Number.isFinite(s?.twaDeg) ? s.twaDeg
+        : (Number.isFinite(s?.twdDeg) && Number.isFinite(s?.headingDeg)) ? wrap180(s.twdDeg - s.headingDeg)
+          : null;
+      usingSog = !Number.isFinite(s?.stwKt);
+      const kt = Number.isFinite(s?.stwKt) ? s.stwKt : Number.isFinite(s?.sogKt) ? s.sogKt : null;
+      if (twa == null || kt == null) { ema = null; return null; }
+
+      const dt = ema && lastT ? Math.min(30, (now - lastT) / 1000) : emaTauS;
+      const a = dt / (emaTauS + dt);
+      // Smooth via the SHORTEST-PATH delta (correct across the stern), then re-wrap
+      // the accumulator: without the outer wrap180 a gybe (175°S → 175°P) walks the
+      // EMA past 180 and the label reads "190° S" (and any side test flips wrong).
+      ema = ema
+        ? { twa: wrap180(ema.twa + wrap180(twa - ema.twa) * a), kt: ema.kt + (kt - ema.kt) * a }
+        : { twa, kt };
+      lastT = now;
+      return { raw: { twa, kt }, ema };
+    },
+    avgTws(now) {
+      const cut = now - twsAvgSec * 1000;
+      twsHist = twsHist.filter((p) => p.t >= cut);
+      return twsHist.length ? twsHist.reduce((s, p) => s + p.v, 0) / twsHist.length : null;
+    },
+    get ema() { return ema; },
+    get usingSog() { return usingSog; },
+  };
+}
+
+// The % itself, with its guards. Discriminated by `kind` so callers can render
+// each state distinctly instead of re-deriving the guards:
+//   nodata — no polar / no smoothed point / no wind average yet
+//   irons  — inside the no-go wedge (a % against a 0-ish target is meaningless)
+//   weak   — wind or target below the noise floor (target still reported)
+//   ok     — { pct, target }
+function perfPct(polar, tws, ema) {
+  if (!polar || !ema || !Number.isFinite(tws)) return { kind: 'nodata' };
+  const target = polar.speed(tws, ema.twa);
+  if (Math.abs(ema.twa) < polar.noGoTwa) return { kind: 'irons', target };
+  if (tws < MIN_TWS || target < MIN_TARGET) return { kind: 'weak', target };
+  return { kind: 'ok', target, pct: Math.round((ema.kt / target) * 100) };
+}
+
+module.exports = {
+  createLivePerf, perfPct, wrap180, EMA_TAU_S, TWS_AVG_SEC, MIN_TWS, MIN_TARGET
+}

package/lib/perf/polar.js

@@ -0,0 +1,133 @@
+// VENDORED from sailkick/shared/engine/polar.js @ 128cf97  sha256:6a3166fe17ab5806
+// Do not edit here — fix upstream and re-vendor. One definition of "the %".
+//
+// Converted ESM -> CommonJS ONLY (only the pure Polar class is taken — the getActivePolar/loadPolar store layer is app-side (fetch + localStorage) and has no meaning on the boat). No logic changed: the boat and every app
+// surface must produce the same number, and test/perf.test.js replays the upstream
+// suite's cases against this copy to prove it.
+// The boat resolves the ACTIVE polar from its own profile mirror instead — see index.js.
+
+class Polar {
+  constructor({ id, name, twaRows, twsCols, speeds }) {
+    this.id = id;
+    this.name = name;
+    this.twaRows = twaRows;
+    this.twsCols = twsCols;
+    this.speeds = speeds;
+    this.noGoTwa = twaRows[0];
+    this._maxSpeed = null;
+  }
+
+  // Boat speed in knots at wind speed `twsKn` and signed wind angle
+  // `twaDegSigned`. Polar is port/starboard-symmetric — take |twa|.
+  // Below noGoTwa → 0. Bilinear interpolation in (TWA, TWS), clamped at the
+  // table's TOP edge. Below the FIRST column the table is anchored to a virtual
+  // (0 wind → 0 boat speed) column: target = speed(col0, twa) × tws/col0.
+  // (The old behaviour linearly EXTRAPOLATED down the low-end gradient — a flat
+  // calm still "targeted" 1–2 kn, some tables went NEGATIVE upwind, and the
+  // perf% blew up as the target fell through the noise guard.)
+  speed(twsKn, twaDegSigned) {
+    const twa = Math.min(180, Math.abs(twaDegSigned));
+    if (twa < this.noGoTwa) return 0;
+    const { twaRows, twsCols, speeds } = this;
+    const col0 = twsCols[0];
+    if (twsKn < col0) return this.speed(col0, twa) * Math.max(0, twsKn) / col0;
+    const tws = Math.min(twsCols[twsCols.length - 1], twsKn);
+
+    let i = 0;
+    while (i < twaRows.length - 2 && twaRows[i + 1] < twa) i++;
+    const i1 = i + 1;
+    let j = 0;
+    while (j < twsCols.length - 2 && twsCols[j + 1] < tws) j++;
+    const j1 = j + 1;
+
+    const ta = (twa - twaRows[i]) / (twaRows[i1] - twaRows[i]);
+    const tb = (tws - twsCols[j]) / (twsCols[j1] - twsCols[j]);
+
+    const s00 = speeds[i][j];
+    const s01 = speeds[i][j1];
+    const s10 = speeds[i1][j];
+    const s11 = speeds[i1][j1];
+
+    const s0 = s00 * (1 - tb) + s01 * tb;
+    const s1 = s10 * (1 - tb) + s11 * tb;
+    return s0 * (1 - ta) + s1 * ta;
+  }
+
+  // Peak boat speed across the whole table — used to size the wind grid
+  // (we want it big enough to contain 24 h of travel at max polar speed).
+  maxSpeed() {
+    if (this._maxSpeed != null) return this._maxSpeed;
+    let max = 0;
+    for (const row of this.speeds) for (const s of row) if (s > max) max = s;
+    this._maxSpeed = max;
+    return max;
+  }
+
+  // A bound `speed` function, convenient for passing into the isochrone.
+  speedFn() {
+    return (tws, twa) => this.speed(tws, twa);
+  }
+
+  // ---- parsing -----------------------------------------------------
+
+  static fromCSV(id, text) {
+    let name = null;
+    const twaRows = [];
+    const twsCols = [];
+    const speeds = [];
+    let seenHeader = false;
+
+    for (let rawLine of text.split(/\r?\n/)) {
+      const line = rawLine.trim();
+      if (!line) continue;
+      if (line.startsWith('#')) {
+        const m = line.match(/^#\s*(.+?)\s*$/);
+        if (m && !name) {
+          // Strip trailing empty CSV cells that spreadsheet exports
+          // sometimes leave on the comment line ("Outremer 5X ,,,,,").
+          name = m[1].replace(/[\s,]+$/, '');
+        }
+        continue;
+      }
+      const cells = line.split(',').map(s => s.trim());
+      // Skip "ghost" all-commas rows from spreadsheet exports.
+      if (cells.every(c => c === '')) continue;
+      if (!seenHeader) {
+        if (cells.length < 2) throw new Error(`Polar "${id}": header has <2 columns`);
+        for (let k = 1; k < cells.length; k++) {
+          const v = Number(cells[k]);
+          if (!Number.isFinite(v)) throw new Error(`Polar "${id}": bad TWS header value "${cells[k]}"`);
+          twsCols.push(v);
+        }
+        if (twsCols.length < 2) throw new Error(`Polar "${id}": need at least 2 TWS columns`);
+        seenHeader = true;
+        continue;
+      }
+      if (cells.length !== twsCols.length + 1) {
+        throw new Error(`Polar "${id}": row "${cells[0]}" has ${cells.length - 1} speed cells, expected ${twsCols.length}`);
+      }
+      const twa = Number(cells[0]);
+      if (!Number.isFinite(twa)) throw new Error(`Polar "${id}": bad TWA value "${cells[0]}"`);
+      const row = [];
+      for (let k = 1; k < cells.length; k++) {
+        const v = Number(cells[k]);
+        if (!Number.isFinite(v) || v < 0) throw new Error(`Polar "${id}": bad speed "${cells[k]}" at TWA ${twa}, TWS ${twsCols[k - 1]}`);
+        row.push(v);
+      }
+      twaRows.push(twa);
+      speeds.push(row);
+    }
+
+    if (twaRows.length < 2) throw new Error(`Polar "${id}": need at least 2 TWA rows`);
+    for (let k = 1; k < twaRows.length; k++) if (twaRows[k] <= twaRows[k - 1]) {
+      throw new Error(`Polar "${id}": TWA rows not strictly ascending at ${twaRows[k]}`);
+    }
+    for (let k = 1; k < twsCols.length; k++) if (twsCols[k] <= twsCols[k - 1]) {
+      throw new Error(`Polar "${id}": TWS columns not strictly ascending at ${twsCols[k]}`);
+    }
+
+    return new Polar({ id, name: name || id, twaRows, twsCols, speeds });
+  }
+}
+
+module.exports = { Polar }

package/lib/telemetry/index.js

@@ -3,6 +3,24 @@
 const crypto = require('crypto')
 const { signalkValuesToPatch, resolveHeadingDeg } = require('./signalk-map')
 
+// Choosing between competing sources is SIGNAL K'S JOB, not this module's. A boat
+// commonly has several devices publishing the same path — this one carries two compasses
+// 7.5 deg apart on navigation.headingMagnetic, and three log sources on
+// speedThroughWater, one of which reports a constant 0. Signal K resolves that from
+// `sourcePriorities` in settings.json, applied in its delta pipeline (deltaPriority.js,
+// called at index.js:268) BEFORE anything downstream sees the delta. So by the time a
+// value reaches here it has already been arbitrated, and every consumer on the boat —
+// this plugin, KIP, the instruments — agrees.
+//
+// This module used to keep its own guard for navigation.headingMagnetic: lock onto the
+// first $source seen and ignore the rest. That was a coin flip (it could equally lock
+// onto the WRONG compass and be quietly 7.5 deg out for the whole session), and once
+// priorities were configured it became actively harmful: Signal K replays current values
+// when a client subscribes, so the first headingMagnetic delta after a restart can be a
+// one-off from a de-prioritised device. Latching onto that would have discarded every
+// real heading delta thereafter — heading frozen at a stale value rather than merely
+// wrong. Removed in v0.22.3; set `sourcePriorities` instead.
+//
 // Serves the sailkick app's /ws/telemetry bus FROM the boat's local SignalK, so
 // the app uses the identical telemetry contract whether it talks to the cloud
 // sailkick server or this on-boat plugin. Faithful port of the server's
@@ -26,7 +44,6 @@ function encodeTextFrame (str) {
 function createTelemetry (app, options = {}) {
   const log = (m) => (app.debug ? app.debug('[telemetry] ' + m) : console.log('[sailkick-boat:telemetry]', m))
   let state = null
-  let magSource = null // lock the $source for navigation.headingMagnetic (dual-source guard)
   const clients = new Set()
   const unsubscribes = []
 
@@ -44,13 +61,7 @@ function createTelemetry (app, options = {}) {
     let ts = null
     for (const u of delta.updates) {
       if (!u || !Array.isArray(u.values)) continue
-      const src = u.$source || (u.source && u.source.label) || ''
-      const vals = u.values.filter((v) => {
-        if (!v || v.path !== 'navigation.headingMagnetic') return true
-        if (!magSource) magSource = src
-        return src === magSource
-      })
-      Object.assign(patch, signalkValuesToPatch(vals))
+      Object.assign(patch, signalkValuesToPatch(u.values))
       if (u.timestamp) ts = u.timestamp
     }
     if (Object.keys(patch).length === 0) return
@@ -85,7 +96,6 @@ function createTelemetry (app, options = {}) {
     for (const s of clients) { try { s.destroy() } catch {} }
     clients.clear()
     state = null
-    magSource = null
   }
 
   function status () {

package/package.json

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