speedandcurrent 2.5.0 → 2.6.0

package/CHANGELOG.md

@@ -4,6 +4,15 @@ 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.6.0] - 2026-11-05
+
+### Added
+- Current estimates are also published as an `environment.current` object, with magnetic set calculated from `navigation.magneticVariation` and published at `environment.current.setMagnetic`.
+- The webapp now shows magnetic variation as an estimation input and magnetic current set as an output.
+
+### Fixed
+- Magnetic variation is no longer marked idle or stale, since it may update too infrequently for telemetry staleness checks.
+
 ## [2.5.0] - 2026-10-26
 
 ### Added

package/README.md

@@ -62,6 +62,7 @@ Once configured, all consumers on the Signal K bus — KIP, OpenCPN, Instrument
 | `navigation.courseOverGroundTrue` | GPS ground speed direction |
 | `navigation.headingTrue` | True heading — used to rotate the boat-frame correction into the ground frame |
 | `navigation.attitude` | Roll angle — provides the heel index into the correction table |
+| `navigation.magneticVariation` | Magnetic variation — used to convert estimated current set to magnetic north |
 
 ---
 
@@ -73,6 +74,8 @@ Once configured, all consumers on the Signal K bus — KIP, OpenCPN, Instrument
 | `navigation.leewayAngle` | rad | Leeway angle (starboard positive). Derived from the lateral correction component. |
 | `environment.current.drift` | m/s | Estimated current speed. |
 | `environment.current.setTrue` | rad | Estimated current direction (the direction the water moves *toward*). |
+| `environment.current.setMagnetic` | rad | Estimated current direction relative to magnetic north, calculated from `environment.current.setTrue` and `navigation.magneticVariation`. |
+| `environment.current` | object | Current estimate containing `drift`, `setTrue`, and, when magnetic variation is available, `setMagnetic`. |
 
 A 60-second stabilisation period applies after startup. Corrected boatspeed may be published during this window, but current estimation and table learning wait until it ends.
 
@@ -107,6 +110,7 @@ The **Inputs** section shows live readings from the raw sensors as they arrive f
 | Boat speed | `navigation.speedThroughWater` |
 | Ground speed | `navigation.speedOverGround` + `navigation.courseOverGroundTrue` |
 | Attitude (heel) | `navigation.attitude` (roll) |
+| Magnetic variation | `navigation.magneticVariation` |
 
 ### Settings
 
@@ -124,7 +128,7 @@ The **Boatspeed Estimation** section is enabled with the toggle in the panel hea
 
 The panel is organised into three groups:
 
-**Inputs** — the raw sensor values used for correction: heading, boat speed, ground speed, and attitude. Warnings appear here if any are unavailable.
+**Inputs** — the raw signals used by the estimation calculations: heading, boat speed, ground speed, attitude, and magnetic variation. Warnings appear here if any are unavailable.
 
 **Intermediates** — computed vectors that give insight into what the plugin is doing:
 - *Speed correction* — the correction vector currently being applied (longitudinal + lateral components).
@@ -134,6 +138,7 @@ The panel is organised into three groups:
 **Outputs** — what is being published to Signal K:
 - *Corrected boatspeed / Leeway* — corrected STW magnitude and leeway angle.
 - *Current* — estimated current drift and set.
+- *Magnetic set* — estimated current direction relative to magnetic north, calculated using magnetic variation.
 
 ### Settings
 

package/index.js

@@ -295,6 +295,9 @@ module.exports = function (app) {
   let smoothedAttitude = null;
   let rawCurrent = null;
   let smoothedCurrent = null;
+  let magneticVariationHandler = null;
+  let setMagneticHandler = null;
+  let setMagneticPublished = false;
   let smoothedBoatSpeed = null;
   let correctedBoatSpeed = null;
   let lrnBoatSpeed = null;
@@ -684,6 +687,25 @@ module.exports = function (app) {
     // send metadata for current
     MessageHandler.setMeta(app, plugin.id, "environment.current.drift", {units: "m/s", type: "number", description: "Speed of the current"});
     MessageHandler.setMeta(app, plugin.id, "environment.current.setTrue", { units: "rad", type: "number", description: "Direction of the current" });
+    MessageHandler.setMeta(app, plugin.id, "environment.current", { type: "object", description: "Estimated water current" });
+    MessageHandler.setMeta(app, plugin.id, "environment.current.setMagnetic", {
+      units: "rad",
+      type: "number",
+      description: "Direction of the current relative to magnetic north",
+      displayName: "Magnetic set",
+      displayUnits: { category: "angle" }
+    });
+    magneticVariationHandler = new MessageHandler(app, plugin.id, "magneticVariation");
+    magneticVariationHandler.configure("navigation.magneticVariation");
+    magneticVariationHandler.idlePeriod = 0;
+    magneticVariationHandler.stalePeriod = 0;
+    magneticVariationHandler.onDelta = () => {
+      clearLifecycleWarning("magneticVariation");
+      publishCurrentObject();
+    };
+    magneticVariationHandler.subscribe();
+    setMagneticHandler = new MessageHandler(app, plugin.id, "setMagnetic");
+    setMagneticHandler.configure("environment.current.setMagnetic");
     rawCurrent = new Polar(app, plugin.id, "current");
     rawCurrent.configureMagnitude("environment.current.drift");
     rawCurrent.configureAngle("environment.current.setTrue");
@@ -843,6 +865,8 @@ module.exports = function (app) {
       reportFull.addPolar(residual);
       reportFull.addPolar(smoothedResidual);
     }
+    reportFull.addDelta(magneticVariationHandler);
+    reportFull.addDelta(setMagneticHandler);
     // Smoothed learning inputs are always subscribed regardless of updateCorrectionTable,
     // so always add them to the report — otherwise warnings never clear when
     // learning was disabled at startup and later toggled on.
@@ -874,12 +898,14 @@ module.exports = function (app) {
         }
         // Clear all active output paths from the SK bus before teardown.
         if (smoothedCurrent) PolarSmoother.clear(app, plugin.id, [smoothedCurrent]);
+        clearCurrentObjectOutputs();
         if (options.estimateBoatSpeed && correctedBoatSpeed) Polar.clear(app, plugin.id, [correctedBoatSpeed]);
         smoothedHeading = smoothedHeading?.terminate();
         smoothedAttitude = smoothedAttitude?.terminate();
         rawCurrent = rawCurrent?.terminate();
         smoothedCurrent = smoothedCurrent?.terminate?.();
         navigationStateHandler = navigationStateHandler?.terminate();
+        magneticVariationHandler = magneticVariationHandler?.terminate();
         smoothedBoatSpeed = smoothedBoatSpeed?.terminate();
         correctedBoatSpeed = correctedBoatSpeed?.terminate();
         lrnBoatSpeed = lrnBoatSpeed?.terminate();
@@ -895,6 +921,8 @@ module.exports = function (app) {
         noCurrent = null;
         rawBoatSpeed = null;
         rawGroundSpeed = null;
+        setMagneticHandler = null;
+        setMagneticPublished = false;
         lastNavigationStateValue = null;
         learningStabilizingUntil = 0;
         learningStabilizingReason = 'startup';
@@ -986,10 +1014,50 @@ module.exports = function (app) {
     }
 
     PolarSmoother.send(app, plugin.id, [smoothedCurrent]);
+    publishCurrentObject();
 
     Polar.send(app, plugin.id, [correctedBoatSpeed]);
   }
 
+  function publishCurrentObject() {
+    if (!options.estimateBoatSpeed || !smoothedCurrent?.ready) return;
+    const drift = smoothedCurrent.magnitude;
+    const setTrue = smoothedCurrent.angle;
+    if (!Number.isFinite(drift) || !Number.isFinite(setTrue)) return;
+
+    const current = { drift, setTrue };
+    const values = [{ path: "environment.current", value: current }];
+    const magneticVariation = magneticVariationHandler?.value;
+    if (magneticVariationHandler?.ready && Number.isFinite(magneticVariation)) {
+      const setMagnetic = ((setTrue - magneticVariation) % (2 * Math.PI) + 2 * Math.PI) % (2 * Math.PI);
+      current.setMagnetic = setMagnetic;
+      setMagneticHandler.value = setMagnetic;
+      values.push({ path: "environment.current.setMagnetic", value: setMagnetic });
+      setMagneticPublished = true;
+    } else {
+      setMagneticHandler.invalidate();
+      if (setMagneticPublished) {
+        values.push({ path: "environment.current.setMagnetic", value: null });
+      }
+      setMagneticPublished = false;
+    }
+
+    app.handleMessage(plugin.id, { updates: [{ values }] });
+  }
+
+  function clearCurrentObjectOutputs() {
+    setMagneticHandler?.invalidate();
+    setMagneticPublished = false;
+    app.handleMessage(plugin.id, {
+      updates: [{
+        values: [
+          { path: "environment.current", value: null },
+          { path: "environment.current.setMagnetic", value: null }
+        ]
+      }]
+    });
+  }
+
   /**
    * Updates the correction table from the current smoothed inputs.
     * Reads minSpeed from module-level state;
@@ -1188,6 +1256,7 @@ module.exports = function (app) {
       if (key === 'estimateBoatSpeed' && !value && correctedBoatSpeed) {
         Polar.clear(app, plugin.id, [correctedBoatSpeed]);
         PolarSmoother.clear(app, plugin.id, [smoothedCurrent]);
+        clearCurrentObjectOutputs();
       }
 
       delete changedOptions[key];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "speedandcurrent",
-  "version": "2.5.0",
+  "version": "2.6.0",
   "description": "A plugin that automatically corrects boat speed and calculates current and leeway using sensor fusion.",
   "main": "index.js",
   "scripts": {

package/public/app.js

@@ -118,7 +118,7 @@ async function loadMeta() {
 
 const computedItemIds = new Set([
   'current.smoothed', 'boatSpeedRefGround', 'speedCorrection',
-  'correctedBoatSpeed', 'residual', 'residual.smoothed'
+  'correctedBoatSpeed', 'residual', 'residual.smoothed', 'setMagnetic'
 ]);
 
 function getPathStatus(pathState, hasValue, computed = false, computedReady = false) {
@@ -564,6 +564,8 @@ function renderLiveSections() {
   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 magneticVariationInput = filterById(state.deltasAll, ['magneticVariation']);
+  fallbackInputDeltas.push(...magneticVariationInput);
   const fallbackInputAttitudes = inputAttitudes.length ? inputAttitudes : filterById(state.attitudesAll, ['attitude.smoothed']);
   const displayedInputs = [...fallbackInputPolars, ...fallbackInputDeltas, ...fallbackInputAttitudes];
 
@@ -584,7 +586,7 @@ function renderLiveSections() {
     ? [...groundSpeedInputs, ...boatSpeedInputs]
     : [...boatSpeedInputs, ...groundSpeedInputs];
   estimationInputs.push(
-    ...filterById(state.deltasAll, ['heading.angle']),
+    ...filterById(state.deltasAll, ['heading.angle', 'magneticVariation']),
     ...filterById(state.attitudesAll, ['attitude'])
   );
   renderItemsInto('estimation-inputs', estimationInputs);
@@ -599,9 +601,10 @@ function renderLiveSections() {
   renderGroupInto('estimation-intermediates', estimationIntermediates, [], [], statisticRows);
   // Estimation — outputs
   const estimationOutputs = filterById(state.polarsAll, ['correctedBoatSpeed', 'current.smoothed']);
-  renderGroupInto('estimation-outputs', estimationOutputs, [], []);
+  const estimationOutputDeltas = filterById(state.deltasAll, ['setMagnetic']);
+  renderGroupInto('estimation-outputs', estimationOutputs, estimationOutputDeltas, []);
   // Estimation — warnings
-  renderWarnings('estimation-warnings', [...estimationInputs, ...estimationIntermediates, ...estimationOutputs]);
+  renderWarnings('estimation-warnings', [...estimationInputs, ...estimationIntermediates, ...estimationOutputs, ...estimationOutputDeltas]);
 
   // Learning — inputs
   const learningPolars = filterById(state.polarsAll, ['groundSpeed.smoothed']);