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

package/CHANGELOG.md

@@ -5,9 +5,189 @@ 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.4.0] - 2026-08-28
+
+### Added
+- **Example Status Tiles set (work doc #22)** — the plugin now ships a
+  ready-made Status Tiles set (`status-tiles-examples.json`) that a
+  boat owner copies into their panel with one tap — no JSON editing,
+  no hand-authoring predicates. The set exposes the underway DR
+  integrity tile: the sensor-health and divergence-advisory
+  notifications, the DR-override (`navigation.deadReckoning.active`)
+  state, and banded checks on the uncertainty radius (1 nm warn / 3 nm
+  crit) and time-since-fix (3 h / 6 h), with footer readouts for
+  uncertainty, DR–GPS divergence, and the DR method. It is advertised
+  through the standard resources API as a read-only
+  `statusTileExamples` provider (keyed by the plugin id, returning `{}`
+  when stopped so a disabled plugin contributes no stale sets),
+  which the signalk-status-tiles webapp discovers and offers as a
+  one-tap "Add" that merges into the user's config (skipping existing
+  ids — idempotent, never overwrites user edits). Mirrors the existing
+  plotter-extension provider pattern; no running server is required to
+  ship or consume it.
+- **Shadow vessel on chart plotters (work doc #21)** — the DR
+  shadow-boat position is now published as a synthetic vessel on a
+  stable `vessels.<uuid>` context, so chart plotters that source
+  vessels from the Signal K stream (Freeboard-SK's AIS layer) render
+  it on the chart alongside the own vessel and AIS traffic, with a
+  projected COG line. Freeboard-SK draws it as a green `ais_buddy`
+  target — the only per-target data-driven visual lever in its AIS
+  style decision tree is the `buddy` flag, which the plugin sets on the
+  root-value delta. The gap between the shadow's heading (bow) and its
+  COG line visualizes set + leeway, mirroring how the plotter treats
+  the own vessel. Opt-in via *Shadow Vessel* in the plugin settings
+  (off by default); the configurable label defaults to "DR Shadow".
+  The plugin stays the source of truth — the shadow is an additional
+  chart-visible target, not a navigational authority. The context UUID
+  is generated once and persisted so the plotter's target id is
+  continuous across restarts. While DR is idle (moored, no speed or
+  heading) the shadow keeps publishing the last position at SOG 0 so
+  it doesn't vanish or go stale, and the COG line clears. No
+  Freeboard-SK change is required.
+- **Vector chart tiles in the webapp map (work doc #20)** — charts
+  with `format: 'pbf'` in the server's configured charts resource
+  (NOAA ENC-derived S-57 MBTiles, an Open Waters passage cache, any
+  vector MBTiles served by `signalk-charts-provider-simple`) now
+  render instead of failing silently as broken image tiles. MapLibre
+  GL JS 5.24.0 and the official Leaflet bridge are vendored under
+  `public/vendor/maplibre-gl/` (same policy as Leaflet — no CDN, no
+  build step) and mounted via `L.maplibreGL`, so all DR overlays stay
+  plain Leaflet. When the corridor downloader's asset manifest
+  (`/plugins/signalk-corridor-tile-downloader/assets/manifest.json`)
+  advertises a mirrored Open Waters `style` URL, that style is mounted
+  wholesale — full marine symbology (buoys by shape and colour,
+  lights, restricted-area hatching), bathymetry contours and soundings
+  with labels, base map and hillshade, online and offline alike —
+  while terrarium-DEM (`webp`) stores stay mirror internals and never
+  appear as overlays. For sources without a manifest the style is
+  composed client-side by the pure `maplibreStyleFor` (view-model):
+  one vector source on the chart's absolute tile URL (MapLibre's
+  blob-URL workers can't resolve relative paths) with native max zoom
+  — vector charts keep rendering past the raster maxNativeZoom
+  ceiling — plus a dark sea background and geometry-only
+  fill/line/circle layers with marine styling for known source-layer
+  families (S-57 LNDARE/DEPARE/DEPCNT/COALNE/SOUNDG ids and the
+  OSM-marine names the corridor cache carries: seamark, waterway,
+  wetland, sea_area, light as amber dots). Chart-mount failures are
+  logged instead of vanishing. Right-clicking a charted symbol
+  (lighthouse, seamark, peak, island) resolves its charted name and
+  seeds the sight form's *Object* field — bearings are taken to
+  identified objects, not bare coordinates.
+- **Plotter-extension status tile for Freeboard-SK (work doc #19)** —
+  the plugin now registers a `plotterExtensions` resource provider
+  (Plotter Extensions API v1) so chart plotters that host the
+  mechanism (Freeboard-SK ≥ 3.0) offer a "Dead Reckoning" widget:
+  a 2×1 glanceable tile showing GPS↔DR divergence, the DR uncertainty
+  radius, fix cadence and DR health (tracking / maneuver / fouled /
+  stale / warm), colored by severity like the webapp status line, with
+  an OVERRIDE badge when DR is authoritative and an amber night-mode
+  palette following the host's `nightMode` capability. Live values
+  arrive through the host's multiplexed Signal K relay (the tile opens
+  no connection of its own). The iframe assets are served from a new
+  publicly readable `/plotterext/signalk-dead-reckoning/` route (a
+  minimal in-repo static handler — the plugin stays zero-dependency);
+  discovery is the authenticated resources API, enablement is the
+  plugin's own enable switch. The bus client
+  (`signalk-plotterext-bus` 0.11.0, MIT) is vendored under
+  `public/vendor/plotterext-bus/` like Leaflet. The standalone webapp
+  is unaffected.
+
+## [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,41 @@
 # 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.
+
+## Requirements
+
+* This plugin installed and configured
+* Some chart source available to Signal K
+* Hand bearing compass and/or sextant
+
+## Getting started
+
+1. Install the plugin from the Signal K Appstore (or `npm install @meri-imperiumi/signalk-dead-reckoning`) and enable it. The defaults are sane — you only need to revisit the configuration if you want to change intervals or integrations.
+2. Make sure the required data feeds are available on the vessel network:
+   * `navigation.position` (GPS) — the training baseline and anomaly reference
+   * `navigation.speedThroughWater` (paddlewheel log) and `navigation.headingMagnetic` (compass + variation) — the water-track inputs
+   * Wind data — used by the calibration model and the polar speed fallback
+3. Just sail. While GPS is reliable and you're under sail (propulsion stopped), the engine continuously learns vessel-specific leeway and speed-loss corrections against GPS ground truth. There is nothing to activate: the "shadow boat" runs at all times, and the uncertainty polygon tightens over a season as the calibration bins fill up. Early on, expect conservative uncertainty estimates.
+4. Optional integrations, configured in the plugin settings:
+   * `signalk-logbook` — write confirmed fixes and maneuvers to the vessel's logbook
+   * `signalk-polar-performance-plugin` — polar-derived speed when the paddlewheel is fouled or silent
+   * `@meri-imperiumi/signalk-autostate` — keeps the navigation state (anchored, sailing, motoring) accurate, which gates training
+   * Signal K Weather API — point-forecast current vectors for the DR solution
+
+## Daily use
+
+Open the webapp from your Signal K server's *Web apps* menu. It shows the vessel and the shadow boat on the chart, GPS↔DR divergence, the uncertainty polygon, and the water-track log. A status tile is also available for Freeboard-SK ≥ 3.0.
+
+**Entering fixes.** Open *⊕ Sight / LOP* and pick the method:
+
+* **Bearing** — compass bearing to a known object (lighthouse, tower) gives a line of position
+* **Vert. Angle** — vertical angle to a known object of known height gives a circular position line
+* **Celestial** — sextant sight of the Sun, Moon, or an almanac star
+
+You can right-click an object on the map to pre-fill its coordinates. Sights can be entered with a stopwatch delay ("minutes ago") instead of clock time. Observations accumulate in the pending list; select two or more, *Preview selected* to resolve the candidate fix, then *Confirm fix* to snap dead reckoning to it. A single line of position can also be advanced to a later sight (running fix).
+
+**When GPS looks wrong.** The plugin raises notifications for GPS anomalies, growing DR divergence, and paddlewheel fouling — but it never switches navigational authority by itself. If you decide to trust DR over GPS, press *Engage OVERRIDE*; the shadow boat takes over `navigation.position` instantly (it has been running all along). Release it when position is re-established, e.g. after confirming a fix.
+
+**Other controls.** *≋ Current* sets a manual set-and-drift override with a TTL, which outranks the automatic current sources while it lasts.

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