signalk-sailboat-simulator 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [0.3.0] - 2026-09-09
+
+- Calculate simulated boat speed directly from the active `signalk-polar-management` polar resource via `polar-math`.
+- Replace the `signalk-polar-performance-plugin` recommendation with `signalk-polar-management`.
+- Stop requiring `performance.polarSpeed` as an input path.
+- Keep the active polar cached for up to 60 seconds so edits made under the same resource id are picked up automatically.
+
 ## [0.2.0] - 2026-08-17
 
 - Follow `steering.autopilot.output.turnRate` from `signalk-autopilot-emulator-v2` directly instead of deriving and rate-limiting turns from autopilot target headings.

package/README.md

@@ -1,8 +1,8 @@
 # Signal K Sailboat Simulator
 
-Signal K plugin that simulates a sailing boat by integrating a virtual position from data already present in Signal K: autopilot turn-rate output, weather and polar performance.
+Signal K plugin that simulates a sailing boat by integrating a virtual position from data already present in Signal K: autopilot turn-rate output, weather and an active polar resource.
 
-The design goal is to keep this plugin small. It publishes only the simulated vessel state and expects specialised plugins to provide autopilot intent, weather and polar calculations.
+The design goal is to keep this plugin small. It publishes only the simulated vessel state and expects specialised plugins to provide autopilot intent, weather and polar management.
 
 ## Quick Start
 
@@ -11,11 +11,11 @@ The easiest setup is to use the Signal K App Store:
 1. Install these recommended plugins:
    - `@signalk/open-meteo-provider`
    - `signalk-autopilot-emulator-v2`
-   - `signalk-polar-performance-plugin`
+   - `signalk-polar-management`
    - `signalk-derived-data`
    - `signalk-distance-to-shore`
 2. Configure `@signalk/open-meteo-provider` and make it the default Signal K Weather API provider. You can also leave the Signal K default as-is and set `wind.providerId` to `open-meteo` in this plugin.
-3. Configure `signalk-polar-performance-plugin` with a polar file for the simulated boat.
+3. Open `signalk-polar-management`, import a polar file for the simulated boat, and set it as the active polar.
 4. Configure `signalk-derived-data` to publish `navigation.magneticVariation`, so the simulator can publish `navigation.headingMagnetic` for plugins that need magnetic heading.
 5. Install and enable `signalk-sailboat-simulator`.
 6. Keep the default simulator options for a first run.
@@ -36,7 +36,7 @@ Minimum capabilities for a useful simulation:
 
 - Autopilot output: `signalk-autopilot-emulator-v2` provides `steering.autopilot.output.turnRate`, which the simulator integrates as the boat heading change.
 - Weather: `@signalk/open-meteo-provider` can provide Weather API observations or forecasts at the simulated position.
-- Polar performance: `signalk-polar-performance-plugin` uses the published true wind values to calculate `performance.polarSpeed`, which the simulator uses as boat speed.
+- Polar management: `signalk-polar-management` stores the simulated boat polars and publishes the active polar resource. The simulator uses `polar-math` internally to calculate boat speed from that active polar.
 - Derived data: enable the `signalk-derived-data` option that publishes `navigation.magneticVariation`; when this path is available, the simulator also publishes `navigation.headingMagnetic` for plugins that need magnetic heading.
 - Shore distance: `signalk-distance-to-shore` can provide `navigation.distanceToShore` and `navigation.shore.bearingTrue` for grounding protection.
 
@@ -61,13 +61,13 @@ Wind:
 - `environment.wind.speedApparent`
 - `environment.wind.angleApparent`
 
-Performance input expected by the simulator:
+Polar input expected by the simulator:
 
-- `performance.polarSpeed`
+- `polars.activePolar`
 
 All values are published with `$source: signalk-sailboat-simulator`.
 
-The plugin status will show `waitingForPerformance` until `performance.polarSpeed` is available. If `steering.autopilot.output.turnRate` is missing, the simulated boat keeps its current heading. If grounding protection is enabled and `navigation.distanceToShore` is below the configured minimum, the status will show `groundingProtection` and the simulated boat will stop.
+The plugin status will show `waitingForPolar` until an active polar is selected, `waitingForWind` until weather wind is available, or `waitingForPolarSpeed` when the active polar cannot produce a speed for the current wind angle. If `steering.autopilot.output.turnRate` is missing, the simulated boat keeps its current heading. If grounding protection is enabled and `navigation.distanceToShore` is below the configured minimum, the status will show `groundingProtection` and the simulated boat will stop.
 
 ## Input contract
 
@@ -75,11 +75,12 @@ The simulator reads these fixed Signal K input paths:
 
 - `steering.autopilot.output.turnRate`: desired heading change rate in rad/s
 - `navigation.magneticVariation`: optional magnetic variation in radians, used only to publish `navigation.headingMagnetic`
-- `performance.polarSpeed`: boat speed from the active polar in m/s
+- `polars.activePolar`: active polar resource pointer published by `signalk-polar-management`
+- `polars.performanceFactor`: optional speed multiplier published by `signalk-polar-management`
 - `navigation.distanceToShore`: optional distance to the nearest coast in m, used for grounding protection
 - `navigation.shore.bearingTrue`: optional bearing from the vessel to the nearest coast in radians, used to allow recovery headings away from shore
 
-When true or apparent wind publishing is enabled, wind is read from Signal K Weather API data at the simulated position. The simulator first tries observations, then falls back to the closest point forecast when no usable observation is available.
+Wind is always read from Signal K Weather API data at the simulated position because it is required for the internal polar speed calculation. The simulator first tries observations, then falls back to the closest point forecast when no usable observation is available. The true and apparent wind options only control whether those values are also published as Signal K paths.
 
 By default the simulator uses the Signal K default weather provider. Set `wind.providerId` to a registered provider id, for example `open-meteo`, to use that provider explicitly.
 
@@ -93,9 +94,9 @@ The simulator publishes virtual wind for the rest of the Signal K stack. The pub
 - `environment.wind.speedApparent`
 - `environment.wind.angleApparent`
 
-This gives `signalk-polar-performance-plugin` the `environment.wind.speedTrue` and `environment.wind.angleTrueWater` inputs it needs to calculate `performance.polarSpeed`.
+The simulator uses the same true wind values with the active polar resource to calculate boat speed. The active polar must use the canonical `polar-format` structure provided by `signalk-polar-management`.
 
-The first version uses `performance.polarSpeed` as the boat speed, integrates heading from `steering.autopilot.output.turnRate`, and integrates position along that simulated heading. Current, leeway, route following and manoeuvre rules are intentionally left as separate steps.
+The simulator uses the calculated polar speed as boat speed, integrates heading from `steering.autopilot.output.turnRate`, and integrates position along that simulated heading. Current, leeway, route following and manoeuvre rules are intentionally left as separate steps.
 
 ## Configuration
 
@@ -107,16 +108,16 @@ The plugin intentionally keeps its configuration surface small:
   Options: latitude, longitude and heading in degrees. These values are only used when persistence is disabled or no previous runtime state has been saved.
 
 - `wind`
-  What it does: reads wind at the simulated position from the Signal K Weather API and publishes the selected wind values.
-  Goal: feed `signalk-polar-performance-plugin` with wind data so it can calculate `performance.polarSpeed`, which the simulator then uses as boat speed.
-  Requires: a Weather API provider. The recommended provider is `@signalk/open-meteo-provider`; the recommended polar plugin is `signalk-polar-performance-plugin`.
+  What it does: always reads wind at the simulated position from the Signal K Weather API for the speed calculation, and optionally publishes the selected wind values.
+  Goal: provide the true wind data used by the simulator to calculate polar speed, and publish that same virtual wind for other Signal K tools.
+  Requires: a Weather API provider. The recommended provider is `@signalk/open-meteo-provider`.
   Options: publish true wind, publish apparent wind, optional provider id, and polling interval.
   Published true wind paths: `environment.wind.speedTrue`, `environment.wind.directionTrue`, `environment.wind.angleTrueWater`.
   Published apparent wind paths: `environment.wind.speedApparent`, `environment.wind.angleApparent`.
 
 - `publishing`
   What it does: publishes the simulated navigation state.
-  Requires: `steering.autopilot.output.turnRate` to steer and `performance.polarSpeed` to move. Recommended providers are `signalk-autopilot-emulator-v2`, `signalk-polar-performance-plugin`, and `signalk-derived-data` when magnetic heading output is needed.
+  Requires: `steering.autopilot.output.turnRate` to steer, an active polar from `signalk-polar-management`, and weather wind to calculate boat speed. Recommended providers are `signalk-autopilot-emulator-v2`, `signalk-polar-management`, and `signalk-derived-data` when magnetic heading output is needed.
   Options: publish navigation state.
   Published paths: `navigation.position`, `navigation.headingTrue`, `navigation.headingMagnetic` when `navigation.magneticVariation` is available, `navigation.courseOverGroundTrue`, `navigation.speedOverGround`, `navigation.speedThroughWater`.
 
@@ -169,7 +170,8 @@ Then restart Signal K.
 - `@signalk/open-meteo-provider`: https://www.npmjs.com/package/@signalk/open-meteo-provider
 - `signalk-autopilot-emulator-v2`: https://www.npmjs.com/package/signalk-autopilot-emulator-v2
 - `signalk-autopilot-emulator-v2` source: https://github.com/macjl/signalk-autopilot-emulator-v2
-- `signalk-polar-performance-plugin`: https://www.npmjs.com/package/signalk-polar-performance-plugin
+- `signalk-polar-management`: https://www.npmjs.com/package/signalk-polar-management
+- `polar-math`: https://www.npmjs.com/package/polar-math
 - `signalk-derived-data`: https://www.npmjs.com/package/signalk-derived-data
 - `signalk-distance-to-shore`: https://www.npmjs.com/package/signalk-distance-to-shore
 

package/index.js

@@ -1,5 +1,6 @@
 'use strict'
 
+const { Polar } = require('polar-math')
 const { createInitialState, stepSimulation } = require('./lib/simulation-engine')
 const { buildSchema } = require('./lib/plugin-schema')
 const { degToRad, radToDeg, wrap360Rad } = require('./lib/angles')
@@ -8,11 +9,13 @@ const { applyPersistedState, createStateStore, stateFromSimulation } = require('
 
 const PLUGIN_ID = 'sailboat-simulator'
 const PUBLISH_SOURCE = 'signalk-sailboat-simulator'
+const POLAR_CACHE_MAX_AGE_MS = 60_000
 
 const INPUT_PATHS = {
   turnRatePath: 'steering.autopilot.output.turnRate',
   magneticVariationPath: 'navigation.magneticVariation',
-  performanceSpeedPath: 'performance.polarSpeed',
+  activePolarPath: 'polars.activePolar',
+  performanceFactorPath: 'polars.performanceFactor',
   distanceToShorePath: 'navigation.distanceToShore',
   shoreBearingTruePath: 'navigation.shore.bearingTrue'
 }
@@ -60,11 +63,12 @@ module.exports = function createPlugin (app) {
   let lastStateSaveAt = 0
   let weatherSnapshot = null
   let stateStore = null
+  let polarCache = null
 
   const plugin = {
     id: PLUGIN_ID,
     name: 'Sailboat Simulator',
-    description: 'Simulates a sailing boat position from Signal K autopilot turn-rate output, weather and polar performance data.',
+    description: 'Simulates a sailing boat position from Signal K autopilot turn-rate output, weather and an active polar resource.',
     schema: buildSchema,
     start,
     stop,
@@ -78,6 +82,7 @@ module.exports = function createPlugin (app) {
     lastWeatherFetchAt = 0
     lastStateSaveAt = 0
     weatherSnapshot = null
+    polarCache = null
     stateStore = createStateStore(app, PLUGIN_ID)
     state = createInitialState(options)
     if (options.persistence.enabled) {
@@ -103,7 +108,7 @@ module.exports = function createPlugin (app) {
     const now = Date.now()
     try {
       await refreshWeather(now)
-      const inputs = readInputs()
+      const inputs = await readInputs()
       state = stepSimulation(state, inputs, options, now)
       publishState(inputs)
       persistState(now)
@@ -126,12 +131,13 @@ module.exports = function createPlugin (app) {
     if (stateStore.save(persisted)) lastStateSaveAt = now
   }
 
-  function readInputs () {
+  async function readInputs () {
     const weatherWind = freshWeatherWind()
-    return {
+    const inputs = {
       turnRate: readNumber(INPUT_PATHS.turnRatePath),
       magneticVariation: readNumber(INPUT_PATHS.magneticVariationPath),
-      polarSpeed: readNumber(INPUT_PATHS.performanceSpeedPath),
+      activePolar: readValue(INPUT_PATHS.activePolarPath),
+      performanceFactor: readNumber(INPUT_PATHS.performanceFactorPath),
       windSpeedTrue: weatherWind && weatherWind.speedTrue != null
         ? weatherWind.speedTrue
         : null,
@@ -143,14 +149,89 @@ module.exports = function createPlugin (app) {
       weatherObservedAt: weatherWind ? weatherWind.observedAt : null,
       weatherDescription: weatherWind ? weatherWind.description : ''
     }
+    const polarSpeed = await calculatePolarSpeed(inputs)
+    inputs.polarSpeed = polarSpeed.speed
+    inputs.polar = polarSpeed.status
+    return inputs
   }
 
-  function readNumber (path) {
+  function readValue (path) {
     if (!path || typeof app.getSelfPath !== 'function') return null
-    const value = app.getSelfPath(`${path}.value`)
+    return app.getSelfPath(`${path}.value`)
+  }
+
+  function readNumber (path) {
+    const value = readValue(path)
     return Number.isFinite(value) ? value : null
   }
 
+  async function calculatePolarSpeed (inputs) {
+    const activePolar = activePolarFromValue(inputs.activePolar)
+    const performanceFactor = Number.isFinite(inputs.performanceFactor)
+      ? inputs.performanceFactor
+      : 1
+    const status = {
+      status: 'missingActivePolar',
+      id: activePolar.id,
+      href: activePolar.href,
+      performanceFactor,
+      speedState: null,
+      speed: null,
+      windAngleTrueWaterDeg: null
+    }
+
+    if (!activePolar.id) {
+      return { speed: null, status }
+    }
+
+    if (!Number.isFinite(inputs.windSpeedTrue) || !Number.isFinite(inputs.windDirectionTrue)) {
+      status.status = 'waitingForWind'
+      return { speed: null, status }
+    }
+
+    const windAngleTrueWater = trueWindFromDirection(inputs.windDirectionTrue, state.headingTrue)
+    status.windAngleTrueWaterDeg = Number.isFinite(windAngleTrueWater)
+      ? radToDeg(windAngleTrueWater)
+      : null
+
+    try {
+      const polar = await loadActivePolar(activePolar.id)
+      const result = polar.speedAt({
+        tws: inputs.windSpeedTrue,
+        twa: windAngleTrueWater,
+        performanceFactor
+      })
+      status.speedState = result.state
+      if (Number.isFinite(result.value)) {
+        status.status = 'ready'
+        status.speed = result.value
+        return { speed: result.value, status }
+      }
+      status.status = 'noSpeedForConditions'
+      return { speed: null, status }
+    } catch (error) {
+      status.status = 'error'
+      status.error = error.message
+      return { speed: null, status }
+    }
+  }
+
+  async function loadActivePolar (id) {
+    const now = Date.now()
+    if (polarCache && polarCache.id === id && now - polarCache.loadedAt < POLAR_CACHE_MAX_AGE_MS) {
+      return polarCache.polar
+    }
+
+    if (!app.resourcesApi || typeof app.resourcesApi.getResource !== 'function') {
+      throw new Error('Signal K resources API is not available')
+    }
+
+    const table = await app.resourcesApi.getResource('polars', id)
+    const polar = Polar.fromTable(table)
+    polarCache = { id, polar, loadedAt: now }
+    return polar
+  }
+
   function publishState (inputs) {
     if (!state || !app.handleMessage) return
 
@@ -224,12 +305,7 @@ module.exports = function createPlugin (app) {
     return options.wind.apparentWind !== false
   }
 
-  function publishesAnyWind () {
-    return publishTrueWind() || publishApparentWind()
-  }
-
   async function refreshWeather (now) {
-    if (!publishesAnyWind()) return
     const intervalSeconds = freshWeatherWind()
       ? options.wind.pollIntervalSeconds
       : options.wind.retryIntervalSeconds
@@ -355,9 +431,7 @@ module.exports = function createPlugin (app) {
   function updateRuntime (inputs) {
     const headingMagnetic = magneticHeadingFromTrue(state.headingTrue, inputs.magneticVariation)
     runtime = {
-      status: state.groundingProtectionActive
-        ? 'groundingProtection'
-        : Number.isFinite(state.speedThroughWater) && state.speedThroughWater > 0 ? 'sailing' : 'waitingForPerformance',
+      status: runtimeStatus(inputs),
       position: state.position,
       headingTrueDeg: radToDeg(state.headingTrue),
       headingMagneticDeg: Number.isFinite(headingMagnetic) ? radToDeg(headingMagnetic) : null,
@@ -377,11 +451,14 @@ module.exports = function createPlugin (app) {
             providerId: weatherSnapshot.providerId,
             description: weatherSnapshot.description
           }
-        : { status: publishesAnyWind() ? 'missing' : 'disabled' },
+        : { status: 'missing' },
+      polar: inputs.polar || { status: 'missingActivePolar' },
       inputs: {
         turnRate: valueStatus(inputs.turnRate),
         magneticVariation: valueStatus(inputs.magneticVariation),
-        performanceSpeed: valueStatus(inputs.polarSpeed),
+        activePolar: activePolarFromValue(inputs.activePolar).id ? 'present' : 'missing',
+        performanceFactor: valueStatus(inputs.performanceFactor),
+        polarSpeed: valueStatus(inputs.polarSpeed),
         distanceToShore: valueStatus(inputs.distanceToShore),
         shoreBearingTrue: valueStatus(inputs.shoreBearingTrue),
         windSpeedTrue: valueStatus(inputs.windSpeedTrue),
@@ -391,6 +468,16 @@ module.exports = function createPlugin (app) {
     }
   }
 
+  function runtimeStatus (inputs) {
+    if (state.groundingProtectionActive) return 'groundingProtection'
+    if (Number.isFinite(state.speedThroughWater) && state.speedThroughWater > 0) return 'sailing'
+    if (!inputs.polar || inputs.polar.status === 'missingActivePolar') return 'waitingForPolar'
+    if (inputs.polar.status === 'waitingForWind') return 'waitingForWind'
+    if (inputs.polar.status === 'error') return 'polarError'
+    if (inputs.polar.status === 'noSpeedForConditions') return 'waitingForPolarSpeed'
+    return 'waitingForPolarSpeed'
+  }
+
   function setStatus () {
     if (!app.setPluginStatus) return
     if (runtime.status === 'sailing') {
@@ -458,6 +545,36 @@ function valueStatus (value) {
   return Number.isFinite(value) ? 'present' : 'missing'
 }
 
+function activePolarFromValue (value) {
+  if (typeof value === 'string' && value.trim()) {
+    const hrefId = polarIdFromHref(value)
+    return { id: hrefId || value.trim(), href: hrefId ? value : null }
+  }
+
+  if (!value || typeof value !== 'object') {
+    return { id: null, href: null }
+  }
+
+  const href = typeof value.href === 'string' ? value.href : null
+  return {
+    id: typeof value.id === 'string' && value.id.trim()
+      ? value.id.trim()
+      : polarIdFromHref(href),
+    href
+  }
+}
+
+function polarIdFromHref (href) {
+  if (typeof href !== 'string') return null
+  const match = href.match(/\/resources\/polars\/([^/?#]+)/)
+  if (!match) return null
+  try {
+    return decodeURIComponent(match[1])
+  } catch (_) {
+    return match[1]
+  }
+}
+
 function magneticHeadingFromTrue (headingTrue, magneticVariation) {
   if (!Number.isFinite(headingTrue) || !Number.isFinite(magneticVariation)) return null
   return wrap360Rad(headingTrue - magneticVariation)

package/lib/plugin-schema.js

@@ -4,7 +4,7 @@ function buildSchema () {
   return {
     type: 'object',
     title: 'Sailboat Simulator',
-    description: 'Simulates a virtual sailboat from autopilot turn-rate output, polar performance, weather and optional shore-distance data already present in Signal K.',
+    description: 'Simulates a virtual sailboat from autopilot turn-rate output, an active polar resource, weather and optional shore-distance data already present in Signal K.',
     properties: {
       initialState: {
         type: 'object',
@@ -37,12 +37,12 @@ function buildSchema () {
       wind: {
         type: 'object',
         title: 'Wind',
-        description: 'What it does: reads wind at the simulated boat position from the Signal K Weather API and publishes the selected wind values. The main goal is to feed polar performance calculations so another plugin can produce performance.polarSpeed, which the simulator then uses as boat speed. Requires: a Weather API provider, preferably @signalk/open-meteo-provider, and a polar performance plugin such as signalk-polar-performance-plugin. Options: publish true wind, publish apparent wind, optionally force a provider id instead of the Signal K default, and choose the polling interval.',
+        description: 'What it does: reads wind at the simulated boat position from the Signal K Weather API and publishes the selected wind values. The simulator also uses this wind with the active polar resource to calculate boat speed. Requires: a Weather API provider, preferably @signalk/open-meteo-provider. Options: publish true wind, publish apparent wind, optionally force a provider id instead of the Signal K default, and choose the polling interval.',
         properties: {
           trueWind: {
             type: 'boolean',
             title: 'Publish true wind',
-            description: 'Publishes environment.wind.speedTrue, environment.wind.directionTrue and environment.wind.angleTrueWater. This is usually needed by polar performance plugins.',
+            description: 'Publishes environment.wind.speedTrue, environment.wind.directionTrue and environment.wind.angleTrueWater. These are also the true wind values used for the internal polar speed calculation.',
             default: true
           },
           apparentWind: {
@@ -60,7 +60,7 @@ function buildSchema () {
           pollIntervalSeconds: {
             type: 'number',
             title: 'Weather polling interval in seconds',
-            description: 'How often the simulator refreshes wind from the Weather API while wind publishing is enabled.',
+            description: 'How often the simulator refreshes wind from the Weather API for its speed calculation and optional wind publication.',
             default: 60,
             minimum: 30
           }
@@ -69,7 +69,7 @@ function buildSchema () {
       publishing: {
         type: 'object',
         title: 'Navigation output',
-        description: 'What it does: publishes the simulated boat navigation state. Requires steering.autopilot.output.turnRate to steer and performance.polarSpeed to move. If navigation.magneticVariation is available, navigation.headingMagnetic is also published. Recommended providers: signalk-autopilot-emulator-v2, signalk-polar-performance-plugin and signalk-derived-data with navigation.magneticVariation publishing enabled.',
+        description: 'What it does: publishes the simulated boat navigation state. Requires steering.autopilot.output.turnRate to steer, an active polar from signalk-polar-management, and weather wind to calculate boat speed. If navigation.magneticVariation is available, navigation.headingMagnetic is also published. Recommended providers: signalk-autopilot-emulator-v2, signalk-polar-management and signalk-derived-data with navigation.magneticVariation publishing enabled.',
         properties: {
           navigation: {
             type: 'boolean',

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "signalk-sailboat-simulator",
-  "version": "0.2.0",
-  "description": "Signal K plugin that simulates a sailing boat from autopilot turn-rate output, weather and polar performance data.",
+  "version": "0.3.0",
+  "description": "Signal K plugin that simulates a sailing boat from autopilot turn-rate output, weather and an active polar resource.",
   "main": "index.js",
   "scripts": {
     "test": "node --test"
@@ -33,16 +33,17 @@
     "url": "https://github.com/macjl/signalk-sailboat-simulator/issues"
   },
   "engines": {
-    "node": ">=18"
+    "node": ">=20"
+  },
+  "dependencies": {
+    "polar-math": "^1.0.0"
   },
-  "dependencies": {},
-  "devDependencies": {},
   "signalk-plugin-enabled-by-default": false,
   "signalk": {
     "displayName": "Sailboat Simulator",
     "recommends": [
       "signalk-autopilot-emulator-v2",
-      "signalk-polar-performance-plugin",
+      "signalk-polar-management",
       "signalk-derived-data",
       "@signalk/open-meteo-provider",
       "signalk-distance-to-shore"