From 451c2c353f6f7df64280b4347e1fb1538ba209f0 Mon Sep 17 00:00:00 2001 From: Grant Date: Tue, 14 Jul 2026 11:21:44 +0200 Subject: [PATCH] =?UTF-8?q?docs:=20record=2014=20Jul=20session=20design=20?= =?UTF-8?q?=E2=80=94=20widget=20wiring=20map,=20depth=20dual-source,=20fau?= =?UTF-8?q?lt-injection=20required,=20FSM=20rework=20top=20priority?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit docs/design_intent_register.md v1.5: - New DIR-13 — widget-to-hardware ownership map. W1 is a two-stage health gate: RPi4 FC-heartbeat MUST pass first (implemented, 86b2728), then RPi5 autonomy-stack self-health (not yet built) — only when both pass is W1 GREEN. W5 reflects the RPi4-connected battery. W2/W3/W4/W6/W8 reflect the RPi5 stack; W6 deliberately kept RPi5-direct per the standalone-autonomy principle. W7 specced, not built. Cross-references DIR-12. - New DIR-14 — depth as a dual-source, operator-selectable input: RPi4 sensor (via the FC), an RPi5-direct sensor, or a blend, selected at mission setup (W4) and carried in the resolved mode profile like health_role. Redundancy plus operator choice. Design-captured, not yet specified in detail. docs/handover.md v2.27: - New §9 widget-to-hardware wiring table matching the DIR-13 ownership map. - Test-data/fault-injection capability flagged as an approaching required workstream, not optional — the failsafe logic (and the pending count- based FSM rework) cannot be properly tested without injecting sensor states and simulating running-vs-failed conditions. Incremental approach agreed: altitude/depth/sonar first. Near-term prerequisite for validating the FSM rework; added to §0 PARKED/NEXT and §16. - FSM rework to the corrected count-based model (255096f) reconfirmed as top build priority — 2a3e577/bf815cc's condition-clear commit logic remains known-wrong pending that rework. Recorded as related to, and to be planned alongside, W1's RPi5-side health gating (DIR-13) and the fault-injection capability above. - Confirmed and recorded: W2 reflects live mission state (observed ABORTED after a live abort); W3's label change to RETURN TO SAFE is complete (9aa5b5d) — stale references to this as outstanding work corrected in §0 Blocked/Open Items/NEXT and §16. argonaut-api.service manual-start reminder recorded for rov_api/backend testing. - DIR pointer section bumped to DIR-1 through DIR-14. Documentation only — no code, widget, or diagram files touched. Not uploaded to Claude project knowledge; that remains a manual step. --- docs/design_intent_register.md | 83 +++++++++++++++++++- docs/handover.md | 136 +++++++++++++++++++++++++++------ 2 files changed, 193 insertions(+), 26 deletions(-) diff --git a/docs/design_intent_register.md b/docs/design_intent_register.md index 06658e5..d2401b3 100644 --- a/docs/design_intent_register.md +++ b/docs/design_intent_register.md @@ -1,7 +1,7 @@ # Design Intent Register — Argonaut 3 -**Version:** 1.4 -**Date:** 13 July 2026 +**Version:** 1.5 +**Date:** 14 July 2026 **File:** `docs/design_intent_register.md` (repo-tracked, no version number in filename) **Purpose of this register:** Capture operator/owner *intent* — what each behaviour MEANS and MUST/MUST NOT do — separately from mechanism (topics, code). Mechanism is recorded elsewhere. This register is the source of truth for *why*, against which any implementation is validated. Every entry dated and attributed. @@ -12,6 +12,7 @@ | Version | Date | Change | |---|---|---| +| 1.5 | 14 Jul 2026 | **Two new DIRs — documentation-only pass, no code changed.** **DIR-13 — widget-to-hardware ownership map:** records which subsystem (RPi4 gateway vs RPi5 autonomy brain) each widget reflects, as owner-stated intent. W1 is a two-stage health gate — FC heartbeat on RPi4 MUST pass first (already implemented, `86b2728`, 11 Jul), then RPi5 autonomy-stack self-health (not yet built); only when both pass is W1 GREEN. W5 reflects the RPi4-connected battery. W2/W3/W4/W6/W8 reflect the RPi5 stack; W6 altitude is deliberately kept RPi5-direct, consistent with the standalone-autonomy principle (BlueOS/Cockpit integration is the only current external dependency). W7 specced, not built. Cross-references DIR-12. **DIR-14 — depth is a dual-source, operator-selectable input:** depth may come from an RPi4 sensor (via the FC) or an RPi5-direct sensor; the system should support selecting one, the other, or a blend, chosen at mission setup (W4) and carried in the resolved mode profile like other settings. Redundancy plus operator choice; consistent with the same standalone-autonomy principle as DIR-13/W6. Design-captured intent for a future build, not yet specified in detail. | | 1.4 | 13 Jul 2026 | **CORRECTION: DIR-7 "in-mission recovery is mode-dependent" addendum was inverted — fixed.** The 11 Jul wording had AUV gate mode commit to recovery ON CONDITION-CLEAR; that produced a contradictory GREEN-while-in-`RETURN_TO_SAFE` state observed live. Corrected model: GREEN is unconditionally a working state; committed recovery is triggered by fault PERSISTENCE or RECURRENCE, never by clearing. Records a three-tier fault model (uncontrollable/out-of-scope for the FSM; transient/self-resetting with a raw failure-count trigger, deliberately no time window; hard/persistent, a RED that doesn't clear) with all thresholds configuration-driven via the resolved mode profile, same as `health_role`. Records what survives (health_role mode-awareness from `2a3e577`; the safe-zone-reached arrival-exit mechanism from `bf815cc`, unchanged in role) vs what's retired (the condition-clear entry logic in `2a3e577`, which `bf815cc` built its exit on top of) — pending next-session rework into the count-based model. **New Parked Design Item:** adaptive restart-timing (monitor own restore count/duration, weigh future attempts against observed history rather than a fixed time) — depends on the count-based retry machinery above existing first; design-captured, not build-specified. | | 1.3 | 13 Jul 2026 | **New Parked Design Item:** mode-aware safe-zone-reached arrival event (relates to the DIR-7 "in-mission recovery is mode-dependent" addendum) — the permanent `/rov/nav/safe_zone_reached` interface, mode-aware/sensor-derived arrival judgement (GPS at surface + EKF/dead-reckoning underwater), GPS recorded as first-class across mission types (not a hull/jacket-specific surface concern), gate-only scope, and the temporary W1-button bench-scaffolding publisher pending navigation. Implemented same day in `failsafe_monitor` (`bf815cc`) — see `docs/handover.md` §15f for the fix narrative; this entry records the design intent, not the commit detail. DIR-7 addendum's Implementation note updated: the mode-dependent recovery mechanism is no longer mode-blind (`2a3e577`, 13 Jul 2026). | | 1.2 | 11 Jul 2026 | **DIR-7's FC-connectivity MUST — RESOLVED**, four commits 11 Jul 2026 (full detail in `docs/handover.md` Changelog); open-flag callout updated accordingly. **DIR-7 gains two addenda:** in-mission recovery is mode-dependent (AUV commits to recovery on condition-clear, does not auto-resume; ROV holds and hands the continue-or-recover decision to the operator); and in-mission AMBER runtime-response (AMBER means action-required, not just informational, once a mission is underway — response branches by mode, AUV's autonomous curtailment logic left unspecified pending further design). **New "Parked Design Items" section** — auto-recovery (failsafe_monitor should attempt to re-establish the FC link itself before escalating) and a dedicated `string cause` field in `FailsafeStatus.msg` (replacing the `cockpit_bridge` message-substring shortcut) — both tracked as open implementation gaps against existing DIR-7/12 intent, not new decisions. Filename de-versioned as part of the 11 Jul doc restructure — this file moved into the repo `docs/` folder. | @@ -497,6 +498,84 @@ are "is the vehicle actually going to keep talking to me" questions. --- +## DIR-13 — Widget-to-hardware ownership map + +**Source:** Grant, 14 Jul 2026 session. + +**Intent:** Record, as owner-stated intent, which physical subsystem (RPi4 BlueOS gateway vs +RPi5 autonomy brain) each Cockpit widget actually reflects — the wiring picture behind the UI, +so it is not left to be inferred from code. Relates directly to DIR-12 (vehicle health and +autonomy health are distinct subjects) — this DIR is the widget-level instance of that same +distinction, enumerated per widget rather than argued in the abstract. + +**W1 (System Health Indicator) is a two-stage health gate, not a single-subsystem readout:** +1. **Flight-controller heartbeat (RPi4 gateway) MUST pass first.** A dead or unreachable FC + makes autonomy meaningless regardless of how healthy the RPi5 stack is — this is DIR-12's + "vehicle health is distinct from autonomy health" applied concretely. **Already implemented** + (commit `86b2728`, 11 Jul 2026) — `failsafe_monitor` forces RED on FC comms loss. +2. **RPi5 autonomy-stack self-health** — nodes alive, EKF converged, recorder active, bridge up + — is the second stage. **Not yet built.** + +Only when both stages pass is W1 GREEN. W1 is not "an RPi5 stack indicator" and never was +intended to be one — the FC-heartbeat stage is what makes it a *vehicle* health gate rather +than an *autonomy* health gate (DIR-12). + +**Per-widget ownership (owner-stated intent):** +- **W1 (System Health Indicator)** — BOTH: RPi4 (FC heartbeat, implemented) + RPi5 (autonomy + self-health, not yet built). See above. +- **W2 (Mission Status)** — RPi5 (`mission_executor`). +- **W3 (Return To Safe button)** — RPi5 (`failsafe_monitor` via `/rov/mission/abort`). +- **W4 (Mission Setup button)** — RPi5 (FastAPI setup page, not yet built). +- **W5 (Return Budget)** — RPi4. Reflects the battery, which is connected to the RPi4 (via + MAVROS/Pixhawk), not the RPi5. +- **W6 (Altitude)** — RPi5. **Deliberately** kept sourced direct from the RPi5 (Ping2 on RPi5), + not routed via the RPi4 — consistent with the principle that the autonomy unit should be + standalone, with BlueOS/Cockpit integration as its only current external dependency. +- **W7 (Backup Due Notice)** — RPi5 (+ server, Option A design). Specced, not built. +- **W8 (Mode Indicator)** — RPi5 (`mode_profile_loader`). + +**Must:** Keep this ownership map in sync with `docs/handover.md`'s current-state material — +that document carries the same table for quick operator reference; this entry is the intent +record, that one is the live status pointer. + +**Must not:** Let a widget's *apparent* subject (what it visually looks like it's reporting on) +diverge from its *actual* data source without recording the divergence here — this is exactly +the DIR-12 failure mode (a green light that doesn't say what it's green about). + +--- + +## DIR-14 — Depth is a dual-source, operator-selectable input + +**Source:** Grant, 14 Jul 2026 session. + +**Intent:** Depth may be sourced from a sensor on the RPi4 (via the flight controller) OR a +sensor added directly to the RPi5, and the system should support selecting one source, the +other, or a blend of both — chosen at mission setup time (associated with the W4 Mission Setup +widget) and carried in the resolved configuration the same way other mode-profile settings +(e.g. `health_role`) are, not hardcoded. + +**Rationale — redundancy plus operator choice:** Two independent depth sources give a fallback +if one fails, and let the operator (or the setup wizard) pick whichever is more trustworthy for +a given deployment, rather than the system being permanently committed to one sensor's data +path. + +**Consistent with the standalone-autonomy principle (see DIR-13):** an RPi5-direct depth sensor +means the RPi5 autonomy unit is not solely dependent on the RPi4 for this input — the same +reasoning already applied to W6 altitude. + +**Must (once built):** Read the selected depth source (RPi4 / RPi5 / blend) from the resolved +mode profile, the same mechanism `health_role` and the other mode-profile flags already use — +never hardcode a single source. + +**Must not:** Assume depth always comes from one fixed sensor path. Both paths are legitimate; +the choice is a configuration, not a constant. + +> **Status:** Design-captured intent for a future build. Not yet specified in detail — no +> sensor selection mechanism, blending algorithm, or config-profile field decided here, only +> the shape of the requirement (dual-source, operator-selectable, mode-profile-carried). + +--- + ## Parked Design Items (intent-adjacent, not yet actioned) Tracked here so they aren't lost between sessions. Not full DIR entries — each is an diff --git a/docs/handover.md b/docs/handover.md index bb95aa8..cfac740 100644 --- a/docs/handover.md +++ b/docs/handover.md @@ -1,7 +1,7 @@ # ROV Autonomous Inspection System — Project Handover **Project Name:** Argonaut 3 -**Version:** 2.26 -**Date:** 13 July 2026 +**Version:** 2.27 +**Date:** 14 July 2026 **File:** `docs/handover.md` (repo-tracked, no version number in filename — see Version History for versioning) **This document is the single source of truth for current project state** — what's built, @@ -34,6 +34,17 @@ GREEN is unconditionally a working state. The safe-zone-reached arrival EXIT mec (`bf815cc`) is unaffected and still correct; only the ENTRY trigger needs rework. This is the **top-priority next-session task** — see §0 NEXT and §15g. +✅ **Documentation-only session (14 Jul 2026)** — no code changed. Recorded: a widget-to-hardware +wiring map (`docs/design_intent_register.md` DIR-13 — W1 is a two-stage gate, RPi4 FC-heartbeat +already implemented + RPi5 self-health not yet built; W5 reflects the RPi4-connected battery; +W6 deliberately kept RPi5-direct); depth as a dual-source, W4-selectable input (DIR-14, future +build); test-data/fault-injection flagged as an approaching required workstream, not optional, +needed to validate the FSM rework; and the FSM rework itself reconfirmed as top build priority, +planned together with W1's RPi5-side health gating and the fault-injection capability. Also +confirmed this session: W2 reflects live mission state (observed `ABORTED` after a live abort); +W3's label change to "RETURN TO SAFE" is complete (`9aa5b5d`). See §0 and Changelog, 14 Jul +entries. + > Full narrative for each prior version is in Version History below — not repeated here. --- @@ -97,8 +108,10 @@ GREEN is unconditionally a working state. The safe-zone-reached arrival EXIT mec - All three (Gitea/laptop/RPi5) level at `4e48dc2`. **UNTESTED (visual/UI confirmed, real data not flowing yet):** -- W2 Mission Status — UI confirmed (IDLE state + progress bar). Untested: needs a mission - running. Test: `POST /mission/start` via FastAPI (now available) with a loaded plan, observe widget. +- W2 Mission Status — **partially verified live (14 Jul 2026):** observed `ABORTED` state + correctly reflected after a live abort. Still untested: `RUNNING` state + progress bar during + an actual active mission. Test: `POST /mission/start` via FastAPI (now available) with a + loaded plan, observe widget. - W4 Mission Setup Button — UI confirmed (cyan button, opens setup URL). Untested: needs a setup page served by FastAPI (not yet built — Stage 2b/Phase 6). - W5 Return Budget — UI confirmed (shows pending). Untested: bridge does not yet publish @@ -106,9 +119,10 @@ GREEN is unconditionally a working state. The safe-zone-reached arrival EXIT mec discussion — "shortest path to safety" concept to be defined). **BLOCKED / NOT BUILT:** -- W3 RETURN TO SAFE button — backend now LIVE (`/abort` verified end-to-end). Remaining: - update widget code label from "ABORT MISSION" to "RETURN TO SAFE" and set `FASTAPI_HOST` - to `http://192.168.1.101:8081`. +- ~~W3 RETURN TO SAFE button — label/host~~ **DONE (14 Jul 2026, `9aa5b5d`):** label changed to + "RETURN TO SAFE"; `FASTAPI_HOST` found already correct at `http://192.168.1.101:8081`. + Backend (`/abort`) already verified end-to-end. Remaining: click-test the button itself in + Cockpit (the underlying `/abort` path is already independently verified). - W4 setup page — the page FastAPI would serve is not built (Stage 2b/Phase 6). - W5 return budget — `/return_budget` endpoint deferred to Stage 2b. - W7 Backup Due Notice — not built. Depends on FastAPI `/backup/*` (Stage 2b, Option A design: @@ -116,7 +130,8 @@ GREEN is unconditionally a working state. The safe-zone-reached arrival EXIT mec - `external/rov-return-budget` — not published by cockpit_bridge. W5 budget figure pending. **OPEN ITEMS / HOUSEKEEPING:** -- W3 widget code: update button label to "RETURN TO SAFE"; set `FASTAPI_HOST` constant. +- ~~W3 widget code: update button label to "RETURN TO SAFE"; set `FASTAPI_HOST` constant.~~ + DONE 14 Jul 2026 (`9aa5b5d`). - W6 full test: hardware-gated on Ping2 sonar purchase (Phase 3, ~$280 USD). - RPi5 SSH password: weak dev password. Harden before field deployment (bundled with UFW). - UFW: inactive on RPi5. Deferred to pre-field/pre-remote hardening pass (no online exposure @@ -172,19 +187,37 @@ GREEN is unconditionally a working state. The safe-zone-reached arrival EXIT mec `rov_api` endpoint + data lake variable already built, `2def2b1`) is PAUSED pending this rework — see Open Items above and §15g. Advisory mode's operator resume is also still a placeholder topic pending the proper `rov_api` endpoint. -3. **Auto-recovery** — `failsafe_monitor` should attempt to re-establish the FC link itself, +3. **Test-data / fault-injection capability — APPROACHING REQUIRED, not optional (14 Jul + 2026).** The failsafe logic — and the count-based FSM rework above in particular — cannot be + properly tested without the ability to inject sensor states and simulate + running-vs-failed sensor conditions. Agreed approach is **incremental**: start with the + sensors that matter now (altitude, depth, sonar) and the ability to mark each as running or + failed to exercise FSM transitions — not a full simulation build up front. Near-term + prerequisite for validating item 2. Plan together with item 2 and item 4 below. +4. **W1 RPi5-side autonomy self-health gating (DIR-13, 14 Jul 2026).** W1 is intended as a + two-stage gate: RPi4 FC-heartbeat (stage 1, **already implemented**, `86b2728`) then RPi5 + autonomy-stack self-health (stage 2, **not yet built** — nodes alive, EKF converged, recorder + active, bridge up). Only when both pass should W1 be GREEN. Related to, and should be + planned alongside, item 2 (FSM rework) and item 3 (fault-injection) above — all three are + failsafe/health workstreams that touch the same code. +5. **Auto-recovery** — `failsafe_monitor` should attempt to re-establish the FC link itself, escalating/holding RED only if it cannot. Real-world dives have no operator to restore comms. **Intent now recorded** in DIR's Parked Design Items (11 Jul 2026) — implementation still open. -4. **Dedicated `string cause` field** in `FailsafeStatus.msg`, to replace the message-substring +6. **Dedicated `string cause` field** in `FailsafeStatus.msg`, to replace the message-substring shortcut currently used in `cockpit_bridge`. **Intent now recorded** in DIR's Parked Design Items (11 Jul 2026) — implementation still open. -5. **Operator control surface** (start/pause/stop via `rov_api`) and one-command stack +7. **Operator control surface** (start/pause/stop via `rov_api`) and one-command stack startup + healthcheck. -6. **UFW / SSH pre-field hardening** — see Open Items above. -7. **In-mission AMBER runtime-response** — AMBER means action-required once a mission is +8. **UFW / SSH pre-field hardening** — see Open Items above. +9. **In-mission AMBER runtime-response** — AMBER means action-required once a mission is underway, not just informational; response branches by mode. **Intent now recorded** as a DIR-7 addendum (11 Jul 2026) — AUV's autonomous curtailment logic is unspecified, left for a dedicated design session. +10. **Depth dual-source, operator-selectable input (DIR-14, 14 Jul 2026).** Depth from an RPi4 + sensor (via the FC), an RPi5-direct sensor, or a blend — selected at mission setup (W4) and + carried in the resolved mode profile like `health_role`. Redundancy plus operator choice; + consistent with the standalone-autonomy principle already applied to W6 altitude. + Design-captured intent for a future build, not yet specified in detail. **NEXT (priority order, carried from §12):** 1. **FSM entry-trigger rework — count-based fault-persistence model (TOP PRIORITY, 13 Jul @@ -195,23 +228,28 @@ GREEN is unconditionally a working state. The safe-zone-reached arrival EXIT mec that doesn't clear — immediate commit); all thresholds config-wizard-driven via the resolved mode profile, like `health_role`. The safe-zone-reached arrival EXIT mechanism (`bf815cc`) needs no rework — only the entry trigger. -2. **Safe-zone-reached arrival button (bench scaffolding) — PAUSED, waiting on item 1.** +2. **Test-data / fault-injection capability (14 Jul 2026) — near-term prerequisite for item 1.** + Incremental: start with altitude/depth/sonar and the ability to mark each running or failed, + to exercise FSM transitions. Not a full simulation build up front. Plan together with item 1 + and the W1 RPi5-side health gating item in §0 PARKED. +3. **Safe-zone-reached arrival button (bench scaffolding) — PAUSED, waiting on item 1.** `rov_api`'s `POST /nav/safe_zone_reached` endpoint and the `external/rov-failsafe-state` data lake variable it depends on are built and committed (`2def2b1`); a pre-edit W1 widget backup was made per CREATE-THEN-BACKUP. The widget edit itself is not started — the button would surface FSM state reached via the known-wrong trigger above, so it is meaningless until item 1 lands. Disposable once navigation can raise the real GPS/EKF-derived arrival event on the same permanent topic. See §15g, DIR-7 addendum, and the Parked Design Items. -3. **W3 widget code**: update label to "RETURN TO SAFE", set `FASTAPI_HOST` = - `http://192.168.1.101:8081`, then test W3 end-to-end (button → /abort → FSM, already - verified server-side). -4. **Stage 2b design decisions** (deferred pending Grant): return budget "shortest path to +4. ~~**W3 widget code**: update label, set `FASTAPI_HOST`~~ **DONE (14 Jul 2026, `9aa5b5d`).** + Remaining: click-test the button itself in Cockpit end-to-end (the underlying `/abort` path + is already independently verified server-side). +5. **Stage 2b design decisions** (deferred pending Grant): return budget "shortest path to safety" concept; W7 backup notice (Option A confirmed: server read-only JSON, RPi5 polls outbound). -5. **W2 testing**: test with live mission via `POST /mission/start` (backend now available) - + loaded plan. -6. **Ping2 sonar purchase** (~$280 USD): required for W6 full end-to-end test. -7. **Pre-field hardening pass**: UFW + RPi5 SSH password (bundled, triggered before remote +6. **W2 testing** — **partially done (14 Jul 2026):** `ABORTED` state confirmed live. Remaining: + test `RUNNING` state + progress bar via `POST /mission/start` (backend now available) with a + loaded plan. +7. **Ping2 sonar purchase** (~$280 USD): required for W6 full end-to-end test. +8. **Pre-field hardening pass**: UFW + RPi5 SSH password (bundled, triggered before remote ops/field). **DATA LAKE VARIABLES (19 total, published by cockpit_bridge):** @@ -273,6 +311,7 @@ GREEN is unconditionally a working state. The safe-zone-reached arrival EXIT mec | Version | Date | Changes | |---|---|---| +| 2.27 | 14 Jul 2026 | **Documentation-only session — no code changed.** Records design surfaced in discussion: (1) widget-to-hardware wiring map (`docs/design_intent_register.md` DIR-13) — W1 is a two-stage gate (RPi4 FC-heartbeat, already implemented `86b2728`; RPi5 autonomy self-health, not yet built); W5 reflects the RPi4-connected battery; W2/W3/W4/W6/W8 reflect RPi5; W6 deliberately kept RPi5-direct (standalone-autonomy principle); W7 specced, not built. New §9 wiring table added. (2) Depth as a dual-source, W4-selectable input (DIR-14) — RPi4 sensor, RPi5-direct sensor, or a blend, carried in the resolved mode profile like `health_role`; design-captured, future build. (3) Test-data/fault-injection capability flagged **approaching required, not optional** — the failsafe logic (and the pending count-based FSM rework) cannot be properly tested without injecting sensor states and simulating running-vs-failed conditions; incremental approach agreed (altitude/depth/sonar first, mark running/failed), not a full simulation build up front; near-term prerequisite for validating the FSM rework. (4) FSM rework to the corrected count-based model (`255096f`) reconfirmed as top build priority — `2a3e577`/`bf815cc`'s condition-clear commit logic remains known-wrong pending that rework; the rework, W1's RPi5-side health gating, and the fault-injection capability are related and should be planned together. Also confirmed this session: W2 reflects live mission state (observed `ABORTED` after a live abort — §0 UNTESTED updated); W3's label change to "RETURN TO SAFE" is complete (`9aa5b5d` — §0 Blocked/Open Items/NEXT updated, §16 row marked resolved); `argonaut-api.service` is manual-start and must be started for any `rov_api`/backend testing. §0 Confirmed Working, Blocked/Not Built, Open Items, PARKED, NEXT, §9, §16, and the DIR pointer section all updated. Companion DIR bump: `docs/design_intent_register.md` v1.5 — see that changelog for the full DIR-13/14 text, not repeated here. | | 2.26 | 13 Jul 2026 | **Same-day correction, extending v2.25's record.** The mode-aware recovery built earlier today (`2a3e577`) was found to be internally contradictory: its gate-mode entry trigger commits to `RETURN_TO_SAFE` ON CONDITION-CLEAR, which produced a live state that should not be possible — W1 showing GREEN ("Systems nominal") while the vehicle sat in `RETURN_TO_SAFE` ("Recovering to safe zone"). Corrected in `docs/design_intent_register.md` v1.4 (`255096f`): GREEN is unconditionally a working state; committed recovery is triggered by fault PERSISTENCE (transient tier — config-driven raw failure count, deliberately no time window) or immediate hard-persistence (RED that doesn't clear), never by condition-clear; all thresholds config-wizard-driven via the resolved mode profile like `health_role`. Survives unaffected: `health_role` mode-awareness (`2a3e577`'s subscription mechanism) and the safe-zone-reached arrival EXIT mechanism (`bf815cc`) — only ENTRY into committed recovery was wrong. `2a3e577`'s entry logic is now flagged KNOWN-WRONG pending rework, which is the new top-priority NEXT item, ahead of everything previously listed. Also recorded: (1) the W1 safe-zone-reached button is PAUSED, not abandoned — its `rov_api` endpoint (`POST /nav/safe_zone_reached`) and the `external/rov-failsafe-state` data lake variable are built and committed (`2def2b1`), a pre-edit W1 widget backup was made per CREATE-THEN-BACKUP, but the widget edit itself was not started because the FSM state it would surface is reached via a known-wrong trigger; (2) a recurring `rov_mission` build failure (recurred 2-3 times) was root-caused to stray nested `build`/`install`/`log` directories inside `src/rov-autonomy` on RPi5 (from `colcon build` run from the wrong directory), colliding with the real workspace at `/data/ros2_ws` — fixed by removing the stray directories (gitignored, local cleanup only, no git change); durable guard recorded: `colcon build` only ever from `/data/ros2_ws`. §0 Confirmed Working, Open Items, PARKED, NEXT, Recent Commits all updated; new §15g narrative section. Companion DIR bump: `docs/design_intent_register.md` v1.4 — see that changelog for the full corrected-intent detail, not repeated here. | | 2.25 | 13 Jul 2026 | **Two-part fix session, both surfaced by putting the 11 Jul mode-aware work under load.** (1) `mode_profile_loader` was found never to have been wired into `rov_full.launch.py` despite being committed 7 Jul (`4e48dc2`) — `/rov/mode/profile` had zero publishers at runtime since then, so the entire operating-mode profile system had been dark and `failsafe_monitor`'s `health_role` had been silently running on its gate default the whole time. Fixed by adding the node to the launch file with respawn (`464e17e`), verified live (publisher count 0→1). (2) With the mode system now actually publishing, `failsafe_monitor`'s mode-aware recovery (`2a3e577`, same session — subscribes to the resolved profile, branches condition-clear recovery on `health_role`) surfaced a second gap: gate-mode committed recovery entered `RETURN_TO_SAFE` and could never leave it, because that branch deliberately ignores further condition-clear so recovery runs to completion, and nothing signalled completion. Fixed by a new PERMANENT interface, `/rov/nav/safe_zone_reached` (std_msgs/Bool), that transitions the FSM `RETURN_TO_SAFE`→`NORMAL` on arrival when gate-mode (`bf815cc`), verified live end-to-end on the bench (published the event by hand, watched the FSM release and the `motion_controller` recovery broadcast stop). Today's publisher is temporary bench scaffolding only — real navigation-raised arrival and a temporary W1-contextual operator button are both still to come; see the new Parked Design Item in `docs/design_intent_register.md` v1.3. §0 Confirmed Working, PARKED, and NEXT updated; new §15f narrative section. **Two pre-existing `failsafe_monitor` defects found this session (not caused by it):** `flag_manual_abort` is a one-way latch never reset, permanently shadowing all lower-priority handling (including this session's own new logic) after any single manual abort — field-deployment concern, needs its own session; and `failsafe_monitor` produced no log output in `journalctl` this session, costing diagnostic time. Both added to §0 Open Items and §15f. Companion DIR bump: `docs/design_intent_register.md` v1.3 adds the mode-aware safe-zone-reached Parked Design Item — see that changelog for detail. | | 2.24 | 11 Jul 2026 | **§15d resolved.** Vehicle health / FC-comms-loss fault (discovered 9 Jul, flagged OPEN/SAFETY-CRITICAL in v2.22) is fixed as of four commits today: `86b2728` (unconditional RED on comms loss + `fcu_ever_connected` latch + cause text), `1b0050d` (FSM recovery fix — `RETURN_TO_SAFE` was a terminal trap), `dbe9515` (new `external/rov-failsafe-cause` variable), `3409ae5` (W1 widget shows state + cause text). Verified live end-to-end. Related fault found+fixed same session: `cockpit_bridge` was publishing `failsafe_state` (FSM, 3+) not `assessment_state` (0/1/2) to `rov-failsafe` — the actual cause of that day's "widgets show no data," fixed in `d854641`, compounded by a restart-storm wedging port 9001 (→ CLAUDE.md's one-restart-then-verify-9001 rule). §0 Confirmed Working and Recent Commits updated; PARKED list updated to reflect intent now recorded in the DIR (mode-dependent recovery, auto-recovery, dedicated cause field, AMBER runtime-response — all still open on implementation, closed on design intent). Companion DIR bump: `docs/design_intent_register.md` v1.2 adds the two DIR-7 addenda and a Parked Design Items section — see that changelog for detail, not repeated here. | @@ -450,12 +489,39 @@ context needed. Full trigger-rule text lives in `CLAUDE.md`. gitignored and untracked, so this was a local filesystem cleanup only, no git change. Durable guard: colcon build must only ever be run from /data/ros2_ws, never from inside src/rov-autonomy. Recorded so this is not reintroduced. +- 2026-07-14 — Documentation-only session, no code changed. Recorded a widget-to-hardware + wiring map (docs/design_intent_register.md DIR-13): W1 is a two-stage health gate — RPi4 + FC-heartbeat MUST pass first (already implemented, 86b2728, 11 Jul), then RPi5 + autonomy-stack self-health (not yet built) — only when both pass is W1 GREEN. W5 reflects + the RPi4-connected battery. W2/W3/W4/W6/W8 reflect the RPi5 stack; W6 altitude is + deliberately kept RPi5-direct, consistent with the standalone-autonomy principle (BlueOS/ + Cockpit integration is the only current external dependency). W7 specced, not built. New + wiring table added to §9. Also recorded depth as a dual-source, operator-selectable input + (DIR-14): RPi4 sensor (via the FC) or an RPi5-direct sensor, or a blend, selected at mission + setup (W4) and carried in the resolved mode profile like health_role. Redundancy plus + operator choice; consistent with the same standalone-autonomy principle as W6. Design- + captured intent for a future build, not yet specified in detail. +- 2026-07-14 — FLAGGED: test-data / fault-injection capability is now an approaching required + workstream, not optional. The failsafe logic — and the pending count-based FSM rework in + particular — cannot be properly tested without the ability to inject sensor states and + simulate running-vs-failed sensor conditions. Agreed approach is incremental: start with the + sensors that matter now (altitude, depth, sonar) and the ability to mark each as running or + failed to exercise failsafe state transitions, not a full simulation build up front. Near- + term prerequisite for validating the FSM rework. +- 2026-07-14 — Confirmed current top build priority: the failsafe FSM rework to the corrected + count-based fault-persistence model (DIR correction 255096f). The condition-clear commit + logic in 2a3e577/bf815cc remains known-wrong pending that rework. This rework, W1's RPi5-side + health gating (DIR-13, second stage of the two-stage gate), and the test-data/fault-injection + capability above are related workstreams that touch the same code and should be planned + together. Also verified this session: W2 reflects live mission state (observed ABORTED after + a live abort); W3's label change to RETURN TO SAFE is complete (9aa5b5d). Reminder recorded: + argonaut-api.service is manual-start and must be started for any rov_api/backend testing. --- ## Design Intent Register — pointer -The full Design Intent Register (DIR-1 through DIR-12) lives in **`docs/design_intent_register.md`**, +The full Design Intent Register (DIR-1 through DIR-14) lives in **`docs/design_intent_register.md`**, git-tracked in the repo, not duplicated here. That file is the source of truth for *why* — read it before any design/architecture decision. @@ -471,6 +537,10 @@ read it before any design/architecture decision. - **DIR-5/5a/5b** — return-to-safe is mission-bounded, vehicle-layer, and mode-dependent (AUV automatic, ROV alert+override); operator override continues the mission, it does not pause it. +- **DIR-13/DIR-14 (14 Jul 2026)** — DIR-13: widget-to-hardware ownership map (which of RPi4/RPi5 + each widget reflects; W1 is a two-stage FC-heartbeat + autonomy-self-health gate). DIR-14: + depth as a dual-source, W4-selectable input (RPi4 sensor / RPi5-direct sensor / blend). + Design-captured; see §9 for the wiring table and §0 PARKED for build status. --- @@ -801,6 +871,23 @@ between v2.21 (8 vars, this table) and v2.22 (19 vars, §0's table) before this > requires a live mission, FastAPI backend, and/or Ping2 hardware depending on the widget. > W6 full test requires Ping2 sonar hardware. W7 not started. +### Widget-to-Hardware Wiring (owner intent — DIR-13, 14 Jul 2026) + +Which physical subsystem each widget actually reflects — not always obvious from the UI alone. +Full intent record: `docs/design_intent_register.md` DIR-13. Keep this table in sync with that +entry. + +| Widget | Reflects | Subsystem | Notes | +|---|---|---|---| +| W1 — System Health Indicator | Vehicle health (two-stage gate) | **RPi4 + RPi5** | Stage 1: RPi4 FC heartbeat MUST pass first — **implemented** (`86b2728`). Stage 2: RPi5 autonomy-stack self-health — **not yet built**. GREEN only when both pass. | +| W2 — Mission Status | `mission_executor` | RPi5 | — | +| W3 — Return To Safe button | `failsafe_monitor` via `/rov/mission/abort` | RPi5 | — | +| W4 — Mission Setup button | FastAPI setup page | RPi5 | Setup page itself not yet built. | +| W5 — Return Budget | Battery | **RPi4** | Battery is connected to the RPi4 (via MAVROS/Pixhawk), not the RPi5. | +| W6 — Altitude | Ping2 sonar | RPi5 | **Deliberately** kept RPi5-direct, not routed via RPi4 — standalone-autonomy principle (BlueOS/Cockpit integration is the only current external dependency). | +| W7 — Backup Due Notice | Backup status | RPi5 (+ server) | Specced (Option A), not built. | +| W8 — Mode Indicator | `mode_profile_loader` | RPi5 | — | + ### How to Install a Widget 1. Open Cockpit native desktop app @@ -1412,8 +1499,9 @@ executables in `lib//`. This is now the standard build command. | DVL absent | X/Y position dead-reckoned from IMU — drifts | High — Phase 7 | | Ping2 sonar not purchased | W6 full test blocked; downward altitude not flowing | Phase 3 (~$280 USD) | | FastAPI backend not built | W3 abort, W4 setup, W5 budget, W7 backup all blocked | High — Phase 3 Stage 2 | -| W3 button label not updated | Widget still shows "ABORT MISSION"; should be "RETURN TO SAFE" | Next session | +| ~~W3 button label not updated~~ | RESOLVED 14 Jul 2026 (`9aa5b5d`) — label now "RETURN TO SAFE" | Closed | | ~~Widget JSON not in Gitea~~ | RESOLVED — W6 committed as `w6_altitude.json`, probe widget removed (`785ec56`), see §12 | Closed | +| Test-data / fault-injection capability absent | Failsafe logic (incl. pending FSM rework) cannot be properly tested without injecting sensor states / simulating running-vs-failed conditions. Incremental approach agreed: altitude/depth/sonar first. | Near-term — prerequisite for FSM rework validation | | RPi5 weak SSH password | Password auth enabled, Tailscale service disabled but installed | Pre-field | | RPi5 thermal in sealed enclosure | Conduction cooling path unresolved | Phase 3 | | ML inference compute | RPi5 has no GPU. ONNX/TFLite on-device or Jetson Orin Nano. | Phase 5 |