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

package/CHANGELOG.md

@@ -5,9 +5,102 @@ 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

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.2.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",