signalk-performance-processor 0.0.4 → 0.0.5

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 0.0.5 — 2026-10-29
+
+Still a proof of concept: run it in Shadow mode alongside your instruments.
+
+- **Fix: feedback loop with another STW plugin in Replace mode.** With `signalk-stw-heel-correction` (0.2 or earlier) on the same server, each plugin corrected the other's STW and handed it back, so STW and true wind ran away. Without a chosen STW source, STW is now read from sensors only (updates that carry a `source` object from a data connection), never from another plugin. Choosing a source in Settings still overrides this.
+- **Rate limit as a circuit breaker:** no path is published more often than 20 Hz. A feedback loop is cut at its first repeat, and a backlog flushed after a dropout is thinned rather than stopped; nothing latches. While updates are being dropped, the status and the Live page say so, with a count and the source driving them, for 10 s after the last one; the first is logged.
+- The status says when STW is arriving only from other plugins, and names them.
+- Settings: the STW source's blank choice reads **Auto (sensors only)**.
+
 ## 0.0.4 — 2026-10-29
 
 Still a proof of concept: run it in Shadow mode alongside your instruments. Saved configurations are upgraded to schema 2 on first load.

package/README.md

@@ -8,7 +8,7 @@ If your TWD swings 5–10° every time you tack or gybe, the wind hasn't shifted
 
 This plugin does the calibration job of a B&G H5000-class instrument processor inside Signal K. It corrects boat speed and leeway, then applies H5000-style TWA and TWS correction tables, and publishes corrected true wind and current. You edit everything in a webapp and can watch each correction work live. Run it in **Shadow mode** first: it publishes alongside your existing instruments without changing anything they do.
 
-> **Proof of concept (0.0.4).** Compare it against your instruments in Shadow mode before relying on it. See the [changelog](CHANGELOG.md).
+> **Proof of concept (0.0.5).** Compare it against your instruments in Shadow mode before relying on it. See the [changelog](CHANGELOG.md).
 
 ## Why it exists
 
@@ -73,7 +73,17 @@ The corrections run in this order, each on the output of the one before:
 
 True wind is worked out on every apparent wind update. Inputs older than 3 seconds are not used. Without STW there is no true wind. Without heel, the heel correction and leeway are skipped. Without heading, there is no TWD or current.
 
-Feed it **measured** apparent wind and **raw** paddlewheel speed. If another plugin already corrects STW (for example `signalk-stw-heel-correction`), choose the instrument as the STW source in Settings, or the correction is applied twice.
+Feed it **measured** apparent wind and **raw** paddlewheel speed. Unless you choose an STW source in Settings, STW is read **from sensors only**: updates that came in through a data connection (NMEA 0183, NMEA 2000), which carry a `source` object, and not STW published by another plugin, which does not. See [Running alongside other STW plugins](#running-alongside-other-stw-plugins).
+
+### Running alongside other STW plugins
+
+This plugin publishes STW too, so it must never correct another plugin's STW and hand the result back. Two correctors on `navigation.speedThroughWater` that each take any source but their own correct each other's output without end: STW, and true wind with it, run away. Signal K's own pattern for correction plugins (subscribe with `sourcePolicy: 'all'`, skip your own `$source`, publish on the same path) does not cover this case, because neither plugin ever sees its own source come back.
+
+- **By default it reads STW from sensors only**, so another corrector's output is ignored and no loop can form.
+- **Choosing a source in Settings overrides this**, including choosing another plugin, for a deliberate chain such as `signalk-stw-heel-correction` → this plugin with the STW correction here turned off. That plugin must then read only the paddlewheel (its own default from 0.3.0).
+- **Circuit breaker:** whatever the sources, the plugin never publishes a path more often than 20 Hz: an update less than 50 ms after the last one on that path is not published. A loop's next hop arrives within the same millisecond, so the chain ends at the first repeat instead of running away, and the server stays responsive. A backlog flushed after a dropout is thinned, not stopped. Nothing latches. While updates are being dropped the status and the Live page end with `Rate limited: N updates over 20 Hz not published in the last 10 s, driven by "…"`, naming the source. If it stays up, look for a loop with another STW plugin; a loop that is cut still leaves STW corrected twice.
+
+Only one plugin should correct STW. Otherwise the correction is applied twice even without a loop. In Shadow mode, note that `signalk-stw-heel-correction` also uses `navigation.speedThroughWaterCorrected` for its separate-path output, so the two would overwrite each other there.
 
 ### Outputs
 
@@ -86,7 +96,7 @@ Feed it **measured** apparent wind and **raw** paddlewheel speed. If another plu
 | Leeway (when on) | `navigation.leewayAngle` | `navigation.leewayAngleCorrected` |
 | Current | `environment.current` (`drift`, `setTrue`) | `environment.currentCorrected` |
 
-Everything is published under this plugin's own `$source`. Corrected STW goes out each time the paddlewheel reports, while the STW correction is on; the rest goes out with each apparent wind update. Shadow paths carry `meta` with units, since they are not in the Signal K schema.
+Everything is published under this plugin's own `$source`. Corrected STW goes out each time the paddlewheel reports, while the STW correction is on; the rest goes out with each apparent wind update. No path goes out more often than 20 Hz (see **Circuit breaker** under [Running alongside other STW plugins](#running-alongside-other-stw-plugins)). Shadow paths carry `meta` with units, since they are not in the Signal K schema.
 
 ## Modes
 
@@ -101,7 +111,7 @@ Open **Webapps → Performance Processor**.
 
 - **Live**: the outputs next to their uncorrected values; the pipeline, with each step's result tagged **Published** (sent to Signal K) or **Working** (only feeds the next step); a **Published to Signal K** table listing every value sent and its path; and which source and how fresh each input is.
 - **Calibration**: every correction in pipeline order with an on/off switch. Select one to edit its values, then **Save**. Table headings (the breakpoints) are fixed; only the values are edited, and blank cells are allowed where a table says so. The boat speed table also has **Paste a table**, which reads the `signalk-stw-heel-correction` CSV format. **Reset to defaults** puts back this boat's values for that correction.
-- **Settings**: Shadow or Replace, the fallback magnetic variation, and which source to read for each input.
+- **Settings**: Shadow or Replace, the fallback magnetic variation, and which source to read for each input. **Any** takes every source; for STW the blank choice is **Auto (sensors only)**.
 
 All configuration lives in the webapp. It is saved to `config.json` in the plugin's data directory (under `~/.signalk/plugin-config-data/`), not in the admin **Plugin Config** form, which only points here; saving that form cannot overwrite the tables. Saving needs write access when Signal K security is on.
 

package/index.js

@@ -20,6 +20,12 @@ const MAX_PLAUSIBLE_HEEL_DEG = 90
 // See signalk-stw-heel-correction: below this a correction is float noise, and recording
 // it as an output would make the next identical raw sample look like an echo.
 const ECHO_MIN_DELTA_MS = 1e-6
+// Circuit breaker: no path is published more often than this (20 Hz). A feedback loop
+// through another plugin delivers its next update within the same millisecond, so the
+// chain ends at the first repeat rather than running away, and the server stays
+// responsive. Nothing latches; the status says while it is happening.
+const MIN_PUBLISH_INTERVAL_MS = 50
+const RATE_NOTE_MS = 10000 // how long a dropped update keeps the status flagged
 
 // Inputs, grouped the way they are chosen in Settings.
 const INPUTS = {
@@ -84,10 +90,38 @@ module.exports = function (app) {
     return s === plugin.id || s.startsWith(plugin.id + '.')
   }
 
+  // A plugin publishes with no source object, so the server gives its update only a
+  // $source. Data from a connection (NMEA 0183, NMEA 2000) always carries one.
+  const fromSensor = update => update.source != null && typeof update.source === 'object'
+
   // Backstop echo detector for the one path that is both input and output (STW in
   // replace mode): remember published values that differ from their input.
   const recentStw = []
   let loopWarned = false
+
+  // Rate limit (see MIN_PUBLISH_INTERVAL_MS): when each path was last published, and
+  // when updates were dropped recently, for the status.
+  let publishedAt = {}
+  let dropsAt = []
+  let dropFrom = ''
+  function recentDrops (now) {
+    while (dropsAt.length && now - dropsAt[0] > RATE_NOTE_MS) dropsAt.shift()
+    return dropsAt.length
+  }
+  function noteDrop (now, from) {
+    const first = !recentDrops(now)
+    dropsAt.push(now)
+    dropFrom = from
+    if (!first) return
+    app.error(`Rate limited: "${from}" is driving updates faster than ${1000 / MIN_PUBLISH_INTERVAL_MS} Hz. Is another plugin correcting this plugin's output?`)
+    lastStatus = statusText + rateNote(now) // flag it now, not at the next refresh
+    app.setPluginStatus(lastStatus)
+  }
+  function rateNote (now) {
+    const n = recentDrops(now)
+    return n ? ` · Rate limited: ${n} update${n === 1 ? '' : 's'} over ${1000 / MIN_PUBLISH_INTERVAL_MS} Hz not published in the last ${RATE_NOTE_MS / 1000} s, ` +
+      `driven by "${dropFrom}". Usually a feedback loop with another STW plugin: check the STW source in Settings` : ''
+  }
   function noteStw (ms) {
     recentStw.push(ms)
     if (recentStw.length > 32) recentStw.shift()
@@ -103,10 +137,13 @@ module.exports = function (app) {
   // live numbers in the status keep moving without flooding the admin UI.
   let statusAt = 0
   let statusKind = null
+  let statusText = ''
   function status (kind, text) {
     const now = Date.now()
     if (kind === statusKind && now - statusAt < STATUS_INTERVAL_MS) return
     statusKind = kind
+    statusText = text
+    text += rateNote(now)
     lastStatus = text
     statusAt = now
     app.setPluginStatus(text)
@@ -120,7 +157,15 @@ module.exports = function (app) {
     return Math.abs(h) > MAX_PLAUSIBLE_HEEL_DEG ? null : h
   }
 
-  function publish (values, timestamp) {
+  function publish (values, timestamp, from) {
+    const now = Date.now()
+    const kept = values.filter(v => {
+      if (now - (publishedAt[v.path] ?? -Infinity) < MIN_PUBLISH_INTERVAL_MS) return false
+      publishedAt[v.path] = now
+      return true
+    })
+    if (kept.length < values.length) noteDrop(now, from)
+    values = kept
     if (!values.length) return
     // No source object: the server stamps $source with plugin.id, which is what the
     // loop guard and the user's Source Priorities entry match on.
@@ -128,7 +173,7 @@ module.exports = function (app) {
   }
 
   // Corrected STW goes out as soon as the paddlewheel reports, at its own rate.
-  function onStw (rawMs, timestamp, now) {
+  function onStw (rawMs, timestamp, now, from) {
     const stw = config.corrections.stw
     if (!stw.enabled) return
     const stwKn = rawMs * MS_TO_KN
@@ -138,16 +183,21 @@ module.exports = function (app) {
     const { c } = correctInputs({ stw: stwKn, heel: heelDeg(now) }, config)
     const ms = c.stw / MS_TO_KN
     if (config.mode === 'replace' && Math.abs(ms - rawMs) > ECHO_MIN_DELTA_MS) noteStw(ms)
-    publish([{ path: outPath('stw'), value: ms }], timestamp)
+    publish([{ path: outPath('stw'), value: ms }], timestamp, from)
   }
 
   // True wind, current and leeway go out on every apparent wind update.
-  function onWind (timestamp, now) {
+  function onWind (timestamp, now, from) {
     const awa = fresh('environment.wind.angleApparent', now)
     const aws = fresh('environment.wind.speedApparent', now)
     const stw = fresh('navigation.speedThroughWater', now)
     if (awa == null || aws == null) return status('nowind', 'Waiting for apparent wind')
-    if (stw == null) return status('nostw', 'Waiting for speed through water — no true wind without it')
+    if (stw == null) {
+      const others = !config.sources.stw && sourcesSeen.stw ? Array.from(sourcesSeen.stw) : []
+      return status('nostw', others.length
+        ? `No speed through water from a sensor, only from ${others.join(', ')}. Choose the STW source in Settings`
+        : 'Waiting for speed through water — no true wind without it')
+    }
 
     const awsKn = aws * MS_TO_KN
     const stwKn = stw * MS_TO_KN
@@ -178,7 +228,7 @@ module.exports = function (app) {
     if (o.twd != null) values.push({ path: outPath('twd'), value: o.twd / RAD_TO_DEG })
     if (config.corrections.leeway.enabled) values.push({ path: outPath('leeway'), value: o.leeway / RAD_TO_DEG })
     if (o.current) values.push({ path: outPath('current'), value: { drift: o.current.drift / MS_TO_KN, setTrue: o.current.set / RAD_TO_DEG } })
-    publish(values, timestamp)
+    publish(values, timestamp, from)
 
     const missing = []
     if (input.heel == null) missing.push('heel')
@@ -191,6 +241,7 @@ module.exports = function (app) {
     const now = Date.now()
     let windChanged = false
     let windTimestamp = null
+    let windFrom = ''
     for (const update of (delta.updates || [])) {
       if (isOwnSource(update.$source)) continue
       for (const v of (update.values || [])) {
@@ -199,9 +250,14 @@ module.exports = function (app) {
         if (v.path !== 'navigation.attitude' && !Number.isFinite(v.value)) continue
 
         const src = String(update.$source || '')
+        const sensor = fromSensor(update)
         ;(sourcesSeen[group] = sourcesSeen[group] || new Set()).add(src)
         const wanted = config.sources[group]
         if (wanted && src !== wanted) continue
+        // Without a chosen source, STW is read from sensors only. Another plugin's STW
+        // is already corrected, and this plugin publishes STW too: taking each other's
+        // output, two correctors feed each other without end.
+        if (!wanted && group === 'stw' && !sensor) continue
 
         if (v.path === 'navigation.speedThroughWater' && config.mode === 'replace' && isStwEcho(v.value)) {
           if (!loopWarned) {
@@ -212,16 +268,18 @@ module.exports = function (app) {
         }
 
         latest[v.path] = { value: v.value, source: src, at: now }
-        if (group === 'apparentWind') { windChanged = true; windTimestamp = update.timestamp }
-        if (group === 'stw') onStw(v.value, update.timestamp, now)
+        if (group === 'apparentWind') { windChanged = true; windTimestamp = update.timestamp; windFrom = src }
+        if (group === 'stw') onStw(v.value, update.timestamp, now, src)
       }
     }
-    if (windChanged) onWind(windTimestamp, now)
+    if (windChanged) onWind(windTimestamp, now, windFrom)
   }
 
   function startWith (cfg) {
     stopEverything()
     config = cfg
+    publishedAt = {}
+    dropsAt = []
     latest = {}
     sourcesSeen = {}
     lastResult = null

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "signalk-performance-processor",
-  "version": "0.0.4",
+  "version": "0.0.5",
   "description": "True wind direction that holds steady through tacks and gybes. H5000-style calibration in Signal K: boat speed, leeway, and TWA/TWS tables by wind speed, edited and watched live in a webapp. Try it in shadow mode beside your existing instruments.",
   "main": "index.js",
   "scripts": {

package/public/app.js

@@ -357,7 +357,7 @@
       const chosen = state.draft.sources[key] || ''
       const opts = Array.from(new Set([...(seen[key] || []), chosen].filter(Boolean)))
       return `<label>${esc(label)}<select data-path="sources.${key}">` +
-        `<option value="">Any</option>` +
+        `<option value="">${key === 'stw' ? 'Auto (sensors only)' : 'Any'}</option>` +
         opts.map(s => `<option value="${esc(s)}" ${s === chosen ? 'selected' : ''}>${esc(s)}${(seen[key] || []).includes(s) ? '' : ' (not seen)'}</option>`).join('') +
         '</select></label>'
     }).join('')