signalk-pypilot-newui 3.3.0 → 3.4.0

package/CHANGELOG.md

@@ -1,5 +1,42 @@
 # Changelog
 
+## 3.4.0 — 2026-10-18 — The sailor always wins, and the pilot gets unstuck
+
+Rolls up Rev506 → Rev508 on top of 3.3.0, from the strong-wind sea
+trial of 2026-10-18 (26 kn TWS, 48° heel). Minor bump: new opt-in
+recovery and alarms. No breaking changes; everything new is off until
+enabled.
+
+### Added
+- **Stuck pilot recovery** (Smart Pilot card, opt-in). With no rudder
+  sensor, pypilot treats an overcurrent as the end of rudder travel and
+  stops driving that way. If the AP is engaged, the heading error is
+  over 25° and growing and the servo is not pushing for 4 s, the plugin
+  turns the AP off and on (0.7 s, same mode and target), which clears
+  that fault in pypilot. At most 3 tries per minute. An order from the
+  sailor during the cycle wins, and a running virtual tack is kept.
+- **New alarms** (opt-in, Setup > Alarms): `steer-stuck`,
+  `steer-gave-up` ("steer by hand") and `steer-dropped` (AP disengaged
+  from the remote or the TinyPilot keys while underway).
+- **+-1 / +-10 during a virtual tack** move the tack's final heading
+  instead of being rejected.
+- `servo.flags` is watched and saved in every session sample.
+
+### Fixed
+- **Taking the AP off now cancels a virtual tack**, whatever the source
+  (visor, KIP, remote, TinyPilot). Before, the tack kept running and
+  rejected the sailor's own headings until it finished. After a cancel
+  the boat holds its current wind angle.
+- Repeated taps on the tack button within 1.5 s no longer chain
+  start / cancel / start (wind modes).
+- `unable-to-steer` can fire again: it required servo duty, which the
+  TinyPilot never reports. It now also fires on a large error while the
+  servo is stopped by an overcurrent fault.
+- Settings tab: unlocking a group no longer asks about the profile; the
+  question appears only for PROFILE settings. Open or unlocked groups
+  are no longer folded, relocked and reset to old values by the 10 s
+  background refresh.
+
 ## 3.3.0 — 2026-10-19 — Light on the Pi, AIS on the ring, settings shared by every device
 
 Rolls up Rev483 → Rev505 on top of 3.2.0. Minor bump: new shared

package/README.md

@@ -147,7 +147,12 @@ up automatically.
     for 20 s, temporarily switch to the Heavy profile for 30 s, or
     just warn.
 17. **Auto-disengage on lost authority** — RMS heading error > 30°
-    with servo duty > 90% sustained 10 s.
+    with servo duty > 90% sustained 10 s. **Stuck pilot recovery**
+    (opt-in): with no rudder sensor, pypilot treats an overcurrent as
+    the end of rudder travel and stops driving that way; when the error
+    keeps growing and the servo is not pushing, the plugin turns the AP
+    off and on (same mode and target) to clear it, at most 3 times per
+    minute.
 18. **Pre-departure Autopilot Check** — a single READY / CAVEATS /
     DO-NOT-ENGAGE verdict aggregating every sensor, servo, voltage
     and link signal.
@@ -156,8 +161,9 @@ up automatically.
 20. **Servo Health** — learns a baseline for typical servo duty at
     sea and flags recent, peak, temperature or voltage deviations
     from that baseline.
-21. **Alarm engine — 14 rules** — heading deviation, cruise drift,
-    unable-to-steer, servo overcurrent, servo current near trip,
+21. **Alarm engine — 17 rules** — heading deviation, cruise drift,
+    unable-to-steer, pilot stuck, pilot cannot recover, AP disengaged
+    from the remote / TinyPilot, servo overcurrent, servo current near trip,
     rudder near its end stop, servo controller temperature, motor
     temperature, high AP load, low voltage, sensor lost, pypilot
     disconnected, extreme heel, extreme pitch — all published as

package/dist/alarms.js

@@ -122,7 +122,7 @@ exports.DEFAULT_RULES = [
         severity: "alarm",
         defaultEnabled: true,
         sustainSec: 20,
-        description: `Sustained high error AND servo running at ${(exports.RULE_UNABLE_DUTY_MIN * 100) | 0}%+ duty - the AP is losing authority.`,
+        description: `Sustained high error AND servo running at ${(exports.RULE_UNABLE_DUTY_MIN * 100) | 0}%+ duty (or stopped by an overcurrent fault) - the AP is losing authority.`,
         evaluate: (c) => {
             if (!c.kpis || !c.sample || !c.sample.engaged)
                 return false;
@@ -132,15 +132,57 @@ exports.DEFAULT_RULES = [
                 return false; // Rev323: idem pseudo-modo
             const r = c.kpis.window1m.rmsErrorRad;
             const d = c.kpis.window1m.servoDutyPct;
-            return typeof r === "number" && r > exports.RULE_UNABLE_ERR_RAD
-                && typeof d === "number" && d > exports.RULE_UNABLE_DUTY_MIN;
+            if (typeof r !== "number" || r <= exports.RULE_UNABLE_ERR_RAD)
+                return false;
+            // Rev508: servoDuty never arrives from Carlos's TinyPilot, so the
+            // rule could not fire on 2026-10-18. A directional overcurrent
+            // fault (false end stop) with the same error is the same verdict.
+            if (c.steer?.dirFault)
+                return true;
+            return typeof d === "number" && d > exports.RULE_UNABLE_DUTY_MIN;
         },
         message: (c) => {
             const r = c.kpis?.window1m.rmsErrorRad ?? 0;
-            const d = c.kpis?.window1m.servoDutyPct ?? 0;
-            return `AP losing authority: ${(r * 180 / Math.PI).toFixed(0)}° error, servo ${(d * 100).toFixed(0)}% duty`;
+            const d = c.kpis?.window1m.servoDutyPct;
+            if (c.steer?.dirFault && !(typeof d === "number" && d > exports.RULE_UNABLE_DUTY_MIN)) {
+                return `AP losing authority: ${(r * 180 / Math.PI).toFixed(0)}° error, servo stopped by overcurrent`;
+            }
+            return `AP losing authority: ${(r * 180 / Math.PI).toFixed(0)}° error, servo ${((d ?? 0) * 100).toFixed(0)}% duty`;
         },
     },
+    // Rev508 (Carlos sea trial 2026-10-18): the pilot stopped steering.
+    // Opt-in like every alarm (BASIC vs Performance rule); enabled on the
+    // Tunatunes from Setup > Alarms. Sustain lives in steer-watch.
+    {
+        id: "steer-stuck",
+        label: "Pilot stuck",
+        severity: "alarm",
+        defaultEnabled: false,
+        sustainSec: 0,
+        description: "AP engaged, heading error > 25° and growing, servo not pushing (overcurrent false end stop or 0 A) for 4 s. With recovery enabled the plugin cycles AP off/on.",
+        evaluate: (c) => !!c.steer?.stuck && !c.steer.gaveUp,
+        message: () => "Pilot stuck: servo not pushing, error growing",
+    },
+    {
+        id: "steer-gave-up",
+        label: "Pilot cannot recover",
+        severity: "alarm",
+        defaultEnabled: false,
+        sustainSec: 0,
+        description: "Three recovery cycles in one minute did not get the servo pushing again. Steer by hand.",
+        evaluate: (c) => !!c.steer?.gaveUp,
+        message: () => "Pilot cannot recover: steer by hand",
+    },
+    {
+        id: "steer-dropped",
+        label: "AP disengaged from outside the app",
+        severity: "alarm",
+        defaultEnabled: false,
+        sustainSec: 0,
+        description: "ap.enabled went off with no order from this app (TinyPilot keys, remote, native UI) while underway. Clears on re-engage or after 60 s.",
+        evaluate: (c) => !!c.steer?.droppedActive,
+        message: () => "AP disengaged from outside the app (remote / TinyPilot)",
+    },
     {
         id: "servo-overcurrent",
         label: "Servo overcurrent",

package/dist/autopilot-provider.js

@@ -110,6 +110,9 @@ class AutopilotProvider {
          *  adjust target, legacy countdown) that would compete with the
          *  maneuver. */
         this._vtInternalWrite = false;
+        /** Rev506: recovery cycles (steer-recovery) toggle the AP off/on on
+         *  purpose; that must NOT annul the tack the cycle is trying to save. */
+        this._recoveryCycleUntil = 0;
         if (opts?.allowDodge)
             this.allowDodge = true;
         this.onDataChanged = opts?.onDataChanged;
@@ -290,6 +293,8 @@ class AutopilotProvider {
                     const pendVal = this.pendingEngaged.value;
                     if (eng === pendVal) {
                         this.pendingEngaged = null;
+                        if (!eng)
+                            this._cancelVirtualTackOnDisengage("disengage echo");
                         this.onStageEvent?.("provider", {
                             path: "ap.enabled",
                             decision: "echo_dropped_match",
@@ -317,6 +322,17 @@ class AutopilotProvider {
                     this.data.engaged = eng;
                     changed = true;
                     changedField = "engaged";
+                    // Rev506: AP off from ANY source (pypilot itself, physical
+                    // remote, native UI, KIP switch, /raw) annuls the virtual tack.
+                    if (!eng)
+                        this._cancelVirtualTackOnDisengage("disengaged externally");
+                    // Rev508: steer-dropped alarm (skip our own recovery cycle).
+                    if (!eng && Date.now() >= this._recoveryCycleUntil) {
+                        try {
+                            this.onExternalDisengage?.();
+                        }
+                        catch { /* observer only */ }
+                    }
                 }
                 this.onStageEvent?.("provider", {
                     path: "ap.enabled",
@@ -391,6 +407,16 @@ class AutopilotProvider {
         // echoes while pending.
         const eng = st.engaged;
         const apSt = eng ? "enabled" : "disabled";
+        // Rev506 (Carlos sea trial 2026-10-18): taking the AP off annuls a
+        // running virtual tack ("si quito AP la virada queda anulada"). The
+        // FSM used to keep driving after a disengage and then rejected the
+        // sailor's own targets ("FSM is driving") until it finished.
+        if (!eng)
+            this._cancelVirtualTackOnDisengage("disengage order");
+        try {
+            this.onAppEngageOrder?.();
+        }
+        catch { /* observer only */ }
         // Rev271 (audit R01+R04): bump generation and cancel any NAV
         // pending timer. If this call is superseded before we make it past
         // the retry backoff, the stale isStale() check aborts the retry
@@ -983,22 +1009,33 @@ class AutopilotProvider {
             // pypilot pick the short arc in the WRONG direction).
             let remainingIntermediates = geometry.intermediatesRad.slice();
             let stepCounter = 0;
-            let finalCompassTargetRad = geometry.hTargetRad;
-            // Rev410 (fix T.1-A, Carlos 2026-10-04): publish an initial
-            // `remainingDeg` so the visor's mirror HUD shows a meaningful
-            // number from the first snapshot, not just elapsed seconds.
-            // Granularity thereafter is "once per intermediate step reached"
-            // (option A, confirmed by Carlos — no 500 ms tick).
-            {
-                const h0 = this._readHeadingRad();
-                if (h0 !== null && this._virtualTack && this._virtualTack.id === vtId) {
-                    this._virtualTack.remainingDeg = Math.abs(shortestArcRad(finalCompassTargetRad, h0) * RAD_TO_DEG);
+            // Rev506: final targets follow the sailor's nudges (adjustRad).
+            const curAdjust = () => (this._virtualTack && this._virtualTack.id === vtId) ? this._virtualTack.adjustRad : 0;
+            const curAdjustVersion = () => (this._virtualTack && this._virtualTack.id === vtId) ? this._virtualTack.adjustVersion : 0;
+            const finalCompass = () => (0, virtual_tack_1.adjustedFinalCompassRad)(geometry, curAdjust());
+            const finalWind = () => (0, virtual_tack_1.adjustedFinalWindRad)(geometry, curAdjust());
+            let seenAdjustVersion = curAdjustVersion();
+            // Rev506: publish remaining degrees on every tick (not only per
+            // step) so the countdown shows what is LEFT to turn.
+            const publishRemaining = (hRad) => {
+                if (hRad === null || !this._virtualTack || this._virtualTack.id !== vtId)
+                    return;
+                const rem = Math.abs(shortestArcRad(finalCompass(), hRad) * RAD_TO_DEG);
+                const prev = this._virtualTack.remainingDeg;
+                if (prev === null || Math.abs(prev - rem) >= 1) {
+                    this._virtualTack.remainingDeg = rem;
                     try {
                         this.notifyChanged("virtualTack");
                     }
                     catch { /* noop */ }
                 }
-            }
+            };
+            // Rev410 (fix T.1-A, Carlos 2026-10-04): publish an initial
+            // `remainingDeg` so the visor's mirror HUD shows a meaningful
+            // number from the first snapshot, not just elapsed seconds.
+            // Granularity thereafter is "once per intermediate step reached"
+            // (option A, confirmed by Carlos — no 500 ms tick).
+            publishRemaining(this._readHeadingRad());
             while (remainingIntermediates.length > 0) {
                 checkCancelled();
                 this._virtualTack.stepIndex = stepCounter;
@@ -1018,8 +1055,16 @@ class AutopilotProvider {
                 // if they want to abort for any other reason.
                 let lastHeadingRad = null;
                 let lastHeadingChangeTs = Date.now();
+                let retarget = false;
                 while (true) {
                     const hNow = this._readHeadingRad();
+                    publishRemaining(hNow);
+                    // Rev506: sailor nudged the destination -> re-aim from here.
+                    if (curAdjustVersion() !== seenAdjustVersion) {
+                        seenAdjustVersion = curAdjustVersion();
+                        retarget = true;
+                        break;
+                    }
                     if (hNow !== null) {
                         if ((0, virtual_tack_1.isAtTarget)({
                             hNowRad: hNow,
@@ -1046,27 +1091,35 @@ class AutopilotProvider {
                     await sleep(500);
                     checkCancelled();
                 }
+                if (retarget) {
+                    const hNow = this._readHeadingRad();
+                    if (hNow !== null) {
+                        remainingIntermediates = (0, virtual_tack_1.recomputeRemainingIntermediates)({
+                            hNowRad: hNow,
+                            finalCompassTargetRad: finalCompass(),
+                            originalDeltaSign: Math.sign(geometry.deltaHRad),
+                        });
+                    }
+                    else {
+                        // No heading: keep the plan but aim the last step at the new final.
+                        remainingIntermediates[remainingIntermediates.length - 1] = finalCompass();
+                    }
+                    // eslint-disable-next-line no-console
+                    console.log(`[virtual-tack ${vtId}] re-aimed by sailor: adjust=${(curAdjust() * RAD_TO_DEG).toFixed(0)}deg, steps=${remainingIntermediates.length}`);
+                    continue; // write the new first step; nothing was "reached"
+                }
                 // Step reached. Pop it and recompute the rest from REAL heading.
                 remainingIntermediates.shift();
                 stepCounter++;
                 // Rev410 (fix T.1-A): refresh `remainingDeg` from the current
                 // heading. One update per step reached is the agreed granularity.
-                {
-                    const hAfter = this._readHeadingRad();
-                    if (hAfter !== null && this._virtualTack && this._virtualTack.id === vtId) {
-                        this._virtualTack.remainingDeg = Math.abs(shortestArcRad(finalCompassTargetRad, hAfter) * RAD_TO_DEG);
-                        try {
-                            this.notifyChanged("virtualTack");
-                        }
-                        catch { /* noop */ }
-                    }
-                }
+                publishRemaining(this._readHeadingRad());
                 if (remainingIntermediates.length > 0) {
                     const hNow = this._readHeadingRad();
                     if (hNow !== null) {
                         remainingIntermediates = (0, virtual_tack_1.recomputeRemainingIntermediates)({
                             hNowRad: hNow,
-                            finalCompassTargetRad,
+                            finalCompassTargetRad: finalCompass(),
                             originalDeltaSign: Math.sign(geometry.deltaHRad),
                         });
                     }
@@ -1091,12 +1144,13 @@ class AutopilotProvider {
             checkCancelled();
             this._vtInternalWrite = true;
             try {
-                await this.setTarget(geometry.angleNewRad);
+                await this.setTarget(finalWind());
             }
             finally {
                 this._vtInternalWrite = false;
             }
             checkCancelled();
+            seenAdjustVersion = curAdjustVersion();
             // Rev387: settling phase. Watches the wind angle error until
             // it stays under tolerance for a short dwell.
             // Rev407: no artificial "declaring completed anyway" fallback.
@@ -1139,10 +1193,23 @@ class AutopilotProvider {
                     }
                 }
                 catch { /* noop */ }
+                // Rev506: a nudge during settling re-aims the wind target.
+                if (curAdjustVersion() !== seenAdjustVersion) {
+                    seenAdjustVersion = curAdjustVersion();
+                    this._vtInternalWrite = true;
+                    try {
+                        await this.setTarget(finalWind());
+                    }
+                    finally {
+                        this._vtInternalWrite = false;
+                    }
+                    checkCancelled();
+                    dwellStart = null;
+                }
                 const sampleFresh = windNowRad !== null && (sampleAgeMs === null || sampleAgeMs < STALE_SAMPLE_MS);
                 if (sampleFresh) {
                     awaEmaRad = (0, virtual_tack_1.awaEmaStep)(awaEmaRad, windNowRad, EMA_ALPHA);
-                    const errDeg = Math.abs(((((awaEmaRad - geometry.angleNewRad) * RAD_TO_DEG) + 540) % 360) - 180);
+                    const errDeg = Math.abs(((((awaEmaRad - finalWind()) * RAD_TO_DEG) + 540) % 360) - 180);
                     if (errDeg < SETTLE_TOLERANCE_DEG) {
                         if (dwellStart === null)
                             dwellStart = Date.now();
@@ -1286,18 +1353,84 @@ class AutopilotProvider {
      *  when the sailor taps the tack button a second time (frontend
      *  Rev379). Sets phase to "abort" so the running driver bails and
      *  rolls back on its next await. */
-    cancelVirtualTack() {
+    cancelVirtualTack(reason = "user cancelled") {
         if (!this._virtualTack)
             return;
         const terminal = ["completed", "cancelled", "failed"];
         if (terminal.includes(this._virtualTack.phase))
             return;
         // eslint-disable-next-line no-console
-        console.log(`[virtual-tack] external cancel at phase=${this._virtualTack.phase}`);
+        console.log(`[virtual-tack] external cancel at phase=${this._virtualTack.phase} (${reason})`);
         this._virtualTack.phase = "cancelling";
-        this._virtualTack.outcomeReason = "user cancelled";
+        this._virtualTack.outcomeReason = reason;
         this.notifyChanged("all");
     }
+    /** Rev506 (Carlos sea trial 2026-10-18): +-1/+-10 during a virtual tack
+     *  move its final destination. deltaRad is bow-relative, positive = bow
+     *  to starboard (same sign as the visor's nudge buttons). Returns false
+     *  when no tack is running so the caller can fall back to a normal nudge. */
+    adjustVirtualTack(deltaRad) {
+        if (!Number.isFinite(deltaRad) || !this.isVirtualTackActive())
+            return false;
+        const vt = this._virtualTack;
+        if (vt.phase === "cancelling")
+            return false;
+        vt.adjustRad = (0, virtual_tack_1.accumulateTackAdjust)(vt.adjustRad, deltaRad);
+        vt.adjustVersion += 1;
+        // eslint-disable-next-line no-console
+        console.log(`[virtual-tack ${vt.id}] sailor adjust ${(deltaRad * RAD_TO_DEG).toFixed(0)}deg -> total ${(vt.adjustRad * RAD_TO_DEG).toFixed(0)}deg`);
+        this.notifyChanged("virtualTack");
+        return true;
+    }
+    /** Rev506: true while a virtual tack is running (not terminal). */
+    isVirtualTackActive() {
+        const vt = this._virtualTack;
+        return !!vt && !["idle", "completed", "cancelled", "failed"].includes(vt.phase);
+    }
+    /** Rev508 (steer recovery): AP off -> gapMs -> AP on, same mode and
+     *  target (pypilot keeps both). Changing ap.enabled clears pypilot's
+     *  directional overcurrent fault (servo.py), the false end stop that
+     *  left the servo at 0 A on 2026-10-18. A running virtual tack is NOT
+     *  annulled by the cycle. If any other engage/disengage order arrives
+     *  meanwhile, the cycle aborts and does not re-engage. */
+    async recoveryCycle(gapMs = 700) {
+        if (!this.data.engaged || !this.client.connected)
+            return "skipped";
+        this._recoveryCycleUntil = Date.now() + gapMs + 3000;
+        try {
+            await this.setState("disabled");
+        }
+        catch {
+            this._recoveryCycleUntil = 0;
+            return "aborted";
+        }
+        const gen = this.engageGen;
+        await new Promise((r) => setTimeout(r, gapMs));
+        if (this.engageGen !== gen) {
+            // The sailor gave an order during the gap: theirs wins. If it was a
+            // disengage, the tack must be annulled as usual.
+            this._recoveryCycleUntil = 0;
+            if (!this.data.engaged)
+                this._cancelVirtualTackOnDisengage("disengage during recovery");
+            return "aborted";
+        }
+        try {
+            await this.setState("enabled");
+        }
+        catch {
+            this._recoveryCycleUntil = 0;
+            this._cancelVirtualTackOnDisengage("recovery re-engage failed");
+            return "aborted";
+        }
+        return "done";
+    }
+    _cancelVirtualTackOnDisengage(reason) {
+        if (Date.now() < this._recoveryCycleUntil)
+            return;
+        if (!this.isVirtualTackActive())
+            return;
+        this.cancelVirtualTack(reason);
+    }
     async engage() {
         // Rev279 (audit follow-up A): the catch used to fall through to
         // setState("enabled") on ANY setNavMode failure, including a