speedandcurrent 2.1.2 → 2.2.1

package/README.md

@@ -6,6 +6,8 @@ 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.
+
 In broad terms the plugin:
 
 - corrects paddle wheel speed using a learned, heel- and speed-aware correction table

package/index.js

@@ -38,8 +38,7 @@ module.exports = function (app) {
     smootherTau: 3,
     smootherTimeSpan: 5,
     smootherSteadyState: 0.2,
-    showStatistics: false,
-    stalenessDetection: true
+    showStatistics: false
   };
 
   
@@ -140,6 +139,56 @@ module.exports = function (app) {
   let started = null;
   let minSpeed = 0;
   let lastSave = 0;
+  let lifecycleWarningMap = new Map();
+  let lifecycleWarnings = [];
+
+  function setLifecycleWarning(id, status, path) {
+    const safePath = path || 'unknown path';
+    const message = status === 'idle'
+      ? `Input ${id} is idle on ${safePath}; resubscribing`
+      : `Input ${id} is stale on ${safePath}`;
+    lifecycleWarningMap.set(id, {
+      id,
+      status,
+      path: safePath,
+      message,
+      updatedAt: Date.now()
+    });
+    lifecycleWarnings = Array.from(lifecycleWarningMap.values())
+      .sort((a, b) => b.updatedAt - a.updatedAt);
+  }
+
+  function clearLifecycleWarning(id) {
+    if (!lifecycleWarningMap.has(id)) return;
+    lifecycleWarningMap.delete(id);
+    lifecycleWarnings = Array.from(lifecycleWarningMap.values())
+      .sort((a, b) => b.updatedAt - a.updatedAt);
+  }
+
+  function buildLifecycleCallbacks(id, getPath, resubscribe) {
+    return {
+      onDelta: () => {
+        clearLifecycleWarning(id);
+      },
+      onStale: () => {
+        if (!isRunning) return;
+        const path = getPath();
+        app.debug(`[${plugin.id}] stale input ${id} on ${path}`);
+        setLifecycleWarning(id, 'stale', path);
+      },
+      onIdle: () => {
+        if (!isRunning) return;
+        const path = getPath();
+        app.debug(`[${plugin.id}] idle input ${id} on ${path}; resubscribing`);
+        setLifecycleWarning(id, 'idle', path);
+        try {
+          resubscribe();
+        } catch (e) {
+          app.debug(`[${plugin.id}] resubscribe failed for ${id}: ${e.message}`);
+        }
+      }
+    };
+  }
 
   const plugin = {};
   plugin.id = "SpeedAndCurrent";
@@ -161,7 +210,9 @@ module.exports = function (app) {
       if (!isRunning) {
         res.status(503).json({ error: "Plugin is not running" });
       } else {
-        res.json(reportFull.report());
+        const payload = reportFull.report();
+        payload.lifecycleWarnings = lifecycleWarnings;
+        res.json(payload);
       }
     });
 
@@ -176,7 +227,7 @@ module.exports = function (app) {
 
 
     router.get('/api/status', (req, res) => {
-      res.json({ status: pluginStatus, isRunning });
+      res.json({ status: pluginStatus, isRunning, lifecycleWarnings });
     });
 
     // --- Settings API ---
@@ -305,6 +356,8 @@ module.exports = function (app) {
   plugin.start = (settings) => {
     setStatus('Starting');
     app.debug("Starting");
+    lifecycleWarningMap = new Map();
+    lifecycleWarnings = [];
     readOptions(); // pick up any saves since registerWithRouter ran
     migrateConfig(); // strip obsolete fields from persisted config
     const tableName = options.tableName || 'correctionTable';
@@ -320,12 +373,13 @@ module.exports = function (app) {
       angleRange: '0to2pi',
       meta: { displayName: 'Heading', plane: 'Ground' },
       SmootherClass,
-      smootherOptions
+      smootherOptions,
+      ...buildLifecycleCallbacks(
+        'heading.angle',
+        () => smoothedHeading?.handler?.path || 'navigation.headingTrue',
+        () => { smoothedHeading?.unsubscribe(); smoothedHeading?.subscribe(false, true); }
+      )
     });
-    // The magnitude handler has a fixed value of 1 and is never subscribed, so its timestamp
-    // stays null forever. Staleness detection on it would always force _stale=true, blocking
-    // processChanges() from setting polar._ready=true on every heading delta.
-    smoothedHeading.polar.magnitudeHandler.stalenessDetection = false;
     rawHeading = smoothedHeading.handler;
 
     //attitude
@@ -335,7 +389,12 @@ module.exports = function (app) {
       path: 'navigation.attitude',
       subscribe: true,
       SmootherClass,
-      smootherOptions
+      smootherOptions,
+      ...buildLifecycleCallbacks(
+        'attitude.smoothed',
+        () => smoothedAttitude?.handler?.path || 'navigation.attitude',
+        () => { smoothedAttitude?.unsubscribe(); smoothedAttitude?.subscribe(); }
+      )
     });
     rawAttitude = smoothedAttitude.handler;
 
@@ -370,7 +429,6 @@ module.exports = function (app) {
     });
     noCurrent.xSmoother.reset(0,0);
     noCurrent.ySmoother.reset(0,0);
-    noCurrent.stalenessDetection = false; // noCurrent is a fixed zero-vector, never receives live data
     PolarSmoother.send(app, plugin.id, [noCurrent]);
 
     MessageHandler.setMeta(app, plugin.id, 'navigation.leewayAngle', {
@@ -388,7 +446,49 @@ module.exports = function (app) {
       path: 'navigation.speedThroughWater',
       subscribe: true,
       SmootherClass,
-      smootherOptions
+      smootherOptions,
+      onDelta: () => {
+        clearLifecycleWarning('boatSpeed.smoothed');
+        // Drain any pending option changes before calculating
+        if (Object.keys(changedOptions).length) applyOptionChanges();
+
+        const wellUnderway = started < new Date() - 60 * 1000;
+
+        setStatus(wellUnderway ? 'Running' : 'Stabilizing');
+        if (options.estimateBoatSpeed) correct(wellUnderway);
+        if (options.updateCorrectionTable) {
+          if (wellUnderway) {
+            updateTable();
+            // Save correction table periodically (skip if table is empty to avoid overwriting good data on disk)
+            const now = Date.now();
+            if (now - lastSave > 60_000) {
+              if (!isTableEmpty(table)) {
+                saveTable(table, path.join(app.getDataDirPath(), table.id + '.json'));
+              }
+              lastSave = now;
+            }
+          } else {
+            table.lastUpdateResult = 'stabilizing';
+          }
+        } else {
+          table.lastUpdateResult = null;
+        }
+      }
+      ,
+      onIdle: () => {
+        if (!isRunning) return;
+        const path = smoothedBoatSpeed?.handler?.path || 'navigation.speedThroughWater';
+        app.debug(`[${plugin.id}] idle input boatSpeed.smoothed on ${path}; resubscribing`);
+        setLifecycleWarning('boatSpeed.smoothed', 'idle', path);
+        smoothedBoatSpeed?.unsubscribe();
+        smoothedBoatSpeed?.subscribe();
+      },
+      onStale: () => {
+        if (!isRunning) return;
+        const path = smoothedBoatSpeed?.handler?.path || 'navigation.speedThroughWater';
+        app.debug(`[${plugin.id}] stale input boatSpeed.smoothed on ${path}`);
+        setLifecycleWarning('boatSpeed.smoothed', 'stale', path);
+      }
     });
     rawBoatSpeed = smoothedBoatSpeed.handler;
 
@@ -419,7 +519,12 @@ module.exports = function (app) {
       angleRange: '0to2pi',
       meta: { displayName: 'Groundspeed', plane: 'Ground' },
       SmootherClass,
-      smootherOptions
+      smootherOptions,
+      ...buildLifecycleCallbacks(
+        'groundSpeed.smoothed',
+        () => `${smoothedGroundSpeed?.polar?.pathMagnitude || 'navigation.speedOverGround'}, ${smoothedGroundSpeed?.polar?.pathAngle || 'navigation.courseOverGroundTrue'}`,
+        () => { smoothedGroundSpeed?.unsubscribe(); smoothedGroundSpeed?.subscribe(true, true); }
+      )
     });
     rawGroundSpeed = smoothedGroundSpeed.polar;
 
@@ -466,50 +571,12 @@ module.exports = function (app) {
 
     //#endregion
 
-    // Apply staleness detection to all subscribed smoother instances.
-    // noCurrent is intentionally excluded — it is a fixed zero-vector and never receives live data.
-    // Only apply when sd = false: all smoothers already default to stalenessDetection = true.
-    // Explicitly calling the setter with true at startup forces _stale = true on handlers that have
-    // never received data, causing the first sample to be dropped (library side-effect).
-    const sd = options.stalenessDetection ?? true;
-    if (!sd) {
-      for (const s of [smoothedHeading, smoothedAttitude, smoothedBoatSpeed, smoothedGroundSpeed, smoothedCurrent, smoothedResidual]) {
-        if (s) s.stalenessDetection = false;
-      }
-    }
-
     isRunning = true;
     started = Date.now();
     lastSave = 0;
     setStatus('Running');
     app.debug("Running");
 
-    smoothedBoatSpeed.onChange = () => {
-      // Drain any pending option changes before calculating
-      if (Object.keys(changedOptions).length) applyOptionChanges();
-
-      const wellUnderway = started < new Date() - 60 * 1000;
-
-      setStatus(wellUnderway ? 'Running' : 'Stabilizing');
-      if (options.estimateBoatSpeed) correct(wellUnderway);
-      if (options.updateCorrectionTable) {
-        if (wellUnderway) {
-          updateTable();
-          // Save correction table periodically (skip if table is empty to avoid overwriting good data on disk)
-          const now = Date.now();
-          if (now - lastSave > 60_000) {
-            if (!isTableEmpty(table)) {
-              saveTable(table, path.join(app.getDataDirPath(), table.id + '.json'));
-            }
-            lastSave = now;
-          }
-        } else {
-          table.lastUpdateResult = 'stabilizing';
-        }
-      } else {
-        table.lastUpdateResult = null;
-      }
-    };
   }
 
   plugin.stop = () => {
@@ -546,6 +613,8 @@ module.exports = function (app) {
 
         pluginStatus = 'Stopped';
         isRunning = false;
+        lifecycleWarningMap = new Map();
+        lifecycleWarnings = [];
         resolve();
       } catch (error) {
         reject(error);
@@ -723,13 +792,7 @@ module.exports = function (app) {
       const value = changedOptions[key];
       options[key] = value;
 
-      if (key === 'stalenessDetection') {
-        const sdVal = Boolean(value);
-        for (const s of [smoothedHeading, smoothedAttitude, smoothedBoatSpeed, smoothedGroundSpeed, smoothedCurrent, smoothedResidual]) {
-          if (s) s.stalenessDetection = sdVal;
-        }
-        // noCurrent is always excluded from staleness detection
-      } else if (key === 'updateCorrectionTable') {
+      if (key === 'updateCorrectionTable') {
         if (!value && table && !isTableEmpty(table)) {
           // Learning switched off — persist current state before periodic saves stop
           saveTableSync(table, path.join(app.getDataDirPath(), table.id + '.json'));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "speedandcurrent",
-  "version": "2.1.2",
+  "version": "2.2.1",
   "description": "A plugin that automatically corrects boat speed and calculates current and leeway using sensor fusion.",
   "main": "index.js",
   "scripts": {
@@ -38,7 +38,7 @@
   },
   "dependencies": {
     "kalman-filter": "^2.3.0",
-    "signalkutilities": "^3.0.1"
+    "signalkutilities": "^3.1.0"
   },
   "files": [
     "icon.png",

package/public/app.js

@@ -97,6 +97,7 @@ function normaliseState(data) {
 
 // ─── Static meta (fetched once at startup from /api/meta) ─────────────────────
 let metaById = {}; // keyed by item id
+let lifecycleWarnings = [];
 
 async function loadMeta() {
   const data = await apiGet('/api/meta');
@@ -182,6 +183,29 @@ function renderWarnings(elId, ids) {
   el.appendChild(ul);
 }
 
+function renderInputWarnings(elId, ids) {
+  const el = document.getElementById(elId);
+  if (!el) return;
+  el.innerHTML = '';
+  const lines = [];
+  lifecycleWarnings.forEach(w => {
+    if (w && typeof w.message === 'string') lines.push(w.message);
+  });
+  if (lines.length === 0) return;
+  const h = document.createElement('h6');
+  h.className = 'text-uppercase fw-bold text-muted border-bottom pb-1 mt-3 mb-1 small';
+  h.textContent = 'Warnings';
+  el.appendChild(h);
+  const ul = document.createElement('ul');
+  ul.className = 'list-unstyled text-danger small ps-3';
+  lines.forEach(line => {
+    const li = document.createElement('li');
+    li.textContent = line;
+    ul.appendChild(li);
+  });
+  el.appendChild(ul);
+}
+
 // ─── Config (live settings mirror) ───────────────────────────────────────────
 let config = null;
 
@@ -296,15 +320,15 @@ const paramMeta = {
     min: 0.01, max: 0.99, step: 0.01, default: 0.2,
     description: 'Steady-state Kalman gain (0 ≈ slow/smooth, 1 ≈ fast/raw). Clamped to 0.01–0.99.'
   },
-  stalenessDetection: {
-    label: 'Staleness detection',
-    type: 'boolean',
-    description: 'Mark inputs as unavailable when no data has been received for a period. '
-  },
 };
 
 // Settings groups for each UI section
-const INPUTS_SETTING_KEYS     = ['stalenessDetection'];
+const INPUTS_SETTING_KEYS     = [
+  'smootherClass',
+  { key: 'smootherTau',         showIf: cfg => cfg.smootherClass === 'ExponentialSmoother' },
+  { key: 'smootherTimeSpan',    showIf: cfg => (cfg.smootherClass || 'MovingAverageSmoother') === 'MovingAverageSmoother' },
+  { key: 'smootherSteadyState', showIf: cfg => cfg.smootherClass === 'KalmanSmoother' },
+];
 const ESTIMATION_SETTING_KEYS = ['sogFallback'];
 const LEARNING_SETTING_KEYS   = ['stability','assumeCurrent','showStatistics'];
 const SMOOTHER_SETTING_KEYS   = [
@@ -511,12 +535,22 @@ function renderGroupInto(elId, polars, deltas, attitudes) {
 }
 
 function renderLiveSections() {
+  const inputPolars = filterById(state.polarsAll, ['groundSpeed']);
+  const inputDeltas = filterById(state.deltasAll, ['heading.angle', 'boatSpeed']);
+  const inputAttitudes = filterById(state.attitudesAll, ['attitude']);
+  const fallbackInputPolars = inputPolars.length ? inputPolars : filterById(state.polarsAll, ['groundSpeed.smoothed']);
+  const fallbackInputDeltas = inputDeltas.length ? inputDeltas : filterById(state.deltasAll, ['heading.smoothed', 'boatSpeed.smoothed']);
+  const fallbackInputAttitudes = inputAttitudes.length ? inputAttitudes : filterById(state.attitudesAll, ['attitude.smoothed']);
+
   // Inputs section — raw sensor readings only (smoothing is internal to the plugin)
   renderGroupInto('inputs-values',
-    filterById(state.polarsAll,    ['groundSpeed']),
-    filterById(state.deltasAll,    ['heading.angle', 'boatSpeed']),
-    filterById(state.attitudesAll, ['attitude'])
+    fallbackInputPolars,
+    fallbackInputDeltas,
+    fallbackInputAttitudes
   );
+  const inputWarningIds = ['boatSpeed', 'attitude', 'heading.angle', 'groundSpeed', 'boatSpeed.smoothed', 'groundSpeed.smoothed', 'heading.smoothed', 'attitude.smoothed'];
+  if (config && config.assumeCurrent) inputWarningIds.push('current.smoothed');
+  renderInputWarnings('inputs-warnings', inputWarningIds);
 
   // Estimation — inputs (raw sensor data used for boat speed estimation)
   renderGroupInto('estimation-inputs',
@@ -535,9 +569,8 @@ function renderLiveSections() {
     [], []
   );
   // Estimation — warnings
-  renderWarnings('estimation-warnings',
-    ['boatSpeed', 'attitude', 'heading.angle', 'groundSpeed']
-  );
+  const estimationWarnings = document.getElementById('estimation-warnings');
+  if (estimationWarnings) estimationWarnings.innerHTML = '';
 
   // Learning — inputs: smoothed sensors + current if assumeCurrent
   const learningCurrentPolars = (config && config.assumeCurrent)
@@ -549,9 +582,8 @@ function renderLiveSections() {
     filterById(state.attitudesAll, ['attitude.smoothed'])
   );
   // Learning — warnings
-  const learningWarningIds = ['boatSpeed.smoothed', 'groundSpeed.smoothed', 'heading.smoothed', 'attitude.smoothed'];
-  if (config && config.assumeCurrent) learningWarningIds.push('current.smoothed');
-  renderWarnings('learning-warnings', learningWarningIds);
+  const learningWarnings = document.getElementById('learning-warnings');
+  if (learningWarnings) learningWarnings.innerHTML = '';
   // Learning status section
   const statusTbody = document.querySelector('#learning-status-table tbody');
   if (statusTbody) {
@@ -620,6 +652,7 @@ async function tick() {
     .then(r => r.ok ? r.json() : null)
     .catch(() => null);
   _pluginStatus = statusData?.status ?? '';
+  lifecycleWarnings = Array.isArray(statusData?.lifecycleWarnings) ? statusData.lifecycleWarnings : [];
   _refreshMessage();
 }
 

package/public/index.html

@@ -97,6 +97,7 @@
               </table>
               <h6 class="text-uppercase fw-bold text-muted border-bottom pb-1 mt-3 mb-1 small">Live Values</h6>
               <div id="inputs-values"></div>
+              <div id="inputs-warnings"></div>
             </div>
           </div>
         </div>