signalk-pelora 0.0.0-stage → 0.3.0

package/LICENSE

@@ -0,0 +1,17 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+Copyright 2026 SignalNav
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -1,3 +1,121 @@
-# Temporary Holding Version
+# signalk-pelora
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Sends a boat's engine hours, engine alarms, position and conditions from a
+[Signal K](https://signalk.org) server to [Pelora](https://signalnav.io), the
+maintenance platform by SignalNav. Works on any Signal K server: a Raspberry Pi
+with OpenPlotter, a Hat Labs HALPI2, a Victron Cerbo GX with Venus OS Large, or
+a laptop.
+
+The boat **pushes** to your operator's own Pelora address with a per-boat
+beacon id and secret. Nothing on the boat is opened to the internet, and
+nothing is sent anywhere but that address.
+
+## Setup
+
+1. In Pelora, open the boat → **Engines & data** → create a device of kind
+   *Signal K plugin*. Copy the beacon id and the secret (the secret is shown
+   once).
+2. On the Signal K server: **App Store** → search `signalk-pelora` → install →
+   restart the server.
+3. **Server → Plugin Config → Pelora**: paste the Pelora URL (for example
+   `https://yourcompany.signalnav.io`), the beacon id and the secret. Enable
+   and submit.
+4. Back in Pelora, the Engines & data page shows the device as seen within a
+   minute, and engine hours after the first counters upload (one minute).
+
+If your engines are not called `port` / `starboard` / `generator` in Signal K
+(many NMEA 2000 gateways call them `0` and `1`), either fill in *Which engine
+is which* in the plugin, or leave it: the engine arrives as *unknown* and the
+Engines & data page offers to place it.
+
+## What is sent
+
+| Every | Endpoint | Content |
+|---|---|---|
+| 5 min (configurable) | `telemetry/operating/ingest` | one sample per engine per second: rpm, load, fuel rate, coolant and oil temperatures, oil pressure, alternator and battery voltage, gear; the boat's position on top |
+| 5 min | `telemetry/vessel/ingest` | position, SOG, COG, depth, apparent wind, water temperature, autopilot state, one sample every 5 s |
+| 5 min | `telemetry/signalk/ingest` | a snapshot of heading, log, GNSS quality, outside conditions |
+| 5 min (configurable) | `telemetry/counters/ingest` | per engine: `runTime` as hours, fuel used, the interval's coolant / oil pressure / battery min and max |
+| at once | `telemetry/events/ingest` | engine start and stop; every Signal K notification under `notifications.*` when it is raised (`warn`/`alert` → warning, `alarm`/`emergency` → critical) and once more when it clears |
+| 60 s, off by default | `ais/contacts/ingest` | other vessels seen on AIS |
+
+Every batch is gzip-compressed and signed as sent; a twin-engine boat under way
+costs about 50 KB an hour, and a boat at rest a few KB.
+
+Units are converted from Signal K's SI to what Pelora expects (rpm, °C, kPa,
+L/h, knots, degrees). Engine hours come from `propulsion.<id>.runTime`; if your
+engine does not report it, Pelora derives hours from run time and the hours by
+hand stay available.
+
+## When there is no internet
+
+Every batch is written to disk first (`<signalk data dir>/signalk-pelora/queue`)
+and uploaded in order. Offline, batches wait up to 50 MB or 7 days, then the
+oldest go. Pelora recognises a batch it already has, so a lost reply never
+duplicates anything. A Pi without a real-time clock boots in 1970: the plugin
+learns the right time from Pelora's first refusal and signs with it.
+
+The plugin's status line in the Signal K dashboard shows the engines seen, the
+last upload and how many batches are queued.
+
+## Signing
+
+Each request carries `X-Beacon-Id`, `X-Timestamp` (unix seconds) and
+`X-Signature: sha256=<HMAC-SHA256(secret, timestamp + "." + body)>`, and
+Pelora refuses anything older than five minutes. `lib/signer.js` holds the
+test vector shared with Pelora's own test suite.
+
+## Trying it without a boat
+
+Signal K's bundled sample boat (`signalk-server --sample-n2k-data`) has position
+and depth but no engines. This repository carries pretend boats instead; they are
+not part of the npm package, so run them from a clone:
+
+```
+git clone https://github.com/signalnav/signalk-pelora.git
+node signalk-pelora/dev/feed.js
+```
+
+Then Server → Data Connections → Add: Input Type *Signal K*, Source *TCP*, host
+`127.0.0.1`, port `10111`, and restart the server. Every twelve minutes the boat
+starts both engines, runs ten minutes with a ninety-second coolant alarm on the
+port engine, and stops — enough to see hours, a trip, an alarm and its clear
+arrive in Pelora.
+
+For a whole day on the water, `dev/passage.js` takes the same boat from Palm Cay
+Marina in Nassau to Highbourne Cay, on the same TCP port: an hour under engine, four
+hours under sail with the engines off, half an hour motoring in, then a night at
+anchor (twelve hours, `--night` to change) before it starts over.
+
+```
+node dev/passage.js [--from dock|motor|sail|approach|anchor] [--speed 60] [--alarm]
+```
+
+`--speed 60` plays a minute of boat time per second, engine hours included.
+`--alarm` adds the coolant alarm to the first motoring leg. The waypoints are
+approximate; it is test data, not a route.
+
+For a whole charter, `dev/week.js` plays a recorded week as the vessel *Aurora*:
+track, speed, depth, wind and temperatures from the recording, engines generated
+from it, because the recording has none. The recording is not in this
+repository; `node dev/make-week.js --src <Beacon trip .jsonl>` builds one from a
+Beacon trip file into `dev/fixtures/exumas-week.json.gz`.
+
+```
+node dev/week.js [--day 1] [--time 08:30] [--speed 60] [--name Aurora]
+```
+
+## Development
+
+```
+npm test                       # node --test, no dependencies
+node dev/make-fixture.js       # 12 minutes of a twin-engine trip as Signal K deltas
+node dev/replay.js --url https://demo.signalnav.io --beacon PEL-… --secret … --speed 60
+```
+
+`dev/replay.js` runs the plugin outside a Signal K server against a real
+Pelora, from any file of one delta per line.
+
+## Licence
+
+Apache-2.0. © 2026 SignalNav.

package/img/pelora-mark.svg

@@ -0,0 +1,6 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100" width="512" height="512" role="img" aria-label="Pelora compass-rose mark">
+  <circle cx="50" cy="50" r="37" fill="none" stroke="#3AB7B0" stroke-width="10"/>
+  <path d="M50 18 L60 40 L82 50 L60 60 L50 82 L40 60 L18 50 L40 40 Z" fill="#2683FA"/>
+  <path d="M50 18 L60 40 L40 40 Z" fill="#FF2E36"/>
+  <circle cx="50" cy="50" r="3.8" fill="#FCFCFC"/>
+</svg>

package/index.js

@@ -0,0 +1,98 @@
+'use strict';
+// signalk-pelora — sends a boat's engine hours, alarms, position and
+// conditions to Pelora (https://signalnav.io). The boat PUSHES to the
+// operator's own Pelora address with a per-boat beacon id and secret; nothing
+// on the boat is opened to the internet, and nothing is sent anywhere else.
+
+const { createRuntime, validate } = require('./lib/runtime');
+
+module.exports = function (app) {
+  const plugin = {
+    id: 'signalk-pelora',
+    name: 'Pelora',
+    description: 'Engine hours, engine alarms, position and conditions to Pelora, the maintenance platform by SignalNav.',
+  };
+
+  plugin.schema = {
+    type: 'object',
+    required: ['peloraUrl', 'beaconId', 'secret'],
+    properties: {
+      peloraUrl: {
+        type: 'string', title: 'Pelora URL',
+        description: 'Your Pelora address, for example https://yourcompany.signalnav.io',
+      },
+      beaconId: {
+        type: 'string', title: 'Beacon id',
+        description: "From this boat's Engines & data page in Pelora (PEL-…).",
+      },
+      secret: {
+        type: 'string', title: 'Secret',
+        description: 'Shown once when the device was created in Pelora. Lost it? Create a new device there.',
+      },
+      uploadIntervalSec: {
+        type: 'integer', title: 'Upload every (seconds)', default: 300, minimum: 5, maximum: 3600,
+        description: 'How often engine samples, position and conditions are sent while there is a connection. Alarms and engine start/stop go at once whatever this says.',
+      },
+      countersIntervalSec: {
+        type: 'integer', title: 'Engine hours every (seconds)', default: 300, minimum: 30, maximum: 3600,
+      },
+      engineMap: {
+        type: 'array', title: 'Which engine is which',
+        description: 'Only needed when your engines are not called port / starboard / generator in Signal K. Unlisted engines are sent as unknown and can be placed from the Engines & data page.',
+        items: {
+          type: 'object',
+          properties: {
+            signalkId: { type: 'string', title: 'Signal K engine id', description: 'The id in propulsion.<id>, e.g. 0, main, engine1' },
+            position: { type: 'string', title: 'Is the', enum: ['port', 'starboard', 'genset'], enumNames: ['Port engine', 'Starboard engine', 'Generator'] },
+          },
+        },
+      },
+      batteryId: {
+        type: 'string', title: 'Battery to report',
+        description: 'The id in electrical.batteries.<id>. Blank picks the start/engine battery, then house, then the first seen.',
+      },
+      includeVessel: { type: 'boolean', title: 'Send position, speed, depth, wind and water temperature', default: true },
+      includeSignalK: { type: 'boolean', title: 'Send a Signal K snapshot (heading, log, GNSS quality, outside conditions)', default: true },
+      includeAis: { type: 'boolean', title: 'Send AIS contacts', default: false,
+        description: 'Other vessels seen by the AIS receiver, once a minute. Off unless your operator asks for it.' },
+      queueMaxMb: { type: 'integer', title: 'Keep up to (MB) while offline', default: 50, minimum: 5, maximum: 2000,
+        description: 'Batches wait on disk when there is no internet and upload in order when it is back. Oldest are dropped past this size or after 7 days.' },
+    },
+  };
+
+  plugin.uiSchema = {
+    secret: { 'ui:widget': 'password' },
+    engineMap: { 'ui:options': { orderable: false } },
+  };
+
+  let runtime = null;
+
+  plugin.start = function (options) {
+    const problems = validate(options || {});
+    if (problems.length) {
+      app.setPluginError(problems.join('; '));
+      return;
+    }
+    try {
+      runtime = createRuntime(app, options);
+      runtime.start();
+    } catch (e) {
+      app.setPluginError('could not start: ' + e.message);
+      app.error(e.stack || String(e));
+      runtime = null;
+    }
+  };
+
+  plugin.stop = function () {
+    if (runtime) {
+      try { runtime.stop(); } catch (e) { app.error('stop: ' + e.message); }
+      runtime = null;
+    }
+  };
+
+  plugin.statusMessage = function () {
+    return runtime ? runtime.statusLine() : 'Not running';
+  };
+
+  return plugin;
+};

package/lib/ais.js

@@ -0,0 +1,64 @@
+'use strict';
+// Other vessels, from the server's `vessels.*` contexts. Pelora keeps none of
+// this itself (it forwards to the beacon service when that is on), so it is
+// off unless the operator turns it on.
+
+const u = require('./units');
+const { iso } = require('./collector');
+
+const MMSI_RE = /^vessels\.urn:mrn:imo:mmsi:(\d{7,9})$/;
+
+class Ais {
+  constructor(options = {}) {
+    this.selfContext = options.selfContext || 'vessels.self';
+    this.expireMs = options.expireMs || 3600 * 1000;
+    this.contacts = new Map();   // mmsi → {mmsi, name, lat, lon, sog_kn, cog_deg, class, lastSeen}
+  }
+
+  onDelta(delta) {
+    if (!delta || !Array.isArray(delta.updates) || !delta.context || delta.context === this.selfContext) return;
+    const m = MMSI_RE.exec(delta.context);
+    if (!m) return;
+    const mmsi = m[1];
+    let c = this.contacts.get(mmsi);
+    if (!c) { c = { mmsi, lastSeen: 0 }; this.contacts.set(mmsi, c); }
+    for (const update of delta.updates) {
+      const parsed = update && update.timestamp ? Date.parse(update.timestamp) : NaN;
+      const at = Number.isFinite(parsed) ? parsed : Date.now();
+      for (const item of (update && update.values) || []) {
+        if (!item || typeof item.path !== 'string') continue;
+        let seen = false;
+        if (item.path === 'navigation.position') {
+          const pos = u.position(item.value);
+          if (pos) { c.lat = pos.lat; c.lon = pos.lon; seen = true; }
+        } else if (item.path === 'navigation.speedOverGround') {
+          const v = u.msToKn(item.value); if (v !== null) { c.sog_kn = v; seen = true; }
+        } else if (item.path === 'navigation.courseOverGroundTrue') {
+          const v = u.radToDeg360(item.value); if (v !== null) { c.cog_deg = v; seen = true; }
+        } else if (item.path === 'name' || item.path === '') {
+          const name = item.path === '' && item.value && typeof item.value === 'object' ? item.value.name : item.value;
+          if (typeof name === 'string' && name.trim()) c.name = name.trim().slice(0, 128);
+        } else if (item.path === 'sensors.ais.class') {
+          c.class = item.value === 'A' || item.value === 'B' ? item.value : 'unknown';
+        }
+        if (seen) c.lastSeen = Math.max(c.lastSeen, at);
+      }
+    }
+  }
+
+  // Contacts with a position heard in the last `maxAgeMs`; forgets the rest.
+  snapshot(now, maxAgeMs = 15 * 60 * 1000, limit = 500) {
+    const out = [];
+    for (const [mmsi, c] of this.contacts) {
+      if (now - c.lastSeen > this.expireMs) { this.contacts.delete(mmsi); continue; }
+      if (c.lat === undefined || now - c.lastSeen > maxAgeMs) continue;
+      const row = { mmsi, lat: c.lat, lon: c.lon, last_seen_utc: iso(c.lastSeen), age_sec: Math.max(0, Math.round((now - c.lastSeen) / 1000)) };
+      for (const f of ['name', 'sog_kn', 'cog_deg', 'class']) if (c[f] !== undefined) row[f] = c[f];
+      out.push(row);
+    }
+    out.sort((a, b) => a.age_sec - b.age_sec);
+    return out.slice(0, limit);
+  }
+}
+
+module.exports = { Ais };

package/lib/alarms.js

@@ -0,0 +1,43 @@
+'use strict';
+// Signal K notifications → Pelora engine events. A notification is a STATE
+// (normal | nominal | alert | warn | alarm | emergency) the server keeps
+// repeating; Pelora wants the transitions: one event when it is raised, one
+// `fault_clear` when it goes back to normal, nothing in between.
+
+const mapping = require('./mapping');
+const { iso } = require('./collector');
+
+const SEVERITY = { emergency: 'critical', alarm: 'critical', warn: 'warning', alert: 'warning' };
+
+class Alarms {
+  constructor(options = {}) {
+    this.engineMap = options.engineMap || [];
+    this.raised = new Map();   // key → {severity, message}
+  }
+
+  // {key, engineId, value, at} → event or null
+  onNotification({ key, engineId, value, at }) {
+    const state = value && typeof value === 'object' && typeof value.state === 'string' ? value.state.toLowerCase() : null;
+    const severity = state ? SEVERITY[state] || null : null;
+    const message = value && typeof value.message === 'string' ? value.message.slice(0, 255) : null;
+    const previous = this.raised.get(key);
+    const engine = engineId ? mapping.enginePosition(engineId, this.engineMap) : null;
+    const base = { time_utc: iso(at), engine: engine || undefined, rule_id: key.slice(0, 128),
+      dtc_text: message || key, data: { path: 'notifications.' + key, state, method: value && value.method } };
+
+    if (severity) {
+      if (previous && previous.severity === severity) return null;      // repeat
+      this.raised.set(key, { severity, message });
+      return { ...base, event_type: severity === 'critical' ? 'critical' : 'warning', severity };
+    }
+    if (previous) {
+      this.raised.delete(key);
+      return { ...base, event_type: 'fault_clear', severity: 'info' };
+    }
+    return null;
+  }
+
+  open() { return [...this.raised.keys()]; }
+}
+
+module.exports = { Alarms, SEVERITY };

package/lib/batcher.js

@@ -0,0 +1,150 @@
+'use strict';
+// The clock of the plugin: samples every second, uploads every
+// uploadIntervalSec (5 min), counters every countersIntervalSec (5 min),
+// events at once. Pelora wants a daily picture and the alarms, not a live
+// link; five minutes keeps a twin-engine boat near 50 KB an hour gzipped.
+// Every batch goes through the queue — even online — so a lost reply never
+// loses a batch and nothing is ever sent out of order.
+
+const { Collector } = require('./collector');
+const { Alarms } = require('./alarms');
+const { Ais } = require('./ais');
+
+const CAPS = { operating: 600, counters: 120, vessel: 600, events: 200, signalk: 120, ais: 500 };
+const ENDPOINTS = {
+  operating: 'telemetry/operating/ingest',
+  counters: 'telemetry/counters/ingest',
+  vessel: 'telemetry/vessel/ingest',
+  events: 'telemetry/events/ingest',
+  signalk: 'telemetry/signalk/ingest',
+  ais: 'ais/contacts/ingest',
+};
+
+function chunk(items, size) {
+  const out = [];
+  for (let i = 0; i < items.length; i += size) out.push(items.slice(i, i + size));
+  return out;
+}
+
+class Batcher {
+  constructor(options) {
+    this.beaconId = options.beaconId;
+    this.queue = options.queue;
+    this.onBatch = options.onBatch || (() => {});
+    this.log = options.log || (() => {});
+    this.clock = options.clock || (() => Date.now());
+    this.setInterval = options.setInterval || setInterval;
+    this.clearInterval = options.clearInterval || clearInterval;
+    this.uploadIntervalSec = options.uploadIntervalSec || 300;
+    this.countersIntervalSec = options.countersIntervalSec || 300;
+    this.vesselSampleSec = options.vesselSampleSec || 5;
+    this.aisIntervalSec = options.aisIntervalSec || 60;
+    this.includeVessel = options.includeVessel !== false;
+    this.includeSignalK = options.includeSignalK !== false;
+    this.includeAis = !!options.includeAis;
+    this.collector = options.collector || new Collector({ engineMap: options.engineMap, batteryId: options.batteryId, clock: this.clock });
+    this.alarms = options.alarms || new Alarms({ engineMap: options.engineMap });
+    this.ais = options.ais || new Ais({ selfContext: options.selfContext });
+    this.operating = [];
+    this.vessel = [];
+    this.ticks = 0;
+    this.timers = [];
+    this.batches = 0;
+    this.lastEventAt = null;
+  }
+
+  start() {
+    this.timers.push(this.setInterval(() => this.tick(), 1000));
+    this.timers.push(this.setInterval(() => this.flush(), this.uploadIntervalSec * 1000));
+    this.timers.push(this.setInterval(() => this.counters(), this.countersIntervalSec * 1000));
+    if (this.includeAis) this.timers.push(this.setInterval(() => this.aisBatch(), this.aisIntervalSec * 1000));
+  }
+
+  stop() {
+    for (const t of this.timers) this.clearInterval(t);
+    this.timers = [];
+    this.flush();
+    this.counters();
+  }
+
+  onDelta(delta) {
+    this.collector.onDelta(delta);
+    if (this.includeAis) this.ais.onDelta(delta);
+  }
+
+  tick() {
+    const now = this.clock();
+    this.ticks += 1;
+    for (const s of this.collector.engineSamples(now)) this.operating.push(s);
+    if (this.includeVessel && this.ticks % this.vesselSampleSec === 0) {
+      const v = this.collector.vesselSample(now);
+      if (v) this.vessel.push(v);
+    }
+    const events = this.collector.engineEvents(now);
+    for (const n of this.collector.takeNotifications()) {
+      const ev = this.alarms.onNotification(n);
+      if (ev) events.push(ev);
+    }
+    if (events.length) this.push('events', { beacon_id: this.beaconId, events });
+    if (this.operating.length >= CAPS.operating || this.vessel.length >= CAPS.vessel) this.flush();
+  }
+
+  flush() {
+    const now = this.clock();
+    if (this.operating.length) {
+      const head = { beacon_id: this.beaconId, source: 'signalk' };
+      const pos = this.collector.position(now);
+      if (pos) {
+        head.position = pos;
+        if (this.collector.vessel.sog_kn !== undefined) head.sog_kn = this.collector.vessel.sog_kn;
+        if (this.collector.vessel.cog_deg !== undefined) head.cog_deg = this.collector.vessel.cog_deg;
+      }
+      for (const samples of chunk(this.operating, CAPS.operating)) this.push('operating', { ...head, samples });
+      this.operating = [];
+    }
+    if (this.vessel.length) {
+      for (const samples of chunk(this.vessel, CAPS.vessel)) this.push('vessel', { beacon_id: this.beaconId, source: 'signalk', samples });
+      this.vessel = [];
+    }
+    if (this.includeSignalK) {
+      const snap = this.collector.signalkSnapshot(now);
+      if (snap) this.push('signalk', { beacon_id: this.beaconId, source: 'signalk', time_utc: snap.time_utc, values: snap.values });
+    }
+  }
+
+  counters() {
+    const samples = this.collector.counterSamples(this.clock());
+    if (!samples.length) return;
+    for (const part of chunk(samples, CAPS.counters)) this.push('counters', { beacon_id: this.beaconId, source: 'signalk', samples: part });
+  }
+
+  // Said once at start: Pelora stamps the device as seen and a wrong secret
+  // shows in the status line now, not when the engines are next started.
+  hello(info) {
+    const now = this.clock();
+    const values = {};
+    for (const [k, v] of Object.entries(info || {})) values['sk.plugin.' + k] = String(v).slice(0, 64);
+    this.push('signalk', { beacon_id: this.beaconId, source: 'signalk',
+      time_utc: new Date(now).toISOString().replace(/\.\d{3}Z$/, 'Z'), values });
+  }
+
+  aisBatch() {
+    const now = this.clock();
+    const contacts = this.ais.snapshot(now, undefined, CAPS.ais);
+    if (!contacts.length) return;
+    const body = { beacon_id: this.beaconId, source: 'signalk', observed_at_utc: new Date(now).toISOString().replace(/\.\d{3}Z$/, 'Z'), contacts };
+    const pos = this.collector.position(now);
+    if (pos) body.ownship = pos;
+    this.push('ais', body);
+  }
+
+  push(kind, body) {
+    const text = JSON.stringify(body);
+    this.queue.push(ENDPOINTS[kind], text);
+    this.batches += 1;
+    if (kind === 'events') this.lastEventAt = this.clock();
+    this.onBatch(kind, body);
+  }
+}
+
+module.exports = { Batcher, CAPS, ENDPOINTS, chunk };