@meri-imperiumi/signalk-dead-reckoning 0.1.0 → 0.3.0

package/CHANGELOG.md

@@ -5,6 +5,161 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.0] - 2026-08-27
+
+### Added
+- **`inertial-polar` DR speed fallback (SPEC §3.1, work doc #18)** —
+  when the paddlewheel is unusable (`navigation.speedThroughWater`
+  missing, or the debounced §6.3 fouling verdict active), DR integrates
+  speed from the polar performance plugin's `performance.polarSpeed`
+  delta instead of freezing: requires `signalk-polar-performance-plugin`
+  installed and configured with its polar speed output enabled; the
+  super-jittery raw delta is running-averaged (default 60 s window,
+  30 s staleness cutoff) before integration. Gated to underway+sailing
+  (no wind-on-mast drift at the dock, no meaningless polar under
+  power); no matrix corrections while on polar (bins were trained on
+  real STW — a model estimate is circular input); uncertainty grows at
+  the fallback rate; Training Mode and maneuver detection suspended;
+  the divergence advisory keeps watching. `navigation.speedThroughWater`
+  stays silent while on polar (a model estimate is not a measurement).
+  The DR state value gains `speedSource: "paddlewheel"|"polar"`, and a
+  §3.1 sensor-health alert names the switch (paddlewheel
+  unavailable/fouled — DR on polar-derived speed).
+- Scalar sibling paths `navigation.deadReckoning.uncertainty.radius`
+  and `navigation.deadReckoning.divergence.distance` (metres, with
+  nautical-mile display-unit meta) for rule/display engines
+  (signalk-status-tiles threshold checks) that cannot read subfields of
+  object-valued paths — subscribing to a subfield path never sees a
+  delta.
+
+### Changed
+- **All published deltas now follow the Signal K SI unit conventions**
+  (breaking):
+  - `navigation.deadReckoning.log` / `trip.log` publish metres (was
+    nautical miles), with `value/1852` NM display-unit meta.
+  - The `environment.current` object is replaced by the standard
+    `environment.current.setTrue` (radians) and
+    `environment.current.drift` (m/s) paths; the DR-specific
+    tier/source enrichment rides REST `/status` instead of the bus.
+  - The uncertainty object field `radius_nm` becomes `radius_m`; the
+    divergence object fields `distance_nm`/`bearing_true` (deg) become
+    `distance_m`/`bearing_true` (rad).
+  - `navigation.deadReckoning.elapsedSinceFix` gains duration
+    display-unit meta so glance consumers render "3h 05m", not
+    seconds.
+  - All display-unit meta declares `category: "custom"` — the
+    server's unit-preference system rewrites category-less
+    `displayUnits` to the user's global preference (a seconds path
+    rendered as "0.0 hour"); custom keeps the nautical styling.
+- **Inbound sensor deltas are now interpreted per the Signal K unit
+  conventions** (breaking for feeds that were publishing non-SI):
+  `speedThroughWater`/`speedApparent` are read as m/s and heading paths
+  as radians, converting to the engine's internal knots/degrees at the
+  boundary. Previously m/s and radian values were treated as knots and
+  degrees — DR under-travelled ~5× and mis-steered on standard feeds.
+  The standard-path passthroughs (`navigation.speedThroughWater`,
+  `navigation.headingTrue`) publish what they received, unchanged.
+- Logbook fix/tack entries convert SOG/COG/heading at the boundary
+  (`_kn`/`_deg` REST fields previously received raw m/s/radians).
+- The webapp converts SI bus values (m, m/s, rad) to nautical displays
+  centrally in the view model (`metresToNm`/`msToKn`/`radToDeg`).
+- REST `/status` and `/current/manual` keep the plugin's internal
+  nautical units (`logNm`, `current.setTrue` deg, `drift` kn) — they
+  are the plugin's own API, not the Signal K bus.
+- `navigation.deadReckoning.method` now reflects the actual speed
+  source every tick, completing the SPEC §3.1 enum: the idle branch
+  (no usable speed at all) publishes `fallback-zero` instead of
+  inheriting the constructor's `inertial-paddlewheel` — the `Polar`/
+  `Zero` headline labels added earlier are now driven by real values.
+  SPEC §3.1/§3.2/§6.1 aligned with the implemented fallback hierarchy
+  (polar first, fault-based selection, speed output silent on polar).
+- The "Active method" headline shows a short watchkeeper-sized label
+  (`STW` for `inertial-paddlewheel`, `Polar`/`Zero` for the spec's
+  reserved methods) with the full token on hover — one of five figures,
+  it previously gave a full spec token permanent large-type real estate
+  despite having exactly one possible value today.
+- The DR status no longer claims the vessel is `underway` while
+  moored: `navigation.deadReckoning.state.status` gains a `"warm"`
+  value (engine integrating on a tied-up boat, SPEC §5 runs it warm for
+  instant OVERRIDE handoff — that is not being under way) alongside
+  `"underway"` and `"idle"`. The webapp subscribes to the vessel's own
+  `navigation.state` (already in the system — nothing is republished
+  inside our deltas) and words the line accordingly:
+  `DR warm — moored/anchored, integrating sensors` vs
+  `Dead reckoning active`. Text logic moved to the pure `drStatusText()`
+  view-model helper.
+
+## [0.2.0] - 2026-08-27
+
+### Fixed
+- **Map no longer opens blank — defaults to the first chart provider.**
+  The webapp previously kept its tile-less offline-first default unless
+  the server had *configured* charts, so on servers without any (the
+  common case: the layers control showed only "OpenStreetMap (online)",
+  unselected) the plot opened on an empty dark canvas. The first entry
+  of the chart list — first configured chart when the server has them,
+  otherwise the OSM online fallback — is now auto-selected on load, and
+  duplicate chart names no longer clobber each other's entry in the
+  layers control.
+- **Dockside false positives while moored/anchored** — three alerts
+  that misfire on a tied-up boat are now suppressed in the moored/
+  anchored regime (consistent with the divergence monitor's existing
+  §7.1–2 suppression):
+  - *Divergence advisory* no longer raises on GPS wander at the dock:
+    the uncertainty radius previously collapsed to exactly 0.0 nm at
+    zero distance run, so a few metres of marina multipath "exceeded
+    expected uncertainty × 1.5" and sustained for 30 s raised
+    `DR-GPS divergence 0.00 nm exceeds expected 0.00 nm`. The radius
+    now floors at `MIN_RADIUS_NM` (0.02 nm ≈ 37 m, GNSS noise scale)
+    — DR error can never honestly be smaller than the GPS it was
+    seeded from.
+  - *Phantom "paddlewheel fouled" alert* — the fouling detector saw
+    STW≈0 (a moored paddlewheel's honest reading) plus wind on the
+    mast or GPS jitter and concluded the boat was making way. The
+    detector (and the whole training/matrix path, incl. auto tack
+    logging) is skipped while moored/anchored, and any earlier verdict
+    is withdrawn.
+  - *Sticky advisories* — a divergence advisory raised just before
+    mooring could never clear (the monitor isn't fed while suppressed).
+    It is now withdrawn with a `DR monitoring suspended while
+    moored/anchored` notification, and the divergence readout publishes
+    an explicit `null` while suppressed so the UI drops the stale
+    figure instead of showing a frozen `0.00 nm / 306°`.
+- **Sensor-health alerts no longer flap** — the fouling and
+  idle-but-making-way verdicts are raw per-tick threshold comparisons
+  (STW vs 0.3 kn, wind vs 3 kn, SOG vs 1 kn); a sensor hovering at a
+  threshold toggled the alert on and off every tick. Both now pass
+  through a reusable symmetric hysteresis
+  (`plugin/hysteresis.js`, `sensorHealth.sustainS`/`clearS`, default
+  10 s/10 s): a real fault still surfaces after the sustain window,
+  threshold hover raises nothing.
+- **Water-track log survives restart** — `navigation.deadReckoning.log`
+  and the trip log were persisted every flush but never restored at
+  start, resetting the headline to 0.00 nm on every server restart
+  mid-passage. Both are now restored from the `dr_state_store`.
+- **Map layers control usable again** — the divergence chip overlay sat
+  at the top-right corner on top of Leaflet's layers control (equal
+  z-index, later sibling wins), covering its toggle: broken-looking
+  styling and swallowed clicks meant selecting a chart provider did
+  nothing. The chip now lives at the bottom-right (attribution is off,
+  so the corner is free).
+- The DR vs GPS headline no longer shows a bearing below display
+  resolution (`0.00 nm / 306°` → `0.00 nm`): the bearing of a
+  zero-length noise vector is meaningless.
+
+### Changed
+- When the server has no charts configured, the online OpenStreetMap
+  fallback layer is offered in the layers control but no longer
+  auto-added to the map (it was documented as opt-in; the tile-less
+  offline-first plot is the default again until selected).
+
+### Added
+- `plugin/hysteresis.js` — generic symmetric sustain/clear debounce for
+  boolean conditions, extracted from the divergence advisory's shape
+  and unit-tested; also used for the sensor-health alerts.
+- Work doc #17 on the rngit board tracks this batch (dockside false
+  positives: divergence advisory, fouled paddlewheel, layers control).
+
 ## [0.1.0] - 2026-08-27
 
 ### Changed

package/README.md

@@ -1,5 +1,5 @@
 # Signal K Dead Reckoning
 
-An offline-first dead reckoning and sensor fusion engine for Signal K that maintains a continuously computed "shadow boat" position from water-track sensors (speed through water, compass heading, and learned leeway and current corrections), so you always have a navigational fallback when GPS becomes unreliable — whether from jamming, spoofing, or plain receiver failure. While GPS is trusted, the engine learns vessel-specific calibration corrections against ground truth and watches for GPS anomalies; when it isn't, the same learned model keeps the dead-reckoned position, its uncertainty polygon, and a water-track log going. Fixes from celestial sights, compass bearings, and vertical angles are entered through a unified pipeline and can snap dead reckoning back on track, with optional write-through to `signalk-logbook`. Historical data can be backfilled to train the calibration model and backtest it against past passages. Licensed under the EUPL-1.2.
+An offline-first dead reckoning and sensor fusion engine for Signal K that maintains a continuously computed "shadow boat" position from water-track sensors (speed through water, compass heading, and learned leeway and current corrections), so you always have a navigational fallback when GPS becomes unreliable — whether from jamming, spoofing, or plain receiver failure. While GPS is trusted, the engine learns vessel-specific calibration corrections against ground truth and watches for GPS anomalies; when it isn't, the same learned model keeps the dead-reckoned position, its uncertainty polygon, and a water-track log going. Fixes from celestial sights, compass bearings, and vertical angles are entered through a unified pipeline and can snap dead reckoning back on track, with optional write-through to `signalk-logbook`.
 
 **Note:** This is just a toy. Make your own navigation calculations and decisions.

package/SPEC.md

@@ -38,10 +38,10 @@ The three motivations are causally linked: (1) generates the fix data and crew e
 |---|---|---|
 | `navigation.deadReckoning.position` | `{ latitude, longitude, altitude }` | **Always-on** 1Hz inertial "shadow boat" position — computed continuously regardless of mode. |
 | `navigation.deadReckoning.active` | boolean | Whether DR is currently the *authoritative* source feeding `navigation.position` (i.e. OVERRIDE engaged), as distinct from merely running in the background. |
-| `navigation.deadReckoning.method` | string: `inertial-polar` \| `inertial-paddlewheel` \| `fallback-zero` | Active state calculation mode. |
+| `navigation.deadReckoning.method` | string: `inertial-polar` \| `inertial-paddlewheel` \| `fallback-zero` | Active speed-source mode, re-published every tick: `inertial-paddlewheel` while the paddlewheel serves (raw STW present, not fouled); `inertial-polar` when it doesn't and the polar fallback can engage (§6.1); `fallback-zero` when no usable speed source exists (DR holds position). Selection is fault-based, never merit-based — a working measurement always outranks a model. |
 | `navigation.deadReckoning.log` | number (nm) | Cumulative **water-track** distance, integrated from STW. Independent of GPS. |
 | `navigation.deadReckoning.trip.log` | number (nm) | Same, reset at trip boundaries (see §9.2). |
-| `navigation.speedThroughWater` | number | Calibrated STW output (matrix-corrected). |
+| `navigation.speedThroughWater` | number | Calibrated STW output (matrix-corrected). Silent while the polar fallback is active — a model estimate must not masquerade as a measurement. |
 | `navigation.headingTrue` | number | Calibrated true heading (corrected for dynamic deviation). |
 | `environment.current` | `{ setTrue, drift, meta: { source, expiresAt } }` | Current vector broadcast, per §6.2 hierarchy. |
 | `notifications.navigation.gpsSpoofed` | alarm state | High-severity: sudden position discontinuity inconsistent with DR/physics, or at-anchor/moored displacement beyond plausible bound. See §7. |
@@ -55,6 +55,7 @@ The three motivations are causally linked: (1) generates the fix data and crew e
 | `navigation.position` | GPS baseline for training mode and anomaly detection. |
 | `navigation.speedThroughWater`, `navigation.headingMagnetic`, `navigation.attitude` | Raw sensor inputs (heel/pitch). |
 | `environment.wind.angleApparent`, `environment.wind.speedApparent` | Wind inputs for leeway/upwash modeling. |
+| `performance.polarSpeed` | Polar-derived boat speed (m/s) from `signalk-polar-performance-plugin` — requirement for the §6.1 `inertial-polar` fallback: that plugin installed and configured with its polar-speed output enabled. The raw delta is a step-function polar lookup driven by gusty wind and is **running-averaged** before integration; sustained nulls (wind out-of-table) age the average out to staleness rather than decaying it toward zero. |
 | `navigation.sails` | Active sail configuration, from `signalk-logbook`. |
 | `environment.seaState` | Sea state tier, from logbook watch entries. |
 | `navigation.state` | `anchored` \| `moored` \| `sailing` \| `motoring` \| ... — trip boundaries, and the anchored/moored anomaly-detection gates. |
@@ -273,7 +274,14 @@ Worker Thread (DR Physics)
 
 **Inference Mode** — active when `isGpsReliable = false` OR OVERRIDE is manually engaged:
 - Freezes matrix learning. Reads raw sensors, looks up matching bins, applies corrections, integrates the resolved current vector, publishes `navigation.deadReckoning.position` as authoritative (`navigation.deadReckoning.active = true`).
-- If the paddlewheel is fouled during Inference Mode, falls back to GPS-SOG-derived speed (if GPS is at least partially available) or holds last-known-good STW with explicitly faster-growing uncertainty (if not) — distinct fallback branch from the "GPS unreliable" case, since the two can occur independently or together.
+
+**Speed-source fallback** — mode-independent (the shadow boat integrates regardless of GPS trust, §5, so a sensor lost in NORMAL mode is handled the same way as one lost in Inference/OVERRIDE). A fouled or silent paddlewheel degrades the speed source by preference:
+
+1. **Polar-derived speed** — the running-averaged `performance.polarSpeed` (§3.2). Gated to underway + sailing: wind on a moored mast must not sail the shadow boat off the dock, and a polar is meaningless under power. While on this source: no matrix corrections (leeway/speed-loss bins were trained on real paddlewheel STW — feeding them a model estimate is circular), uncertainty grows at the fallback rate, and matrix training / maneuver detection are suspended (never train on synthetic input — same principle as the §6.3/§6.4 write gates). The divergence advisory (§7.3) keeps watching: model drift must be detected even though it never re-selects the method.
+2. **GPS-SOG-derived speed** — if no polar source is available and GPS is at least partially available.
+3. **Hold last-known-good STW** — with explicitly faster-growing uncertainty, if neither.
+
+The paddlewheel-failure fallback is a distinct branch from the "GPS unreliable" case, since the two can occur independently or together.
 
 ### 6.2 Current Hierarchy of Truth
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@meri-imperiumi/signalk-dead-reckoning",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Offline-first dead reckoning and sensor fusion engine for Signal K",
   "main": "plugin/index.js",
   "scripts": {
@@ -33,7 +33,8 @@
     ],
     "recommends": [
       "@meri-imperiumi/signalk-autostate",
-      "@meri-imperiumi/signalk-logbook"
+      "@meri-imperiumi/signalk-logbook",
+      "signalk-polar-performance-plugin"
     ],
     "screenshots": [
       "./doc/dr-map.png",

package/plugin/hysteresis.js

@@ -0,0 +1,82 @@
+/**
+ * Generic symmetric hysteresis for a boolean condition (sustained raise,
+ * sustained clear), extracted from the divergence advisory monitor's
+ * debounce shape so other watchkeeper alerts (§6.3 paddlewheel fouling,
+ * idle-but-making-way) can't flap when a sensor hovers at a threshold.
+ *
+ * The condition must persist for `sustainS` before the debounced flag
+ * goes true, and stay false for `clearS` before it drops — a single
+ * jittery tick neither raises nor clears.
+ *
+ * Pure logic over an explicit state object — unit-testable without
+ * Signal K plumbing.
+ *
+ * @file hysteresis.js
+ */
+
+/**
+ * Default windows (seconds) for sensor-health style flags. Slower than
+ * the divergence advisory's 30 s — fouling and idle transitions are
+ * mechanical conditions that don't change meaningfully in a second, but
+ * fast enough that a real fault surfaces within a watch check.
+ */
+const DEFAULT_SUSTAIN_S = 10;
+const DEFAULT_CLEAR_S = 10;
+
+/**
+ * Creates a fresh debounce state.
+ *
+ * @returns {{active: boolean, exceedS: number, insideS: number}}
+ */
+function createFlagState() {
+  return {
+    /** debounced flag currently raised */
+    active: false,
+    /** sustained seconds of the raw condition accumulated */
+    exceedS: 0,
+    /** sustained seconds of the raw condition being absent */
+    insideS: 0,
+  };
+}
+
+/**
+ * Advances the debounce one tick.
+ *
+ * @param {object} state - from createFlagState(), mutated
+ * @param {boolean} raw - the undebounced per-tick condition
+ * @param {number} dtS - tick interval in seconds
+ * @param {object} [opts]
+ * @param {number} [opts.sustainS=DEFAULT_SUSTAIN_S]
+ * @param {number} [opts.clearS=DEFAULT_CLEAR_S]
+ * @returns {{active: boolean, transition: "raise"|"clear"|null}}
+ */
+function flagTick(state, raw, dtS, opts = {}) {
+  const sustainS = opts.sustainS ?? DEFAULT_SUSTAIN_S;
+  const clearS = opts.clearS ?? DEFAULT_CLEAR_S;
+  let transition = null;
+
+  if (raw) {
+    state.insideS = 0;
+    state.exceedS += dtS;
+    if (!state.active && state.exceedS >= sustainS) {
+      state.active = true;
+      transition = "raise";
+    }
+  } else {
+    state.exceedS = 0;
+    state.insideS += dtS;
+    if (state.active && state.insideS >= clearS) {
+      state.active = false;
+      transition = "clear";
+    }
+  }
+
+  return { active: state.active, transition };
+}
+
+module.exports = {
+  DEFAULT_SUSTAIN_S,
+  DEFAULT_CLEAR_S,
+  createFlagState,
+  flagTick,
+};