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

package/CHANGELOG.md

@@ -5,6 +5,93 @@ 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

package/README.md

@@ -3,3 +3,39 @@
 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@meri-imperiumi/signalk-dead-reckoning",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Offline-first dead reckoning and sensor fusion engine for Signal K",
   "main": "plugin/index.js",
   "scripts": {

package/plugin/index.js

@@ -79,6 +79,12 @@ const {
 const { resolveCandidateFix, confirmFix } = require("./fix-pipeline.js");
 const { reduceSight, reduceNoonSight } = require("./celestial.js");
 const starAlmanac = require("./star-almanac.js");
+const { registerPlotterExtension } = require("./plotterext.js");
+const { registerStatusTileExamples } = require("./statustilesexamples.js");
+const {
+  createShadowVesselPublisher,
+  resolveVelocity: resolveShadowVelocity,
+} = require("./shadow-vessel.js");
 const { computeRadius } = require("./uncertainty.js");
 const {
   DEFAULT_FACTOR,
@@ -297,6 +303,18 @@ const DEFAULT_CONFIG = {
     baseUrl: "", // empty → http://localhost:<server port>
     intervalMs: 1800000,
   },
+  /**
+   * Shadow vessel (work doc #21): publish the DR position as a synthetic
+   * `vessels.<id>` target so chart plotters (Freeboard-SK's AIS layer)
+   * render the shadow boat on the chart. Opt-in — off by default. The
+   * `buddy` flag is hardcoded on (it's the distinctness mechanism, not a
+   * preference): Freeboard-SK's only per-target data-driven visual lever
+   * is the buddy flag → the green ais_buddy glyph.
+   */
+  shadowVessel: {
+    enabled: false,
+    name: "DR Shadow",
+  },
 };
 
 /**
@@ -357,6 +375,8 @@ const deps = {
   createPolarSpeedState,
   polarSpeedSample,
   polarSpeedAverage,
+  createShadowVesselPublisher,
+  resolveShadowVelocity,
   distanceNm,
   bearingDeg,
 };
@@ -397,6 +417,15 @@ module.exports = (app) => {
   /** @type {WeatherCurrentClient|null} §6.2 tier-3 weather current poller */
   let weatherClient = null;
 
+  /** @type {(() => void)|null} plotter-extension provider teardown (work doc #19) */
+  let plotterExtTeardown = null;
+
+  /** @type {(() => void)|null} status-tiles examples provider teardown (work doc #22) */
+  let statusTileExamplesTeardown = null;
+
+  /** @type {{publish: Function, stop: Function}|null} shadow vessel publisher (work doc #21) */
+  let shadow = null;
+
   /**
    * Manual set-and-drift override (§6.2 tier 1): watchstander input,
    * honored while its TTL lasts. Set/cleared via
@@ -585,6 +614,18 @@ module.exports = (app) => {
           title: "Polar speed staleness cutoff (s)",
           default: DEFAULT_CONFIG.polar.staleS,
         },
+        "shadowVessel.enabled": {
+          type: "boolean",
+          title: "Show the DR shadow boat on chart plotters",
+          description:
+            "Publishes the DR position as a synthetic vessel (a green 'buddy' target on Freeboard-SK) so chart plotters that source vessels from the Signal K stream render the shadow boat on the chart alongside your own vessel, with a projected COG line. The plugin stays the source of truth; this only adds a chart-visible target.",
+          default: DEFAULT_CONFIG.shadowVessel.enabled,
+        },
+        "shadowVessel.name": {
+          type: "string",
+          title: "Shadow vessel label",
+          default: DEFAULT_CONFIG.shadowVessel.name,
+        },
       },
     },
 
@@ -615,6 +656,10 @@ module.exports = (app) => {
         ...DEFAULT_CONFIG.polar,
         ...(options?.polar ?? {}),
       };
+      config.shadowVessel = {
+        ...DEFAULT_CONFIG.shadowVessel,
+        ...(options?.shadowVessel ?? {}),
+      };
 
       dbPath = join(app.getDataDirPath(), "dead-reckoning.sqlite");
       db = deps.openDatabase(dbPath);
@@ -700,6 +745,24 @@ module.exports = (app) => {
       const logSinceOrigin = deps.getState(db, "dr_log_since_origin");
       if (logSinceOrigin) engine.logNmSinceOrigin = Number(logSinceOrigin) || 0;
 
+      // Shadow vessel (work doc #21): publish the DR position as a synthetic
+      // vessels.<id> target so chart plotters render it. The context is a
+      // stable UUID persisted across restarts so the plotter's target id
+      // is continuous (no flicker/age-out on restart). Generated once and
+      // reused — never collides with a real AIS target.
+      if (config.shadowVessel.enabled) {
+        let shadowCtx = deps.getState(db, "shadow_vessel_context");
+        if (!shadowCtx) {
+          shadowCtx = `vessels.urn:mrn:signalk:uuid:${crypto.randomUUID()}`;
+          deps.setState(db, "shadow_vessel_context", shadowCtx);
+        }
+        shadow = deps.createShadowVesselPublisher({
+          app,
+          context: shadowCtx,
+          name: config.shadowVessel.name,
+        });
+      }
+
       initLogbook();
 
       // Subscribe to the sensor inputs the engine needs.
@@ -738,6 +801,22 @@ module.exports = (app) => {
       publishMeta();
       setStatus("Dead reckoning started");
 
+      // Plotter-extension host integration (work doc #19): advertise
+      // the status-tile manifest to chart plotters (Freeboard-SK ≥3.0)
+      // and serve the iframe assets at a public, non-admin-gated route.
+      plotterExtTeardown = registerPlotterExtension(app, {
+        id: PLUGIN_ID,
+      });
+
+      // Status Tiles example-set provider (work doc #22): advertise
+      // the DR position tile set so the Status Tiles webapp offers it
+      // as a one-tap "Add" that merges into the user's panel. Read-only,
+      // running-gated — returns {} when stopped so a disabled plugin
+      // contributes no stale sets.
+      statusTileExamplesTeardown = registerStatusTileExamples(app, {
+        id: PLUGIN_ID,
+      });
+
       // Public config endpoint (CONFIG_PATH): mounted on the app so
       // anonymous / read-only clients can read the plugin config
       // (incl. positionFormat) without admin auth. Mirrors
@@ -793,6 +872,12 @@ module.exports = (app) => {
       weatherClient?.stop();
       weatherClient = null;
       training = null;
+      plotterExtTeardown?.();
+      plotterExtTeardown = null;
+      statusTileExamplesTeardown?.();
+      statusTileExamplesTeardown = null;
+      shadow?.stop();
+      shadow = null;
       // Hygiene: clear a live advisory so it doesn't linger after the
       // plugin stops monitoring.
       if (divergence?.active) {
@@ -1067,6 +1152,14 @@ module.exports = (app) => {
         [PATHS.elapsedSinceFix]: engine.elapsedSinceOriginS,
         [PATHS.divergenceDistance]: null,
       });
+      // Shadow vessel (work doc #21): keep the shadow on the chart at the
+      // last position so it doesn't vanish or go stale while DR is idle.
+      // SOG=0 clears any previously-drawn COG line so it doesn't linger
+      // stale; heading/COG are omitted (the plotter retains the last
+      // values, which is honest — the shadow isn't moving).
+      if (shadow && engine.origin) {
+        shadow.publish({ position: engine.origin, sogMs: 0 });
+      }
       return;
     }
 
@@ -1348,6 +1441,29 @@ module.exports = (app) => {
           ? dvg.distance_nm * METRES_PER_NM
           : null,
       });
+
+      // Shadow vessel (work doc #21): emit the DR position + a derived
+      // COG/SOG so the plotter draws the shadow with a projected COG
+      // line. The velocity vector mirrors the engine's motion model
+      // (water-track + current) so the line projects consistently. Units
+      // are Signal K SI (rad, m/s), matching how the plugin publishes
+      // the own-vessel current vector above.
+      if (shadow && pos) {
+        const vel = deps.resolveShadowVelocity({
+          stwKn: effectiveStwKn,
+          headingTrueDeg,
+          leewayDeg: corrections.leeway_angle,
+          speedLoss: corrections.speed_loss,
+          current,
+        });
+        shadow.publish({
+          position: pos,
+          headingTrueRad:
+            headingTrueDeg != null ? degToRad(headingTrueDeg) : null,
+          cogRad: vel ? degToRad(vel.cogDeg) : null,
+          sogMs: vel ? knotsToMs(vel.sogKn) : null,
+        });
+      }
     }
   }
 

package/plugin/plotterext.js

@@ -0,0 +1,194 @@
+/**
+ * Plotter-extension host integration (Freeboard-SK and any Plotter
+ * Extensions API v1 chart plotter).
+ *
+ * Two server-side responsibilities (see freeboard-sk
+ * docs/api/plotter_extension_provider_plugins.md):
+ *
+ * 1. Register a read-only `plotterExtensions` resource provider whose
+ *    single entry is this plugin's manifest — the host discovers the
+ *    extension there. Presence in the collection *is* the enablement
+ *    signal: hosts must not add a second per-extension gate, and the
+ *    provider goes empty on plugin stop so the host tears the contexts
+ *    down.
+ * 2. Serve the extension's iframe assets at a publicly readable,
+ *    non-admin-gated route. `/plugins/*` is admin-only on the server, so
+ *    the manifest URLs point at a self-mounted namespaced prefix instead.
+ *    The assets are inert UI code — all data flows over the host bus.
+ *    Served by a minimal in-repo static handler rather than
+ *    `express.static`: the plugin is zero-dependency by design (SPEC §2)
+ *    and `express` is not resolvable from a plugin's own tree — only
+ *    from inside the server. The handler only needs to serve the small,
+ *    known-good set of files under `public/`.
+ *
+ * @file plotterext.js
+ */
+
+const path = require("node:path");
+const fs = require("node:fs");
+const pkg = require("../package.json");
+
+/**
+ * Directory holding the extension's iframe assets. The same `public/`
+ * the standalone webapp is served from (the webapp keyword mounts it at
+ * the package path); the extension entry pages live alongside the ES
+ * modules they import, so relative imports keep working under either
+ * mount.
+ */
+const PUBLIC_DIR = path.join(__dirname, "..", "public");
+
+/** Content types for the extension's asset kinds (inert UI code). */
+const MIME = {
+  ".html": "text/html; charset=utf-8",
+  ".js": "text/javascript; charset=utf-8",
+  ".mjs": "text/javascript; charset=utf-8",
+  ".css": "text/css; charset=utf-8",
+  ".png": "image/png",
+  ".svg": "image/svg+xml",
+  ".ico": "image/x-icon",
+  ".json": "application/json; charset=utf-8",
+  ".txt": "text/plain; charset=utf-8",
+};
+
+/**
+ * Builds the extension manifest.
+ *
+ * `requires` lists only what the tile genuinely cannot run without: the
+ * widget grid and the Signal K relay (a status tile with no data is dead
+ * weight). Night mode is used when present and guarded with
+ * `hasCapability` at runtime.
+ *
+ * @param {string} assetBase - server-relative URL prefix for assets
+ * @param {string} version - plugin version for display metadata
+ * @returns {object} manifest per the Plotter Extensions API v1
+ */
+function buildManifest(assetBase, version) {
+  return {
+    name: "Dead Reckoning",
+    description:
+      "Dead reckoning status tile: GPS↔DR divergence, uncertainty radius and DR health at a glance.",
+    version,
+    apiVersion: "1",
+    requires: ["widgets", "signalk.stream"],
+    optional: ["nightMode"],
+    widgets: [
+      {
+        id: "dr-status",
+        title: "Dead Reckoning",
+        type: "iframe",
+        url: `${assetBase}/dr-ext-widget.html`,
+        size: "2x1",
+        lifecycle: "whileEnabled",
+      },
+    ],
+  };
+}
+
+/**
+ * Minimal static-asset middleware for the extension's files. Not a
+ * general file server: only regular files directly under `root` are
+ * served (directory indexes and anything escaping `root` fall through).
+ *
+ * @param {string} root - absolute directory to serve
+ * @param {string} assetBase - mount prefix, stripped when the host did
+ *   not already strip it (Express strips it for `app.use(path, fn)`;
+ *   other hosts may pass the full path)
+ * @returns {(req: object, res: object, next: Function) => void}
+ */
+function staticAssetHandler(root, assetBase) {
+  const rootPrefix = root.endsWith(path.sep) ? root : root + path.sep;
+  return (req, res, next) => {
+    let urlPath = req.path ?? req.url ?? "/";
+    const q = urlPath.indexOf("?");
+    if (q >= 0) urlPath = urlPath.slice(0, q);
+    if (urlPath.startsWith(assetBase)) {
+      urlPath = urlPath.slice(assetBase.length);
+    }
+    if (!urlPath.startsWith("/")) urlPath = `/${urlPath}`;
+
+    let resolved;
+    try {
+      resolved = path.normalize(
+        path.join(rootPrefix, decodeURIComponent(urlPath)),
+      );
+    } catch {
+      next(); // malformed percent-encoding
+      return;
+    }
+    // Traversal guard: the resolved path must stay inside root.
+    if (!resolved.startsWith(rootPrefix)) {
+      next();
+      return;
+    }
+
+    fs.stat(resolved, (err, st) => {
+      if (err || !st.isFile()) {
+        next();
+        return;
+      }
+      res.statusCode = 200;
+      res.setHeader(
+        "Content-Type",
+        MIME[path.extname(resolved)] ?? "application/octet-stream",
+      );
+      res.setHeader("Cache-Control", "public, max-age=3600");
+      fs.readFile(resolved, (readErr, data) => {
+        if (readErr) {
+          next();
+          return;
+        }
+        res.end(data);
+      });
+    });
+  };
+}
+
+/**
+ * Registers the plotter-extension provider and mounts the asset route.
+ *
+ * @param {import("@signalk/server-api").ServerAPI} app - Signal K server API
+ * @param {{id: string, version?: string}} opts - plugin id (manifest key)
+ *   and optional version override (defaults to the package version)
+ * @returns {() => void} teardown — empties the provider's listing so
+ *   hosts unload the extension's contexts. The static asset mount stays
+ *   (Express has no unmount, and the files are inert); that matches the
+ *   webapp keyword's behaviour for a disabled plugin.
+ */
+function registerPlotterExtension(app, opts) {
+  const { id } = opts;
+  const version = opts.version ?? pkg.version;
+  const assetBase = `/plotterext/${id}`;
+  const manifest = buildManifest(assetBase, version);
+  let running = true;
+
+  app.registerResourceProvider({
+    type: "plotterExtensions",
+    methods: {
+      listResources: async () => (running ? { [id]: manifest } : {}),
+      getResource: async (resourceId) => {
+        if (!running || resourceId !== id) {
+          throw new Error(`No such plotterExtensions resource: ${resourceId}`);
+        }
+        return manifest;
+      },
+      setResource: async () => {
+        throw new Error(`${id} is a read-only provider`);
+      },
+      deleteResource: async () => {
+        throw new Error(`${id} is a read-only provider`);
+      },
+    },
+  });
+
+  app.use(assetBase, staticAssetHandler(PUBLIC_DIR, assetBase));
+
+  return () => {
+    running = false;
+  };
+}
+
+module.exports = {
+  buildManifest,
+  registerPlotterExtension,
+  staticAssetHandler,
+};