signalk-garmin-keypad-plugin 1.0.2

package/.github/workflows/publish.yml

@@ -0,0 +1,42 @@
+name: Publish to npm
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 18
+          registry-url: https://registry.npmjs.org
+
+      - name: Set version from release tag
+        run: npm version "${GITHUB_REF_NAME#v}" --no-git-tag-version
+        env:
+          GITHUB_REF_NAME: ${{ github.event.release.tag_name }}
+
+      - run: npm ci
+      - run: cd webapp && npm ci
+      - run: npm run build
+      - run: npm test
+
+      - run: npm publish
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+      - name: Commit version bump
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add package.json
+          git commit -m "v${GITHUB_REF_NAME#v}"
+          git push origin HEAD:main
+        env:
+          GITHUB_REF_NAME: ${{ github.event.release.tag_name }}

package/README.md

@@ -0,0 +1,69 @@
+# signalk-garmin-keypad-plugin
+
+Signal K server plugin that acts as a Garmin GNX Keypad on NMEA 2000, allowing control of GNX instrument displays via a web UI or REST API.
+
+![Webapp demo](resources/demo.png)
+
+## Features
+
+- **Preset selection** (1-4) — short press to recall, long press to save
+- **Page navigation** — up/down on the active display
+- **Display selection** — cycle between GNX displays in the group
+- **Power control** — sleep/wake
+- **Auto-discovery** — group ID, display count, keypad fingerprint, and per-property counters are all discovered automatically from bus traffic
+- **Embeddable webapp** — dark-themed UI matching the physical keypad, embedded in the Signal K admin UI via Module Federation
+
+## Protocol
+
+Sends Garmin proprietary NMEA 2000 messages:
+
+- **PGN 61184** — single-frame button events (preset select/save, page navigation)
+- **PGN 126720** — fast-packet property commands (display selection, sleep/wake)
+
+Property commands use a per-property sequence counter and a keypad fingerprint that must match what the displays have stored. On first use, the plugin sends a command that the display rejects (NACK), discovers the correct counter and fingerprint from the rejection, then retries with corrected values.
+
+## Prerequisites
+
+- Signal K server with an NMEA 2000 gateway (e.g. Actisense NGT-1, Yacht Devices YDWG-02)
+- One or more Garmin GNX displays configured in a group
+
+> **Note:** The displays may need to have been grouped with a real Garmin GNX Keypad at least once before this plugin can control them. The group binding token and fingerprint are persisted in display NVM during initial pairing — without a prior pairing, these values may not exist for the plugin to discover. This is speculative and has not been confirmed.
+
+## Configuration
+
+| Option | Description | Default |
+|---|---|---|
+| Source Address | NMEA 2000 source address for the keypad | 0 |
+| GNX Group ID | 4-byte group binding token (8 hex digits). Leave blank to auto-discover. | auto |
+| Display Count | Number of displays in the group. Set to 0 to auto-discover. | 0 |
+| Keypad Fingerprint | 2-byte keypad fingerprint (4 hex digits). Leave blank to auto-discover. | auto |
+
+## REST API
+
+All endpoints at `/plugins/signalk-garmin-keypad/`:
+
+| Method | Path | Body |
+|---|---|---|
+| GET | `/state` | — |
+| POST | `/preset/select` | `{ "index": 0-3 }` |
+| POST | `/preset/save` | `{ "index": 0-3 }` |
+| POST | `/page` | `{ "direction": "next" \| "previous" }` |
+| POST | `/display/cycle` | `{ "direction": "up" \| "down" }` |
+| POST | `/power` | `{ "action": "sleep" \| "wake" }` |
+
+## Development
+
+```sh
+npm install
+npm run build:plugin   # compile TypeScript
+cd webapp && npm install && npm run build  # build React webapp
+npm test               # run tests
+```
+
+## Disclaimer
+
+This project is an independent demo and is not affiliated with, endorsed by, or connected to Garmin or its subsidiaries. "Garmin" and "GNX" are trademarks of Garmin. Use at your own risk. The authors assume no liability for any damage to equipment or loss of functionality resulting from the use of this software.
+
+## License
+
+Apache-2.0

package/dist/index.d.ts

@@ -0,0 +1,45 @@
+interface PluginOptions {
+    sourceAddress: number;
+    groupId?: string;
+    displayCount?: number;
+    fingerprint?: string;
+}
+export default function (app: any): {
+    id: string;
+    name: string;
+    description: string;
+    schema: {
+        type: "object";
+        title: string;
+        properties: {
+            sourceAddress: {
+                type: "number";
+                title: string;
+                description: string;
+                default: number;
+            };
+            groupId: {
+                type: "string";
+                title: string;
+                description: string;
+                default: string;
+            };
+            displayCount: {
+                type: "number";
+                title: string;
+                description: string;
+                default: number;
+            };
+            fingerprint: {
+                type: "string";
+                title: string;
+                description: string;
+                default: string;
+            };
+        };
+    };
+    start: (props: PluginOptions) => void;
+    stop: () => void;
+    registerWithRouter: (router: any) => void;
+};
+export {};

package/dist/index.js

@@ -0,0 +1,395 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const protocol_1 = require("./protocol");
+const n2k_1 = require("./n2k");
+const pgnDefinitions = require('./pgns');
+function default_1(app) {
+    const debug = (...args) => app.debug(...args);
+    let options = { sourceAddress: protocol_1.DEFAULT_SRC };
+    let sleeping = false;
+    let displayCount = 0;
+    let activeDisplay = 0;
+    let n2kDiscoveryListener = null;
+    let propertyListener = null;
+    let rawInputListener = null;
+    let retryTimers = [];
+    const displayAddresses = new Set();
+    const syncedProperties = new Set();
+    function src() {
+        var _a;
+        return (_a = options.sourceAddress) !== null && _a !== void 0 ? _a : protocol_1.DEFAULT_SRC;
+    }
+    function effectiveDisplayCount() {
+        return displayCount > 0 ? displayCount : displayAddresses.size;
+    }
+    function parsePayload(raw) {
+        if (!raw)
+            return null;
+        if (Buffer.isBuffer(raw))
+            return raw;
+        if (typeof raw === "string" && raw.includes(" ")) {
+            return Buffer.from(raw.split(" ").map((b) => parseInt(b, 16)));
+        }
+        if (typeof raw === "string") {
+            return Buffer.from(raw, "hex");
+        }
+        return null;
+    }
+    function emit(pgn) {
+        debug("Sending PGN %d: %j", pgn.pgn, pgn);
+        app.emit("nmea2000JsonOut", pgn);
+    }
+    // Send a property command with lazy discovery retry.
+    // On first use of each property, the display will NACK with stored
+    // counter/fingerprint. rawInputHandler syncs from the NACK, then
+    // the retry (250ms later) sends with corrected values.
+    function emitWithRetry(buildFn, property) {
+        emit(buildFn());
+        if (!syncedProperties.has(property)) {
+            const timer = setTimeout(() => {
+                debug("Retry %s after discovery sync", property);
+                emit(buildFn());
+            }, 250);
+            retryTimers.push(timer);
+        }
+    }
+    const plugin = {
+        id: protocol_1.PLUGIN_ID,
+        name: "Garmin GNX Keypad",
+        description: "Garmin GNX Keypad on NMEA 2000 to control GNX instrument displays",
+        schema: {
+            type: "object",
+            title: "Garmin GNX Keypad",
+            properties: {
+                sourceAddress: {
+                    type: "number",
+                    title: "Source Address",
+                    description: "NMEA 2000 source address for the keypad (note: the CAN gateway may override this)",
+                    default: 0,
+                },
+                groupId: {
+                    type: "string",
+                    title: "GNX Group ID (optional)",
+                    description: 'Manual override for the 4-byte GNX group binding token (8 hex digits, e.g. "80d99efc"). ' +
+                        "Leave blank to auto-discover from the first heartbeat or property message on the bus. " +
+                        "Find it in bytes 10-13 of any PGN 126720 0xe5/0xe7 message on your GNX bus.",
+                    default: "",
+                },
+                displayCount: {
+                    type: "number",
+                    title: "Display Count (optional)",
+                    description: "Number of GNX displays in the group. Set to 0 to auto-discover from bus traffic. " +
+                        "Set manually if auto-discovery fails (displays only broadcast count during startup).",
+                    default: 0,
+                },
+                fingerprint: {
+                    type: "string",
+                    title: "Keypad Fingerprint (optional)",
+                    description: 'Manual override for the 2-byte keypad fingerprint (4 hex digits, e.g. "f9a9"). ' +
+                        "Leave blank to auto-discover from the first property response on the bus. " +
+                        "Displays reject property commands from a fingerprint that doesn't match their stored value.",
+                    default: "",
+                },
+            },
+        },
+        start: function (props) {
+            var _a, _b, _c;
+            options = {
+                sourceAddress: (_a = props.sourceAddress) !== null && _a !== void 0 ? _a : protocol_1.DEFAULT_SRC,
+            };
+            sleeping = false;
+            displayCount = 0;
+            activeDisplay = 0;
+            retryTimers = [];
+            displayAddresses.clear();
+            syncedProperties.clear();
+            (0, n2k_1.resetCounters)();
+            app.emitPropertyValue("canboat-custom-pgns", pgnDefinitions);
+            debug("Registered custom PGN definitions");
+            if (props.displayCount && props.displayCount > 0) {
+                displayCount = props.displayCount;
+                debug("Display count set from config: %d", displayCount);
+            }
+            let fingerprintDiscovered = false;
+            const manualFingerprintHex = (_b = props.fingerprint) === null || _b === void 0 ? void 0 : _b.trim();
+            if (manualFingerprintHex && manualFingerprintHex.length === 4) {
+                const b1 = parseInt(manualFingerprintHex.slice(0, 2), 16);
+                const b2 = parseInt(manualFingerprintHex.slice(2, 4), 16);
+                if (!isNaN(b1) && !isNaN(b2)) {
+                    (0, n2k_1.setFingerprint)([b1, b2]);
+                    fingerprintDiscovered = true;
+                    debug("Keypad fingerprint set from config: %s", manualFingerprintHex);
+                }
+            }
+            const manualGroupId = (_c = props.groupId) === null || _c === void 0 ? void 0 : _c.trim();
+            let groupIdDiscovered = false;
+            if (manualGroupId) {
+                try {
+                    (0, n2k_1.setGroupId)((0, protocol_1.parseGroupId)(manualGroupId));
+                    groupIdDiscovered = true;
+                    debug("Group ID set from config: %s", manualGroupId);
+                }
+                catch (err) {
+                    debug("Invalid groupId in config, will auto-discover: %s", err);
+                }
+            }
+            // Read raw actisense input BEFORE canboatjs parsing to get full trailing
+            // bytes (fingerprint + counter) that canboatjs truncates from the Payload.
+            const rawInputHandler = (msg) => {
+                if (typeof msg !== "string")
+                    return;
+                const parts = msg.split(",");
+                if (parts.length < 9)
+                    return;
+                if (parseInt(parts[2]) !== protocol_1.PGN_FAST)
+                    return;
+                const msgSrc = parseInt(parts[3]);
+                if (!displayAddresses.has(msgSrc))
+                    return;
+                if (parts[6] !== "e5" || parts[8] !== "e5")
+                    return;
+                if (parseInt(parts[5]) < 40)
+                    return;
+                const dataBytes = parts.slice(6).map((h) => parseInt(h, 16));
+                const payload = Buffer.from(dataBytes.slice(3));
+                if (payload.length < 20)
+                    return;
+                const strLen = payload[13];
+                if (payload.length < 14 + strLen)
+                    return;
+                const propName = payload.toString("ascii", 14, 14 + strLen - 1);
+                const valueOffset = 14 + strLen + 3;
+                if (valueOffset >= payload.length)
+                    return;
+                const trailingStart = valueOffset + 1;
+                if (payload.length < trailingStart + 7)
+                    return;
+                const t3 = payload[trailingStart + 3];
+                const t4 = payload[trailingStart + 4];
+                const t5 = payload[trailingStart + 5];
+                const t6 = payload[trailingStart + 6];
+                const storedSeq = (0, n2k_1.decodeCounter)(t5, t6);
+                (0, n2k_1.ensureCounterAbove)(propName, storedSeq);
+                syncedProperties.add(propName);
+                debug("Raw counter sync: %s src=%d seq=%d", propName, msgSrc, storedSeq);
+                if (!fingerprintDiscovered && (t3 !== 0 || t4 !== 0)) {
+                    fingerprintDiscovered = true;
+                    (0, n2k_1.setFingerprint)([t3, t4]);
+                    debug("Fingerprint auto-discovered (raw): %s", t3.toString(16).padStart(2, "0") + t4.toString(16).padStart(2, "0"));
+                }
+            };
+            app.on("canboatjs:rawoutput", rawInputHandler);
+            rawInputListener = rawInputHandler;
+            const discoveryHandler = (msg) => {
+                if (msg.pgn !== protocol_1.PGN_FAST)
+                    return;
+                const fields = msg.fields;
+                const mfr = fields === null || fields === void 0 ? void 0 : fields["Manufacturer Code"];
+                if (mfr !== 229 && mfr !== "Garmin")
+                    return;
+                const cmd = fields === null || fields === void 0 ? void 0 : fields["Command"];
+                if (cmd !== 0xe5 && cmd !== 0xe7)
+                    return;
+                const payload = parsePayload(fields === null || fields === void 0 ? void 0 : fields["Payload"]);
+                if (!groupIdDiscovered && payload) {
+                    const groupId = (0, n2k_1.extractGroupIdFromPayload)(payload);
+                    if (groupId) {
+                        groupIdDiscovered = true;
+                        (0, n2k_1.setGroupId)(groupId);
+                        const hex = groupId.toString("hex");
+                        debug("Group ID auto-discovered: %s", hex);
+                        app.setPluginStatus(`Running — group ${hex}`);
+                    }
+                }
+                // Heartbeat payload[13]: 0x01 = display, 0x00 = keypad
+                if (cmd === 0xe7 && payload && payload.length >= 14 && payload[13] === 0x01) {
+                    if (!displayAddresses.has(msg.src)) {
+                        displayAddresses.add(msg.src);
+                        debug("Display discovered at src=%d (total: %d)", msg.src, displayAddresses.size);
+                    }
+                }
+            };
+            app.on("N2KAnalyzerOut", discoveryHandler);
+            n2kDiscoveryListener = discoveryHandler;
+            const propHandler = (msg) => {
+                if (msg.pgn !== protocol_1.PGN_FAST)
+                    return;
+                const fields = msg.fields;
+                if ((fields === null || fields === void 0 ? void 0 : fields["Manufacturer Code"]) !== 229 && (fields === null || fields === void 0 ? void 0 : fields["Manufacturer Code"]) !== "Garmin")
+                    return;
+                if ((fields === null || fields === void 0 ? void 0 : fields["Command"]) !== 0xe5)
+                    return;
+                const payload = parsePayload(fields === null || fields === void 0 ? void 0 : fields["Payload"]);
+                if (!payload || payload.length < 20)
+                    return;
+                const strLen = payload[13];
+                if (payload.length < 14 + strLen)
+                    return;
+                const propName = payload.toString("ascii", 14, 14 + strLen - 1);
+                const valueOffset = 14 + strLen + 3;
+                if (valueOffset >= payload.length)
+                    return;
+                const value = payload[valueOffset];
+                // Extract stored counter and fingerprint from trailing bytes.
+                // Trailing 7 bytes: [2e T1 T2 T3(fp1) T4(fp2) T5 T6] — T3/T4 = fingerprint, T5/T6 = counter.
+                if (payload.length >= valueOffset + 1 + 7) {
+                    const trailingStart = valueOffset + 1;
+                    const t3 = payload[trailingStart + 3];
+                    const t4 = payload[trailingStart + 4];
+                    const t5 = payload[payload.length - 2];
+                    const t6 = payload[payload.length - 1];
+                    const storedSeq = (0, n2k_1.decodeCounter)(t5, t6);
+                    debug("Counter discovery: %s src=%d stored=%d t5=0x%s t6=0x%s", propName, msg.src, storedSeq, t5.toString(16), t6.toString(16));
+                    (0, n2k_1.ensureCounterAbove)(propName, storedSeq);
+                    syncedProperties.add(propName);
+                    if (!fingerprintDiscovered && (t3 !== 0 || t4 !== 0)) {
+                        fingerprintDiscovered = true;
+                        (0, n2k_1.setFingerprint)([t3, t4]);
+                        debug("Fingerprint auto-discovered: %s", t3.toString(16).padStart(2, "0") + t4.toString(16).padStart(2, "0"));
+                    }
+                }
+                if (propName === protocol_1.PROP_DISP_CNT && value > 0 && displayCount === 0) {
+                    displayCount = value;
+                    debug("Display count discovered: %d", displayCount);
+                }
+                if (propName === protocol_1.PROP_DISPLAY) {
+                    activeDisplay = value;
+                    debug("Active display updated: %d", activeDisplay);
+                }
+            };
+            app.on("N2KAnalyzerOut", propHandler);
+            propertyListener = propHandler;
+            app.setPluginStatus("Started");
+            debug("Plugin started, src=%d", src());
+        },
+        stop: function () {
+            retryTimers.forEach((t) => clearTimeout(t));
+            retryTimers = [];
+            if (n2kDiscoveryListener) {
+                app.removeListener("N2KAnalyzerOut", n2kDiscoveryListener);
+                n2kDiscoveryListener = null;
+            }
+            if (propertyListener) {
+                app.removeListener("N2KAnalyzerOut", propertyListener);
+                propertyListener = null;
+            }
+            if (rawInputListener) {
+                app.removeListener("canboatjs:rawoutput", rawInputListener);
+                rawInputListener = null;
+            }
+            displayAddresses.clear();
+            syncedProperties.clear();
+            debug("Plugin stopped");
+        },
+        registerWithRouter: function (router) {
+            router.use((_req, _res, next) => {
+                var _a;
+                if (_req.method === "POST") {
+                    // express.json() may not be available, parse manually if needed
+                    if (!_req.body && ((_a = _req.headers["content-type"]) === null || _a === void 0 ? void 0 : _a.includes("application/json"))) {
+                        let data = "";
+                        _req.on("data", (chunk) => {
+                            data += chunk;
+                        });
+                        _req.on("end", () => {
+                            try {
+                                _req.body = JSON.parse(data);
+                            }
+                            catch (_a) {
+                                _req.body = {};
+                            }
+                            next();
+                        });
+                        return;
+                    }
+                }
+                next();
+            });
+            router.get("/state", (_req, res) => {
+                const state = {
+                    sleeping,
+                    displayCount: effectiveDisplayCount(),
+                    activeDisplay,
+                };
+                res.json(state);
+            });
+            router.post("/preset/select", (req, res) => {
+                var _a;
+                const index = (_a = req.body) === null || _a === void 0 ? void 0 : _a.index;
+                if (typeof index !== "number" || !Number.isInteger(index) || index < 0 || index > 3) {
+                    return res.status(400).json({ error: "index must be an integer 0-3" });
+                }
+                emit((0, n2k_1.buildSelectPreset)(index, src()));
+                res.json({ ok: true });
+            });
+            router.post("/preset/save", (req, res) => {
+                var _a;
+                const index = (_a = req.body) === null || _a === void 0 ? void 0 : _a.index;
+                if (typeof index !== "number" || !Number.isInteger(index) || index < 0 || index > 3) {
+                    return res.status(400).json({ error: "index must be an integer 0-3" });
+                }
+                emit((0, n2k_1.buildSavePreset)(index, src()));
+                res.json({ ok: true });
+            });
+            router.post("/page", (req, res) => {
+                var _a;
+                const direction = (_a = req.body) === null || _a === void 0 ? void 0 : _a.direction;
+                if (direction !== "next" && direction !== "previous") {
+                    return res.status(400).json({ error: 'direction must be "next" or "previous"' });
+                }
+                emit((0, n2k_1.buildPageNav)(direction, src()));
+                res.json({ ok: true });
+            });
+            router.post("/display/select", (req, res) => {
+                var _a;
+                const index = (_a = req.body) === null || _a === void 0 ? void 0 : _a.index;
+                if (typeof index !== "number" || !Number.isInteger(index)) {
+                    return res.status(400).json({ error: "index must be an integer" });
+                }
+                let target = index;
+                const count = effectiveDisplayCount();
+                if (count > 0) {
+                    target = ((index % count) + count) % count;
+                }
+                else if (index < 0) {
+                    target = 0;
+                }
+                emitWithRetry(() => (0, n2k_1.buildDisplaySelect)(target, src()), protocol_1.PROP_DISPLAY);
+                activeDisplay = target;
+                res.json({ ok: true, displayIndex: target });
+            });
+            router.post("/display/cycle", (req, res) => {
+                var _a;
+                const direction = (_a = req.body) === null || _a === void 0 ? void 0 : _a.direction;
+                if (direction !== "up" && direction !== "down") {
+                    return res.status(400).json({ error: 'direction must be "up" or "down"' });
+                }
+                let next;
+                const count = effectiveDisplayCount();
+                if (count > 0) {
+                    const delta = direction === "down" ? 1 : -1;
+                    next = (((activeDisplay + delta) % count) + count) % count;
+                }
+                else {
+                    next = direction === "down" ? activeDisplay + 1 : Math.max(0, activeDisplay - 1);
+                }
+                emitWithRetry(() => (0, n2k_1.buildDisplaySelect)(next, src()), protocol_1.PROP_DISPLAY);
+                activeDisplay = next;
+                res.json({ ok: true, displayIndex: next });
+            });
+            router.post("/power", (req, res) => {
+                var _a;
+                const action = (_a = req.body) === null || _a === void 0 ? void 0 : _a.action;
+                if (action !== "sleep" && action !== "wake") {
+                    return res.status(400).json({ error: 'action must be "sleep" or "wake"' });
+                }
+                const goToSleep = action === "sleep";
+                emitWithRetry(() => (0, n2k_1.buildSleepWake)(goToSleep, src()), protocol_1.PROP_SLEEP);
+                sleeping = goToSleep;
+                res.json({ ok: true });
+            });
+        },
+    };
+    return plugin;
+}
+exports.default = default_1;

package/dist/n2k.d.ts

@@ -0,0 +1,19 @@
+/// <reference types="node" />
+export interface PgnMessage {
+    pgn: number;
+    dst: number;
+    prio: number;
+    src: number;
+    [key: string]: any;
+}
+export declare function setGroupId(groupId: Buffer): void;
+export declare function extractGroupIdFromPayload(payload: Buffer | null): Buffer | null;
+export declare function buildSelectPreset(index: number, src?: number): PgnMessage;
+export declare function buildSavePreset(index: number, src?: number): PgnMessage;
+export declare function buildPageNav(direction: 'next' | 'previous', src?: number): PgnMessage;
+export declare function resetCounters(): void;
+export declare function decodeCounter(t5: number, t6: number): number;
+export declare function ensureCounterAbove(property: string, minSeq: number): void;
+export declare function setFingerprint(fp: [number, number]): void;
+export declare function buildSleepWake(sleep: boolean, src?: number): PgnMessage;
+export declare function buildDisplaySelect(index: number, src?: number): PgnMessage;