signalk-performance-processor 0.0.2 → 0.0.3

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 0.0.3 — 2026-10-29
+
+Still a proof of concept: run it in Shadow mode alongside your instruments.
+
+- Fix: the Calibration and Settings pages were empty on a real server. The plugin's `/config` endpoint was shadowed by the server's own route of that name; it is now `/calibration`, and the webapp says so if the calibration cannot be loaded.
+- README and App Store description explain the problem this solves, who it is for, and the results on the boat it was built for.
+
 ## 0.0.2 — 2026-10-29
 
 Still a proof of concept: run it in Shadow mode alongside your instruments.

package/README.md

@@ -2,13 +2,51 @@
 
 # signalk-performance-processor
 
-> **Proof of concept (0.0.2).** Run it in Shadow mode alongside your instruments and compare before relying on it.
+**True wind direction that holds steady when you tack.**
 
-Signal K plugin and webapp that does the calibration job of an instrument processor such as a B&G H5000: it corrects boat speed and leeway, works out true wind from apparent wind, applies H5000-style TWA and TWS correction tables, and publishes true wind and current.
+If your TWD swings 5–10° every time you tack or gybe, the wind hasn't shifted: your true wind calibration is off. It makes real shifts hard to call, puts laylines in the wrong place, and feeds bad numbers into your polars and targets.
 
-Each correction can be switched on or off and edited in the webapp. A fresh install starts with values fitted to this boat's 2025 race logs.
+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.
 
-See the [changelog](CHANGELOG.md) for what changed in each release.
+> **Proof of concept (0.0.3).** Compare it against your instruments in Shadow mode before relying on it. See the [changelog](CHANGELOG.md).
+
+## Why it exists
+
+True wind is worked out from apparent wind, boat speed and heading, so it inherits every error in them. The masthead sensor reads a bent airflow upwind, the paddlewheel misreads when heeled, and the boat slides sideways. None of these is the same on every point of sail, and some flip from one tack to the other. That is why an uncalibrated TWD jumps through every tack.
+
+Instrument processors fix this with calibration tables, but:
+
+- **The tables are locked in the box.** You edit them through display menus, cannot see what each one is doing at any moment, and keep no history of what you changed or why.
+- **Older and simpler systems have less to work with.** An H2000, for example, has a TWS correction that only applies downwind, and many systems have no tables at all.
+- **Formula-based corrections don't fit every boat.** A single upwash formula cannot follow a boat whose correction is twice as big in light air as in a breeze at the same apparent wind angle. That was the case on the boat this was built for; a table can follow it.
+
+This plugin moves the calibration into Signal K, where you can see it, change it, log it and fit it from your own race data:
+
+- **The same shape as an H5000:** boat speed linearity and heel correction, leeway, and TWA/TWS tables by wind speed with upwind, reach and downwind rows. An existing calibration carries across, and the H5000 tuning rule ("TWD lifts on every tack: take half the error off TWA") works unchanged.
+- **Every correction has a switch and a live readout,** so you can see what each one does to the numbers right now.
+- **The calibration is a versioned JSON file,** easy to back up, compare and fit from logged races offline.
+- **It is safe to try.** Shadow mode publishes `…Corrected` paths beside your instruments. Replace mode takes over the standard paths only when you choose it.
+
+### On the boat it was built for
+
+From the offline model the defaults were fitted with: trained on 2025 race logs, tested on Jan–Mar 2026 races it had not seen, and measured by how far true wind direction jumps through each manoeuvre (median). The shipped defaults differ slightly (the owner's leeway K, and the TWA table resampled to H5000 breakpoints).
+
+| | Uncorrected | Instrument (H2000) | This plugin |
+|---|---|---|---|
+| Tacks (41) | 6.2° | 2.5° | 2.2° |
+| Gybes (5) | 2.4° | 4.7° | 1.1° |
+| Roundings (38) | 9.3° | 9.7° | 7.3° |
+| Current step through manoeuvres | 0.65 kn | 0.65 kn | 0.37 kn |
+
+These figures are one boat's, and the defaults are that boat's. On a different boat, start from the defaults in Shadow mode and refit. After the boat's own rig and log changes in late 2026, the defaults needed refitting too.
+
+## Who it's for
+
+- **Racing sailors running Signal K** who want TWD they can call shifts on, and polars built on corrected wind.
+- **Boats with an older or limited instrument processor,** or none, that still have apparent wind, a paddlewheel, heading and heel on the network.
+- **Anyone who wants to see and log** what their wind calibration is doing, rather than trust a box.
+
+You need apparent wind, boat speed through the water and heading in Signal K. Heel (`navigation.attitude`) enables the heel and leeway corrections; SOG and COG enable current.
 
 ## What it does
 
@@ -109,8 +147,8 @@ Corrections live in `lib/processor.js` as entries in `CORRECTIONS`, each with a
 
 Under `/plugins/signalk-performance-processor`:
 
-- `GET /config` returns the configuration in use and the defaults.
-- `PUT /config` validates, saves and restarts with a new configuration. It returns 400 with the reasons if the configuration is invalid.
+- `GET /calibration` returns the configuration in use and the defaults.
+- `PUT /calibration` validates, saves and restarts with a new configuration. It returns 400 with the reasons if the configuration is invalid.
 - `GET /live` returns the latest result, each step, input ages and the sources seen.
 
 ## Development

package/index.js

@@ -48,7 +48,7 @@ module.exports = function (app) {
   const plugin = {
     id: 'signalk-performance-processor',
     name: 'gh - Performance Processor',
-    description: 'H5000-style calibration: corrects STW and leeway, then true wind angle and speed, and publishes true wind and current'
+    description: 'Steady true wind through tacks and gybes: H5000-style calibration of boat speed, leeway and TWA/TWS, configured in the Performance Processor webapp'
   }
 
   let config = null
@@ -356,12 +356,14 @@ module.exports = function (app) {
   }
 
   plugin.registerWithRouter = function (router) {
-    router.get('/config', (req, res) => {
+    // Not /config: the server registers GET and POST /config on every plugin's router
+    // for its own options, ahead of the plugin's routes, so ours would never be reached.
+    router.get('/calibration', (req, res) => {
       res.set('Cache-Control', 'no-store')
       res.json({ config: config || normalizeConfig(loadStored()).config, defaults: DEFAULTS })
     })
 
-    router.put('/config', async (req, res) => {
+    router.put('/calibration', async (req, res) => {
       let body
       try { body = await readBody(req) } catch (e) { return res.status(400).json({ errors: ['body is not valid JSON'] }) }
       const { config: cfg, errors } = normalizeConfig(body)

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "signalk-performance-processor",
-  "version": "0.0.2",
-  "description": "H5000-style calibration for Signal K: corrects boat speed and leeway, applies TWA and TWS correction tables, and publishes true wind and current. Proof of concept.",
+  "version": "0.0.3",
+  "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": {
     "test": "node --test",

package/public/app.js

@@ -50,14 +50,16 @@
 
   async function loadConfig () {
     try {
-      const body = await getJson('/config')
+      const body = await getJson('/calibration')
+      if (!body || !body.config || !body.config.corrections) throw new Error('the plugin returned no calibration')
       state.saved = body.config
       state.draft = clone(body.config)
       state.defaults = body.defaults
-      $('conn').hidden = true
+      state.configError = null
     } catch (e) {
-      $('conn').textContent = `Cannot reach the plugin (${e.message}). Is Performance Processor enabled?`
-      $('conn').hidden = false
+      // Kept until a load succeeds: the live poll must not clear it.
+      state.configError = `Could not load the calibration (${e.message}). Is Performance Processor enabled and up to date?`
+      setTimeout(loadConfig, 5000)
     }
     renderAll()
   }
@@ -80,7 +82,7 @@
     state.saving = true
     renderSaveBar()
     try {
-      const res = await fetch(API + '/config', {
+      const res = await fetch(API + '/calibration', {
         method: 'PUT',
         credentials: 'include',
         headers: { 'Content-Type': 'application/json' },
@@ -138,6 +140,8 @@
   }
 
   function renderHeader () {
+    $('cfgError').textContent = state.configError || ''
+    $('cfgError').hidden = !state.configError
     const mode = state.saved ? state.saved.mode : null
     const badge = $('mode')
     badge.textContent = mode === 'replace' ? 'Replace' : mode === 'shadow' ? 'Shadow' : '--'

package/public/index.html

@@ -20,6 +20,7 @@
     </nav>
     <div id="status" class="muted status"></div>
     <div id="conn" class="warn" hidden></div>
+    <div id="cfgError" class="warn" hidden></div>
   </header>
 
   <div id="saveBar" class="save-bar" hidden>