signalk-aiscast 0.0.0

package/README.md

@@ -0,0 +1,44 @@
+# signalk-aiscast
+
+Signal K plugin for [aiscast](https://github.com/openwatersio/aiscast), the open AIS network from [Open Waters](https://openwaters.io). It does two things over one connection:
+
+- **Share**: every AIS sentence your receiver hears (`!AIVDM` on NMEA 0183, or NMEA 2000 AIS PGNs re-encoded as sentences) is sent to aiscast as it arrives, so the places only boats can hear get coverage. Your own transponder's position (`!AIVDO`) is shared too; it has its own switch if you would rather share only what you hear from others.
+- **Receive**: when the boat hears no AIS of its own (no receiver, receiver off, server running ashore), the plugin subscribes to aiscast around your position and injects the traffic as Signal K targets with `$source` `signalk-aiscast.net`, so Freeboard and friends show them. `Always` mode also fills in beyond VHF range; locally heard targets win.
+
+No account. On first start the plugin generates an Ed25519 keypair in its data directory and requests its own access token from aiscast (sent as an `Authorization: Bearer` header); receptions are credited to that key. Paste an operator-issued token into the config to publish as a named station with higher limits.
+
+## Install
+
+Signal K App Store → `signalk-aiscast`, or `npm install signalk-aiscast` in `~/.signalk`. Enable it in Plugin Config.
+
+## Settings
+
+| Setting | Default | Meaning |
+|---|---|---|
+| Share → Other vessels | on | publish AIS heard by the receiver (NMEA 0183 `!AIVDM`, NMEA 2000 AIS) |
+| Share → Own ship | on | publish `!AIVDO`; your position becomes public open data on aiscast (it is already broadcast on VHF) |
+| Receive → Show traffic from aiscast | auto | `Off`, `Auto` (only while nothing is heard locally for 90 s), `Always` (also beyond local VHF range; local reception wins per target) |
+| Receive → Radius | 50 nm | subscription box around the vessel (5–200) |
+| Advanced → Server | `https://ais.openwaters.io` | aiscast base URL |
+| Advanced → Access token | empty | optional operator-issued token; empty = self-minted personal token |
+
+## Behaviour worth knowing
+
+- Sentences go out as received, each stamped with a NMEA TAG block carrying the receive time. Anything not acknowledged, or heard while offline, waits in `<data dir>/queue/` (cap 100 MB) and replays oldest-first on reconnect; aiscast archives replayed sentences older than a minute without putting them on the live map.
+- Reconnects with jittered backoff (5 s → 5 min; 30 min after a refusal) and a 60 s silence watchdog. Status line in Plugin Config shows the key prefix, send rate, queue depth, targets, and link state.
+- Injected targets come through the server's own AIS parser, so they are shaped exactly like VHF-received ones; the server's *Maximum age of inactive vessels* setting expires them. Your own vessel and echoes of your own receptions are never injected, and payloads received from aiscast are never published back.
+- NMEA 2000 AIS needs nothing extra: PGNs 129038/129039/129041/129794/129809/129810 are re-encoded to `!AIVDM` (own ship to `!AIVDO`) and tagged `s:n2k`, since N2K carries decoded fields rather than the VHF bits. `signalk-n2kais-to-nmea0183` is not required and not listened to.
+
+## Data and licensing
+
+What you share is published by aiscast under its open data terms (see the [aiscast README](https://github.com/openwatersio/aiscast#readme)). The plugin never shares anything other than AIS sentences and, if you enable it, your own AIS position. Removal requests and the privacy policy are on the aiscast site.
+
+## Development
+
+```sh
+npm install
+npm test          # vitest against a fake aiscast server
+npm run build     # dist/
+```
+
+Released to npm by the repo's `release.yml` when a GitHub release tagged `signalk-plugin-v*` is created.

package/dist/downlink.d.ts

@@ -0,0 +1,47 @@
+import type { ServerAPI } from "@signalk/server-api";
+import type { Link } from "./link.js";
+export type ReceiveMode = "off" | "auto" | "always";
+export interface DownlinkOptions {
+    mode: ReceiveMode;
+    radiusNm: number;
+    source: string;
+    selfSource: string | null;
+    onReceived?: (sentence: string) => void;
+}
+export interface DownlinkStats {
+    targets: number;
+    events: number;
+    subscribed: boolean;
+}
+interface Box {
+    lat: number;
+    lon: number;
+    radiusNm: number;
+}
+export declare class Downlink {
+    private readonly app;
+    private readonly link;
+    private opts;
+    private readonly log;
+    private parser;
+    private lastLocal;
+    private box;
+    private subscribed;
+    private timer;
+    private targets;
+    private selfMmsi;
+    stats: DownlinkStats;
+    constructor(app: ServerAPI, link: Link, opts: DownlinkOptions, log?: (msg: string) => void);
+    start(): void;
+    stop(): void;
+    localHeard(now?: number): void;
+    private wanted;
+    private ownPosition;
+    tick(now?: number): void;
+    private onFrame;
+    private vhfIsFresh;
+    private pruneTargets;
+}
+export declare function bbox(b: Box): [number, number, number, number];
+export declare function distanceNm(lat1: number, lon1: number, lat2: number, lon2: number): number;
+export {};

package/dist/downlink.js

@@ -0,0 +1,187 @@
+import { Parser } from "@signalk/nmea0183-signalk";
+import { stripTag } from "./nmea.js";
+const LOCAL_QUIET = 90_000; // auto: no local AIS for this long → subscribe
+const RESUBSCRIBE_FRACTION = 0.25; // re-send the box after moving this fraction of the radius
+const VHF_WINS = 60_000; // always: leave a target alone when another source updated it this recently
+const TARGET_TTL = 10 * 60_000;
+// Subscribes to aiscast around the boat and injects the events as Signal K deltas through the server's own
+// AIS parser, so injected targets are indistinguishable in shape from VHF-received ones except by $source.
+export class Downlink {
+    app;
+    link;
+    opts;
+    log;
+    parser = new Parser();
+    lastLocal = 0;
+    box = null;
+    subscribed = false;
+    timer = null;
+    targets = new Map();
+    selfMmsi;
+    stats = { targets: 0, events: 0, subscribed: false };
+    constructor(app, link, opts, log = () => { }) {
+        this.app = app;
+        this.link = link;
+        this.opts = opts;
+        this.log = log;
+        const mmsi = app.getSelfPath("mmsi");
+        this.selfMmsi = mmsi == null ? null : String(mmsi);
+    }
+    start() {
+        this.link.on("open", () => {
+            this.subscribed = false;
+            this.tick();
+        });
+        this.link.on("close", () => {
+            this.subscribed = false;
+            this.stats.subscribed = false;
+        });
+        this.link.on("error", (message) => {
+            if (/bbox/.test(message))
+                this.subscribed = this.stats.subscribed = false; // aiscast kept the old subscription (none)
+        });
+        this.link.on("frame", (f) => this.onFrame(f));
+        this.timer = setInterval(() => this.tick(), 10_000);
+        this.tick();
+    }
+    stop() {
+        if (this.timer)
+            clearInterval(this.timer);
+        this.timer = null;
+    }
+    // The boat's own receiver heard AIS; in `auto` mode that silences the network feed.
+    localHeard(now = Date.now()) {
+        this.lastLocal = now;
+        if (this.subscribed && this.opts.mode === "auto")
+            this.tick(now);
+    }
+    wanted(now) {
+        switch (this.opts.mode) {
+            case "off":
+                return false;
+            case "always":
+                return true;
+            case "auto":
+                return now - this.lastLocal > LOCAL_QUIET;
+        }
+    }
+    ownPosition() {
+        const p = this.app.getSelfPath("navigation.position");
+        const v = p && "value" in p ? p.value : p;
+        if (!v || typeof v.latitude !== "number" || typeof v.longitude !== "number")
+            return null;
+        if (Math.abs(v.latitude) < 1e-6 && Math.abs(v.longitude) < 1e-6)
+            return null; // Null Island
+        return v;
+    }
+    tick(now = Date.now()) {
+        if (!this.link.open)
+            return;
+        if (!this.wanted(now)) {
+            if (this.subscribed && this.link.send({ type: "unsubscribe" })) {
+                this.subscribed = false;
+                this.stats.subscribed = false;
+                this.log("unsubscribed");
+            }
+            return;
+        }
+        const pos = this.ownPosition();
+        if (!pos)
+            return; // never subscribe without a position: an empty bbox is the whole world
+        const moved = this.box
+            ? distanceNm(pos.latitude, pos.longitude, this.box.lat, this.box.lon) > this.box.radiusNm * RESUBSCRIBE_FRACTION ||
+                this.box.radiusNm !== this.opts.radiusNm
+            : true;
+        if (this.subscribed && !moved)
+            return;
+        const box = { lat: pos.latitude, lon: pos.longitude, radiusNm: this.opts.radiusNm };
+        if (this.link.send({ type: "subscribe", bbox: [bbox(box)] })) {
+            this.box = box;
+            this.subscribed = true;
+            this.stats.subscribed = true;
+            this.log(`subscribed ${box.radiusNm} nm around ${box.lat.toFixed(3)},${box.lon.toFixed(3)}`);
+        }
+    }
+    onFrame(f) {
+        if (f.type !== "event")
+            return;
+        const ev = f;
+        if (!Array.isArray(ev.nmea) || ev.nmea.length === 0)
+            return;
+        for (const s of ev.nmea)
+            this.opts.onReceived?.(s);
+        if (this.opts.selfSource && ev.source === this.opts.selfSource)
+            return;
+        if (!ev.mmsi || String(ev.mmsi) === this.selfMmsi)
+            return;
+        if (POSITION_TYPES.has(ev.msg_type ?? "") && (ev.lat == null || ev.lon == null))
+            return; // aiscast rejected the position
+        let delta = null;
+        for (const s of ev.nmea) {
+            try {
+                delta = this.parser.parse(stripTag(s)) ?? delta;
+            }
+            catch (err) {
+                this.log(`parse failed for ${s}: ${err.message}`);
+                return;
+            }
+        }
+        if (!delta?.context || !delta.updates?.length)
+            return;
+        if (delta.context === this.app.selfContext)
+            return;
+        if (this.opts.mode === "always" && this.vhfIsFresh(delta.context, Date.now()))
+            return;
+        for (const u of delta.updates) {
+            delete u.source;
+            u.$source = this.opts.source;
+            if (ev.time)
+                u.timestamp = ev.time;
+        }
+        this.app.handleMessage(this.opts.source, delta);
+        this.stats.events++;
+        this.targets.set(delta.context, Date.now());
+        if (this.stats.events % 100 === 0)
+            this.pruneTargets();
+        this.stats.targets = this.targets.size;
+    }
+    // Another source (the boat's receiver) updated this target recently: do not overwrite it.
+    vhfIsFresh(context, now) {
+        const pos = this.app.getPath(`${context}.navigation.position`);
+        if (!pos?.$source || pos.$source === this.opts.source || !pos.timestamp)
+            return false;
+        return now - Date.parse(pos.timestamp) < VHF_WINS;
+    }
+    pruneTargets() {
+        const cutoff = Date.now() - TARGET_TTL;
+        for (const [k, t] of this.targets)
+            if (t < cutoff)
+                this.targets.delete(k);
+    }
+}
+const POSITION_TYPES = new Set([
+    "PositionReport",
+    "StandardClassBPositionReport",
+    "ExtendedClassBPositionReport",
+    "LongRangeAisBroadcastMessage",
+    "StandardSearchAndRescueAircraftReport",
+]);
+// [minLat, minLon, maxLat, maxLon] around a centre. ponytail: clamped at the poles and antimeridian rather than split.
+export function bbox(b) {
+    const dLat = b.radiusNm / 60;
+    const dLon = b.radiusNm / (60 * Math.max(0.05, Math.cos((b.lat * Math.PI) / 180)));
+    return [
+        Math.max(-90, b.lat - dLat),
+        Math.max(-180, b.lon - dLon),
+        Math.min(90, b.lat + dLat),
+        Math.min(180, b.lon + dLon),
+    ];
+}
+export function distanceNm(lat1, lon1, lat2, lon2) {
+    const toRad = Math.PI / 180;
+    const dLat = (lat2 - lat1) * toRad;
+    const dLon = (lon2 - lon1) * toRad;
+    const a = Math.sin(dLat / 2) ** 2 + Math.cos(lat1 * toRad) * Math.cos(lat2 * toRad) * Math.sin(dLon / 2) ** 2;
+    return 2 * 3440.065 * Math.asin(Math.sqrt(a));
+}
+//# sourceMappingURL=downlink.js.map

package/dist/downlink.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"downlink.js","sourceRoot":"","sources":["../src/downlink.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,EAAE,MAAM,2BAA2B,CAAC;AAEnD,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAkBrC,MAAM,WAAW,GAAG,MAAM,CAAC,CAAC,+CAA+C;AAC3E,MAAM,oBAAoB,GAAG,IAAI,CAAC,CAAC,2DAA2D;AAC9F,MAAM,QAAQ,GAAG,MAAM,CAAC,CAAC,4EAA4E;AACrG,MAAM,UAAU,GAAG,EAAE,GAAG,MAAM,CAAC;AAa/B,2GAA2G;AAC3G,2GAA2G;AAC3G,MAAM,OAAO,QAAQ;IAWA;IACA;IACT;IACS;IAbX,MAAM,GAAG,IAAI,MAAM,EAAE,CAAC;IACtB,SAAS,GAAG,CAAC,CAAC;IACd,GAAG,GAAe,IAAI,CAAC;IACvB,UAAU,GAAG,KAAK,CAAC;IACnB,KAAK,GAA0B,IAAI,CAAC;IACpC,OAAO,GAAG,IAAI,GAAG,EAAkB,CAAC;IACpC,QAAQ,CAAgB;IAChC,KAAK,GAAkB,EAAE,OAAO,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,UAAU,EAAE,KAAK,EAAE,CAAC;IAEpE,YACmB,GAAc,EACd,IAAU,EACnB,IAAqB,EACZ,MAA6B,GAAG,EAAE,GAAE,CAAC;QAHrC,QAAG,GAAH,GAAG,CAAW;QACd,SAAI,GAAJ,IAAI,CAAM;QACnB,SAAI,GAAJ,IAAI,CAAiB;QACZ,QAAG,GAAH,GAAG,CAAkC;QAEtD,MAAM,IAAI,GAAG,GAAG,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;QACrC,IAAI,CAAC,QAAQ,GAAG,IAAI,IAAI,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IACrD,CAAC;IAED,KAAK;QACH,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,MAAM,EAAE,GAAG,EAAE;YACxB,IAAI,CAAC,UAAU,GAAG,KAAK,CAAC;YACxB,IAAI,CAAC,IAAI,EAAE,CAAC;QACd,CAAC,CAAC,CAAC;QACH,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE;YACzB,IAAI,CAAC,UAAU,GAAG,KAAK,CAAC;YACxB,IAAI,CAAC,KAAK,CAAC,UAAU,GAAG,KAAK,CAAC;QAChC,CAAC,CAAC,CAAC;QACH,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,OAAO,EAAE,EAAE;YAChC,IAAI,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC;gBAAE,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,KAAK,CAAC,UAAU,GAAG,KAAK,CAAC,CAAC,2CAA2C;QACxH,CAAC,CAAC,CAAC;QACH,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC;QAC9C,IAAI,CAAC,KAAK,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,EAAE,MAAM,CAAC,CAAC;QACpD,IAAI,CAAC,IAAI,EAAE,CAAC;IACd,CAAC;IAED,IAAI;QACF,IAAI,IAAI,CAAC,KAAK;YAAE,aAAa,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAC1C,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;IACpB,CAAC;IAED,oFAAoF;IACpF,UAAU,CAAC,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE;QACzB,IAAI,CAAC,SAAS,GAAG,GAAG,CAAC;QACrB,IAAI,IAAI,CAAC,UAAU,IAAI,IAAI,CAAC,IAAI,CAAC,IAAI,KAAK,MAAM;YAAE,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACnE,CAAC;IAEO,MAAM,CAAC,GAAW;QACxB,QAAQ,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;YACvB,KAAK,KAAK;gBACR,OAAO,KAAK,CAAC;YACf,KAAK,QAAQ;gBACX,OAAO,IAAI,CAAC;YACd,KAAK,MAAM;gBACT,OAAO,GAAG,GAAG,IAAI,CAAC,SAAS,GAAG,WAAW,CAAC;QAC9C,CAAC;IACH,CAAC;IAEO,WAAW;QACjB,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,WAAW,CAAC,qBAAqB,CAAgD,CAAC;QACrG,MAAM,CAAC,GAAG,CAAC,IAAI,OAAO,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAE,CAA0B,CAAC;QACpE,IAAI,CAAC,CAAC,IAAI,OAAO,CAAC,CAAC,QAAQ,KAAK,QAAQ,IAAI,OAAO,CAAC,CAAC,SAAS,KAAK,QAAQ;YAAE,OAAO,IAAI,CAAC;QACzF,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC,GAAG,IAAI,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI;YAAE,OAAO,IAAI,CAAC,CAAC,cAAc;QAC5F,OAAO,CAAC,CAAC;IACX,CAAC;IAED,IAAI,CAAC,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE;QACnB,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI;YAAE,OAAO;QAC5B,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC;YACtB,IAAI,IAAI,CAAC,UAAU,IAAI,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,aAAa,EAAE,CAAC,EAAE,CAAC;gBAC/D,IAAI,CAAC,UAAU,GAAG,KAAK,CAAC;gBACxB,IAAI,CAAC,KAAK,CAAC,UAAU,GAAG,KAAK,CAAC;gBAC9B,IAAI,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;YAC3B,CAAC;YACD,OAAO;QACT,CAAC;QACD,MAAM,GAAG,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC;QAC/B,IAAI,CAAC,GAAG;YAAE,OAAO,CAAC,uEAAuE;QACzF,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG;YACpB,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,QAAQ,EAAE,GAAG,CAAC,SAAS,EAAE,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,QAAQ,GAAG,oBAAoB;gBAC9G,IAAI,CAAC,GAAG,CAAC,QAAQ,KAAK,IAAI,CAAC,IAAI,CAAC,QAAQ;YAC1C,CAAC,CAAC,IAAI,CAAC;QACT,IAAI,IAAI,CAAC,UAAU,IAAI,CAAC,KAAK;YAAE,OAAO;QACtC,MAAM,GAAG,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,QAAQ,EAAE,GAAG,EAAE,GAAG,CAAC,SAAS,EAAE,QAAQ,EAAE,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC;QACpF,IAAI,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;YAC7D,IAAI,CAAC,GAAG,GAAG,GAAG,CAAC;YACf,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC;YACvB,IAAI,CAAC,KAAK,CAAC,UAAU,GAAG,IAAI,CAAC;YAC7B,IAAI,CAAC,GAAG,CAAC,cAAc,GAAG,CAAC,QAAQ,cAAc,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QAC/F,CAAC;IACH,CAAC;IAEO,OAAO,CAAC,CAAQ;QACtB,IAAI,CAAC,CAAC,IAAI,KAAK,OAAO;YAAE,OAAO;QAC/B,MAAM,EAAE,GAAG,CAAwB,CAAC;QACpC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,IAAI,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO;QAC5D,KAAK,MAAM,CAAC,IAAI,EAAE,CAAC,IAAI;YAAE,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC,CAAC;QACnD,IAAI,IAAI,CAAC,IAAI,CAAC,UAAU,IAAI,EAAE,CAAC,MAAM,KAAK,IAAI,CAAC,IAAI,CAAC,UAAU;YAAE,OAAO;QACvE,IAAI,CAAC,EAAE,CAAC,IAAI,IAAI,MAAM,CAAC,EAAE,CAAC,IAAI,CAAC,KAAK,IAAI,CAAC,QAAQ;YAAE,OAAO;QAC1D,IAAI,cAAc,CAAC,GAAG,CAAC,EAAE,CAAC,QAAQ,IAAI,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,GAAG,IAAI,IAAI,IAAI,EAAE,CAAC,GAAG,IAAI,IAAI,CAAC;YAAE,OAAO,CAAC,gCAAgC;QAEzH,IAAI,KAAK,GAAiB,IAAI,CAAC;QAC/B,KAAK,MAAM,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC;YACxB,IAAI,CAAC;gBACH,KAAK,GAAI,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,CAA6B,IAAI,KAAK,CAAC;YAC/E,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,IAAI,CAAC,GAAG,CAAC,oBAAoB,CAAC,KAAM,GAAa,CAAC,OAAO,EAAE,CAAC,CAAC;gBAC7D,OAAO;YACT,CAAC;QACH,CAAC;QACD,IAAI,CAAC,KAAK,EAAE,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,MAAM;YAAE,OAAO;QACtD,IAAI,KAAK,CAAC,OAAO,KAAK,IAAI,CAAC,GAAG,CAAC,WAAW;YAAE,OAAO;QACnD,IAAI,IAAI,CAAC,IAAI,CAAC,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,OAAO,EAAE,IAAI,CAAC,GAAG,EAAE,CAAC;YAAE,OAAO;QAEtF,KAAK,MAAM,CAAC,IAAI,KAAK,CAAC,OAAO,EAAE,CAAC;YAC9B,OAAQ,CAA0B,CAAC,MAAM,CAAC;YAC1C,CAAC,CAAC,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,MAA6C,CAAC;YACpE,IAAI,EAAE,CAAC,IAAI;gBAAE,CAAC,CAAC,SAAS,GAAG,EAAE,CAAC,IAA6C,CAAC;QAC9E,CAAC;QACD,IAAI,CAAC,GAAG,CAAC,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;QAChD,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC;QACpB,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,OAAO,EAAE,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;QAC5C,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,GAAG,KAAK,CAAC;YAAE,IAAI,CAAC,YAAY,EAAE,CAAC;QACvD,IAAI,CAAC,KAAK,CAAC,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC;IACzC,CAAC;IAED,0FAA0F;IAClF,UAAU,CAAC,OAAe,EAAE,GAAW;QAC7C,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,OAAO,sBAAsB,CAAyD,CAAC;QACvH,IAAI,CAAC,GAAG,EAAE,OAAO,IAAI,GAAG,CAAC,OAAO,KAAK,IAAI,CAAC,IAAI,CAAC,MAAM,IAAI,CAAC,GAAG,CAAC,SAAS;YAAE,OAAO,KAAK,CAAC;QACtF,OAAO,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC,GAAG,QAAQ,CAAC;IACpD,CAAC;IAEO,YAAY;QAClB,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,UAAU,CAAC;QACvC,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,IAAI,CAAC,OAAO;YAAE,IAAI,CAAC,GAAG,MAAM;gBAAE,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;IAC5E,CAAC;CACF;AAaD,MAAM,cAAc,GAAG,IAAI,GAAG,CAAC;IAC7B,gBAAgB;IAChB,8BAA8B;IAC9B,8BAA8B;IAC9B,8BAA8B;IAC9B,uCAAuC;CACxC,CAAC,CAAC;AAEH,uHAAuH;AACvH,MAAM,UAAU,IAAI,CAAC,CAAM;IACzB,MAAM,IAAI,GAAG,CAAC,CAAC,QAAQ,GAAG,EAAE,CAAC;IAC7B,MAAM,IAAI,GAAG,CAAC,CAAC,QAAQ,GAAG,CAAC,EAAE,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,GAAG,IAAI,CAAC,EAAE,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC;IACnF,OAAO;QACL,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,GAAG,IAAI,CAAC;QAC3B,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,GAAG,GAAG,IAAI,CAAC;QAC5B,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,GAAG,IAAI,CAAC;QAC1B,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,CAAC,GAAG,GAAG,IAAI,CAAC;KAC5B,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,IAAY,EAAE,IAAY,EAAE,IAAY,EAAE,IAAY;IAC/E,MAAM,KAAK,GAAG,IAAI,CAAC,EAAE,GAAG,GAAG,CAAC;IAC5B,MAAM,IAAI,GAAG,CAAC,IAAI,GAAG,IAAI,CAAC,GAAG,KAAK,CAAC;IACnC,MAAM,IAAI,GAAG,CAAC,IAAI,GAAG,IAAI,CAAC,GAAG,KAAK,CAAC;IACnC,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,GAAG,KAAK,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,GAAG,KAAK,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC;IAC9G,OAAO,CAAC,GAAG,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;AAChD,CAAC"}

package/dist/identity.d.ts

@@ -0,0 +1,15 @@
+import { type JsonWebKey } from "node:crypto";
+export interface Identity {
+    pubkey: string;
+    jwk: JsonWebKey;
+}
+export declare function loadIdentity(dir: string): Promise<Identity>;
+export interface Token {
+    token: string;
+    exp: number;
+    pubkey: string;
+    server: string;
+}
+export declare function loadToken(dir: string, server: string, pubkey: string, now?: number): Promise<Token>;
+export declare function forgetToken(dir: string): Promise<void>;
+export declare function mintToken(server: string, pubkey: string): Promise<Token>;

package/dist/identity.js

@@ -0,0 +1,51 @@
+import { generateKeyPairSync } from "node:crypto";
+import { readFile, writeFile, unlink } from "node:fs/promises";
+import { join } from "node:path";
+// The keypair is the boat's identity with aiscast. It is generated once and never leaves the data dir.
+export async function loadIdentity(dir) {
+    const file = join(dir, "identity.json");
+    try {
+        const jwk = JSON.parse(await readFile(file, "utf8"));
+        if (jwk.kty === "OKP" && jwk.crv === "Ed25519" && jwk.x && jwk.d)
+            return { pubkey: jwk.x, jwk };
+    }
+    catch {
+        // first start, or unreadable: generate below
+    }
+    const { privateKey } = generateKeyPairSync("ed25519");
+    const jwk = privateKey.export({ format: "jwk" });
+    await writeFile(file, JSON.stringify(jwk), { mode: 0o600 });
+    return { pubkey: jwk.x, jwk };
+}
+const RENEW_BEFORE = 3 * 24 * 3600; // seconds before expiry at which a new token is requested
+// A personal token from POST /v1/keys, cached in the data dir and renewed a few days before it expires.
+export async function loadToken(dir, server, pubkey, now = Date.now()) {
+    const file = join(dir, "token.json");
+    try {
+        const t = JSON.parse(await readFile(file, "utf8"));
+        if (t.pubkey === pubkey && t.server === server && t.exp - now / 1000 > RENEW_BEFORE)
+            return t;
+    }
+    catch {
+        // none cached
+    }
+    const t = await mintToken(server, pubkey);
+    await writeFile(file, JSON.stringify(t), { mode: 0o600 });
+    return t;
+}
+export async function forgetToken(dir) {
+    await unlink(join(dir, "token.json")).catch(() => { });
+}
+export async function mintToken(server, pubkey) {
+    const res = await fetch(new URL("/v1/keys", server), {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ pubkey }),
+        signal: AbortSignal.timeout(15_000),
+    });
+    if (!res.ok)
+        throw new Error(`POST /v1/keys: ${res.status} ${(await res.text()).trim()}`);
+    const body = (await res.json());
+    return { token: body.token, exp: body.claims.exp, pubkey, server };
+}
+//# sourceMappingURL=identity.js.map

package/dist/identity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity.js","sourceRoot":"","sources":["../src/identity.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+import type { Plugin, ServerAPI } from "@signalk/server-api";
+import { type ReceiveMode } from "./downlink.js";
+export declare const PLUGIN_ID = "signalk-aiscast";
+export interface Config {
+    share?: {
+        targets?: boolean;
+        ownShip?: boolean;
+    };
+    receive?: {
+        mode?: ReceiveMode;
+        radiusNm?: number;
+    };
+    advanced?: {
+        server?: string;
+        token?: string;
+    };
+    server?: string;
+    token?: string;
+}
+export default function (app: ServerAPI): Plugin;

package/dist/index.js

@@ -0,0 +1,263 @@
+import { Downlink } from "./downlink.js";
+import { forgetToken, loadIdentity, loadToken, } from "./identity.js";
+import { Link } from "./link.js";
+import { n2kToSentence } from "./n2k.js";
+import { isAis, isOwnShip } from "./nmea.js";
+import { Uplink } from "./uplink.js";
+export const PLUGIN_ID = "signalk-aiscast";
+const DEFAULT_SERVER = "https://ais.openwaters.io";
+const STATUS_EVERY = 5_000;
+const TOKEN_CHECK_EVERY = 6 * 3600_000;
+export default function (app) {
+    const events = app;
+    let generation = 0; // bumped by stop(); a start() still in its awaits checks it and gives up
+    let teardown = null;
+    const plugin = {
+        id: PLUGIN_ID,
+        name: "AIScast",
+        description: "Show nearby traffic without an AIS receiver and share your AIS data with the world.",
+        schema: {
+            type: "object",
+            properties: {
+                share: {
+                    type: "object",
+                    title: "Share",
+                    properties: {
+                        targets: {
+                            type: "boolean",
+                            title: "Other vessels (NMEA 0183 !AIVDM and NMEA 2000 AIS)",
+                            default: true,
+                        },
+                        ownShip: {
+                            type: "boolean",
+                            title: "Own ship (!AIVDO)",
+                            default: true,
+                        },
+                    },
+                },
+                receive: {
+                    type: "object",
+                    title: "Receive",
+                    properties: {
+                        mode: {
+                            type: "string",
+                            title: "Show traffic from aiscast",
+                            enum: ["off", "auto", "always"],
+                            enumNames: [
+                                "Off",
+                                "Auto (when no local receiver available)",
+                                "Always (fills in beyond local VHF range)",
+                            ],
+                            default: "auto",
+                        },
+                        radiusNm: {
+                            type: "number",
+                            title: "Radius around the vessel (nautical miles)",
+                            default: 50,
+                            minimum: 5,
+                            maximum: 200,
+                        },
+                    },
+                },
+                advanced: {
+                    type: "object",
+                    title: "Advanced",
+                    properties: {
+                        server: {
+                            type: "string",
+                            title: "Server",
+                            default: DEFAULT_SERVER,
+                        },
+                        token: {
+                            type: "string",
+                            title: "Access token (optional)",
+                            description: "Leave empty: the plugin creates a keypair on first start and requests its own personal token. Paste a token from the aiscast operator to publish with a named station and higher limits.",
+                        },
+                    },
+                },
+            },
+        },
+        uiSchema: {
+            "ui:order": ["share", "receive", "advanced"],
+            advanced: { token: { "ui:widget": "password" } },
+        },
+        start(config) {
+            const gen = ++generation;
+            startAsync(config, gen).catch((err) => {
+                app.setPluginError(`start failed: ${err.message}`);
+            });
+        },
+        async stop() {
+            generation++;
+            const t = teardown;
+            teardown = null;
+            await t?.();
+        },
+    };
+    async function startAsync(config, gen) {
+        const server = (config.advanced?.server ||
+            config.server ||
+            DEFAULT_SERVER).replace(/\/+$/, "");
+        const configuredToken = config.advanced?.token || config.token;
+        const wsBase = server.replace(/^http/, "ws");
+        const shareTargets = config.share?.targets ?? true;
+        const shareOwn = config.share?.ownShip ?? true;
+        const mode = config.receive?.mode ?? "auto";
+        const radiusNm = Math.min(200, Math.max(5, config.receive?.radiusNm ?? 50));
+        const dir = app.getDataDirPath();
+        const log = (msg) => app.debug(msg);
+        const live = () => gen === generation;
+        const identity = await loadIdentity(dir);
+        if (!live())
+            return;
+        let token = null;
+        let publishRefused = false;
+        const selfSource = `v1:ed25519:${identity.pubkey}`;
+        const refreshToken = async () => {
+            if (configuredToken) {
+                token = {
+                    token: configuredToken,
+                    exp: Infinity,
+                    pubkey: identity.pubkey,
+                    server,
+                };
+                return;
+            }
+            try {
+                token = await loadToken(dir, server, identity.pubkey);
+            }
+            catch (err) {
+                token = null;
+                app.setPluginError(`No token: ${err.message}. Receiving only; nothing is shared.`);
+            }
+        };
+        await refreshToken();
+        if (!live())
+            return;
+        // Token in a header, not the URL, so it stays out of proxy and server logs.
+        const l = new Link(() => `${wsBase}/v1/stream`, () => token ? { Authorization: `Bearer ${token.token}` } : {}, log);
+        const up = new Uplink(l, dir, log);
+        const down = new Downlink(app, l, {
+            mode,
+            radiusNm,
+            source: `${PLUGIN_ID}.net`,
+            selfSource,
+            onReceived: (s) => up.noteReceived(s),
+        }, log);
+        const canShare = () => token !== null && !publishRefused && (shareTargets || shareOwn);
+        up.enabled = canShare();
+        l.on("open", () => {
+            publishRefused = false;
+            up.enabled = canShare();
+        });
+        l.on("error", (message) => {
+            if (/token/i.test(message) && !/publish/.test(message)) {
+                app.setPluginError(`aiscast refused the token: ${message}`);
+                if (!configuredToken) {
+                    const refused = token?.token;
+                    // A fresh token reconnects at once; the same token again waits out the refusal backoff.
+                    forgetToken(dir)
+                        .then(refreshToken)
+                        .then(() => {
+                        up.enabled = canShare();
+                        if (token && token.token !== refused)
+                            l.reconnect();
+                    })
+                        .catch((err) => log(`token refresh: ${err.message}`));
+                }
+            }
+            else if (/publish/.test(message)) {
+                publishRefused = true;
+                up.enabled = false;
+                app.setPluginError(`aiscast refused publishing: ${message}`);
+            }
+            else if (/bbox/.test(message)) {
+                app.setPluginError(`aiscast refused the subscription: ${message} (reduce the radius)`);
+            }
+            else {
+                log(`aiscast: ${message}`);
+            }
+        });
+        await up.start();
+        if (!live()) {
+            await up.stop();
+            return;
+        }
+        down.start();
+        l.start();
+        const onSentence = (sentence, source) => {
+            if (typeof sentence !== "string" || !isAis(sentence))
+                return;
+            const own = isOwnShip(sentence);
+            if (!own)
+                down.localHeard();
+            if (own ? shareOwn : shareTargets)
+                up.hear(sentence, Date.now(), source);
+        };
+        const onNmea = (sentence) => onSentence(sentence);
+        const onN2k = (msg) => {
+            const m = msg;
+            if (!m || typeof m.pgn !== "number")
+                return;
+            try {
+                onSentence(n2kToSentence(app, m), "n2k");
+            }
+            catch (err) {
+                log(`N2K PGN ${m.pgn}: ${err.message}`);
+            }
+        };
+        events.on("nmea0183", onNmea);
+        events.on("N2KAnalyzerOut", onN2k);
+        let lastSent = 0;
+        let lastAt = Date.now();
+        const timers = [
+            setInterval(() => {
+                const now = Date.now();
+                const perMin = Math.round(((up.stats.sent - lastSent) * 60_000) / (now - lastAt));
+                lastSent = up.stats.sent;
+                lastAt = now;
+                const key = identity.pubkey.slice(0, 8);
+                const upText = up.enabled
+                    ? `↑ ${perMin}/min (queue ${up.stats.queued})`
+                    : "↑ off";
+                const downText = mode === "off"
+                    ? "↓ off"
+                    : down.stats.subscribed
+                        ? `↓ ${down.stats.targets} targets`
+                        : "↓ idle";
+                const linkText = l.open
+                    ? "connected"
+                    : l.lastRefusal
+                        ? `refused: ${l.lastRefusal}`
+                        : "reconnecting";
+                app.setPluginStatus(`key ${key}…  ${upText}  ${downText}  ${linkText}`);
+            }, STATUS_EVERY),
+            setInterval(() => {
+                const before = token?.token;
+                refreshToken()
+                    .then(() => {
+                    up.enabled = canShare();
+                    if (token?.token !== before)
+                        l.reconnect();
+                })
+                    .catch((err) => log(`token refresh: ${err.message}`));
+            }, TOKEN_CHECK_EVERY),
+        ];
+        teardown = async () => {
+            for (const t of timers)
+                clearInterval(t);
+            events.removeListener("nmea0183", onNmea);
+            events.removeListener("N2KAnalyzerOut", onN2k);
+            down.stop();
+            await up.stop();
+            l.stop();
+        };
+        if (!live()) {
+            const t = teardown;
+            teardown = null;
+            await t();
+        }
+    }
+    return plugin;
+}
+//# sourceMappingURL=index.js.map