speedandcurrent 2.4.0 → 2.5.0

package/CHANGELOG.md

@@ -0,0 +1,204 @@
+# Changelog
+
+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.1.0/),
+
+## [2.5.0] - 2026-10-26
+
+### Added
+- Correction-table files now use version 2 with per-cell update timestamps, capped time-based aging, and silent migration of existing version-1 files.
+- The webapp now polls at the plugin's actual sample rate instead of a fixed 1s interval, reported via a new `pollIntervalMs` field on `/api/report`.
+- Correction estimates now fuse mature nearby table cells using their full covariance and normalized distance, with an automatically estimated spatial variance, a two-cell search radius, and fusion-weight diagnostics in the webapp.
+- The correction table now overlays the current uncorrected (raw) and corrected speed/heel as red and blue dots positioned directly on the grid, with a matching legend entry.
+
+### Changed
+- The npm package now includes this changelog.
+- Updated the `signalkutilities` dependency to `^3.2.0`, including non-finite sample protection, explicit-null smoother resets, and subscription-manager-controlled startup values.
+- Requires signalk-server >=2.35.0 for the upstream metadata-first subscription fix ([SignalK/signalk-server#3216](https://github.com/SignalK/signalk-server/pull/3216)).
+- Read-only Signal K users can now access live reports, status, and metadata; settings and correction-table listing or changes remain administrator-only.
+- Correction-table learning no longer incorporates the estimated current, and the related setting has been removed.
+- Correction-table process noise is now configured as a user-facing correction drift rate in knots/month, with a conservative default of 0.3 and an SI conversion internally. Legacy stability settings migrate silently.
+- Correction interpolation now includes mature cells within 2.5 normalized grid-cell units.
+- Correction learning now always uses a moving-average window of at least 5 seconds, with a one-second gap between observation windows. Older smoother selections migrate silently.
+- Cells become eligible after one accepted observation; the explicit maturity gate remains in place at zero for future tuning.
+
+### Fixed
+- Removed idle-triggered input resubscriptions, including boat-speed inputs, to avoid replaying cached values during sensor outages. Idle/stale warnings remain, and existing subscriptions receive data when the source resumes. Synchronous startup safeguards are preserved.
+- The boat-speed estimation inputs now prioritize Boatspeed unless groundspeed fallback is selected, and the correction table marks its most recently updated cell with a thin black border reflected in the legend.
+- The learning status Reason row is now hidden when the last observation was accepted, instead of showing a redundant "Observation recorded" message.
+- `navigation.state` no longer misreports as "not ready" a few seconds after each update; it is an event path that only publishes on transition, so the generic telemetry staleness timer no longer applies to it. The Inputs tab now also displays its current value.
+- Learning and leeway are now gated on the vessel's own SOG-based moving/not-moving state, rather than solely on `navigation.state` freshness. Previously, an infrequent `navigation.state` update could go stale within seconds, silently letting learning continue while anchored or moored. `navigation.state`, when known and `suspendLearningOnNavigationState` is enabled, can still override to "not moving" (anchored/moored/motoring), but can no longer force "moving" against the vessel's own SOG.
+- Webapp report parsing failures now remain visible and still refresh plugin status instead of aborting the polling tick.
+- Disabled current estimation no longer publishes a zero-current value during plugin startup.
+- Malformed correction tables now recover safely at startup, while explicit loads reject invalid files without replacing the active table.
+- The correction-table Kalman filter now uses each observation's own measurement-noise covariance (already computed from live sensor variances) instead of a fixed identity matrix, so anisotropic and rotated observation uncertainty is correctly reflected in cell covariances. Persisted tables store a serializable model descriptor rather than the runtime model; existing table files still load unchanged.
+
+## [2.3.4] - 2026-09-17
+
+### Fixed
+- Boat-speed startup now preserves synchronously replayed cached values, avoids restart errors, and keeps current estimation behind the startup stabilization period regardless of table-learning settings.
+- Attitude roll handling now treats incomplete or stale values as invalid during correction-table learning, preventing fabricated heel-based corrections while the input is not yet usable.
+- Webapp values and warnings now share per-path lifecycle status, distinguish subscribed and computed data, report polar magnitude and angle independently, and show stale raw inputs consistently across all pages.
+
+## [2.3.3] - 2026-09-06
+
+### Fixed
+- `navigation.leewayAngle` no longer reports a correction-table artifact when the vessel is stationary. The lateral component of the table correction is now suppressed below the table speed step and while `navigation.state` is `anchored` or `moored`, so leeway is published as 0 instead of an angle derived from a near-zero speed. The longitudinal speed correction, and leeway while motoring, are unaffected.
+- Updated `signalkutilities` to 3.1.2, which completes the 3.1.1 recovery fix for polar-backed inputs. Smoothed heading and the ground-speed vector are built on `Polar`/`PolarSmoother`, where the idle timer was still cleared rather than re-armed on each delta, so those inputs did not recover after going silent following a healthy start.
+
+## [2.3.2] - 2026-09-04
+
+### Fixed
+- Updated `signalkutilities` to 3.1.1, so an input that goes silent *after* having delivered data is now detected and resubscribed. Previously recovery only ran for subscriptions that had never received a delta, meaning an upstream outage after a healthy start could leave the plugin dead until it was restarted.
+
+## [2.3.1] - 2026-08-18
+
+### Fixed
+- Signal K admin styling now loads from standalone CSS records in current Vite manifests while retaining support for entry-associated CSS and older server fallbacks.
+
+## [2.3.0] - 2026-08-16
+
+### Added
+- Learning status now distinguishes between active learning and observations that were skipped, rejected, or invalid, and the webapp reports the current reason more clearly.
+
+### Changed
+- Correction-table learning now uses automatic gates based on `navigation.state`, with `anchored` and `moored` always suspending learning when available and `motoring` optionally suspending it.
+- The learning threshold for both STW and SOG now follows the active table speed-step size.
+- The webapp no longer exposes a separate minimum-SOG learning setting.
+
+### Fixed
+- When learning is off or suspended, the webapp no longer keeps showing a stale previous observation result.
+
+## [2.2.1] - 2026-08-14
+
+### Fixed
+- Input subscriptions now recover automatically after idle or stale periods, and the webapp exposes lifecycle warnings for affected paths.
+- Corrected output paths are now explicitly cleared with `null` when estimation is disabled or when the plugin stops, preventing stale values from lingering on the Signal K bus.
+- The webapp-facing status and report endpoints now reflect the plugin's current runtime state more directly.
+- SOG fallback now checks raw STW (`rawBoatSpeed`) directly when detecting a zero paddlewheel reading, avoiding dependence on the derived corrected speed value.
+
+## [2.1.2] - 2026-07-23
+
+### Fixed
+- App Store icon was missing (monogram fallback shown): added `icon.png` at the package root so the App Store CDN can fetch it from the npm tarball via unpkg.com. The runtime `signalk.appIcon: ./icon.png` path is unchanged - the server still serves it from `public/icon.png` via the webapp mount.
+- Updated `signalkutilities` to 3.0.1, fixing continuous 401 log flooding on SK servers with security enabled and anonymous read access disabled.
+
+## [2.1.1] - 2026-07-20
+
+### Fixed
+- Sidebar toggler was unreachable on mobile viewports.
+
+### Changed
+- Updated `signalkutilities` dependency to `^3.0.0` (removes `PolarTable` from the shared library; no behaviour change for this plugin).
+
+## [2.1.0] - 2026-07-10
+
+### Added
+- `null` is written to corrected boat speed (`navigation.speedThroughWater`, `navigation.leewayAngle`) and current (`environment.current.drift`, `environment.current.setTrue`) paths when `estimateBoatSpeed` is toggled off.
+- `null` is written to all active output paths (current, corrected boat speed) when the plugin stops, preventing stale values on the SK bus.
+
+## [2.0.2] - 2026-6-18
+### Fixed
+- The plugin icon was not displayed in the Signal K App Store because the icon path in the package metadata was incorrect.
+- Test files are no longer included in the published npm package.
+
+## [2.0.1] - 2026-6-17
+### Fixed
+- Correction table reporting was doing unnecessary work on every update, causing higher CPU use especially on low-power hardware such as a Raspberry Pi.
+- The variance values used for interpolating between correction table cells were calculated with an incorrect formula, causing them to be overestimated. This made the Kalman outlier gate slightly less accurate.
+
+## [2.0.0] - 2026-6-17
+### Changed
+- Moving average smoother is now O(1) in both CPU and memory: it no longer slows down or uses more memory as the window size grows.
+
+- **Breaking:** Requires `signalkutilities` v2.0.0. Source-selection and pass-through machinery has been removed from the library; Signal K Server now handles source priorities natively.
+- Per-path source settings (`headingSource`, `boatSpeedSource`, `SOGSource`, `attitudeSource`) have been removed. Use Signal K Server's built-in source priority configuration instead.
+- The **Prevent Speed Duplication** setting has been removed. The server's `excludeSelf` behaviour and source priorities replace it.
+
+### Removed
+- Source dropdowns in the webapp Inputs section.
+- Source-related fields from persisted plugin configuration. A one-time migration strips these fields automatically on first start with the new version.
+
+### Added
+- Documentation explaining how to configure Signal K source priorities so that the corrected `navigation.speedThroughWater` is delivered to all consumers.
+
+## [1.7.10] - 2026-5-14
+### Fixed
+- Removed incorrect `self.` prefix from Signal K paths.
+
+## [1.7.9] - 2026-5-14
+### Added
+- Learning status indicator in the webapp showing whether the correction table is active, stabilising, or off, and whether the last observation was accepted, rejected, invalid, or below threshold.
+- Outlier rejection using Mahalanobis distance: bad observations are discarded before being fed into the Kalman filter, preventing a single bad sample from corrupting a cell.
+
+### Fixed
+- Smoothed learning inputs are now always registered in the reporter regardless of whether `updateCorrectionTable` is enabled, so warnings clear correctly when learning is toggled on at runtime.
+
+## [1.7.8] - 2026-5-14
+### Added
+- Legend below the correction table explaining factor / leeway values, background colour coding, stripe direction, active cell, and neighbour cell indicators.
+
+### Fixed
+- Correction table learning never started when `assumeCurrent` is off.
+- Active cell highlighting (most recently updated cell) was not visible.
+
+## [1.7.7] - 2026-5-13
+### Added
+- Optional staleness detection for inputs.
+- Precise warnings on state of inputs.
+
+## [1.7.5] - 2025-11-19
+### Added
+- New webApp.
+- WebApp allows to change plugin configuration while the plugin is running.
+- Support for multiple correction tables (new, copy, delete).
+- Support for altering the dimensions of a correction table (alter).
+- Better edge case handling.
+- User selectable options for smoothing method and smoothing parameters.
+- Support for unitPreferences.
+
+### Fixed
+- Bug where navigation.speedThroughWater was removed from the signalk bus.
+
+### Removed
+- Possibility to set options via the signalk plugin configuration.
+
+## [1.6.0] - 2025-11-19
+### Added
+- Option to copy navigation.speedOverGround to navigation.speedThroughWater when speedThroughWater is not properly measured. Thanks to Jean-Laurent Girod for the suggestion.
+
+## [1.5.1] - 2025-10-06
+### Fixed
+- Bug preventing current to be displayed in KIP.
+
+## [1.5.0] - 2025-10-06
+### Changed
+- Separate loops for correcting speed and for updating correction factors.
+- Speed correction loop uses raw values.
+- Updating correction factors using moving averages.
+- Unified cell rendering driven by "Show" selections; removed the previous Table style toggle.
+
+### Added
+- Option to set the source for input paths.
+- Full integration of uncertainty estimations (variance) in estimations and corrections.
+- Ability to resize the correction table without losing all correction data.
+- WebApp: "Show" multi-select to choose per-cell metrics (correction X/Y, factor, leeway, trace, N) for the correction table.
+- WebApp: Color mode options for the correction table.
+- WebApp: Persistence for speed unit, angle unit, color mode, and shown metrics via localStorage.
+
+### Fixed
+- Angles are now reported in the appropriate range, 0 to 2 * PI or -PI to PI, depending on path.
+
+## [1.1.0] - 2025-8-20
+### Changed
+- Path names for current. It now is self.environment.current.setTrue and self.environment.current.drift.
+
+### Fixed
+- Case error in filename that prevented the webapp from displaying the correction table.
+- Corrected speed through water is now calculated when the correction table is fixed.
+
+## [1.0.1] - 2025-1-27
+### Added
+- Basic functionality to estimate speed, leeway and current using Kalman filters.
+- Basic functionality for a webapp that shows what is going on.

package/README.md

@@ -6,7 +6,9 @@ Most paddle wheel logs carry a systematic error that varies with boat speed and
 
 This plugin builds and maintains a **2-dimensional correction table** — indexed by speed and heel — that is populated automatically from real sailing observations. No calibration runs, no spreadsheets, no manual entry. Once the table has enough coverage the plugin applies per-point corrections to `navigation.speedThroughWater`, derives leeway from the lateral component of the correction, and estimates water current by subtracting the corrected boat speed vector from the GPS ground speed vector.
 
-In the current implementation the plugin is also explicit about runtime state: if an input goes idle or stale, the webapp shows a warning and the handler resubscribes; when estimation is disabled or the plugin stops, the active output paths are cleared with `null` so downstream consumers do not keep stale values.
+Requires signalk-server >=2.35.0 for reliable metadata-first input subscriptions.
+
+If an input goes idle or stale, the webapp shows a warning while the subscription stays attached, ready for the next delta; when estimation is disabled or the plugin stops, the active output paths are cleared with `null` so downstream consumers do not keep stale values.
 
 In broad terms the plugin:
 
@@ -31,6 +33,12 @@ The plugin requires no further configuration in the Signal K admin UI. All setti
 
 ---
 
+## HTTP endpoint access
+
+Signal K read-only users can access the live report (`/api/report`), metadata (`/api/meta`), and status (`/api/status`) endpoints. Settings (`/api/settings`) and correction-table listing or management (`/api/tables...`) require administrator access. Anonymous requests still follow the server's configured security policy; this plugin does not enable anonymous access.
+
+---
+
 ## Configuring Signal K source priorities
 
 Signal K Server manages source priorities natively. When multiple devices publish the same path, the server delivers the highest-priority source to all subscribers — including this plugin. No per-path source selection is needed inside the plugin itself.
@@ -289,7 +297,7 @@ Every time conditions are right — plugin running for >60 seconds, smoothers se
 observation = R(ψ)⁻¹ · V_SOG − R(ψ)⁻¹ · V_current − V_STW
 ```
 
-where `R(ψ)` rotates from ground frame to boat frame using true heading `ψ`. In plain terms: rotate GPS velocity into the boat frame, subtract the raw paddle wheel velocity. The residual is the implied sensor error for the current speed and heel.
+where `R(ψ)` rotates from ground frame to boat frame using true heading `ψ`. In plain terms: rotate GPS velocity into the boat frame, subtract the current estimate (also rotated), subtract the raw paddle wheel velocity. The residual is the implied sensor error for the current speed and heel.
 
 The Kalman update combines this observation with the cell's existing belief:
 
@@ -298,11 +306,11 @@ K = P · (P + R_obs)⁻¹
 x_new = x_old + K · (observation − x_old)
 ```
 
-where P is the cell's current covariance and R_obs is the observation covariance derived from the measurement uncertainty of all contributing signals (SOG variance + STW variance, rotated appropriately). It also includes heading uncertainty in radians squared. For $u = R(-heading)(groundSpeed - current)$, the heading contribution is $J \sigma_h^2 J^T$, where $J = [u_y, -u_x]^T$. This is applied once to the combined ground-speed-minus-current vector because both vectors share the same heading error. **Noisy observations produce a smaller gain and move the cell estimate less.**
+where P is the cell's current covariance and R_obs is the observation covariance derived from the measurement uncertainty of all contributing signals (SOG variance + current variance + STW variance, rotated appropriately). It also includes heading uncertainty in radians squared. For $u = R(-heading)(groundSpeed - current)$, the heading contribution is $J \sigma_h^2 J^T$, where $J = [u_y, -u_x]^T$. This is applied once to the combined ground-speed-minus-current vector because both vectors share the same heading error. **Noisy observations produce a smaller gain and move the cell estimate less.**
 
 ### Time-scaled aging and correction drift
 
-Each cell has a small **process-noise rate** that allows it to drift slowly over time, reflecting that a paddle wheel's error can change. For an elapsed interval `dt`, the process covariance added to each diagonal is:
+Each cell has a small **process-noise rate** that allows it to drift slowly over time, reflecting that a paddle wheel's error can change with fouling, recalibration, or crew weight distribution. For an elapsed interval `dt`, the process covariance added to each diagonal is:
 
 ```text
 effectiveDt = min(dt, 90 days)

package/index.js

@@ -385,7 +385,7 @@ module.exports = function (app) {
   function setLifecycleWarning(id, status, path) {
     const safePath = path || 'unknown path';
     const message = status === 'idle'
-      ? `Input ${id} is idle on ${safePath}; resubscribing`
+      ? `Input ${id} is idle on ${safePath}`
       : status === 'incomplete'
       ? `Input ${id} is missing ${safePath}`
       : `Input ${id} is stale on ${safePath}`;
@@ -407,7 +407,7 @@ module.exports = function (app) {
       .sort((a, b) => b.updatedAt - a.updatedAt);
   }
 
-  function buildLifecycleCallbacks(id, getPath, resubscribe) {
+  function buildLifecycleCallbacks(id, getPath) {
     return {
       onDelta: () => {
         clearLifecycleWarning(id);
@@ -421,13 +421,8 @@ module.exports = function (app) {
       onIdle: () => {
         if (!isRunning) return;
         const path = getPath();
-        app.debug(`[${plugin.id}] idle input ${id} on ${path}; resubscribing`);
+        app.debug(`[${plugin.id}] idle input ${id} on ${path}`);
         setLifecycleWarning(id, 'idle', path);
-        try {
-          resubscribe();
-        } catch (e) {
-          app.debug(`[${plugin.id}] resubscribe failed for ${id}: ${e.message}`);
-        }
       }
     };
   }
@@ -448,7 +443,7 @@ module.exports = function (app) {
     app.debug('registerWithRouter');
     readOptions(); // pre-load so /api/settings works before start()
 
-    router.get('/api/report', (req, res) => {
+    router.access('readonly').get('/api/report', (req, res) => {
       if (!isRunning) {
         res.status(503).json({ error: "Plugin is not running" });
       } else {
@@ -462,7 +457,7 @@ module.exports = function (app) {
       }
     });
 
-    router.get('/api/meta', (req, res) => {
+    router.access('readonly').get('/api/meta', (req, res) => {
       if (!isRunning) {
         res.status(503).json({ error: "Plugin is not running" });
       } else {
@@ -472,7 +467,7 @@ module.exports = function (app) {
 
 
 
-    router.get('/api/status', (req, res) => {
+    router.access('readonly').get('/api/status', (req, res) => {
       res.json({ status: pluginStatus, isRunning, lifecycleWarnings, learningState: getLearningStatePayload() });
     });
 
@@ -653,8 +648,7 @@ module.exports = function (app) {
       smootherOptions,
       ...buildLifecycleCallbacks(
         'heading.angle',
-        () => smoothedHeading?.handler?.path || 'navigation.headingTrue',
-        () => { smoothedHeading?.unsubscribe(); smoothedHeading?.subscribe(false, true); }
+        () => smoothedHeading?.handler?.path || 'navigation.headingTrue'
       )
     });
     rawHeading = smoothedHeading.handler;
@@ -669,8 +663,7 @@ module.exports = function (app) {
       smootherOptions,
       ...buildLifecycleCallbacks(
         'attitude.smoothed',
-        () => smoothedAttitude?.handler?.path || 'navigation.attitude',
-        () => { smoothedAttitude?.unsubscribe(); smoothedAttitude?.subscribe(); }
+        () => smoothedAttitude?.handler?.path || 'navigation.attitude'
       )
     });
     rawAttitude = smoothedAttitude.handler;
@@ -776,10 +769,8 @@ module.exports = function (app) {
       onIdle: () => {
         if (!isRunning) return;
         const path = smoothedBoatSpeed?.handler?.path || 'navigation.speedThroughWater';
-        app.debug(`[${plugin.id}] idle input boatSpeed.smoothed on ${path}; resubscribing`);
+        app.debug(`[${plugin.id}] idle input boatSpeed.smoothed on ${path}`);
         setLifecycleWarning('boatSpeed.smoothed', 'idle', path);
-        smoothedBoatSpeed?.unsubscribe();
-        smoothedBoatSpeed?.subscribe();
       },
       onStale: () => {
         if (!isRunning) return;
@@ -820,8 +811,7 @@ module.exports = function (app) {
       smootherOptions,
       ...buildLifecycleCallbacks(
         'groundSpeed.smoothed',
-        () => `${smoothedGroundSpeed?.polar?.pathMagnitude || 'navigation.speedOverGround'}, ${smoothedGroundSpeed?.polar?.pathAngle || 'navigation.courseOverGroundTrue'}`,
-        () => { smoothedGroundSpeed?.unsubscribe(); smoothedGroundSpeed?.subscribe(true, true); }
+        () => `${smoothedGroundSpeed?.polar?.pathMagnitude || 'navigation.speedOverGround'}, ${smoothedGroundSpeed?.polar?.pathAngle || 'navigation.courseOverGroundTrue'}`
       )
     });
     rawGroundSpeed = smoothedGroundSpeed.polar;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "speedandcurrent",
-  "version": "2.4.0",
+  "version": "2.5.0",
   "description": "A plugin that automatically corrects boat speed and calculates current and leeway using sensor fusion.",
   "main": "index.js",
   "scripts": {
@@ -18,7 +18,7 @@
   "homepage": "https://github.com/Asw1n/speedandcurrent#readme",
   "engines": {
     "node": ">=22.0.0",
-    "signalk-server": ">=2.28.0"
+    "signalk-server": ">=2.35.0"
   },
   "keywords": [
     "signalk-webapp",
@@ -41,9 +41,10 @@
   },
   "dependencies": {
     "kalman-filter": "^2.3.0",
-    "signalkutilities": "^3.1.6"
+    "signalkutilities": "^3.2.0"
   },
   "files": [
+    "CHANGELOG.md",
     "icon.png",
     "index.js",
     "correctionTable.js",