signalk-telltale-plugin

Telltale Uplink — a Signal K server plugin that streams a decimated, disk-buffered copy of your boat's data to a self-hosted shore collector over HTTPS, with an HMAC-signed command channel back to the boat. It also supports bounded raw NMEA 2000 capture, switch discovery, and gated digital-switching actuation — a "universal remote" for your CZone/N2K loads.

Part of the Telltale project (boat plugin + shore stack: collector, public portal, Grafana, TimescaleDB).

What it does

• Telemetry uplink — samples a path allowlist on an interval, batches snapshots, and POSTs them to the shore collector. A bounded, flash-friendly disk queue survives reboots and drains only on ack, so a flaky cellular link never loses or duplicates data and never fills the Cerbo's /data partition.
• Command channel — every POST may return an HMAC-signed directive: change the sample/post intervals (declarative + versioned) or run a one-shot command (e.g. flushBuffer). Signatures are verified with a shared commandKey before anything is applied; a bad signature is ignored.
• Raw N2K capture — a shore-initiated, time-boxed, rate-limited window taps the canboat-parsed N2K stream (N2KAnalyzerOut) and ships {pgn, src, dst, fields} frames for remote viewing. Auto-expires so cellular usage stays sane.
• Discovery (Phase 1, read-only) — name a load, flip its physical switch a few times, and the plugin edge-correlates the switching PGNs to infer the (pgn, instance, switch) signature, with confidence + co-moving ambiguities.
• Digital-switching actuation (gated) — send 127502 / 126208 to switch a load, with read-back confirmation — behind a layered safety model (see below).

Install

In the Signal K admin UI: Appstore → Available → search "telltale" → Install, then restart. No SSH/root required. (Or npm install signalk-telltale-plugin in your server's data directory.)

Then Server → Plugin Config → Telltale Uplink, enable it, and set:

| Setting | Notes | |---|---| | Shore collector URL | e.g. https://your-shore/api/ingest | | Vessel id | the source your shore expects (e.g. goblin) | | Ingest token | bearer that proves the boat may write (matches shore INGEST_TOKEN) | | Command key | shared secret that signs/verifies directives (matches shore COMMAND_KEY) | | Sample / post interval (ms) | default 15000 each | | Paths to send | empty = a sensible nav/wind/depth/battery default | | Enable actuation | master arm — leave OFF unless actively switching loads | | Switching allowlist | the boat-side list of confirmed, actuatable targets |

Actuation safety model

Actuation is off by default and gated by more than the HMAC:

1. The boat-side allowlist is the real control. The plugin only emits commands matching a locally-configured, confirmed, non-excluded target. A compromised or buggy shore cannot address anything you haven't explicitly enabled on the boat.
2. Master arm toggle, default OFF. Telemetry, raw capture, and discovery always work; actuation is ignored entirely unless armed.
3. TTL on commands. Stale actuation commands are dropped, never executed late after a buffered outage.
4. Closed-loop confirm. A target is only confirmed after a Phase-2 test toggles it and reads back the resulting 127501 status; only confirmed targets are actuatable.
5. Hard exclusions. Never allowlist loads where a wrong/stale/spoofed state could endanger the boat (bilge pumps, nav/steaming lights underway, engine, windlass, anything affecting watertight integrity). Cabin lights, fans, fridge: fine.

Actuation requires Signal K's writable canboatjs N2K connection (sends to NMEA 2000). Raw capture and discovery work with any N2K input.

Development

npm test        # node:test unit suite (hmac, buffer, discovery, actuation, n2k)

Local edit-in-place loop, the shore stack, and the offline simulators are documented in the project INSTRUCTIONS.

License

MIT