speedandcurrent 1.7.8 → 1.7.9

package/README.md

@@ -1,208 +1,285 @@
-# Speed Correction & Current Estimation Plugin
+# Speed and Current — Signal K Plugin
 
-## Overview
-This SignalK plugin estimates **corrected speed through water**, **leeway**, and **water current (drift)** in real-time using adaptive sensor fusion and statistical filtering. It continuously refines its estimates based on vessel speed, heading, ground speed, and heel angle. Its primary goal is to significantly improve paddle wheel speed (navigation.speedThroughWater), where raw errors of 10% or more are common. It does this automatically from real-world observations—no manual calibration required. Leeway (navigation.leewayAngle) is derived from observed dynamics rather than formulas, and current is estimated only after speed is corrected, using a slowly adapting filter.
+## What it does
 
-## Quick Start
-1. Install / enable the plugin in the Signal K Server admin UI.
-2. Open the plugin webapp (Signal K: Apps → Speed and Current).
-3. Go to **Correction Table** and click **New** to create your first correction table (or use the default that was created for you).
-4. Start learning by enabling **Correction Table Learning** in the webapp.
-5. Once your correction table is filled enable **Boatspeed Estimation** in the webapp.
-6. Watch the corrected speed, leeway, and current fields begin populating as data arrives. Initial stabilization may take some sailing at varying speeds and heel angles.
+Most paddle wheel logs carry a systematic error that varies with boat speed and heel angle. A boat heeled at 20° with a fouled bottom at 6 knots may read 5% low; the same boat upright at 3 knots may read 2% high. Manual calibration with a single factor misses this structure entirely.
 
-## Requirements & Data Inputs
-The plugin automatically starts collecting and learning once enabled, but waits the first ~60 seconds before producing estimates to stabilize.
+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.
 
-Required paths:
-- navigation.speedThroughWater (raw paddle wheel speed)
-- navigation.speedOverGround
-- navigation.courseOverGroundTrue (true)
-- navigation.headingTrue (true)
-- navigation.attitude
+In broad terms the plugin:
 
-## Output & Published Paths
-After the initial ~60 second stabilization period the plugin starts sending the following Signal K paths:
+- corrects paddle wheel speed using a learned, heel- and speed-aware correction table
+- estimates leeway angle from the observed lateral correction
+- estimates water current drift and set
+- continuously refines all three as you sail
 
-| Purpose | Path(s) | Units | Notes |
-|---------|---------|-------|-------|
-| Corrected speed through water (magnitude) | navigation.speedThroughWater | m/s | navigation.speedThroughWater. Source attribute distinguishes plugin value from the original sensor. |
-| Leeway angle | navigation.leewayAngle | rad | Angle (starboard positive) associated with corrected STW vector. |
-| Water current speed | self.environment.current.drift | m/s | Magnitude of estimated water current over ground. |
-| Water current set (direction) | self.environment.current.setTrue | rad | True direction (set) the current flows toward. |
+---
+
+## Installation
+
+Install the plugin from the Signal K App Store, or manually by placing it in your Signal K plugin directory and running `npm install`. After installation:
+
+1. Enable the plugin in the Signal K Server admin UI (**Server → Plugin Config → Speed and Current → Active**).
+2. Open the plugin webapp from the Signal K app list (**Apps → Speed and Current**).
+3. The plugin creates a default correction table on first start. You do not need to create one manually.
+4. Enable **Update Correction Table** to start learning.
+5. After the table has some coverage, enable **Estimate Boat Speed**.
+
+The plugin requires no further configuration in the Signal K admin UI. All settings are managed from its own webapp.
+
+---
 
-Boat speed overwrite / duplication behavior:
-- When the setting "Prevent speed duplication" = true (default): plugin overwrites navigation.speedThroughWater with corrected value.
-- When false: both raw and corrected updates exist under navigation.speedThroughWater with distinct source attributes (viewable in deltas / data browser) allowing comparison.
+## Required Signal K paths
 
-Current vector representation: Published as polar (drift + set). Set angle is the direction the water moves toward (oceanographic convention). Verify tooling expectations if it assumes FROM direction.
+| Path | Role |
+|------|------|
+| `navigation.speedThroughWater` | Raw paddle wheel speed — the signal being corrected |
+| `navigation.speedOverGround` | GPS ground speed magnitude |
+| `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 |
 
+---
+
+## Output paths
 
-## The correction table
-At the heart of the plugin is a correction table that provides a correction vector based on observed boat speed and heel. The correction table is built and maintained by the plugin itself, no user input is required. The plugin can even build a correction table on tidal waters, although this feature is experimental and may not work properly under all circumstances.
+| Path | Unit | Description |
+|------|------|-------------|
+| `navigation.speedThroughWater` | m/s | Corrected speed through water. Source attribute identifies it as the plugin output. |
+| `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*). |
 
-Every time the paddle wheel provides a measurement the plugin does two things. First it corrects boat speed and estimates leeway and current using the correction table. Second, using boat speed, ground speed and current estimation the correction table is updated. So the correction table is used and updated simultaneously.
+A 60-second stabilisation period applies after startup. No output is published during this window; the status bar shows **Stabilizing**.
+
+---
 
-## Configuration
-All settings are managed from the plugin webapp. The Signal K admin UI is not used for configuration.
+## The webapp
 
-### Core
-| Setting | Default | Description | When to Change |
-|---------|---------|-------------|----------------|
-| Estimate Boat Speed | Off | Enables speed correction, leeway and current estimation. | Turn on after creating a correction table. |
-| Update Correction Table | On | Learns / refines correction table. | Temporarily disable in abnormal conditions (heavy seas, abnormal current). |
+The plugin is configured and monitored through its own webapp (Signal K Apps → **Speed and Current**). The sidebar has four sections: **Inputs**, **Boatspeed Estimation**, **Correction Table Learning**, and **Correction Table**. Settings changes take effect immediately without restarting.
 
-### Learning & Stability
-| Setting | Default | Description | Guidance |
-|---------|---------|-------------|----------|
-| Correction Table Stability | 7 | Higher = slower changes (more conservative). | Increase once table broadly populated; lower briefly if you think the sensor error has changed. |
-| Assume Current (experimental) | Off | Learns table while assuming a current may be present. | Enable cautiously on tidal waters. |
-| Show Statistics | Off | Displays σ (standard deviation) next to smoothed values. | Enable for debugging or to inspect signal quality. |
+### Warning indicators
 
-### Smoother
-Controls how raw sensor signals are smoothed before being fed into the learning calculations. The smoother type and its parameter apply to heading, boat speed, ground speed, and attitude.
+Whenever a required signal is not available, the relevant section shows a **Warnings** panel listing each affected input and why:
+
+| Reason | Meaning |
+|--------|---------|
+| *not subscribed to Signal K* | Subscription did not succeed. Try restarting the plugin. |
+| *path not found in Signal K* | No device is publishing this path. Check instrument connections and your multiplexer configuration. |
+| *waiting for first data* | The path is known but no value has arrived since the plugin started. Normal for a few seconds at startup. |
+| *data is stale* | Data was arriving but has stopped. The instrument may have gone offline, or its update rate has dropped below the staleness threshold. |
+
+---
+
+## Inputs
+
+The **Inputs** section shows live readings from the raw sensors as they arrive from Signal K, before any smoothing or correction. This is a useful first stop when diagnosing instrument problems.
+
+### Live values
+
+| Value | Signal K path |
+|-------|--------------|
+| Heading | `navigation.headingTrue` |
+| Boat speed | `navigation.speedThroughWater` |
+| Ground speed | `navigation.speedOverGround` + `navigation.courseOverGroundTrue` |
+| Attitude (heel) | `navigation.attitude` (roll) |
+
+### Source selection
+
+For each path you can pin the plugin to a specific Signal K source. This is useful when multiple devices publish the same path — for example two GPS receivers, or a fluxgate and a satellite compass both publishing `navigation.headingTrue`. Leave a source blank or select **(any)** to accept values from all sources. This is independent of the Signal K server's global source priority settings.
+
+### Settings
 
 | Setting | Default | Description |
 |---------|---------|-------------|
-| Smoother type | Moving average (window) | Moving average (window), Exponential (τ), or Kalman filter. |
-| Window (s) | 5 s | (Moving average) Integration window in seconds. Minimum 2 s. |
-| Time constant τ (s) | 3 s | (Exponential) Exponential decay time constant in seconds. Minimum 1 s. |
-| Steady-state gain | 0.2 | (Kalman) Kalman gain at steady state. Range 0.01–0.99. Lower = smoother but slower. |
-
-### Table Dimensions
-Table dimensions are set when creating or resizing a table via the webapp (New / Resize buttons). The parameters are:
-
-| Parameter | Default | Description |
-|-----------|---------|-------------|
-| Name | — | Identifier used as the filename on disk. |
-| Max speed (kn) | 9 kn | Upper speed coverage. |
-| Speed step (kn) | 1 kn | Speed increment for table rows. |
-| Max heel (°) | 32° | Max absolute heel covered (± value). |
-| Heel step (°) | 8° | Heel increment for table columns (positive & negative). |
-
-### Data Sources (optional overrides)
-| Setting | Description |
-|---------|-------------|
-| Heading Source | Force a specific source for navigation.headingTrue. |
-| Boat Speed Source | Force a specific source for navigation.speedThroughWater. |
-| Ground Speed Source (SOG Source) | Source for navigation.speedOverGround. |
-| Attitude Source | Source for navigation.attitude (roll/heel). |
-
-Leave a source blank or set to *(any)* to accept values from all sources. If multiple sources exist for a path, you can also set source priorities in the Signal K Server settings (under data sources).
-
-### Output Behavior
-| Setting | Default | Description | Notes |
-|---------|---------|-------------|-------|
-| Prevent speed duplication | On | Overwrites navigation.speedThroughWater with corrected value. | Disable to compare raw vs corrected via distinct source attributes under the same path. |
-| Groundspeed fallback | Off | Copy navigation.speedOverGround (GPS) to navigation.speedThroughWater (Paddle wheel) if paddle wheel malfunction is detected. | Activates when navigation.speedThroughWater = 0 and navigation.speedOverGround > threshold. |
-
-### Tips
-1. Be patient with the correction table. Its corrections will improve over time.
-2. Once corrections stabilize, raise Stability to lock in values.
-3. Freeze learning (disable Update Correction Table) before performance-sensitive events (e.g., racing) or in unstable conditions (waves, currents).
-4. After paddle wheel cleaning or if fouling suspected: temporarily LOWER Stability (e.g., from 7 → 5) to let corrections adapt, then raise again; do not rebuild unless the grid itself must change.
-5. The plugin will always estimate currents when Estimate boat speed is enabled. Even when Assume currents is disabled, as this setting is only used in updating the correction table.
-
-## Persistence & Data Storage
-Each correction table is saved as a `.json` file in Signal K's plugin data directory (typically `~/.signalk/plugin-config-data/speedandcurrent/`). The active table name is stored in the plugin options and reloaded automatically on restart. While learning is active, the table is written to disk approximately every 60 seconds.
-
-Safety & backup:
-- Tables can be copied to a new name with the **Copy** button before experimenting.
-- The data directory can be backed up directly; each table is a self-contained `.json` file.
-
-## Experimental Note
-The "Assume Current" option is experimental. It works best on a stable correction table as it takes time for the plugin to properly distinguish currents from paddle wheel errors. 
-
-## WebApp Usage Guide
-Open via Signal K Server: Apps → Speed and current.
-
-The webapp has a collapsible sidebar with four sections, and a status message in the top-right of the nav bar (blue = stabilizing, amber = SOG fallback active, red = error or stopped). All settings changes take effect immediately — no plugin restart required.
-
-### Inputs
-The **Inputs** section contains two sub-sections:
-- **Signal K Sources**: Drop-downs to pin specific Signal K sources for heading, boat speed, SOG, and attitude. Leave blank to accept any source.
-- **Live Values**: Real-time display of the raw sensor values being fed into the plugin.
-
-### Boatspeed Estimation
-The **Boatspeed Estimation** section has an On/Off toggle at the top of the card and contains:
-- **Settings**: `Groundspeed fallback` and `Prevent speed duplication`.
-- **Inputs**: The raw signal values used for correction (heading, raw STW, SOG, attitude).
-- **Intermediates**: Internally derived quantities including the speed correction vector, boat speed over ground, and residual.
-- **Outputs**: Corrected boatspeed & leeway, and estimated current.
-
-### Correction Table Learning
-The **Correction Table Learning** section has an On/Off toggle and contains:
-- **Settings**: Stability, Assume Current, and Show Statistics (σ display toggle).
-- **Smoother**: Type selector (Moving average / Exponential / Kalman) and its single tuning parameter. Only the parameter relevant to the selected smoother is shown.
-- **Inputs**: Smoothed values fed into the learning algorithm. When Show Statistics is on, σ values are shown.
-
-### Correction Table
-The **Correction Table** section shows the current correction table grid. Table management buttons appear top-right:
-- **New** — create a new table, setting its name and grid dimensions.
-- **Load** — switch to a previously saved table.
-- **Copy** — duplicate the current table under a new name.
-- **Resize** — resize the grid (existing cells are mapped to the new grid; some data may be lost).
-
-Each populated cell shows:
-- **Factor** (±%): how much the paddle wheel over- or under-reads at this speed and heel (green = reads slow, orange = reads fast).
-- **Leeway** (°): the estimated sideways drift angle; also encoded visually as the stripe direction in the cell background.
-
-Cell highlighting:
-- **Blue values**: the most recently updated table cell (factor and leeway text rendered in blue).
-- **Thin border**: cells contributing to the current interpolation.
-- **No content**: not yet populated by learning.
-
-### Correction Table Health Checklist
-- Leeway ≈ 0 at zero heel; increases logically with heel. Non-zero leeway at zero heel may indicate a heading offset.
-- Speed corrections should trend consistently with adjacent cells (direction & magnitude smooth across the table).
-- Port / starboard symmetry: similar magnitudes at ± matching heel angles. Large asymmetry can indicate a paddle wheel mounting offset.
-
-### Interpreting Live Values
-- **Corrected Speed vs Raw**: Stable, plausible separation between the two indicates the table is working.
-- **Corrected speed** includes leeway and therefore is not aligned with the ship's axis.
-- **Residual**: Remaining ground-speed discrepancy after applying corrected STW and estimated current. Should trend toward small values as learning progresses.
-- **Trace**: Uncertainty indicator derived from internal variance (higher = less reliable). Shown alongside most values.
-
-
-
-## How It Works
-
-
-### 1. Speed Correction
-- Vessel speed errors depend on **heel** and **speed** and are treated as locally constant within grid cells.
-- The correction table stores a vector (magnitude & direction of sensor error) per (speed, heel) cell.
-- A correction vector is computed by weighting (interpolation) of the nearest populated cells.
-- The corrected speed-through-water vector = raw STW vector + correction vector (sign chosen so magnitude bias is reduced).
-
-### 2. Leeway Estimation
-- Leeway is derived from the angular difference between the corrected STW direction and the hull axis / heading reference.
-
-### 3. Current Estimation
-- The water current is estimated as a **slowly changing** ground-plane vector.
-- A Kalman filter updates the current using residual between ground speed (GPS) and the heading-rotated corrected boat speed, weighted by estimated variances.
-- ![current estimation model](https://github.com/Asw1n/speedandcurrent/raw/main/currentModel.png)
-
-### 4. Correction Estimating
-- Each populated cell maintains its own lightweight Kalman filter.
-- For each incoming raw boat speed sample the instantaneous sensor error candidate is derived from boat speed, heel, heading, ground speed and (optionally) current.
-- That error sample updates the cell’s Kalman state (mean correction vector + variance).
-- Sensor and estimation variances are continuously updated; the displayed Trace in the webApp reflects confidence (higher = less reliable).
-- ![correction model](https://github.com/Asw1n/speedandcurrent/raw/main/correctionModel.png)
-
-## Glossary
-- Set: Direction the water current flows toward (true angle).
-- Drift: Magnitude (speed) of the water current over ground.
-- Leeway: Lateral angular difference between boat’s heading axis and its actual movement through water (starboard positive).
-- Residual: Remaining ground-speed vector difference after applying corrected STW and estimated current; indicator of modeling error and sensor noise.
-- Stability (setting): Damps rate of change in learned corrections; higher = slower adaptation.
-- Trace: Reported uncertainty indicator derived from internal variance (higher = less confidence in that vector/cell).
-- Kalman filter: An adaptive algorithm that estimates the true value of a variable (such as speed or current) by combining noisy measurements and prior estimates, updating both the value and its uncertainty over time. Used here to refine correction vectors (cell-by-cell) and current estimates .
-
-### Coordinate Frames
-- Boat Plane: Vectors relative to hull axis (used for raw & corrected STW, leeway angle computation).
-- Ground Plane: Vectors in earth-referenced frame (used for GPS ground speed, current, residual).
+| **Staleness Detection** | On | Mark an input as unavailable when it stops updating. Disable when testing the plugin with simulated or replayed data, where timing is irregular and would otherwise trigger spurious warnings. |
+
+---
+
+## Boatspeed Estimation
+
+The **Boatspeed Estimation** section is enabled with the toggle in the panel header. When off, no corrected output is published; the raw paddle wheel value passes through to the SK bus unchanged (subject to the Prevent Speed Duplication setting).
+
+### What it shows
+
+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.
+
+**Intermediates** — computed vectors that give insight into what the plugin is doing:
+- *Speed correction* — the correction vector currently being applied (longitudinal + lateral components).
+- *Boat speed over ground* — the corrected STW vector rotated into the ground frame using heading.
+- *Residual* and *Smoothed residual* — the difference between ground speed and (corrected boat speed + estimated current). Ideally near zero; a persistent non-zero residual indicates remaining systematic error or a current the plugin has not yet picked up.
+
+**Outputs** — what is being published to Signal K:
+- *Corrected boatspeed / Leeway* — corrected STW magnitude and leeway angle.
+- *Current* — estimated current drift and set.
+
+### Settings
+
+| 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. |
+| **Prevent Speed Duplication** | On | Replace the raw sensor value on the SK bus with the corrected value. When off, both raw and corrected exist under `navigation.speedThroughWater` with different source attributes — useful for comparing before and after. |
+| **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. |
+
+---
+
+## Correction Table Learning
+
+The **Correction Table Learning** section has its own independent toggle. Learning and estimation are decoupled: you can learn without estimating (building the table during a passage before trusting it), and you can estimate without learning (freezing the table once you are satisfied with it).
+
+### What it shows
+
+The panel shows the **smoothed** sensor inputs used for table updates — heading, boat speed, ground speed, and attitude. These are the same signals as in the Estimation panel, but averaged over the smoother window before being fed into the learning algorithm. This averaging reduces the influence of short-term fluctuations on the table update.
+
+When **Assume Current** is enabled, the smoothed current estimate is also shown as a learning input.
+
+Warnings appear here if any smoothed input is unavailable.
+
+### 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. |
+| **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. |
+
+### Smoother settings
+
+Controls how raw sensor values are averaged before being used for table updates. These settings have no effect on the published corrected values — only on the inputs to the learning algorithm.
+
+The smoother serves a second purpose beyond noise reduction: its output variance tells the plugin how much to trust each observation. A tight, stable signal (low variance) produces an observation that is weighted heavily in the Kalman update. A signal that has been varying rapidly — because the boat is turning, the sails are flogging, or conditions are rough — has high variance, and the resulting observation is trusted less and moves the cell estimate by a smaller amount. The smoother therefore acts as an automatic quality gate: the table learns most from steady, settled sailing.
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| **Smoother Type** | Moving average | Moving Average (window), Exponential decay (τ), or Kalman filter. Moving average is the most predictable. |
+| **Window size** | 5 s | (Moving average) Integration window. Larger = smoother but slower to respond. Minimum 2 s. |
+| **Time constant (τ)** | 3 s | (Exponential) Decay time constant. Larger = smoother. Minimum 1 s. |
+| **Kalman gain** | 0.2 | (Kalman) Steady-state gain. Lower = smoother / slower. Range 0.01–0.99. |
+
+A 5-second moving average window suits typical 1 Hz instrument update rates. In rough conditions with high sensor noise, increasing it to 8–10 seconds may improve table quality at the cost of temporal resolution.
 
+---
+
+## Correction Table
+
+The **Correction Table** section displays the active correction table. Rows are speed bins, columns are heel bins — port heel on the left (negative values), starboard on the right (positive values).
+
+### Reading the table
+
+Each cell that has received at least one observation shows two values:
+
+- **Speed factor** (e.g. `+3.2%` or `−1.5%`): how much faster or slower the true speed is compared to what the paddle wheel reads. **Green** = paddle wheel reads slow (the correction adds speed). **Orange** = paddle wheel reads fast (the correction reduces speed). Colour intensity scales with the magnitude of the factor relative to the largest factor in the table.
+- **Leeway** (e.g. `+4°`): the observed lateral correction for that speed/heel combination. Positive is starboard. When leeway is non-zero the cell background shows diagonal stripes; the stripe angle encodes the leeway direction visually.
+
+Empty cells have not yet received any observations and show no correction.
+
+### Active cell and neighbours
+
+The **active cell** — the one most recently updated by an incoming STW sample — is highlighted with a bold border and blue text. The **neighbour cells** contributing to the current interpolation are shown with a faint tint. Watching these as you sail shows exactly which part of the table is being applied and updated at any moment.
+
+### Table management
+
+| Action | Description |
+|--------|-------------|
+| **New** | Create a new table with specified speed and heel dimensions. The current table is replaced. |
+| **Load** | Switch to a previously saved table. Tables are stored as JSON files in the plugin's data directory. |
+| **Copy** | Save the current table under a new name without modifying it. |
+| **Resize** | Change the speed/heel range or step size. Existing cell values are resampled onto the new grid — nothing is lost, but resampled cells benefit from a few more observations to consolidate on the new grid. |
+
+Multiple tables can coexist on disk; only the active one is used. This makes it straightforward to keep separate tables for different configurations such as racing vs. cruising sails, or before and after antifouling.
 
 ---
 
+## Operating notes
+
+**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.
+
+**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.
+
+**Corrections improve in context.** A correction derived from rough seas with high GPS variance receives a small Kalman gain and moves the cell estimate less than a correction from flat water at steady speed. The table naturally weights calm, steady observations more heavily.
+
+**Resizing the table is non-destructive.** The Resize function resamples existing cell values onto the new grid. Nothing is lost — resampled cells just need a few more observations to consolidate at the new resolution.
+
+**Current estimation lags behind reality.** The slow Kalman smoother is intentional — it prevents GPS noise and short-term manoeuvres from corrupting the estimate. In rapidly changing tidal conditions the estimate will lag the actual current by several minutes. For precise tidal navigation use an independent current source.
+
+---
+
+## How it works — technical detail
+
+### How corrections are applied
+
+Each cell in the correction table holds a 2-dimensional correction vector **[x, y]** in the boat frame:
+- **x** is the longitudinal component (along the centreline, positive = forward). This is the main speed error.
+- **y** is the lateral component (positive = starboard). This becomes the leeway estimate.
+
+When a new paddle wheel sample arrives the plugin:
+1. Looks up the current speed and heel.
+2. Retrieves an interpolated correction vector from the table.
+3. Adds that vector to the raw STW vector.
+4. The corrected magnitude is published as `navigation.speedThroughWater`; the lateral component divided by the corrected forward speed gives `navigation.leewayAngle`.
+
+### Neighbour interpolation
+
+Rather than bi-linear interpolation the plugin uses **inverse-distance weighting** over the five nearest cells in speed/heel space:
+
+$$w_i = \frac{1}{d_i + \epsilon}$$
+
+where $d_i$ is the Euclidean distance from the query point to cell centre $i$ in normalised speed/heel space. Only cells that have received at least one observation ($N > 0$) contribute.
+
+The final correction is the normalised weighted average:
+
+$$\hat{x} = \frac{\sum_i w_i \cdot x_i}{\sum_i w_i}, \quad \hat{y} = \frac{\sum_i w_i \cdot y_i}{\sum_i w_i}$$
+
+The variance of each axis is propagated through the same weighting, so cells with low confidence (high covariance) influence the result less. If only one or two cells have data, the correction extrapolates gradually to nearby conditions. As more cells fill in, the correction becomes tighter and more local.
+
+### How the correction table is populated
+
+Each cell is an independent **2-dimensional Kalman filter** tracking the correction vector $[x, y]$ for that speed/heel bin, with a 2×2 covariance matrix expressing confidence in each axis.
+
+Every time conditions are right — plugin running for >60 seconds, smoothers settled, speed above minimum threshold — the plugin computes an **observation** of what the correction should be:
+
+$$\text{observation} = R(\psi)^{-1} \cdot \vec{V}_{SOG} - R(\psi)^{-1} \cdot \vec{V}_{current} - \vec{V}_{STW}$$
+
+where $R(\psi)$ rotates from ground frame to boat frame using true heading $\psi$. In plain terms: rotate GPS velocity into the boat frame, subtract the current estimate (also rotated), subtract the raw paddle wheel velocity. The residual is the implied sensor error for the current speed and heel.
+
+The Kalman update combines this observation with the cell's existing belief:
+
+$$K = P \cdot (P + R_{obs})^{-1}$$
+$$x_{new} = x_{old} + K \cdot (\text{observation} - x_{old})$$
+
+where $P$ is the cell's current covariance and $R_{obs}$ is the observation covariance derived from the measurement uncertainty of all contributing signals (SOG variance + current variance + STW variance, rotated appropriately). **Noisy observations produce a smaller gain and move the cell estimate less.**
+
+### The stability setting in detail
+
+Each cell has a small **process noise** that allows it to drift slowly over time, reflecting that a paddle wheel's error can change with fouling, recalibration, or crew weight distribution. Process noise is:
+
+$$Q = 10^{-\text{stability}}$$
+
+With stability = 7 (default), $Q = 10^{-7}$, making the cell very resistant to change — it effectively averages hundreds of observations before settling. Stability 4–5 makes the table react faster to recent conditions; stability 10–12 is appropriate for a well-characterised boat that changes rarely.
+
+In practical terms: high stability = trust the accumulated history; low stability = trust recent observations more.
+
+### How current is estimated
+
+Current is estimated as:
+
+$$\vec{V}_{current} = \vec{V}_{SOG} - R(\psi) \cdot \vec{V}_{STW, corrected}$$
+
+The corrected STW vector is rotated into the ground frame using heading, then subtracted from the GPS velocity. The residual is the water velocity.
+
+This raw estimate is fed into a **Kalman smoother with very low process noise** (process variance $\approx 10^{-6}$), so it changes very slowly, integrating over many minutes rather than chasing individual GPS fluctuations. At startup the estimate is strongly initialised to zero.
+
+Current estimation requires an accurate boat speed, so it is gated by the 60-second stabilisation period and only runs when **Estimate Boat Speed** is enabled.
+
+### Current and table learning
+
+Current estimation always runs alongside speed correction — it is a direct byproduct of comparing the GPS velocity with the corrected STW vector. You cannot have one without the other.
+
+For table *learning*, however, current can be left out of the equation without significant harm. When a boat sails different headings over time — tacking, gybing, reaching — any steady current appears as an error in one direction on one heading and the opposite direction on another. These errors cancel in the long-term average, so the table converges on the correct speed correction regardless. This is why the default (**Assume Current** off) uses a zero-current placeholder rather than the live estimate.
 
+Including the current estimate (**Assume Current** on) would be more accurate in principle, but it introduces a dependency: the current estimate is only as good as the speed correction that produced it. Early in the table's life, when corrections are rough, the current estimate is also rough, and feeding it back into learning can amplify rather than reduce error. There is also a circularity: better speed correction → better current estimate → better speed correction. Enabling this before the table has had time to settle can cause the two to pull each other in the wrong direction, particularly in changing tidal conditions. Use it only once the table is reasonably well populated and current conditions are stable.

package/correctionTable.js

@@ -82,13 +82,15 @@ class CorrectionTable extends Table2D{
   constructor(id, row, col, stability=5) {
     super(id, row, col, CorrectionEstimator, CorrectionEstimator.getFilterModel(stability));
     this.lastUpdatedCell = null;
+    this.lastUpdateResult = null;
     this.neighbours = [];
   }
   
   update(speed, heel, groundSpeed, current, boatSpeed, heading) {
     const cell = this.getCell(speed, heel);
-    cell?.update(groundSpeed, current, boatSpeed, heading);
+    const accepted = cell?.update(groundSpeed, current, boatSpeed, heading);
     this.lastUpdatedCell = cell;
+    this.lastUpdateResult = accepted === true ? 'accepted' : 'rejected';
   }
 
   getCorrection(speed, heel) {
@@ -177,7 +179,8 @@ class CorrectionTable extends Table2D{
           return cellReport;
         })
       ),
-      displayAttributes: this.displayAttributes 
+      displayAttributes: this.displayAttributes,
+      lastUpdateResult: this.lastUpdateResult ?? null
     };
   }
 
@@ -260,6 +263,36 @@ class CorrectionEstimator {
       groundCov[1][0] + currentCov[1][0] + boatCov[1][0],
       groundCov[1][1] + currentCov[1][1] + boatCov[1][1]],
     ];
+    // Mahalanobis distance check.
+    // For empty cells (filterState === null) we use a diffuse prior — mean (0,0),
+    // variance DIFFUSE_PRIOR_VAR — expressing "assume no correction needed, but
+    // with high uncertainty".  This gates the very first observation instead of
+    // accepting it unconditionally, preventing a single outlier from locking a
+    // cell at a bad value.
+    const DIFFUSE_PRIOR_VAR = 1.0; // (m/s)² — rejects corrections > ~3 m/s from zero
+    const priorMean = this.filterState !== null
+      ? [this.filterState.mean[0][0], this.filterState.mean[1][0]]
+      : [0, 0];
+    const priorCov = this.filterState !== null
+      ? this.filterState.covariance
+      : [[DIFFUSE_PRIOR_VAR, 0], [0, DIFFUSE_PRIOR_VAR]];
+    const inno = [observation[0] - priorMean[0], observation[1] - priorMean[1]];
+    const S = [
+      [priorCov[0][0] + observationCovariance[0][0],
+       priorCov[0][1] + observationCovariance[0][1]],
+      [priorCov[1][0] + observationCovariance[1][0],
+       priorCov[1][1] + observationCovariance[1][1]]
+    ];
+    const det = S[0][0] * S[1][1] - S[0][1] * S[1][0];
+    if (Number.isFinite(det) && det > 1e-12) {
+      const Sinv = [
+        [ S[1][1] / det, -S[0][1] / det],
+        [-S[1][0] / det,  S[0][0] / det]
+      ];
+      const d2 = inno[0] * (Sinv[0][0] * inno[0] + Sinv[0][1] * inno[1])
+               + inno[1] * (Sinv[1][0] * inno[0] + Sinv[1][1] * inno[1]);
+      if (d2 > 9.21) return false;
+    }
     this.filterState = this.filter.filter({ previousCorrected: this.filterState, observation, observationCovariance });
     return true;
   }

package/index.js

@@ -447,14 +447,17 @@ module.exports = function (app) {
       reportFull.addPolar(residual);
       reportFull.addPolar(smoothedResidual);
     }
-    if (options.updateCorrectionTable) {
-      reportFull.addDelta(smoothedHeading);
-      reportFull.addAttitude(smoothedAttitude);
-      reportFull.addDelta(smoothedBoatSpeed);
-      reportFull.addPolar(smoothedGroundSpeed);
-      if (options.assumeCurrent) {
-        reportFull.addPolar(smoothedCurrent);
-      }
+    // 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.
+    reportFull.addDelta(smoothedHeading);
+    reportFull.addAttitude(smoothedAttitude);
+    reportFull.addDelta(smoothedBoatSpeed);
+    reportFull.addPolar(smoothedGroundSpeed);
+    // smoothedCurrent is already added by the estimateBoatSpeed block when that is on;
+    // only add it here when estimateBoatSpeed is off, to avoid a duplicate entry.
+    if (options.assumeCurrent && !options.estimateBoatSpeed) {
+      reportFull.addPolar(smoothedCurrent);
     }
     reportFull.addTable(table);
 
@@ -486,14 +489,20 @@ module.exports = function (app) {
 
       setStatus(wellUnderway ? 'Running' : 'Stabilizing');
       if (options.estimateBoatSpeed) correct(wellUnderway);
-      if (options.updateCorrectionTable && wellUnderway) {
-        updateTable();
-        // Save correction table periodically
-        const now = new Date();
-        if (now - lastSave > 60 * 1000) {
-          saveTable(table, path.join(app.getDataDirPath(), table.id + '.json'));
-          lastSave = now;
+      if (options.updateCorrectionTable) {
+        if (wellUnderway) {
+          updateTable();
+          // Save correction table periodically
+          const now = new Date();
+          if (now - lastSave > 60 * 1000) {
+            saveTable(table, path.join(app.getDataDirPath(), table.id + '.json'));
+            lastSave = now;
+          }
+        } else {
+          table.lastUpdateResult = 'stabilizing';
         }
+      } else {
+        table.lastUpdateResult = null;
       }
     };
   }
@@ -606,11 +615,16 @@ 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)) return;
+    if (!smoothedAttitude.ready || !smoothedBoatSpeed.ready || !smoothedHeading.ready || !smoothedGroundSpeed.ready || (options.assumeCurrent && !smoothedCurrent.ready)) {
+      table.lastUpdateResult = 'invalid';
+      return;
+    }
     
     // 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';
     }
 
   }

package/package.json

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

package/public/app.js

@@ -609,6 +609,31 @@ function renderLiveSections() {
   const learningWarningIds = ['boatSpeed.smoothed', 'groundSpeed.smoothed', 'heading.smoothed', 'attitude.smoothed'];
   if (config && config.assumeCurrent) learningWarningIds.push('current.smoothed');
   renderWarnings('learning-warnings', learningWarningIds);
+  // 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';
+    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>`;
+  }
   // Correction table
   const tableEl = document.getElementById('table-container');
   if (tableEl) {

package/public/index.html

@@ -155,6 +155,10 @@
               </table>
               <h6 class="text-uppercase fw-bold text-muted border-bottom pb-1 mt-3 mb-1 small">Inputs</h6>
               <div id="learning-inputs"></div>
+              <h6 class="text-uppercase fw-bold text-muted border-bottom pb-1 mt-3 mb-1 small">Status</h6>
+              <table class="table table-sm table-borderless mb-0" id="learning-status-table">
+                <tbody></tbody>
+              </table>
               <div id="learning-warnings"></div>
             </div>
           </div>