signalk-pypilot-newui 1.0.0 → 2.0.0

package/CHANGELOG.md

@@ -1,5 +1,96 @@
 # Changelog
 
+## 2.0.0 — 2026-08-20 — Rev63
+
+**Breaking release addressing feedback from Sean D'Epagnier (pypilot author,
+[#1](https://github.com/Aitonos/signalk-pypilot-newui/issues/1) and
+[#2](https://github.com/Aitonos/signalk-pypilot-newui/issues/2)).**
+
+### Breaking - path standardisation (issue #1)
+
+Every pypilot key now maps 1:1 to `steering.autopilot.pypilot.<key>`
+verbatim. The old `FIXED_MAPPINGS` table with hand-picked renames and
+C -> K / deg -> rad conversions is gone. Signal K infers units cleanly
+enough from the path type, consumers pick their display unit, and we
+surface pypilot's own `meta.units` verbatim.
+
+**If you have KIP widgets or WilhelmSK dashboards wired to 1.0.0 paths,
+rewire them per the table below**:
+
+| Old (1.0.0)                                                       | New (2.0.0)                                              |
+|-------------------------------------------------------------------|----------------------------------------------------------|
+| `steering.autopilot.pypilot.availableModes`                       | `steering.autopilot.pypilot.ap.modes`                    |
+| `steering.autopilot.pypilot.pilot`                                | `steering.autopilot.pypilot.ap.pilot`                    |
+| `steering.autopilot.pypilot.gains.<pilot>.<gain>`                 | `steering.autopilot.pypilot.ap.pilot.<pilot>.<gain>`     |
+| `steering.autopilot.pypilot.servo.controllerTemperature` (K)      | `steering.autopilot.pypilot.servo.controller_temp` (C)   |
+| `steering.autopilot.pypilot.servo.motorTemperature` (K)           | `steering.autopilot.pypilot.servo.motor_temp` (C)        |
+| `steering.autopilot.pypilot.servo.ampHours`                       | `steering.autopilot.pypilot.servo.amp_hours`             |
+| `steering.autopilot.pypilot.calibration.imuHeadingOffset` (rad)   | `steering.autopilot.pypilot.imu.heading_offset` (deg)    |
+| `steering.autopilot.pypilot.calibration.rudderRange` (rad)        | `steering.autopilot.pypilot.rudder.range` (deg)          |
+| `steering.autopilot.pypilot.calibration.rudderOffset`             | `steering.autopilot.pypilot.rudder.offset`               |
+| `steering.autopilot.pypilot.calibration.rudderScale`              | `steering.autopilot.pypilot.rudder.scale`                |
+| `steering.autopilot.pypilot.calibration.rudderNonlinearity`       | `steering.autopilot.pypilot.rudder.nonlinearity`         |
+| `steering.autopilot.pypilot.calibration.state`                    | `steering.autopilot.pypilot.rudder.calibration_state`    |
+| `steering.autopilot.pypilot.tack.state`                           | `steering.autopilot.pypilot.ap.tack.state`               |
+| `steering.autopilot.pypilot.tack.direction`                       | `steering.autopilot.pypilot.ap.tack.direction`           |
+| `steering.autopilot.pypilot.tack.timeout`                         | `steering.autopilot.pypilot.ap.tack.timeout`             |
+| `steering.autopilot.pypilot.errors.imu`                           | `steering.autopilot.pypilot.imu.error`                   |
+| `steering.autopilot.pypilot.warnings.imu`                         | `steering.autopilot.pypilot.imu.warning`                 |
+| `steering.autopilot.pypilot.errors.controller`                    | `steering.autopilot.pypilot.servo.controller`            |
+
+`steering.autopilot.pypilot.profile`, `.profiles`, `.availablePilots`,
+`.version`, `.runtime`, `.servo.voltage`, `.servo.current`,
+`.servo.engaged`, `.servo.flags`, `.servo.controller` are unchanged
+(their pypilot keys already matched the SK-side name).
+
+### Fixed (issue #2) - `pypilot_values` is not one-shot
+
+Sean noted that `pypilot_values` can arrive multiple times, and on
+subsequent deliveries it carries only the newly-appeared keys (typically
+during boot while calibration is still loading). Our code assumed
+one-shot AND replaced `this.catalog` wholesale on each delivery.
+
+- Comment in `pypilot-client.ts` fixed.
+- Catalog is now MERGED, not replaced.
+- `catalog` event carries `{ isDelta, newKeys }` so downstream handlers
+  can register put-handlers only for the new keys and avoid re-emitting
+  meta for paths already published.
+
+### Added - Debug console in Setup
+
+New closed-whitelist SSH endpoint `POST /plugins/*/debug-cmd` accepting
+one of the following presets (nothing arbitrary):
+
+- `logs.pypilot` - last 200 lines of `journalctl -u pypilot`
+- `logs.pypilot_web` - last 200 lines of the web unit
+- `logs.follow` - last 30 s (polled every 3 s from the UI when
+  "Follow logs" is on)
+- `dmesg.tail` - last 100 lines of `dmesg`
+- `top.snapshot` - one-shot `top -bn1`
+- `uptime`, `df`, `pypilot.version`
+- `restart.web` - restart only `pypilot_web` (level 1 of the triad)
+- `reboot.pi` - full `sudo reboot` (level 3 of the triad)
+
+UI in Setup: preset buttons, scrollable output textarea, follow-logs
+toggle (3 s polling), copy-to-clipboard, share-to-anywhere (Web Share
+API), clear.
+
+### Changed - three escalated restart levels in Setup / Emergency
+
+The old single "RESTART pypilot" button becomes a triad, colour-coded
+from green (safest) to red (loudest):
+
+- **1. restart pypilot_web** (~3-5 s) - AP keeps steering.
+- **2. RESTART pypilot** (~10-15 s) - the previous behaviour: AP drops
+  the heading briefly and re-engages after reconnect.
+- **3. reboot Pi** (~35-60 s) - full Raspberry Pi reboot, no AP for
+  almost a minute.
+
+All three go through a shared **helm-manned confirmation modal** that
+states the outage duration and scope in the current UI language and
+asks the operator to confirm someone is at the helm before executing.
+Cancel button, click outside and Escape all decline safely.
+
 ## 1.0.0 — 2026-08-18 — Rev32..Rev62 first public release
 
 The webapp went from a minimum viable control panel to a full-blown touch

package/README.md

@@ -9,6 +9,24 @@ and switches out of the box.
 Runs alongside [`pypilot-autopilot-provider`](https://www.npmjs.com/package/pypilot-autopilot-provider)
 by Panaaj — see [Working alongside pypilot-autopilot-provider](#working-alongside-pypilot-autopilot-provider).
 
+## Upgrading from 1.0.0 to 2.0.0
+
+2.0.0 is a **breaking release** addressing feedback from Sean D'Epagnier
+(pypilot author). Every pypilot key now maps 1:1 to
+`steering.autopilot.pypilot.<key>` verbatim - no more hand-picked renames
+or C -> K / deg -> rad conversions. If you have KIP widgets or WilhelmSK
+dashboards wired to 1.0.0 paths, see the full migration table in
+[`CHANGELOG.md`](./CHANGELOG.md) - most notable examples:
+
+- `.servo.controllerTemperature` (K) -> `.servo.controller_temp` (C)
+- `.calibration.rudderRange` (rad) -> `.rudder.range` (deg)
+- `.gains.<pilot>.<gain>` -> `.ap.pilot.<pilot>.<gain>`
+
+Also new in 2.0.0: three escalated **restart / reboot levels** in
+Setup -> Emergency, all guarded by a helm-manned confirmation modal, and
+a **Debug console** with an SSH-based whitelist of preset diagnostic
+commands (logs, dmesg, top, uptime, df, pypilot version).
+
 ## What it does
 
 **Touch webapp** (mobile / tablet / chart-plotter, dark theme):
@@ -98,13 +116,34 @@ register the same ID and behaviour is undefined). Valid setups:
 
 Absorb mode lives in **Setup → Autopilot Provider (one-socket mode)**.
 
-## Remote `RESTART pypilot`
+## Remote restart / reboot triad + Debug console
 
 When the autopilot process on the TinyPilot gets wedged you don't need to open
 an SSH session by hand. In **Setup → Emergency**, save the TinyPilot's SSH user
-+ password once; the **RESTART pypilot** button then runs
-`sudo systemctl restart pypilot pypilot_web` over SSH and reconnects the local
-socket. Signal K stores plugin configs in plain text under
++ password once. From then on you get three escalated actions, colour-coded
+from safest to loudest, each guarded by a helm-manned confirmation modal that
+asks whether someone is at the helm before executing:
+
+1. **restart pypilot_web** (~3-5 s) - only the web server restarts. The AP
+   core keeps steering. Use when the visor gets stuck but the pilot is fine.
+2. **RESTART pypilot** (~10-15 s) - restarts pypilot core + web. The AP drops
+   the heading briefly and re-engages when it comes back up.
+3. **reboot Pi** (~35-60 s) - full `sudo reboot` of the Raspberry Pi. No
+   autopilot for almost a minute. Last-resort when the box is in a bad state.
+
+Underneath the triad there is a **Debug console** that runs a closed
+whitelist of preset diagnostic commands over the same SSH session:
+`logs pypilot`, `logs pypilot_web`, `dmesg`, `top`, `uptime`, `df`,
+`pypilot --version`. Output goes into a scrollable textarea, a "Follow
+logs" toggle polls `journalctl --since '30 s ago'` every 3 seconds, and
+Copy / Share buttons let you paste the dump straight into a GitHub
+issue or a WhatsApp / email conversation with your friendly rigger.
+
+The endpoint (`POST /plugins/*/debug-cmd`) refuses any command that is
+not in the whitelist, so a leaked JWT cannot be used to run arbitrary
+shell on the TinyPilot.
+
+Signal K stores plugin configs in plain text under
 `~/.signalk/plugin-config-data/` so use credentials that are only valid for
 that isolated TinyPilot.
 
@@ -117,7 +156,8 @@ that isolated TinyPilot.
 | `GET`  | `/plugins/signalk-pypilot-newui/paths`         | Live list of published SK paths with GET / PUT URLs and units |
 | `GET`  | `/plugins/signalk-pypilot-newui/catalog`       | Raw pypilot catalog (all values + metadata) |
 | `PUT`  | `/plugins/signalk-pypilot-newui/raw`           | Send raw `name=value` to pypilot (protected by `allowWrites`) |
-| `POST` | `/plugins/signalk-pypilot-newui/restart-pypilot` | SSH remote restart, uses `sshUser` + `sshPassword` from plugin config |
+| `POST` | `/plugins/signalk-pypilot-newui/restart-pypilot` | SSH remote restart (level 2 of the triad), uses `sshUser` + `sshPassword` from plugin config |
+| `POST` | `/plugins/signalk-pypilot-newui/debug-cmd`     | Run one of a closed whitelist of preset diagnostic / restart commands over SSH (levels 1 and 3 of the triad + logs / dmesg / top / etc). Body: `{ "preset": "<name>" }` |
 | `POST` | `/plugins/signalk-pypilot-newui/pause`         | Disconnect local socket (for scripts) |
 | `POST` | `/plugins/signalk-pypilot-newui/resume`        | Reconnect local socket (for scripts) |
 

package/dist/index.js

@@ -6,7 +6,7 @@ const scanner_1 = require("./scanner");
 const autopilot_provider_1 = require("./autopilot-provider");
 // Rev counter bumped on every build so the user can distinguish deploys
 // from the webapp header (feedback_revision_bump_each_build).
-const PLUGIN_REVISION = "Rev62";
+const PLUGIN_REVISION = "Rev63";
 // Rev59: read package.json once at load time so /status can report the
 // npm package version alongside the internal Rev counter.
 // eslint-disable-next-line @typescript-eslint/no-require-imports
@@ -164,13 +164,23 @@ module.exports = function (app) {
             client.on("pong", (latency) => {
                 lastPingLatencyMs = latency;
             });
-            client.on("catalog", (catalog) => {
+            client.on("catalog", (catalog, info) => {
+                const isDelta = !!info?.isDelta;
                 lastCatalog = catalog;
-                metaSent = new Set(); // resend meta on catalog refresh
+                // Rev63 / 2.0.0 (issue #2): only reset the meta-sent tracker on the
+                // INITIAL catalog. A delta catalog carries only newly-appeared keys
+                // (typically calibration finishing to load a few seconds after
+                // core), and we do NOT want to re-emit meta for the paths we
+                // already published - it would flood the SK bus with duplicate
+                // meta blobs. `metaSent` naturally excludes the new keys because
+                // they were never added to it, so those will emit meta on first
+                // publish as expected.
+                if (!isDelta)
+                    metaSent = new Set();
                 const catalogKeys = Object.keys(catalog);
                 const gainKeys = catalogKeys.filter((k) => k.startsWith("ap.pilot.") && catalog[k].AutopilotGain);
                 const apKeys = catalogKeys.filter((k) => k.startsWith("ap.pilot."));
-                app.setPluginStatus(`${PLUGIN_REVISION} - connected, catalog ${catalogKeys.length} vars (ap.pilots.*=${apKeys.length}, AutopilotGain=${gainKeys.length})`);
+                app.setPluginStatus(`${PLUGIN_REVISION} - connected, catalog ${catalogKeys.length} vars (ap.pilots.*=${apKeys.length}, AutopilotGain=${gainKeys.length})${isDelta ? " [+" + info.newKeys.length + " new]" : ""}`);
                 setupWatches(client, catalog);
                 registerPutHandlers(catalog);
                 publishCatalogDerived(catalog);
@@ -290,15 +300,7 @@ module.exports = function (app) {
                 for (const [name, meta] of Object.entries(lastCatalog)) {
                     if (publisher_1.RESERVED_PYPILOT_KEYS.has(name))
                         continue;
-                    let mapping = publisher_1.FIXED_MAPPINGS[name] || null;
-                    if (!mapping)
-                        mapping = (0, publisher_1.mapDynamicName)(name, lastCatalog);
-                    if (!mapping) {
-                        if (props.publishUnmapped)
-                            mapping = (0, publisher_1.autoMap)(name);
-                        else
-                            continue;
-                    }
+                    const mapping = (0, publisher_1.mappingFor)(name, meta);
                     items.push({
                         pypilotName: name,
                         skPath: mapping.skPath,
@@ -634,6 +636,106 @@ module.exports = function (app) {
                     return res.status(500).json({ error: e?.message || String(e) });
                 }
             });
+            // Rev63 / 2.0.0: Debug console. A whitelist of preset commands
+            // executed over the same ssh2 session as /restart-pypilot. The
+            // whitelist is CLOSED - the endpoint refuses any command not in
+            // DEBUG_PRESETS below, so a leaked JWT cannot be used to run
+            // arbitrary shell on the TinyPilot. Requires allowWrites.
+            const DEBUG_PRESETS = {
+                "logs.pypilot": "journalctl -u pypilot -n 200 --no-pager 2>&1 || (test -f /var/log/pypilot.log && tail -n 200 /var/log/pypilot.log) || echo 'no journal / no logfile'",
+                "logs.pypilot_web": "journalctl -u pypilot_web -n 200 --no-pager 2>&1 || echo 'no pypilot_web unit'",
+                "logs.follow": "journalctl -u pypilot --since '30 seconds ago' --no-pager 2>&1",
+                "dmesg.tail": "dmesg 2>&1 | tail -100",
+                "top.snapshot": "top -bn1 2>&1 | head -20",
+                "uptime": "uptime && cat /proc/loadavg",
+                "df": "df -h 2>&1",
+                "pypilot.version": "pypilot --version 2>&1 || (test -f /home/tc/pypilot/version && cat /home/tc/pypilot/version) || echo 'unknown'",
+                "restart.web": "sudo systemctl restart pypilot_web 2>&1 && echo OK",
+                "reboot.pi": "sudo reboot",
+            };
+            router.post("/debug-cmd", async (req, res) => {
+                if (!props.allowWrites)
+                    return res.status(403).json({ error: "allowWrites disabled" });
+                const preset = (req.body && req.body.preset) || "";
+                const cmd = DEBUG_PRESETS[preset];
+                if (!cmd) {
+                    return res.status(400).json({
+                        error: "unknown preset",
+                        available: Object.keys(DEBUG_PRESETS),
+                    });
+                }
+                const sshUser = props.sshUser || "tc";
+                const sshPassword = props.sshPassword || "";
+                if (!sshPassword) {
+                    return res.status(202).json({
+                        ok: false,
+                        preset,
+                        hint: "SSH password not set - open Setup > Emergency and save it.",
+                    });
+                }
+                try {
+                    // eslint-disable-next-line @typescript-eslint/no-require-imports
+                    const { Client } = require("ssh2");
+                    const conn = new Client();
+                    const t0 = Date.now();
+                    const result = await new Promise((resolve) => {
+                        let settled = false;
+                        const finish = (r) => {
+                            if (settled)
+                                return;
+                            settled = true;
+                            try {
+                                conn.end();
+                            }
+                            catch { }
+                            resolve(r);
+                        };
+                        conn.on("ready", () => {
+                            conn.exec(cmd, { pty: true }, (err, stream) => {
+                                if (err) {
+                                    finish({ ok: false, stdout: err.message });
+                                    return;
+                                }
+                                let out = "";
+                                stream.on("close", (code) => finish({ ok: code === 0, stdout: out, code }));
+                                stream.on("data", (data) => { out += data.toString(); });
+                                stream.stderr.on("data", (data) => { out += data.toString(); });
+                                setTimeout(() => { try {
+                                    stream.write(sshPassword + "\n");
+                                }
+                                catch { } }, 300);
+                            });
+                        });
+                        conn.on("error", (err) => finish({ ok: false, stdout: `ssh: ${err?.message || err}` }));
+                        conn.on("timeout", () => finish({ ok: false, stdout: "ssh timeout" }));
+                        try {
+                            conn.connect({
+                                host: props.host, port: 22,
+                                username: sshUser, password: sshPassword,
+                                readyTimeout: 8000, tryKeyboard: true,
+                            });
+                            conn.on("keyboard-interactive", (_n, _i, _l, _p, finish2) => {
+                                finish2([sshPassword]);
+                            });
+                        }
+                        catch (e) {
+                            finish({ ok: false, stdout: e?.message || String(e) });
+                        }
+                    });
+                    // For reboot.pi the ssh session drops as the box goes down, so we
+                    // report success even on a non-zero exit if we at least connected.
+                    return res.json({
+                        ok: preset === "reboot.pi" ? true : result.ok,
+                        preset,
+                        elapsedMs: Date.now() - t0,
+                        code: result.code,
+                        stdout: result.stdout.slice(0, 32000),
+                    });
+                }
+                catch (e) {
+                    return res.status(500).json({ error: e?.message || String(e), preset });
+                }
+            });
         },
     };
     // ---- helpers ----
@@ -805,17 +907,11 @@ module.exports = function (app) {
                     return;
             }
         }
-        let mapping = publisher_1.FIXED_MAPPINGS[name] || null;
-        if (!mapping)
-            mapping = (0, publisher_1.mapDynamicName)(name, lastCatalog);
-        if (!mapping) {
-            if (!props.publishUnmapped)
-                return;
-            mapping = (0, publisher_1.autoMap)(name);
-        }
-        if (mapping.reserved)
-            return;
-        const skValue = (0, publisher_1.convertForSK)(mapping, value);
+        // Rev63 / 2.0.0: every pypilot key derives to steering.autopilot.pypilot.<key>
+        // verbatim (Sean D'Epagnier's suggestion in #1). No conversions, no rename,
+        // no hardcoded table - Signal K + downstream consumers handle units.
+        const mapping = (0, publisher_1.mappingFor)(name, lastCatalog[name]);
+        const skValue = value;
         const updateEntry = {
             $source: SOURCE_LABEL,
             timestamp: new Date().toISOString(),
@@ -891,13 +987,10 @@ module.exports = function (app) {
                 if (!name) {
                     return { state: "COMPLETED", statusCode: 404, message: "unknown path" };
                 }
-                // Reverse unit conversion for angle paths that we stored in rad.
-                let pypilotValue = value;
-                const mapping = publisher_1.FIXED_MAPPINGS[name];
-                if (mapping?.units === "rad" && typeof value === "number") {
-                    pypilotValue = value * 180 / Math.PI;
-                }
-                client.set(name, pypilotValue);
+                // Rev63 / 2.0.0: values are surfaced verbatim, so PUT writes verbatim
+                // too. No reverse conversion needed - what the consumer sends is what
+                // pypilot receives.
+                client.set(name, value);
                 return { state: "COMPLETED", statusCode: 200 };
             };
             try {
@@ -908,22 +1001,16 @@ module.exports = function (app) {
                 app.debug(`[put] register failed for ${skPath}: ${e?.message || e}`);
             }
         };
-        for (const [name, mapping] of Object.entries(publisher_1.FIXED_MAPPINGS)) {
-            if (mapping.putKind !== "plain")
+        // Register a PUT handler for every catalog key we consider writeable.
+        // With verbatim mapping (Rev63) this collapses to a single loop.
+        for (const [name, meta] of Object.entries(catalog)) {
+            if (publisher_1.RESERVED_PYPILOT_KEYS.has(name))
                 continue;
-            if (!catalog[name])
+            const mapping = (0, publisher_1.mappingFor)(name, meta);
+            if (mapping.putKind !== "plain")
                 continue;
             registerOne(mapping.skPath);
         }
-        // Gains: register handler for each discovered ap.pilots.<pilot>.<gain> that
-        // catalog exposes as AutopilotGain.
-        for (const [name, meta] of Object.entries(catalog)) {
-            if (!meta.AutopilotGain)
-                continue;
-            const m = (0, publisher_1.mapDynamicName)(name, catalog);
-            if (m)
-                registerOne(m.skPath);
-        }
     }
     // Rev24: dedicated ACTION paths for KIP-friendly PUT buttons.
     // KIP has widgets that PUT a fixed value on click - perfect for +10/+1/AP/Tack buttons.