speedandcurrent 2.1.2 → 2.3.0

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
@@ -64,7 +66,7 @@ Once configured, all consumers on the Signal K bus — KIP, OpenCPN, Instrument
 | `environment.current.drift` | m/s | Estimated current speed. |
 | `environment.current.setTrue` | rad | Estimated current direction (the direction the water moves *toward*). |
 
-A 60-second stabilisation period applies after startup. No output is published during this window; the status bar shows **Stabilizing**.
+A 60-second stabilisation period applies after startup. No output is published during this window.
 
 ---
 
@@ -130,7 +132,7 @@ The panel is organised into three groups:
 | Setting | Default | Description |
 |---------|---------|-------------|
 | **Estimate Boat Speed** | Off | Master toggle. Apply the correction table and publish corrected STW, leeway, and current. Turn on once the table has reasonable coverage. |
-| **Groundspeed Fallback** | Off | When the paddle wheel reads zero and SOG is above a minimum threshold, publish SOG as boatspeed. Primarily intended for clogged or stuck paddle wheels where the instrument is physically present but not turning — giving the rest of the instrument system a usable boat speed until the wheel is cleared. |
+| **Groundspeed Fallback** | Off | When the paddle wheel reads zero and SOG is above the current table speed-step threshold, publish SOG as boatspeed. Primarily intended for clogged or stuck paddle wheels where the instrument is physically present but not turning — giving the rest of the instrument system a usable boat speed until the wheel is cleared. |
 
 ---
 
@@ -146,11 +148,14 @@ When **Assume Current** is enabled, the smoothed current estimate is also shown
 
 Warnings appear here if any smoothed input is unavailable.
 
+The panel also shows whether learning is currently active, suspended, or skipped for the latest observation. Learning is automatically suspended when `navigation.state` is `anchored` or `moored` when that path is available. It can also be suspended for `motoring` if enabled in the settings. Observations below the current table speed-step threshold are skipped.
+
 ### Settings
 
 | Setting | Default | Description |
 |---------|---------|-------------|
-| **Update Correction Table** | On | Master toggle. Allow the table to update from current observations. Disable temporarily in conditions you do not want recorded — motoring, surf sailing, very confused seas. |
+| **Update Correction Table** | On | Master toggle. Allow the table to update from current observations. |
+| **Suspend on navigation.state = motoring** | Off | Suspend learning when `navigation.state` reports `motoring`. `anchored` and `moored` always suspend learning when that path is available. |
 | **Stability (1–20)** | 7 | How quickly the correction table adapts to new observations. Higher = slower, more conservative. Lower = faster but noisier. See the technical section for detail. |
 | **Assume Current (experimental)** | Off | Include the running current estimate in the table update calculation. Only enable once the current estimate has had time to stabilise and tidal conditions are relatively steady. |
 | **Show Statistics (σ)** | Off | Display standard deviation alongside each smoothed value. Useful for spotting noisy sensors. |
@@ -206,7 +211,7 @@ Multiple tables can coexist on disk; only the active one is used. This makes it
 
 **Be patient with the correction table.** A fresh table has no data and produces no corrections. Cover a range of speeds and heel angles over a few sails and the table fills in progressively. Upwind sailing covers the heel bins well; downwind and reaching fill the low-heel, varying-speed bins.
 
-**The table learns while sailing normally.** No dedicated calibration runs are needed. Just sail with **Update Correction Table** on.
+**The table learns while sailing normally.** No dedicated calibration runs are needed. Just sail with **Update Correction Table** on. Learning pauses automatically during startup stabilisation, when `navigation.state` indicates `anchored` or `moored`, optionally when it indicates `motoring`, and when SOG or STW are below the current table speed-step threshold.
 
 **Port and starboard are tracked independently.** Heel is signed: starboard positive, port negative. An asymmetric paddle wheel installation will show different corrections on each tack, and the table captures this naturally.
 

package/index.js

@@ -19,27 +19,141 @@ const {
 
 const { CorrectionTable } = require('./correctionTable.js');
 
+const LONG_STABILIZING_MS = 60 * 1000;
+const ALWAYS_BLOCKING_NAVIGATION_STATES = new Set(['anchored', 'moored']);
+const OPTIONAL_BLOCKING_NAVIGATION_STATES = new Set(['motoring']);
+
+function normalizeNavigationState(value) {
+  return typeof value === 'string' ? value.trim().toLowerCase() : null;
+}
+
+function getShortStabilizingMs(options = {}) {
+  return Math.max(0, Number(options.smootherTimeSpan) || 5) * 1000;
+}
+
+function isCogOverrideActive(groundSpeedPolar, speedThreshold) {
+  const sogHandler = groundSpeedPolar?.magnitudeHandler;
+  return !groundSpeedPolar?.ready
+    && sogHandler?.ready
+    && Number.isFinite(sogHandler.value)
+    && sogHandler.value < speedThreshold;
+}
+
+function evaluateLearningMode({ options = {}, navigationState, stabilizingUntil = 0, stabilizingReason = null, now = Date.now() }) {
+  const normalizedNavigationState = normalizeNavigationState(navigationState?.value);
+  const navigationGateReady = navigationState?.ready === true;
+  const navigationGateBlocking = navigationGateReady && (
+    ALWAYS_BLOCKING_NAVIGATION_STATES.has(normalizedNavigationState)
+    || (!!options.suspendLearningOnNavigationState && OPTIONAL_BLOCKING_NAVIGATION_STATES.has(normalizedNavigationState))
+  );
+
+  if (!options.updateCorrectionTable) {
+    return { state: 'off', reason: 'manual', navigationGateBlocking, normalizedNavigationState };
+  }
+
+  if (navigationGateBlocking) {
+    return { state: 'suspended', reason: 'nav_state', navigationGateBlocking, normalizedNavigationState };
+  }
+
+  if (now < stabilizingUntil) {
+    return { state: 'stabilizing', reason: stabilizingReason || 'startup', navigationGateBlocking, normalizedNavigationState };
+  }
+
+  return { state: 'active', reason: null, navigationGateBlocking, normalizedNavigationState };
+}
+
+function evaluateObservationGate({
+  learningMode,
+  inputsReady,
+  assumeCurrent,
+  currentReady,
+  stw,
+  sog,
+  speedThreshold,
+}) {
+  if (learningMode.state === 'off') {
+    return { state: 'skipped', reason: 'learning_off' };
+  }
+  if (learningMode.state === 'suspended') {
+    return { state: 'skipped', reason: learningMode.reason === 'cog_override' ? 'cog_override_active' : 'nav_state_blocked' };
+  }
+  if (learningMode.state === 'stabilizing') {
+    return { state: 'skipped', reason: 'stabilizing' };
+  }
+  if (!inputsReady) {
+    return { state: 'invalid', reason: assumeCurrent && !currentReady ? 'missing_current_when_required' : 'missing_input' };
+  }
+  if (!(stw > speedThreshold)) {
+    return { state: 'skipped', reason: 'stw_below_threshold' };
+  }
+  if (!(sog >= speedThreshold)) {
+    return { state: 'skipped', reason: 'sog_below_threshold' };
+  }
+  return { state: 'pending', reason: null };
+}
+
+function buildNavigationStateStatus(handler, gateEnabled) {
+  if (!handler) {
+    return {
+      enabled: !!gateEnabled,
+      path: 'navigation.state',
+      pathKnown: false,
+      ready: false,
+      value: null,
+      blocking: false
+    };
+  }
+
+  const state = handler.state;
+  const value = handler.value ?? null;
+  const normalized = normalizeNavigationState(value);
+  return {
+    enabled: !!gateEnabled,
+    path: handler.path,
+    pathKnown: state.pathKnown,
+    ready: state.ready,
+    isStale: state.isStale,
+    value,
+    blocking: state.ready && (
+      ALWAYS_BLOCKING_NAVIGATION_STATES.has(normalized)
+      || (!!gateEnabled && OPTIONAL_BLOCKING_NAVIGATION_STATES.has(normalized))
+    )
+  };
+}
+
+function getDerivedObservationStatus(learningMode, lastState, lastReason) {
+  if (learningMode.state === 'off') {
+    return { state: 'skipped', reason: 'learning_off' };
+  }
+  if (learningMode.state === 'stabilizing') {
+    return { state: 'skipped', reason: 'stabilizing' };
+  }
+  if (learningMode.state === 'suspended') {
+    return { state: 'skipped', reason: learningMode.reason === 'cog_override' ? 'cog_override_active' : 'nav_state_blocked' };
+  }
+  return { state: lastState, reason: lastReason };
+}
+
 module.exports = function (app) {
 
   const DEFAULT_DIMS = { maxSpeed: 9, speedStep: 1, maxHeel: 32, heelStep: 8 };
 
   let options = {};
   let changedOptions = {};
-  let hasPendingChanges = false;
   const defaultOptions = {
     sogFallback: true,
     estimateBoatSpeed: false,
     updateCorrectionTable: true,
     stability: 7,
     assumeCurrent: false,
+    suspendLearningOnNavigationState: false,
     tableName: 'correctionTable',
     configVersion: 2,
     smootherClass: 'MovingAverageSmoother',
     smootherTau: 3,
     smootherTimeSpan: 5,
     smootherSteadyState: 0.2,
-    showStatistics: false,
-    stalenessDetection: true
+    showStatistics: false
   };
 
   
@@ -68,7 +182,7 @@ module.exports = function (app) {
    * writes it back if anything changed. Called once on every start().
    */
   function migrateConfig() {
-    const obsoleteKeys = ['headingSource', 'boatSpeedSource', 'SOGSource', 'attitudeSource', 'preventDuplication'];
+    const obsoleteKeys = ['headingSource', 'boatSpeedSource', 'SOGSource', 'attitudeSource', 'preventDuplication', 'minSogForLearning'];
     const hadObsolete = obsoleteKeys.some(k => k in options);
     for (const k of obsoleteKeys) delete options[k];
     if (hadObsolete || (options.configVersion || 0) < 2) {
@@ -110,7 +224,7 @@ module.exports = function (app) {
 
   function swapTable(newTable) {
     table = newTable;
-    minSpeed = table.step[0] / 2;
+    minSpeed = table.step[0];
     if (reportFull) reportFull.setTables([table]);
     lastSave = Date.now(); // explicit table operations already save; defer next periodic save
   }
@@ -137,9 +251,114 @@ module.exports = function (app) {
   let noCurrent = null;
   let rawBoatSpeed = null;
   let rawGroundSpeed = null;
-  let started = null;
   let minSpeed = 0;
   let lastSave = 0;
+  let navigationStateHandler = null;
+  let lastNavigationStateValue = null;
+  let learningStabilizingUntil = 0;
+  let learningStabilizingReason = 'startup';
+  let lastObservationState = null;
+  let lastObservationReason = null;
+  let lifecycleWarningMap = new Map();
+  let lifecycleWarnings = [];
+
+  function setObservationStatus(state, reason = null) {
+    lastObservationState = state;
+    lastObservationReason = reason;
+    if (table) {
+      table.lastUpdateResult = state;
+      table.lastUpdateReason = reason;
+    }
+  }
+
+  function resetLearningStabilization(reason, durationMs) {
+    const delay = Math.max(0, Number(durationMs) || 0);
+    learningStabilizingUntil = Date.now() + delay;
+    learningStabilizingReason = reason;
+  }
+
+  function handleNavigationStateDelta() {
+    const normalized = normalizeNavigationState(navigationStateHandler?.value);
+    if (normalized === lastNavigationStateValue) return;
+    if (lastNavigationStateValue !== null) {
+      resetLearningStabilization('nav_state_change', LONG_STABILIZING_MS);
+    }
+    lastNavigationStateValue = normalized;
+  }
+
+  function getLearningStatePayload() {
+    const navigationState = buildNavigationStateStatus(navigationStateHandler, options.suspendLearningOnNavigationState);
+    const learningMode = evaluateLearningMode({
+      options,
+      navigationState,
+      stabilizingUntil: learningStabilizingUntil,
+      stabilizingReason: learningStabilizingReason,
+      now: Date.now()
+    });
+    if (learningMode.state === 'active' && isCogOverrideActive(rawGroundSpeed, minSpeed)) {
+      learningMode.state = 'suspended';
+      learningMode.reason = 'cog_override';
+    }
+    const observation = getDerivedObservationStatus(learningMode, lastObservationState, lastObservationReason);
+
+    return {
+      state: learningMode.state,
+      reason: learningMode.reason,
+      observationState: observation.state,
+      observationReason: observation.reason,
+      minStwForLearning: minSpeed,
+      minSogForLearning: minSpeed,
+      navigationState
+    };
+  }
+
+  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 +380,10 @@ 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;
+        payload.learningState = getLearningStatePayload();
+        res.json(payload);
       }
     });
 
@@ -176,7 +398,7 @@ module.exports = function (app) {
 
 
     router.get('/api/status', (req, res) => {
-      res.json({ status: pluginStatus, isRunning });
+      res.json({ status: pluginStatus, isRunning, lifecycleWarnings, learningState: getLearningStatePayload() });
     });
 
     // --- Settings API ---
@@ -197,7 +419,6 @@ module.exports = function (app) {
         }
       }
       changedOptions = { ...changedOptions, ...body };
-      hasPendingChanges = true;
       res.json({ ...options, ...changedOptions });
     });
 
@@ -305,12 +526,14 @@ 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';
     const tableFilePath = path.join(app.getDataDirPath(), tableName + '.json');
     table = loadTable(options, tableFilePath);
-    minSpeed = table.step[0] / 2;
+    minSpeed = table.step[0];
 
     //#region Handler and Polar Initialization
     const { SmootherClass, smootherOptions } = resolveSmootherConfig();
@@ -320,25 +543,38 @@ 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
+    // attitude
     smoothedAttitude = createSmoothedHandler({
       app, pluginId: plugin.id,
       id: 'attitude',
       path: 'navigation.attitude',
       subscribe: true,
       SmootherClass,
-      smootherOptions
+      smootherOptions,
+      ...buildLifecycleCallbacks(
+        'attitude.smoothed',
+        () => smoothedAttitude?.handler?.path || 'navigation.attitude',
+        () => { smoothedAttitude?.unsubscribe(); smoothedAttitude?.subscribe(); }
+      )
     });
     rawAttitude = smoothedAttitude.handler;
 
+    navigationStateHandler = new MessageHandler(app, plugin.id, 'navigationState');
+    navigationStateHandler.configure('navigation.state');
+    navigationStateHandler.onDelta = () => {
+      handleNavigationStateDelta();
+    };
+    navigationStateHandler.subscribe();
+
 
     // current
     // send metadata for current
@@ -370,7 +606,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 +623,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 learningMode = evaluateLearningMode({
+          options,
+          navigationState: buildNavigationStateStatus(navigationStateHandler, options.suspendLearningOnNavigationState),
+          stabilizingUntil: learningStabilizingUntil,
+          stabilizingReason: learningStabilizingReason,
+          now: Date.now()
+        });
+
+        const wellUnderway = learningMode.state !== 'stabilizing';
+        setStatus(learningMode.state === 'stabilizing' ? 'Stabilizing' : 'Running');
+        if (options.estimateBoatSpeed) correct(wellUnderway);
+        updateTable();
+        if (lastObservationState === 'accepted' && options.updateCorrectionTable) {
+          const now = Date.now();
+          if (now - lastSave > 60_000) {
+            if (!isTableEmpty(table)) {
+              saveTable(table, path.join(app.getDataDirPath(), table.id + '.json'));
+            }
+            lastSave = now;
+          }
+        }
+      }
+      ,
+      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 +696,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 +748,15 @@ 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;
+    lastObservationState = null;
+    lastObservationReason = null;
+    lastNavigationStateValue = normalizeNavigationState(navigationStateHandler?.value);
+    resetLearningStabilization('startup', LONG_STABILIZING_MS);
     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 = () => {
@@ -525,6 +772,7 @@ module.exports = function (app) {
         smoothedAttitude = smoothedAttitude?.terminate();
         rawCurrent = rawCurrent?.terminate();
         smoothedCurrent = smoothedCurrent?.terminate?.();
+        navigationStateHandler = navigationStateHandler?.terminate();
         smoothedBoatSpeed = smoothedBoatSpeed?.terminate();
         correctedBoatSpeed = correctedBoatSpeed?.terminate();
         lrnBoatSpeed = lrnBoatSpeed?.terminate();
@@ -540,12 +788,18 @@ module.exports = function (app) {
         noCurrent = null;
         rawBoatSpeed = null;
         rawGroundSpeed = null;
-        started = null;
+        lastNavigationStateValue = null;
+        learningStabilizingUntil = 0;
+        learningStabilizingReason = 'startup';
+        lastObservationState = null;
+        lastObservationReason = null;
         app.setPluginStatus("Stopped");
         app.debug("Stopped");
 
         pluginStatus = 'Stopped';
         isRunning = false;
+        lifecycleWarningMap = new Map();
+        lifecycleWarnings = [];
         resolve();
       } catch (error) {
         reject(error);
@@ -573,7 +827,7 @@ module.exports = function (app) {
 
     // Priority 1: SOG fallback when STW is stuck at zero
     // (onChange only fires when STW is ready, so a missing STW cannot reach here)
-    if (options.sogFallback && rawGroundSpeed.ready && correctedBoatSpeed.magnitude === 0 && rawGroundSpeed.magnitude >= minSpeed) {
+    if (options.sogFallback && rawGroundSpeed.ready && rawBoatSpeed.ready && rawBoatSpeed.value === 0 && rawGroundSpeed.magnitude >= minSpeed) {
         correctedBoatSpeed.setVectorValue({ x: rawGroundSpeed.magnitude, y: 0 });
     }
     else if (rawAttitude.ready) {
@@ -584,11 +838,7 @@ module.exports = function (app) {
       }
       // Current estimation and residual also require heading (to rotate into ground frame).
       // Also handle near-zero SOG where COG is unavailable: treat groundspeed as zero vector.
-      const sogHandler = rawGroundSpeed.magnitudeHandler;
-      const nearZeroGroundSpeed = !rawGroundSpeed.ready &&
-        sogHandler.ready &&
-        Number.isFinite(sogHandler.value) &&
-        sogHandler.value < 0.3;
+      const nearZeroGroundSpeed = isCogOverrideActive(rawGroundSpeed, minSpeed);
       if (rawHeading.ready && (rawGroundSpeed.ready || nearZeroGroundSpeed)) {
         boatSpeedRefGround.copyFrom(correctedBoatSpeed);
         boatSpeedRefGround.rotate(rawHeading.value);
@@ -626,18 +876,43 @@ module.exports = function (app) {
    */
   function updateTable() {
     lrnBoatSpeed.setVectorValue({ x: smoothedBoatSpeed.value, y: 0 }, { x: smoothedBoatSpeed.variance ?? 0, y: 0 });
-    if (!smoothedAttitude.ready || !smoothedBoatSpeed.ready || !smoothedHeading.ready || !smoothedGroundSpeed.ready || (options.assumeCurrent && !smoothedCurrent.ready)) {
-      table.lastUpdateResult = 'invalid';
-      return;
+    const learningMode = evaluateLearningMode({
+      options,
+      navigationState: buildNavigationStateStatus(navigationStateHandler, options.suspendLearningOnNavigationState),
+      stabilizingUntil: learningStabilizingUntil,
+      stabilizingReason: learningStabilizingReason,
+      now: Date.now()
+    });
+    if (learningMode.state === 'active' && isCogOverrideActive(rawGroundSpeed, minSpeed)) {
+      learningMode.state = 'suspended';
+      learningMode.reason = 'cog_override';
     }
-    
-    // update correction table
-    if (smoothedBoatSpeed.value > minSpeed) {
-      table.update(smoothedBoatSpeed.value, smoothedAttitude.value?.roll, smoothedGroundSpeed, options.assumeCurrent ? smoothedCurrent : noCurrent, lrnBoatSpeed, smoothedHeading.value);
-    } else {
-      table.lastUpdateResult = 'waiting';
+    const inputsReady = smoothedAttitude.ready && smoothedBoatSpeed.ready && smoothedHeading.ready && smoothedGroundSpeed.ready;
+    const currentReady = !options.assumeCurrent || smoothedCurrent.ready;
+    const observationGate = evaluateObservationGate({
+      learningMode,
+      inputsReady,
+      assumeCurrent: options.assumeCurrent,
+      currentReady,
+      stw: smoothedBoatSpeed.value,
+      sog: smoothedGroundSpeed.magnitude,
+      speedThreshold: minSpeed
+    });
+
+    if (observationGate.state !== 'pending') {
+      if (observationGate.state === 'invalid') {
+        resetLearningStabilization('observation_reset', getShortStabilizingMs(options));
+      }
+      return;
     }
 
+    table.update(smoothedBoatSpeed.value, smoothedAttitude.value?.roll, smoothedGroundSpeed, options.assumeCurrent ? smoothedCurrent : noCurrent, lrnBoatSpeed, smoothedHeading.value);
+    if (table.lastUpdateResult === 'accepted') {
+      setObservationStatus('accepted', 'accepted');
+    } else if (table.lastUpdateResult === 'rejected') {
+      setObservationStatus('rejected', 'estimator_outlier');
+      resetLearningStabilization('observation_reset', getShortStabilizingMs(options));
+    }
   }
 
   /**
@@ -723,13 +998,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'));
@@ -749,7 +1018,6 @@ module.exports = function (app) {
           }
         }
       }
-
       // All other keys (sogFallback, estimateBoatSpeed, assumeCurrent,
       // stability, smootherClass, etc.) are read
       // directly from options.* so no extra action needed.
@@ -771,10 +1039,21 @@ module.exports = function (app) {
       }
       if (smoothedAttitude) { smoothedAttitude.setSmootherClass(SC); smoothedAttitude.setSmootherOptions(so); }
     }
-
-    hasPendingChanges = false;
     saveOptions();
   }
 
   return plugin;
 };
+
+module.exports._test = {
+  normalizeNavigationState,
+  getShortStabilizingMs,
+  evaluateLearningMode,
+  isCogOverrideActive,
+  evaluateObservationGate,
+  getDerivedObservationStatus,
+  buildNavigationStateStatus,
+  ALWAYS_BLOCKING_NAVIGATION_STATES,
+  OPTIONAL_BLOCKING_NAVIGATION_STATES,
+  LONG_STABILIZING_MS,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "speedandcurrent",
-  "version": "2.1.2",
+  "version": "2.3.0",
   "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;
 
@@ -251,11 +275,8 @@ function _refreshMessage() {
     else el.textContent = _explicitMsg;
     return;
   }
-  const isRunningOk = (_pluginStatus === 'Running' || _pluginStatus === '');
+  const isRunningOk = (_pluginStatus === 'Running' || _pluginStatus === 'Stabilizing' || _pluginStatus === '');
   if (!isRunningOk) {
-    el.style.color =
-      _pluginStatus === 'Stabilizing'                    ? '#084298' :
-      _pluginStatus === 'Falling back to Speed Over Ground' ? '#664d03' : '#842029';
     el.textContent = _pluginStatus;
   } else {
     el.style.color = '';
@@ -268,6 +289,7 @@ function _refreshMessage() {
 const paramMeta = {
   estimateBoatSpeed:     { label: 'Estimate boat speed',                  type: 'boolean' },
   updateCorrectionTable: { label: 'Update correction table',              type: 'boolean' },
+  suspendLearningOnNavigationState: { label: 'Suspend on navigation.state = motoring', type: 'boolean', description: 'Suspend learning when navigation.state is motoring. Anchored and moored always suspend learning when the path is available.' },
   assumeCurrent:         { label: 'Assume current during update',         type: 'boolean', description: 'Experimental, works best when currents are relatively stable.' },
   sogFallback:           { label: 'Groundspeed fallback',                 type: 'boolean', description: 'Output Groundspeed as Boatspeed when the paddlewheel sensor is malfunctioning or stalled.' },
   stability:             { label: 'Stability (1–20)',                     type: 'number', min: 1, max: 20, step: 1, default: 7, description: 'How quickly the correction table adapts to new observations. Higher values mean slower, more stable changes.' },
@@ -296,17 +318,17 @@ 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 LEARNING_SETTING_KEYS   = ['stability', 'suspendLearningOnNavigationState', 'assumeCurrent', 'showStatistics'];
 const SMOOTHER_SETTING_KEYS   = [
   'smootherClass',
   { key: 'smootherTau',         showIf: cfg => cfg.smootherClass === 'ExponentialSmoother' },
@@ -511,12 +533,23 @@ function renderGroupInto(elId, polars, deltas, attitudes) {
 }
 
 function renderLiveSections() {
+  const learningState = state.learningState || null;
+  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 +568,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,33 +581,61 @@ 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 = '';
+    const navState = learningState?.navigationState;
+    if (navState?.enabled && navState.pathKnown === false) {
+      const ul = document.createElement('ul');
+      ul.className = 'list-unstyled small ps-3';
+      const li = document.createElement('li');
+      li.textContent = 'navigation.state is not available; navigation-state learning gate is inactive.';
+      ul.appendChild(li);
+      learningWarnings.appendChild(ul);
+    }
+  }
   // Learning status section
   const statusTbody = document.querySelector('#learning-status-table tbody');
   if (statusTbody) {
-    const tableData = Object.values(state.tablesById)[0];
-    const result = tableData?.lastUpdateResult ?? null;
-    const learningText  = result === null          ? 'Off'
-                        : result === 'stabilizing' ? 'Stabilising'
-                        : 'Active';
-    const learningClass = result === null          ? 'text-muted'
-                        : result === 'stabilizing' ? 'text-warning'
-                        : 'text-success';
-    const obsText       = result === 'accepted'    ? 'Accepted'
-                        : result === 'rejected'    ? 'Rejected'
-                        : result === 'invalid'     ? 'Invalid'
-                        : result === 'waiting'     ? 'Below threshold'
-                        : '\u2014';
-    const obsClass      = result === 'accepted'    ? 'text-success'
-                        : result === 'rejected'    ? 'text-danger'
-                        : result === 'invalid'     ? 'text-warning'
-                        : result === 'waiting'     ? 'text-muted'
-                        : 'text-muted';
+    const learningTextMap = {
+      off: 'Off',
+      stabilizing: 'Stabilising',
+      active: 'Active',
+      suspended: 'Suspended',
+    };
+    const observationTextMap = {
+      accepted: 'Accepted',
+      rejected: 'Rejected',
+      invalid: 'Invalid',
+      skipped: 'Skipped',
+    };
+    const reasonTextMap = {
+      manual: 'Manual toggle off',
+      startup: 'Startup stabilising window',
+      observation_reset: 'Recent rejected or invalid observation',
+      nav_state_change: 'navigation.state changed',
+      nav_state: 'Blocked by navigation.state',
+      cog_override: 'Blocked by COG override',
+      accepted: 'Observation recorded',
+      estimator_outlier: 'Estimator rejected observation',
+      missing_input: 'Required learning input unavailable',
+      missing_current_when_required: 'Current estimate unavailable',
+      learning_off: 'Learning is off',
+      stabilizing: 'Stabilising window active',
+      nav_state_blocked: 'Learning blocked by navigation.state',
+      cog_override_active: 'Learning blocked by COG override',
+      stw_below_threshold: 'Below minimum STW for learning',
+      sog_below_threshold: 'Below minimum SOG for learning',
+    };
+    const learningText = learningTextMap[learningState?.state] || '\u2014';
+    const obsText = observationTextMap[learningState?.observationState] || '\u2014';
+    const reason = reasonTextMap[learningState?.observationReason]
+      || reasonTextMap[learningState?.reason]
+      || '\u2014';
     statusTbody.innerHTML =
-      `<tr><td class="text-muted small">Learning</td><td class="small fw-bold ${learningClass}">${learningText}</td></tr>` +
-      `<tr><td class="text-muted small">Observation</td><td class="small fw-bold ${obsClass}">${obsText}</td></tr>`;
+        `<tr><td class="text-muted small">Learning</td><td class="small">${learningText}</td></tr>` +
+        `<tr><td class="text-muted small">Observation</td><td class="small">${obsText}</td></tr>` +
+      `<tr><td class="text-muted small">Reason</td><td class="small">${reason}</td></tr>`;
   }
   // Correction table
   const tableEl = document.getElementById('table-container');
@@ -610,9 +670,11 @@ async function tick() {
     }
     lastTickOk = true;
     normaliseState(data);
+    state.learningState = data.learningState || null;
     renderLiveSections();
   } else {
     lastTickOk = false;
+    state.learningState = null;
   }
   // Always poll status separately so the message reflects plugin state
   // even when /api/report fails (plugin stopped/restarting).
@@ -620,6 +682,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>