signalk-polar-performance-plugin 1.4.0 → 2.0.0

package/CHANGELOG.md

@@ -6,6 +6,18 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 
 ## [Unreleased]
 
+## [2.0.0] - 2026-09-09
+
+### Added
+- External polar provider integration: subscribes to `polars.activePolar` and `polars.performanceFactor` from Signal K (published by a polar provider plugin such as `signalk-polar-management`), decoupling polar storage and file import from live compute.
+- Integration with standalone `polar-math` package for core polar calculations, interpolation models, and target evaluations.
+- Optional peer dependency declaration for `signalk-polar-management`.
+
+### Changed
+- Major architectural split: removed built-in polar file storage, file parsers/converters, and ORC database importing. All polar management is now handled by a dedicated polar provider plugin.
+- Simplified webapp UI: removed polar management and import tabs; Overview tab and Plotter now display the active polar and its metadata from Signal K.
+- Output path safety: output paths are cleanly nullified when no active polar is present or when required instrument inputs are unavailable.
+
 ## [1.4.0] - 2026-09-01
 
 ### Changed

package/README.md

@@ -1,31 +1,38 @@
 # Polar Performance — Signal K Plugin
 
-Polar Performance reads your boat's true wind speed, true wind angle, and boat speed from Signal K, looks up the corresponding target values from your polar diagram, and publishes performance metrics — beat angle, run angle, VMG, polar speed ratio, and others — back to the Signal K bus in real time. An integrated webapp lets you inspect the live values, manage polars, and configure the plugin while it is running.
+Polar Performance calculates live sailing performance metrics — target boat speeds, beat and run angles, target VMG, polar speed ratio, and optimum wind angles — in real time from your boat's instruments in Signal K. An integrated webapp and full-screen plotter let you inspect live values, target angles, and polar curves while sailing.
 
-Current runtime behaviour is also more explicit: when a polar lookup cannot be completed or a required input has no usable value, the plugin writes `null` for the affected output paths and the `/live` and `/status` endpoints expose that state clearly. Idle input recovery is enabled for all live subscriptions, so temporary silence is handled without leaving the plugin in a stale state.
+## Architecture & Polar Providers
+
+**Polar Performance works together with a polar provider plugin** (such as [signalk-polar-management](https://github.com/Asw1n/signalk-polar-management)).
+
+Starting in version 2.0.0, polar file storage, file format conversion, ORC imports, and polar selection are decoupled from this compute plugin:
+- **Polar Provider (`signalk-polar-management`):** Stores polar files, imports ORC/CSV/text polar files, manages polar metadata, and publishes the selected active polar to Signal K (`polars.activePolar`) along with any performance factor (`polars.performanceFactor`).
+- **Performance Plugin (`signalk-polar-performance-plugin`):** Subscribes to the active polar and boat instrument data (TWS, TWA, STW/SOG), calculates real-time performance values using the [`polar-math`](https://github.com/Asw1n/polar-math) engine, and publishes the resulting performance metrics back to the Signal K delta stream.
+
+When a polar lookup cannot be completed or required instrument data is missing/stale, output paths are cleanly set to `null` and the webapp status indicates the exact cause.
 
 ---
 
 ## Installation
 
-Install from the Signal K App Store, or manually:
+Install both plugins from the Signal K App Store, or via npm:
 
 ```sh
 cd ~/.signalk
-npm install signalk-polar-performance-plugin
+npm install signalk-polar-performance-plugin signalk-polar-management
 ```
 
-Then restart Signal K and enable the plugin in **Server → Plugin Config → Polar Performance**.
+Then restart Signal K and enable both plugins in **Server → Plugin Config**. Without a polar resource provider installed and enabled, Polar Performance will wait for an active polar to be published and indicate this in its status.
 
 ---
 
 ## Quick start
 
-1. Open the webapp from **Webapps → Polar Performance**.
-2. Go to the **Polars** tab and either import a polar from the ORC database or import a text polar.
-3. Go to the **Settings** tab and select the polar you just added as the active polar.
-4. The **Overview** tab now shows live performance numbers and a polar diagram.
-5. Enable the outputs you want in the **Outputs** tab.
+1. Open the **Polar Management** webapp and import or select an active polar (and optionally set a performance factor).
+2. Open the **Polar Performance** webapp from **Webapps → Polar Performance**.
+3. The **Overview** tab shows the active polar's details, live performance numbers, and a polar diagram.
+4. Enable the outputs you want in the **Outputs** tab.
 
 ---
 
@@ -35,36 +42,25 @@ The webapp is the primary interface for the plugin. Open it from the Signal K da
 
 ### Overview
 
-A polar diagram on the left and live performance numbers on the right. The diagram shows a live TWS curve interpolated for the current wind speed, and two dots — the polar target speed (what the polar says you should be doing) and your actual boat speed — both at the current TWA. The targets section shows the beat and run angle and VMG interpolated from the polar for the current wind speed. Any data quality warnings appear at the bottom.
+Shows the currently active polar (name, boat type, sail number, year, source) and performance factor — read-only, selected in the polar management webapp — followed by a polar diagram on the left and live performance numbers on the right. The diagram shows a live TWS curve interpolated for the current wind speed, and two dots — the polar target speed (what the polar says you should be doing) and your actual boat speed — both at the current TWA. The targets section shows the beat and run angle and VMG interpolated from the polar for the current wind speed. Any data quality warnings appear at the bottom.
 
 ### Inputs
 
-Shows the raw instrument values as they arrive from Signal K (before smoothing) and the smoothed values actually used for computation, side by side. Useful for spotting stale sensors or checking whether the smoother settings make sense for your data. Any missing inputs are listed as warnings.
+Shows the raw instrument values as they arrive from Signal K (before smoothing) and the smoothed values actually used for computation, side by side. Useful for spotting stale sensors or checking whether the smoother settings make sense for your data. Smoother type/parameter and speed source are configured here. Any missing inputs are listed as warnings.
 
 ### Outputs
 
-Shows the current value of each output path and lets you enable or disable each group with a toggle. Only enabled outputs are published to the Signal K bus. 
-
-### Settings
-
-Lets you alter the settings of the plugin. Polar selection, performance adjustment, smoother type and parameter, and speed source. The polar diagram of the selected polar is shown.
+Shows the current value of each output path and lets you enable or disable each group with a toggle. Only enabled outputs are published to the Signal K bus.
 
-### Polars
-
-Manage stored polars, import polars from the ORC database, and import text polars in supported formats.
 ---
 
 ## Configuration
 
-All configuration is done through the webapp. The settings available are:
-
-### Active polar
-
-Select the polar to use for calculations. The polar diagram in the Settings tab updates when you change this. If no polar is selected the plugin runs but publishes nothing; any previously published values are nullified immediately.
+Most configuration is done through the webapp.
 
-### Performance adjustment
+### Active polar and performance factor
 
-A multiplier applied to all polar speeds before they are used. `1.0` means use the polar as-is. `0.90` means the plugin assumes your boat achieves 90 % of the polar values — useful when your polar is optimistic or you are sailing conservatively. The polar diagram in the Settings tab reflects this adjustment. Step size is 0.05.
+These are **not** configured here. Select the active polar and set the performance factor in the polar management webapp (e.g. signalk-polar-management); this plugin reads them from the `polars.activePolar` and `polars.performanceFactor` Signal K paths. If no polar is active, the plugin runs but publishes nothing; any previously published values are nullified immediately.
 
 ### Smoother
 
@@ -164,47 +160,7 @@ Useful when you want downstream instruments to use the same smoothed values that
 
 ## Managing polars
 
-### Importing from ORC
-
-The plugin can search the official ORC active certificate source directly. Go to **Polars → Import ORC Certificate**, type part of the certificate RefNo, boat name, class, or sail number and click Search. When you find your boat, click Import. The polar is saved locally and immediately available for selection.
-
-Internet access is required only while searching or importing from ORC. In an isolated Signal K installation the ORC source is simply shown as unavailable; that is not treated as a plugin error. After import the polar is stored locally and no further internet access is needed.
-
-### Importing text polars
-
-If you have a polar in a supported text format, you can import it directly from the **Polars** tab. The plugin currently supports Jieter-style semicolon CSV and Expedition-style delimited text. Optional metadata such as display name, sail number, boat type, year, source label, and notes can be added during text import.
-
-The Jieter CSV format uses semicolons as separators. The first row is a header with `twa/tws` in the first column followed by wind speeds in knots. Each subsequent row is a TWA in degrees followed by boat speeds in knots. Beat and run angles appear as separate rows with one non-zero speed per row (the VMG for that wind speed column).
-
-**Example:**
-```
-twa/tws;6;8;10;12;14;16;20
-52;4.57;5.59;6.33;6.87;7.23;7.45;7.65
-60;4.93;5.93;6.66;7.15;7.47;7.68;7.94
-75;5.17;6.18;6.91;7.37;7.68;7.92;8.31
-90;5.29;6.43;7.23;7.71;8.03;8.29;8.57
-110;5.38;6.56;7.36;7.84;8.22;8.6;9.31
-120;5.2;6.38;7.23;7.76;8.16;8.55;9.36
-135;4.65;5.84;6.78;7.43;7.87;8.25;9.03
-150;3.92;5.05;5.97;6.7;7.2;7.58;8.17
-46.9;4.23;0;0;0;0;0;0
-44.8;0;5.09;0;0;0;0;0
-144.2;4.19;0;0;0;0;0;0
-146.4;0;5.25;0;0;0;0;0
-```
-
-### Extrapolation
-
-The polar table covers a finite range of TWA values. The plugin extrapolates outside this range in two ways:
-
-- **Close to the wind (beat zone):** A quadratic curve fitted to ensure continuity with the first measured point. The boat speed reaches zero at 25° (the assumed hard pinching angle).
-- **Deep downwind (run zone):** A cosine-VMG model extending 30 % of the angular gap between the run angle and dead downwind. Beyond this limit the plugin returns no value rather than extrapolate further.
-
-Values derived from extrapolated regions are indicated in the webapp warnings.
-
-### Performance adjustment
-
-The performance adjustment multiplier scales all polar speeds proportionally. Use it to calibrate the polar to your boat's actual performance. A value of `0.95` tells the plugin your boat achieves 95 % of the published polar — the polar diagram in Settings reflects this visually.
+Polar storage, import (ORC, text formats), and active-polar/performance-factor selection are handled by a separate 'polars' resource-provider plugin, such as [signalk-polar-management](https://github.com/Asw1n/signalk-polar-management). See that plugin's documentation for import formats, the ORC certificate search, and extrapolation behaviour of the underlying `polar-math` library.
 
 ---
 
@@ -224,10 +180,22 @@ Install the [B&G Performance Plugin](https://www.npmjs.com/package/signalk-bandg
 
 For laylines on charts: **Settings → Chart → Laylines → Targets → True wind angle → Actual**.
 
+![](https://raw.githubusercontent.com/htool/signalk-polar-performance-plugin/main/doc/BandG_Laylines_Target_TWA_to_Active.png)
+
+SailSteer screen -> Long press tile to add 'Performance -> Target TWA -> decollapse, choose SignalK':
+
+![](https://raw.githubusercontent.com/htool/signalk-polar-performance-plugin/main/doc/BandG_Target_TWA_to_SignalK.png)
+
+Now the Target TWA is coming from SignalK and the laylines will be drawn based on its value:
+
+![](https://raw.githubusercontent.com/htool/signalk-polar-performance-plugin/main/doc/BandG_Sailsteer_with_laylines.png)
+
 ### Garmin / Raymarine / other NMEA 2000
 
 Use a Signal K → NMEA 2000 gateway plugin (such as `canboat` or `signalk-to-n2k`) to forward paths to the PGN fields your plotter expects for performance data. Consult your plotter's documentation for the relevant PGNs — most support Polar Speed, Target TWA, and VMG.
 
+If you have a Raymarine MFD and can share setup instructions, please submit a PR or open an issue!
+
 ### OpenCPN / KIP / other Signal K displays
 
 Subscribe directly to the paths listed in the Outputs section above. 
@@ -253,7 +221,7 @@ The webapp shows warnings whenever something prevents accurate calculation:
 | *True wind speed — no data* | `environment.wind.speedTrue` is not arriving from Signal K.  |
 | *True wind angle — no data* | `environment.wind.angleTrueWater` is not arriving.  |
 | *Boat speed — no data* | `navigation.speedThroughWater` (or SOG) is not arriving.  |
-| *No polar loaded* | No active polar is configured. Select a polar from the settings tab. Or go to the Polars tab and store a canonical polar resource first. |
+| *No active polar* | No `polars.activePolar` is published. Select an active polar in the polar management webapp. |
 | *Sailing in irons* | TWA is below the minimum angle in the polar. No output is produced. |
 | *Pinching* | TWA is between the minimum polar angle and the beat angle. Values come from the extrapolated beat zone. |
 | *Extrapolated beyond run angle* | TWA is deeper than the run angle. Values come from the cosine-VMG extrapolation model. |
@@ -273,28 +241,15 @@ Performance calculations are only as good as the inputs. A few things are worth
 
 ## For integrators and API users
 
-If you want to automate polar management or consume the plugin as a canonical polar provider, use the developer reference:
+If you want to consume this plugin's live performance queries, use the developer reference:
 
-- [Developer reference](docs/developer-reference.md) for the canonical `polarTable` structure and the plugin REST API.
+- [Developer reference](docs/developer-reference.md) for the plugin REST API.
 - [openApi.json](openApi.json) for the authoritative machine-readable contract.
+- For the canonical `polarTable` structure, polar storage, and import, see [signalk-polar-management](https://github.com/Asw1n/signalk-polar-management) and the [polar-format](https://github.com/Asw1n/polar-format) / [polar-math](https://github.com/Asw1n/polar-math) packages it depends on.
 
 ---
 
 ## Known limitations
 
 - Heel angle is not taken into account in the polar lookup. Most ORC polars are upright polars.
-- Polar storage is canonical-only. Text and ORC imports are conversion inputs; they are stored internally as canonical `polarTable` resources.
-
-
- ![](https://raw.githubusercontent.com/htool/signalk-polar-performance-plugin/main/doc/BandG_Laylines_Target_TWA_to_Active.png)
-
- - SailSteer screen -> Long press tile to add 'Performance -> Target TWA -> decollapse, choose SignalK'
-
- ![](https://raw.githubusercontent.com/htool/signalk-polar-performance-plugin/main/doc/BandG_Target_TWA_to_SignalK.png)
-
-Now the Target TWA is coming from SignalK and the laylines will be drawn based on it's value.
-
-![](https://raw.githubusercontent.com/htool/signalk-polar-performance-plugin/main/doc/BandG_Sailsteer_with_laylines.png)
-
-### Raymarine
-If you have a Raymarine MFD and can tell more about this, please add to the README or tell me.
+- Requires a 'polars' resource-provider plugin (e.g. `signalk-polar-management`) to be installed and running for polar storage, import, and active polar selection.

package/docs/developer-reference.md

@@ -1,148 +1,40 @@
 # Polar Performance Developer Reference
 
-This document is for the second kind of user of the plugin: integrators and developers who want to automate polar management, consume the plugin through its REST API, or provide canonical `polarTable` resources directly.
+This document covers the REST API this plugin still exposes. It no longer stores, imports,
+or manages polar files — that is handled by a separate 'polars' resource-provider plugin
+(e.g. [signalk-polar-management](https://github.com/Asw1n/signalk-polar-management)). For the
+canonical `polarTable` format and its management API, see that plugin's documentation and the
+[polar-format](https://github.com/Asw1n/polar-format) / [polar-math](https://github.com/Asw1n/polar-math)
+packages it depends on.
 
 For installation, day-to-day use, and webapp workflow, start with [../README.md](../README.md).
 
-## Canonical polar format
+## How the active polar is resolved
 
-The plugin stores polars as canonical JSON `polarTable` resources. This is the only supported storage and management format for the REST API.
+This plugin subscribes to two Signal K paths published by the 'polars' resource provider:
 
-Required structure:
+- `polars.activePolar` — `{ href: '/resources/polars/<id>' }`, or absent if no polar is active.
+- `polars.performanceFactor` — a number applied as a multiplier to all polar speeds.
 
-- `kind` must be `polarTable`.
-- `schemaVersion` is a version string for the canonical resource format.
-- `units` currently must be SI only: `tws = m/s`, `twa = rad`, `boatSpeed = m/s`.
-- `symmetry.portStarboardSymmetric` currently must be `true`.
-- `axes.tws` is a non-empty sorted array of true wind speeds in m/s.
-- `axes.twa` is a non-empty sorted array of true wind angles in radians over the range `0..pi`.
-- `values.boatSpeedMatrix` is a 2D array of boat speeds in m/s, indexed as `[twsRow][twaColumn]`.
-- The number of matrix rows must match `axes.tws.length`.
-- Each matrix row length must match `axes.twa.length`.
-
-Optional metadata:
-
-- `name`
-- `sailnumber`
-- `boatType`
-- `year`
-- `source`
-- `notes`
-
-Optional derived data:
-
-- `derived.rows` can provide precomputed beat/run/max-speed targets for each TWS row.
-- Each derived row uses the same TWS unit conventions as the main table.
-- `beat` and `run` entries contain `twa`, `tbs`, and `vmg`, all in SI units.
-
-Example:
-
-```json
-{
-  "kind": "polarTable",
-  "schemaVersion": "1.0.0",
-  "name": "Example Boat",
-  "sailnumber": "EX-1",
-  "boatType": "Example 36",
-  "year": 2025,
-  "source": "custom",
-  "notes": "Minimal canonical example",
-  "units": {
-    "tws": "m/s",
-    "twa": "rad",
-    "boatSpeed": "m/s"
-  },
-  "symmetry": {
-    "portStarboardSymmetric": true
-  },
-  "axes": {
-    "tws": [3.0864, 5.144],
-    "twa": [0.75398, 1.5708, 2.65465]
-  },
-  "values": {
-    "boatSpeedMatrix": [
-      [2.5051, 2.65465, 2.23368],
-      [3.16888, 3.34861, 2.74799]
-    ]
-  },
-  "derived": {
-    "rows": [
-      {
-        "tws": 3.0864,
-        "beat": { "twa": 0.75398, "tbs": 2.5051, "vmg": 1.82652 },
-        "run": { "twa": 2.65465, "tbs": 2.23368, "vmg": 1.97371 },
-        "maxSpeed": 2.65465,
-        "maxSpeedAngle": 1.5708
-      }
-    ]
-  }
-}
-```
-
-Notes:
-
-- The resource `id` is not part of the `PUT /polars/:id` body; it comes from the URL path.
-- If `derived` is omitted, the plugin can still load and query the polar from the axis and matrix data alone.
-- Text imports and ORC imports are converted into this canonical structure before being stored.
-- The authoritative machine-readable schema is in [../openApi.json](../openApi.json) under `PolarResource` and `PolarResourceBody`.
+On a change to `polars.activePolar`, the plugin resolves `<id>` via the in-process
+`app.resourcesApi.getResource('polars', id)` call and builds a `polar-math` `Polar` instance
+from the returned canonical document. If the resource provider or the active polar becomes
+unavailable, the last successfully loaded polar is kept until a valid update arrives.
 
 ## REST API
 
-The plugin exposes a REST API under `/plugins/signalk-polar-performance-plugin/`. Authentication follows Signal K server rules; the same session cookie used by the webapp works for direct API calls.
-
-### Operational endpoints
+The plugin exposes a REST API under `/plugins/signalk-polar-performance-plugin/`. Authentication
+follows Signal K server rules; the same session cookie used by the webapp works for direct API calls.
 
 | Method | Path | Description |
 |--------|------|-------------|
 | `GET` | `/live` | Current smoothed TWS, TWA, BSP, polar speed, and polar state. |
 | `GET` | `/status` | Full snapshot: raw inputs, smoothed inputs, and all enabled output values. |
-| `GET` | `/meta` | Display unit metadata for all fields. |
-| `GET` | `/settings` | Current plugin settings. |
+| `GET` | `/meta` | Display unit metadata for all fields, plus a read-only summary of the active polar (name, boatType, sailnumber, year, source) and performance factor. |
+| `GET` | `/settings` | Current plugin settings (smoother, output toggles, speed source — no polar selection). |
 | `PUT` | `/settings` | Update settings. Body: JSON object with changed keys only. |
+| `GET` | `/polar/axes/tws` | TWS axis of the currently active polar. 404 if none is active. |
+| `GET` | `/polar/queries/curve?tws=&step=` | Interpolated curve for the active polar at the given TWS, with beat/run markers, performance factor already applied. |
 
-### Polar manager endpoints
-
-| Method | Path | Description |
-|--------|------|-------------|
-| `GET` | `/polars` | List stored canonical polar resources with metadata. |
-| `GET` | `/polars/active` | Get the active polar id. |
-| `PUT` | `/polars/active` | Set the active polar. Body: JSON `{ id }`. |
-| `DELETE` | `/polars/active` | Clear the active polar. |
-| `GET` | `/polars/:id` | Get a stored canonical `polarTable` resource. |
-| `PUT` | `/polars/:id` | Create or replace a canonical `polarTable` resource. |
-| `DELETE` | `/polars/:id` | Delete a stored polar. |
-| `GET` | `/polars/:id/meta` | Read stored metadata and TWS range for a polar. |
-
-### Query endpoints
-
-| Method | Path | Description |
-|--------|------|-------------|
-| `GET` | `/polars/:id/axes/tws` | Array of TWS values (m/s) in a stored polar. |
-| `GET` | `/polars/:id/queries/curve?tws=<m/s>&step=<rad>` | Interpolated polar curve for a given TWS, with beat and run markers. |
-| `GET` | `/polars/:id/queries/speed?tws=<m/s>&twa=<rad>` | Interpolated boat speed and interpolation state for a single TWS/TWA point. |
-| `GET` | `/polars/:id/queries/targets?tws=<m/s>` | Optimal beat and run targets for a given TWS. |
-| `GET` | `/polars/:id/queries/performance?tws=<m/s>&twa=<rad>&bsp=<m/s>` | Speed and VMG performance ratios against the polar. |
-
-### Import endpoints
-
-| Method | Path | Description |
-|--------|------|-------------|
-| `GET` | `/imports/formats` | List supported text import formats. |
-| `POST` | `/imports/text/:format` | Import a text polar and store it as a canonical resource. |
-| `GET` | `/imports/sources` | List supported external sources and their current availability. |
-| `GET` | `/imports/sources/:source/search?q=<text>` | Search an external source for import candidates. |
-| `POST` | `/imports/sources/:source/items/:externalId` | Import a source item and store it as a canonical resource. |
-
-## External source availability
-
-External sources are optional. Signal K may run in an isolated environment, so lack of internet access is not treated as a plugin error.
-
-- `GET /imports/sources` reports source availability through `available` and `availabilityMessage`.
-- The ORC source is shown as unavailable when the plugin cannot reach the official ORC index within a short timeout.
-- ORC imports do not accept manual metadata overrides; imported metadata is owned by the source data.
-- Certificate search results may be served from a cached ORC active-certificate index.
-
-## Source of truth
-
-- Use [../openApi.json](../openApi.json) as the authoritative machine-readable API contract.
-- Use this document for a human-readable overview of the canonical format and endpoint categories.
+The authoritative machine-readable schema for the two `/polar/*` endpoints is in
+[../openApi.json](../openApi.json).