signalk-polar-performance-plugin 2.0.0 → 2.2.0

package/CHANGELOG.md

@@ -4,7 +4,40 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## Unreleased
+
+### Fixed
+- Keep `performance.targetSpeed` and `performance.targetVelocityMadeGood` published in irons using the selected beat or run target; polar values and ratios based on the boat's current angle are still cleared.
+
+## [2.2.0] - 2026-11-02
+
+### Changed
+- Polar calculations now come directly from signalk-polar-management's live calculation service: the plugin always follows the active polar, the sailplan selection and the performance factor chosen in the Polar Management webapp — including v2 polar sets, which could not be calculated before. The active polar's details shown in the webapp come from the same service. signalk-polar-management (with the calculation service, >=1.5.0) is now required for all polar outputs; the `polar-math` library is no longer bundled.
+- The overview now shows the selected sailplan for v2 polar sets, and the active polar's details refresh automatically after selection changes or edits in the management webapp, without reloading the page.
+- Smoothed-input outputs (damped TWA and boat speed) are now published even while no polar is active; polar-derived outputs are still cleared.
+- The webapp now distinguishes between a missing calculation service (management plugin not installed or disabled) and no active polar being selected.
+
+### Fixed
+- The polar selected in Polar Management is picked up automatically after a Signal K server restart, without reselecting it ([#41](https://github.com/htool/signalk-polar-performance-plugin/issues/41)).
+
+### Known limitations
+- Sea state (wave) correction is not applied: the Signal K specification defines no paths for the required wave height, period and direction inputs. It can be added once such paths exist.
+
+## [2.1.0] - 2026-10-27
+
+### Changed
+- Requires signalk-server >=2.35.0 for the upstream metadata-first subscription fix ([SignalK/signalk-server#3216](https://github.com/SignalK/signalk-server/pull/3216)).
+- Requires signalkutilities >=3.2.0 (subscriptions without cached-value replay, smoothers cleared by `null`) and polar-math >=1.1.1 (in-irons cutoff relative to the 25° curve endpoint).
+- Read-only Signal K users can now access live values, status, active-polar display metadata, and polar curve queries used by the plotter. Curve resolution is bounded to at most 181 samples per request; settings remain administrator-only.
+- Clearer `meta` descriptions for `performance.optimumWindAngle` (where the optimal angle comes from, what zero means) and `performance.polarVelocityMadeGood` (the polar's prediction, not the actual VMG).
+
+### Fixed
+- Removed idle-triggered input resubscriptions to avoid replaying cached values during sensor outages. Idle/stale warnings remain, and existing subscriptions receive data when the source resumes. Source changes and heading toggles still update subscriptions normally.
+- Heading inputs enabled at runtime now use the same lifecycle-warning callbacks as heading inputs enabled at startup.
+- When sailing in irons, all values taken from the polar (polar speed, target speed, target and polar VMG, beat/gybe angles and VMGs, max speed) and the percentages based on them are now cleared consistently. Previously some were cleared, some kept showing and VMG % froze on its last value. This also prevents spikes in the performance percentages while tacking. Steering advice (target angle, optimum wind angle, opposite tack heading) stays available so you can see how far to bear away. Everything returns as soon as you leave irons ([#38](https://github.com/htool/signalk-polar-performance-plugin/issues/38)).
+- When pinching (between the in-irons cutoff and the beat angle), all outputs keep being published.
+- Actual VMG keeps updating in irons instead of freezing on its last value.
+- Performance outputs whose inputs become unavailable (for example missing boat speed, heading or polar targets) are now cleared instead of showing a stale value.
 
 ## [2.0.0] - 2026-09-09
 

package/README.md

@@ -7,8 +7,8 @@ Polar Performance calculates live sailing performance metrics — target boat sp
 **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.
+- **Polar Provider (`signalk-polar-management`):** Stores polar files, imports ORC/CSV/text polar files, manages polar metadata, publishes the selected active polar to Signal K (`polars.activePolar`) along with the shared performance factor (`polars.performanceFactor`), and provides an in-process polar calculation service to other plugins.
+- **Performance Plugin (`signalk-polar-performance-plugin`):** Subscribes to boat instrument data (TWS, TWA, STW/SOG), calculates real-time performance values through the management plugin's live *active polar* calculation handle, and publishes the resulting performance metrics back to the Signal K delta stream. The handle automatically follows the active polar, the sailplan selection, and the performance factor chosen in the Polar Management webapp — including v2 polar sets.
 
 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.
 
@@ -16,6 +16,8 @@ When a polar lookup cannot be completed or required instrument data is missing/s
 
 ## Installation
 
+Requires signalk-server >=2.35.0 for reliable metadata-first input subscriptions. Idle/stale warnings do not trigger resubscriptions; existing subscriptions receive data when the source resumes. Requires signalk-polar-management >=1.5.0, which provides the in-process polar calculation service.
+
 Install both plugins from the Signal K App Store, or via npm:
 
 ```sh
@@ -23,7 +25,13 @@ cd ~/.signalk
 npm install signalk-polar-performance-plugin signalk-polar-management
 ```
 
-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.
+Then restart Signal K and enable both plugins in **Server → Plugin Config**. This plugin requires signalk-polar-management for all polar calculations: without it (or with it disabled), Polar Performance runs but publishes nothing and reports the missing calculation service in its status.
+
+---
+
+## HTTP endpoint access
+
+Signal K read-only users can view live values, status, active-polar display metadata, and polar curves used by the plotter. Plugin settings, including settings reads, require administrator access. Anonymous access remains controlled by the server's security configuration and is not enabled by this plugin. See the [developer reference](./docs/developer-reference.md#rest-api) for the endpoint list and access policies.
 
 ---
 
@@ -60,7 +68,7 @@ Most configuration is done through the webapp.
 
 ### Active polar and performance factor
 
-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.
+These are **not** configured here. Select the active polar (and, for v2 polar sets, a sailplan) and set the performance factor in the polar management webapp (signalk-polar-management); this plugin's calculation handle follows those selections automatically on every calculation. If no polar is active, the plugin runs but publishes nothing; any previously published values are nullified immediately.
 
 ### Smoother
 
@@ -156,11 +164,29 @@ Requires `navigation.headingTrue` to be available.
 
 Useful when you want downstream instruments to use the same smoothed values that drive the performance calculation.
 
+### Output handling when pinching and in irons
+
+The polar defines two zones above the beat angle:
+
+- **Pinching** — TWA is between the in-irons cutoff and the beat angle. The boat is still sailing, and the polar curve is extended smoothly towards zero speed. **All outputs are published.**
+- **In irons** — TWA is below the cutoff, which lies 80 % of the way from 25° to the beat angle (for example ~38.6° for a 42° beat angle). The polar has no sailing state here, so the outputs are handled per kind:
+
+| Kind | Outputs | In irons |
+|------|---------|----------|
+| Measured | `velocityMadeGood`, `angleTrueWaterDamped`, `boatSpeedDamped` | Published |
+| Steering advice | `targetAngle`, `optimumWindAngle`, `tackTrue` | Published, so you can see how far to bear away |
+| Selected target performance | `targetSpeed`, `targetVelocityMadeGood` | Published from the selected beat or run target |
+| Polar values and ratios based on them | `polarSpeed`, `polarSpeedRatio`, `polarVelocityMadeGood`, `polarVelocityMadeGoodRatio`, `beatAngle`, `gybeAngle`, `beatAngleVelocityMadeGood`, `gybeAngleVelocityMadeGood`, `maxSpeed`, `maxSpeedAngle` | Set to `null` |
+
+The selected target speed and VMG remain available in irons because they describe the optimal beat or run target for the current TWS, rather than the boat's current angle. Clearing values based on the boat's current polar state prevents spikes in performance ratios while tacking. Through a tack the boat carries its speed head-to-wind while the polar speed falls towards zero, which would briefly drive the ratios to meaningless values. As soon as you bear away out of irons, all other polar values return on the next wind update.
+
+A value is set to `null` once when it becomes unavailable and is not repeated until it returns.
+
 ---
 
 ## Managing polars
 
-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.
+Polar storage, import (ORC, text formats), and active-polar/sailplan/performance-factor selection are handled by [signalk-polar-management](https://github.com/Asw1n/signalk-polar-management), which also performs all polar calculations for this plugin through its in-process calculation service. See that plugin's documentation for import formats, the ORC certificate search, and extrapolation behaviour of the underlying `polar-math` library.
 
 ---
 
@@ -221,9 +247,10 @@ 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 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. |
+| *No active polar* | No active polar is selected. Select one in the polar management webapp. |
+| *Polar calculation service not available* | signalk-polar-management is not installed, not enabled, or too old to provide the in-process calculation service. |
+| *Sailing in irons* | TWA is below the in-irons cutoff. Polar values and the ratios based on them are set to `null`; measured values and steering advice keep updating. See [Output handling when pinching and in irons](#output-handling-when-pinching-and-in-irons). |
+| *Pinching* | TWA is between the in-irons cutoff and the beat angle. All outputs are published; 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. |
 | *Wind speed below/above polar range* | TWS is outside the range covered by the polar. Values are extrapolated from the nearest TWS entry. |
 
@@ -245,11 +272,12 @@ If you want to consume this plugin's live performance queries, use the developer
 
 - [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.
+- For the canonical `polarTable` / `polarSet` structures, polar storage, import, and the in-process calculation service, 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.
-- Requires a 'polars' resource-provider plugin (e.g. `signalk-polar-management`) to be installed and running for polar storage, import, and active polar selection.
+- Requires `signalk-polar-management` to be installed and running: it stores and imports polars, owns the active selection, and performs all polar calculations for this plugin.
+- Sea state (wave) correction is not applied, even when the active v2 polar set carries a wave-correction table. The Signal K specification currently defines no paths for the required inputs (significant wave height, wave period, wave direction), so this plugin has nothing to feed the correction with. Support can be added once such paths exist in the specification.

package/docs/developer-reference.md

@@ -1,40 +1,64 @@
 # Polar Performance Developer Reference
 
 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.
+or manages polar files — that is handled by
+[signalk-polar-management](https://github.com/Asw1n/signalk-polar-management), which also
+provides the in-process polar calculation service this plugin uses. For the canonical
+`polarTable` / `polarSet` formats and the management API, see that plugin's documentation
+and the [polar-format](https://github.com/Asw1n/polar-format) package; the underlying
+calculation engine, [polar-math](https://github.com/Asw1n/polar-math), is a dependency of
+the management plugin, not of this one.
 
 For installation, day-to-day use, and webapp workflow, start with [../README.md](../README.md).
 
 ## How the active polar is resolved
 
-This plugin subscribes to two Signal K paths published by the 'polars' resource provider:
+All polar calculations and all active-polar metadata go through the in-process
+calculation service announced by signalk-polar-management via the `polarManagement`
+PropertyValue. At startup this plugin subscribes with
+`app.onPropertyValues('polarManagement', …)` and acquires an **active-polar handle**
+(`service.activePolar()`). Every calculation call on that handle automatically follows
+the shared active polar, the shared sailplan selection (for v2 polar sets), the shared
+performance factor, and the shared wave-correction toggle — this plugin applies none of
+them itself. When the management plugin is missing or stopped, calculations are
+unavailable and the plugin reports this in its status; results then carry
+`state.available: false` with a reason such as `no_active_polar`.
 
-- `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.
+Descriptive metadata comes from the same handle: `handle.describe()` returns the active
+document's name, boat details, selected sailplan, the applied performance factor, and the
+selected table's TWS axis. The plugin refreshes this snapshot on `handle.onChange`
+notifications and serves it through `/meta` and `/polar/axes/tws`. It does not subscribe
+to the `polars.*` Signal K paths and performs no resource lookups; those paths remain
+published by signalk-polar-management for other consumers.
 
-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.
+### Sea state / wave correction
+
+v2 polar sets can carry a wave-correction table, and active handles accept per-call
+`seaState` input. This plugin does not supply `seaState`, because the Signal K
+specification currently defines no paths for the required inputs (significant wave height,
+wave period, wave direction). Wave correction therefore has no effect on this plugin's
+outputs. If the specification gains such paths, sea state can be wired into the existing
+handle calls without restructuring.
 
 ## 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.
+The endpoints marked **Read-only** are available to users with Signal K read-only permission.
+Anonymous access is controlled only by the server's `allow_readonly` setting and is not enabled by
+the plugin. Curve queries are capped at 181 sample angles per request (minimum step 1°).
+`/meta` includes the active polar's boat type, sail number, source, and free-text notes, so those
+fields are also available to read-only users.
 
-| 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, 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. |
+| Method | Path | Description | Access |
+|--------|------|-------------|--------|
+| `GET` | `/live` | Current smoothed TWS, TWA, BSP, polar speed, and polar state. | Read-only |
+| `GET` | `/status` | Full snapshot: raw inputs, smoothed inputs, and all enabled output values. | Read-only |
+| `GET` | `/meta` | Display unit metadata for all fields, plus a read-only summary of the active polar (name, boatType, sailnumber, year, source, notes, selected sailplan) and the applied performance factor. | Read-only |
+| `GET` | `/settings` | Current plugin settings (smoother, output toggles, speed source — no polar selection). | Administrator |
+| `PUT` | `/settings` | Update settings. Body: JSON object with changed keys only. | Administrator |
+| `GET` | `/polar/axes/tws` | TWS axis of the currently active polar. 404 if none is active. | Read-only |
+| `GET` | `/polar/queries/curve?tws=&step=` | Interpolated curve for the active polar at the given TWS, with beat/run markers, performance factor already applied. `step` must be at least 1° and at most π/2 radians. | Read-only |
 
 The authoritative machine-readable schema for the two `/polar/*` endpoints is in
 [../openApi.json](../openApi.json).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "signalk-polar-performance-plugin",
-  "version": "2.0.0",
+  "version": "2.2.0",
   "description": "Calculates live sailing performance from the active polar selected in a polar management plugin (e.g. signalk-polar-management).",
   "main": "plugin/index.js",
   "exports": {
@@ -19,23 +19,17 @@
   ],
   "engines": {
     "node": ">=20",
-    "signalk-server": ">=2.28.0"
+    "signalk-server": ">=2.35.0"
   },
   "scripts": {
     "test": "node --test test/**/*.test.js",
     "prepublishOnly": "npm test"
   },
   "dependencies": {
-    "polar-math": "^1.0.0",
-    "signalkutilities": "^3.1.3"
+    "signalkutilities": "^3.2.0"
   },
-  "peerDependencies": {
-    "signalk-polar-management": ">=1.0.0"
-  },
-  "peerDependenciesMeta": {
-    "signalk-polar-management": {
-      "optional": true
-    }
+  "devDependencies": {
+    "polar-math": "^1.1.1"
   },
   "repository": {
     "type": "git",
@@ -51,6 +45,9 @@
   "signalk": {
     "appIcon": "./icon.png",
     "displayName": "Polar Performance",
+    "requires": [
+      "signalk-polar-management"
+    ],
     "screenshots": [
       "./docs/plotter.png",
       "./docs/overview.png",