@aurora-blue/signalk-connector 0.2.0-dev.20

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aurora Blue contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,122 @@
+# Aurora Blue ABOARD Connector
+
+Status: Adaptive protocol 1.1 connector development
+
+The standalone status UI follows the central [Web UI CI](../aurora-blue-documentation/docs/WEB_UI_CI.md). Its packaged `public/ci-tokens.css` reproduces the server's versioned typography, semantic palette and shape contract. The live specimen ships with the server at `/system/web-ui-ci`; the connector requires no server connection to render its own status interface.
+
+The Aurora Blue ABOARD Connector is the lightweight Signal K edge gateway between a Signal K server and an Aurora Blue ABOARD LOCAL, CONNECT or CLOUD target. The public npm package is `@aurora-blue/signalk-connector`. Its runtime plugin ID remains `aurora-blue-signalk-connector`, preserving the configuration and data-directory identity used by Signal K.
+
+## Implemented responsibilities
+
+- Run as a native TypeScript-based Signal K Node server plugin
+- Subscribe to the protocol 1.1 own-vessel navigation, depth, wind, environment, electrical, propulsion, and tank catalog
+- Collect selected AIS target motion and identity data under the original Signal K vessel context
+- Preserve Signal K source references and source timestamps
+- Exchange a short-lived pairing code for a restricted device identity and token
+- Assign one persistent, monotonically increasing sequence per paired device
+- Evaluate an experimental local anchor alarm before historical telemetry reduction
+- Reduce historical telemetry through path-specific change thresholds and maximum heartbeats
+- Persist unacknowledged events in a byte-bounded append-only segmented journal
+- Size the journal from filesystem capacity, free-space reserve, and measured record size
+- Reduce AIS admission progressively as offline-buffer pressure rises
+- Preserve the exact pending batch across retries and restarts
+- Compress larger ingest batches with HTTP gzip content encoding
+- Retry unavailable transfers with bounded exponential backoff and jitter
+- Remove events only after a valid durable server acknowledgement
+- Report pairing, buffer, acknowledgement, transfer, and dropped-event state through Signal K plugin status
+- Apply server-directed active, standby, and disabled operating modes without deriving them from primary-device selection
+- Provide an independent status webapp for Signal K versions that do not render the native plugin status reliably
+- Report the running connector version on authenticated ingest and control requests so updates appear in device administration without pairing again
+- Follow the viewing browser's system light/dark preference, with bundled Ubuntu fonts and the shared Archipelago background available offline
+- Never send control commands to Signal K or the NMEA network
+
+## Runtime
+
+- Node.js 20 or newer
+- Signal K Node server plugin API
+- No native runtime dependencies
+
+The initial development and CI baseline uses Node.js 22. Persistent state is stored below the plugin data directory supplied by Signal K. The directory is restricted to the runtime user and metadata and journal files use mode `0600` on POSIX systems.
+
+## Configuration
+
+Configure the plugin in the Signal K administration interface:
+
+1. Enter the base URL of the Aurora Blue target.
+2. Enter the short-lived pairing code created for the boat in Aurora Blue administration.
+3. Keep insecure HTTP disabled except for an isolated local development environment.
+4. Save and enable the plugin.
+
+Select Aurora Blue ABOARD Connector Status under Signal K Webapps for the cross-version runtime view. The page refreshes every five seconds and reads a plugin-local endpoint governed by the Signal K server's access controls. The response omits device identity and credentials, and the page does not send data to another host.
+
+The connector exchanges the pairing code once and clears it from the Signal K plugin configuration after successful pairing. The returned device token is stored only in the protected connector state file and is never written to logs.
+
+The default configuration sends up to 250 events per batch, waits up to five seconds to combine normal telemetry, samples selected own-vessel Signal K paths every second, samples selected AIS paths every five seconds, and enables the preliminary underway change-or-heartbeat profile. AIS can be disabled independently. The `auto` storage profile selects a constrained, standard, or extended byte budget from filesystem capacity while preserving a free-space reserve. Its effective event limit is derived from measured journal bytes per event instead of a fixed 10,000-event default. Protocol 1.1 permits no more than 500 events per batch, and the server continues to accept exact protocol 1.0 backlog batches during upgrades.
+
+The optional anchor alarm is an experimental development scaffold. When enabled, position is requested every 250 milliseconds and every received position reaches the safety engine before telemetry reduction. The alarm publishes a local Signal K notification and detects stale position input without requiring the Aurora Blue target. It must not yet be used as the sole safety device.
+
+The paired Aurora Blue target controls the device operating mode. Active mode collects and transfers normal telemetry. Standby stops admitting new historical telemetry, drains existing backlog, and keeps only the local position input required by an enabled anchor alarm. Disabled mode preserves the backlog but stops collection, transfer, and local safety subscriptions. Standby and disabled connectors continue a low-rate authenticated configuration heartbeat so an administrator can reactivate them remotely.
+
+## Development
+
+Install locked dependencies and run the same checks used by GitLab CI:
+
+```bash
+npm ci
+npm run check
+```
+
+Build an installable plugin package:
+
+```bash
+npm pack
+```
+
+Create a bounded recording that is pseudonymized before it reaches disk:
+
+```bash
+npm run capture:signalk -- \
+  --base-url http://127.0.0.1:3000 \
+  --output /private/tmp/sample.aurora-blue-recording.jsonl \
+  --duration-seconds 180 \
+  --sample-period-ms 1000
+```
+
+Replay a reviewed recording through normalization, adaptive reduction, journal recovery, compression measurement, and offline-buffer projections:
+
+```bash
+npm run replay:signalk -- \
+  --input /private/tmp/sample.aurora-blue-recording.jsonl \
+  --storage-profile auto \
+  --filesystem-total-megabytes 4096 \
+  --filesystem-free-megabytes 2048 \
+  --scenario-hours 6,12,24
+```
+
+Run the deterministic dense-AIS outage simulation and the packaged-runtime checks for Linux x64, ARM64, and ARMv7:
+
+```bash
+npm run simulate:offline
+npm run verify:package
+npm run verify:platforms
+```
+
+The platform check builds once, then executes the compiled production and test artifacts in the official multi-architecture Node.js 22 image. It does not require native connector dependencies because the runtime package has none.
+
+Capture accepts a Signal K base URL supplied at runtime but never stores that address. It replaces vessel identifiers, identity strings, source references, timestamps, and positions before serialization. It also drops distant position outliers that could reveal the original position offset. Recording files are ignored by Git and must not be committed without an explicit privacy audit.
+
+See [Development and Operations](docs/DEVELOPMENT.md) for the state model, local installation workflow, configuration fields, and failure behavior.
+
+## Project boundary
+
+This connector is licensed under MIT. See LICENSE and THIRD_PARTY_NOTICES.md. This license does not change the licensing of other Aurora Blue ABOARD repositories.
+
+## Installation and updates
+
+The public package name is `@aurora-blue/signalk-connector`. Once its first release has been published and indexed, search for that name in the Signal K App Store, install it, restart Signal K if requested, then configure and enable the plugin. Future updates use the same App Store. The bundled status page supports English, German, French and Spanish.
+
+When migrating from the unscoped development package `aurora-blue-signalk-connector`, back up Signal K configuration and plugin data first. Stop Signal K and replace only the installed package; preserve the existing plugin configuration and data directory. Do not install both package names together: they deliberately share one runtime plugin ID. Restart and verify pairing, buffered records and status before resuming normal use.
+
+Release maintainers use the protected GitLab pipeline described in the central Connector publication document. Package preparation does not itself publish a release or guarantee App Store indexing.
+
+The authoritative architecture and protocol documentation is maintained in the separate `aurora-blue-documentation` repository.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,11 @@
+# Third-party notices
+
+Bundled Ubuntu font files in `public/fonts` retain the Ubuntu Font Licence
+in `public/fonts/LICENSE`. That license is not replaced by the Connector MIT
+license. The application has no third-party runtime JavaScript dependencies.
+Development dependencies are excluded from the installed package.
+
+The MIT release covers this Connector and the Aurora Blue-owned UI files
+bundled with it. It does not change the licenses of separate Aurora Blue
+repositories or grant trademark rights to represent an unofficial fork as
+an official Aurora Blue ABOARD release.

package/VERSION

@@ -0,0 +1 @@
+0.2.0-dev.20

package/dist/src/backoff.d.ts

@@ -0,0 +1 @@
+export declare const retryDelay: (attempt: number, minimumMs: number, maximumMs: number, random?: () => number) => number;

package/dist/src/backoff.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.retryDelay = void 0;
+const retryDelay = (attempt, minimumMs, maximumMs, random = Math.random) => {
+    const exponential = Math.min(maximumMs, minimumMs * 2 ** Math.max(0, attempt - 1));
+    const jitter = 0.5 + random() * 0.5;
+    return Math.max(minimumMs, Math.floor(exponential * jitter));
+};
+exports.retryDelay = retryDelay;

package/dist/src/config.d.ts

@@ -0,0 +1,192 @@
+import type { AnchorAlarmConfig } from "./safety/anchor-alarm";
+import type { StorageProfile } from "./storage-budget";
+import type { OperatingProfile } from "./telemetry-reducer";
+export interface ConnectorConfig {
+    targetUrl: string;
+    deviceName: string;
+    pairingCode?: string;
+    allowInsecureHttp: boolean;
+    batchSize: number;
+    flushIntervalMs: number;
+    samplePeriodMs: number;
+    aisEnabled: boolean;
+    aisSamplePeriodMs: number;
+    safetySamplePeriodMs: number;
+    requestTimeoutMs: number;
+    retryMinimumMs: number;
+    retryMaximumMs: number;
+    storageProfile: StorageProfile;
+    maxBufferEvents: number;
+    maxBufferBytes: number;
+    storageReserveBytes: number;
+    storageMaximumFraction: number;
+    bufferSegmentBytes: number;
+    compressionEnabled: boolean;
+    compressionThresholdBytes: number;
+    adaptiveTelemetryEnabled: boolean;
+    operatingProfile: OperatingProfile;
+    anchorAlarm: AnchorAlarmConfig;
+}
+export declare const resolveConfig: (input: object) => ConnectorConfig;
+export declare const pluginSchema: {
+    readonly type: "object";
+    readonly required: readonly ["targetUrl"];
+    readonly properties: {
+        readonly targetUrl: {
+            readonly type: "string";
+            readonly title: "Aurora Blue target URL";
+            readonly description: "Base URL of Aurora Blue Server or Aurora Blue Cloud. [Open connector status](/aurora-blue-signalk-connector/).";
+        };
+        readonly deviceName: {
+            readonly type: "string";
+            readonly title: "Device name";
+            readonly default: "Aurora Blue Signal K";
+        };
+        readonly pairingCode: {
+            readonly type: "string";
+            readonly title: "Pairing code";
+            readonly description: "Short-lived code from Aurora Blue. Cleared after successful pairing.";
+        };
+        readonly allowInsecureHttp: {
+            readonly type: "boolean";
+            readonly title: "Allow insecure HTTP for local development";
+            readonly default: false;
+        };
+        readonly batchSize: {
+            readonly type: "integer";
+            readonly title: "Maximum events per batch";
+            readonly minimum: 1;
+            readonly maximum: 500;
+            readonly default: 250;
+        };
+        readonly samplePeriodMs: {
+            readonly type: "integer";
+            readonly title: "Signal K sample period in milliseconds";
+            readonly minimum: 250;
+            readonly maximum: 60000;
+            readonly default: 1000;
+        };
+        readonly aisEnabled: {
+            readonly type: "boolean";
+            readonly title: "Collect AIS targets";
+            readonly description: "Collect selected dynamic and identity data for other vessels with conservative transfer reduction.";
+            readonly default: true;
+        };
+        readonly aisSamplePeriodMs: {
+            readonly type: "integer";
+            readonly title: "AIS sample period in milliseconds";
+            readonly minimum: 1000;
+            readonly maximum: 120000;
+            readonly default: 5000;
+        };
+        readonly adaptiveTelemetryEnabled: {
+            readonly type: "boolean";
+            readonly title: "Reduce telemetry by change or heartbeat";
+            readonly default: true;
+        };
+        readonly operatingProfile: {
+            readonly type: "string";
+            readonly title: "Telemetry operating profile";
+            readonly enum: readonly ["anchored", "moored", "underway"];
+            readonly default: "underway";
+        };
+        readonly storageProfile: {
+            readonly type: "string";
+            readonly title: "Offline storage profile";
+            readonly description: "Auto selects a capacity class from the filesystem size. Explicit profiles use capacity-oriented limits and custom uses the advanced limits below.";
+            readonly enum: readonly ["auto", "constrained", "standard", "extended", "custom"];
+            readonly enumNames: readonly ["Auto (recommended)", "Constrained flash", "Standard embedded storage", "Extended or external storage", "Custom"];
+            readonly default: "auto";
+        };
+        readonly anchorAlarmEnabled: {
+            readonly type: "boolean";
+            readonly title: "Enable experimental local anchor alarm";
+            readonly description: "Evaluation remains local, but this development version is not approved as a sole safety device.";
+            readonly default: false;
+        };
+        readonly anchorLatitude: {
+            readonly type: "number";
+            readonly title: "Anchor latitude";
+            readonly minimum: -90;
+            readonly maximum: 90;
+        };
+        readonly anchorLongitude: {
+            readonly type: "number";
+            readonly title: "Anchor longitude";
+            readonly minimum: -180;
+            readonly maximum: 180;
+        };
+        readonly anchorRadiusMeters: {
+            readonly type: "integer";
+            readonly title: "Anchor radius in meters";
+            readonly minimum: 5;
+            readonly maximum: 2000;
+            readonly default: 30;
+        };
+        readonly anchorHysteresisMeters: {
+            readonly type: "integer";
+            readonly title: "Anchor clear hysteresis in meters";
+            readonly minimum: 0;
+            readonly maximum: 500;
+            readonly default: 5;
+        };
+        readonly anchorConfirmationSeconds: {
+            readonly type: "integer";
+            readonly title: "Seconds outside radius before alarm";
+            readonly minimum: 0;
+            readonly maximum: 300;
+            readonly default: 10;
+        };
+        readonly anchorStalePositionSeconds: {
+            readonly type: "integer";
+            readonly title: "Seconds without position before alarm";
+            readonly minimum: 5;
+            readonly maximum: 600;
+            readonly default: 30;
+        };
+        readonly maxBufferEvents: {
+            readonly type: "integer";
+            readonly title: "Custom event safety limit";
+            readonly description: "Absolute secondary safety limit for the custom profile. The effective event limit is derived from the byte budget and measured event size.";
+            readonly minimum: 500;
+            readonly maximum: 1000000;
+            readonly default: 1000000;
+        };
+        readonly maxBufferMegabytes: {
+            readonly type: "integer";
+            readonly title: "Custom maximum journal size in megabytes";
+            readonly minimum: 4;
+            readonly maximum: 1024;
+            readonly default: 64;
+        };
+        readonly storageReserveMegabytes: {
+            readonly type: "integer";
+            readonly title: "Custom free-space reserve in megabytes";
+            readonly minimum: 32;
+            readonly maximum: 16384;
+            readonly default: 256;
+        };
+        readonly storageMaximumPercent: {
+            readonly type: "integer";
+            readonly title: "Custom maximum filesystem percentage";
+            readonly minimum: 1;
+            readonly maximum: 50;
+            readonly default: 5;
+        };
+        readonly compressionEnabled: {
+            readonly type: "boolean";
+            readonly title: "Compress larger batches";
+            readonly default: true;
+        };
+    };
+};
+export declare const pluginUiSchema: {
+    readonly targetUrl: {
+        readonly "ui:options": {
+            readonly enableMarkdownInDescription: true;
+        };
+    };
+    readonly pairingCode: {
+        readonly "ui:widget": "password";
+    };
+};