Aurora Blue ABOARD Connector

Status: Adaptive protocol 1.1 connector development

The standalone status UI follows the central Web UI CI. 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 pairing is bound to the configured target URL. Changing that URL requires a new pairing code and pauses collection and transfer until the replacement pairing succeeds. The configuration and status page warn that a successful replacement permanently discards telemetry buffered for the previous server. A failed pairing attempt retains the existing pairing and buffer.

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 connector also subscribes to scalar values below electrical.switches.*, including separate channels on multi-output devices. Switch paths use the instant subscription policy so a periodic retransmission of a cached Signal K value is not mistaken for fresh device evidence. The server may use selected .state leaves for conservative equipment-runtime estimates. A silent or unpowered device stops contributing runtime after a short bounded interval; accurate long-running counters require a qualified device-originated liveness source.

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:

npm ci
npm run check

Build an installable plugin package:

npm pack

Create a bounded recording that is pseudonymized before it reaches disk:

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:

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:

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 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.