From ca44a258f056591484a75b2dca26f1868874053b Mon Sep 17 00:00:00 2001 From: Evans Klenam Kwashie-Seyram Date: Wed, 11 Nov 2026 01:35:38 +0000 Subject: [PATCH 01/23] feat(base_msgs): add I8 base controller interfaces Signed-off-by: Evans Klenam Kwashie-Seyram --- .gitignore | 3 + STATE.md | 4 +- compatibility/jazzy.json | 598 ++++++++++++++++++ ros2/openamr_base_msgs/CMakeLists.txt | 22 + ros2/openamr_base_msgs/CONTRACT.md | 292 +++++++++ ros2/openamr_base_msgs/README.md | 28 + ros2/openamr_base_msgs/msg/BaseAuxStatus.msg | 78 +++ ros2/openamr_base_msgs/msg/BaseFault.msg | 103 +++ .../msg/BaseMotionConstraint.msg | 12 + ros2/openamr_base_msgs/msg/BaseStatus.msg | 159 +++++ .../msg/BaseSubsystemStatus.msg | 27 + ros2/openamr_base_msgs/package.xml | 33 + tests/test_base_msgs.py | 237 +++++++ 13 files changed, 1595 insertions(+), 1 deletion(-) create mode 100755 ros2/openamr_base_msgs/CMakeLists.txt create mode 100755 ros2/openamr_base_msgs/CONTRACT.md create mode 100755 ros2/openamr_base_msgs/README.md create mode 100755 ros2/openamr_base_msgs/msg/BaseAuxStatus.msg create mode 100755 ros2/openamr_base_msgs/msg/BaseFault.msg create mode 100755 ros2/openamr_base_msgs/msg/BaseMotionConstraint.msg create mode 100755 ros2/openamr_base_msgs/msg/BaseStatus.msg create mode 100755 ros2/openamr_base_msgs/msg/BaseSubsystemStatus.msg create mode 100755 ros2/openamr_base_msgs/package.xml create mode 100755 tests/test_base_msgs.py diff --git a/.gitignore b/.gitignore index 84d8c1e..0a4fa9f 100644 --- a/.gitignore +++ b/.gitignore @@ -1,2 +1,5 @@ .verification/ __pycache__/ +build/ +install/ +log/ diff --git a/STATE.md b/STATE.md index 68cf7e8..5188553 100644 --- a/STATE.md +++ b/STATE.md @@ -10,6 +10,7 @@ The PR evidence check fails when STATE.md exists and a PR neither updates it nor - Readiness: R1 (evidence: ROS 2 Jazzy workflow running `tools/verify.sh` on main, run 37936438992) - Owner role: software-lead - Verification: `bash tools/verify.sh`; last PASS on main at 87ab8a9 (2026-10-09), run 37936438992 +- I8 verification: `bash tools/verify.sh` passed on the working tree (2026-11-11); evidence at `.verification/run.LmU15W`. ## Current work @@ -17,6 +18,7 @@ The PR evidence check fails when STATE.md exists and a PR neither updates it nor |---|---|---|---| | C10 dataset quality gate | PR #25 | draft / synthetic evidence only | Work-package owner reviews placement and supplies real-episode evidence | | Shared rules v2 (rollout step a, pilot) | PR #26 | in review | merge, then step (b) pin the harness | +| I8 base-controller interfaces | Issue #30 / `feat/i8-base-controller-msgs` | implementation and local verification passed (2026-11-11); contract remains proposed | owner review and resolution of open contract decisions | ## Decisions this repository implements @@ -33,5 +35,5 @@ The PR evidence check fails when STATE.md exists and a PR neither updates it nor ## Not verified -- This step-(a) PR changes repository guidance only; it does not run ROS, DDS, hardware or production acceptance tests. +- I8 verification is local ROS 2 Jazzy software verification only; firmware integration, physical robot, safety-chain and hardware validation are not established (2026-11-11). - No physical robot, safety-chain, released binary or cross-version deployment evidence is claimed. diff --git a/compatibility/jazzy.json b/compatibility/jazzy.json index d6bee9a..bffa6ca 100644 --- a/compatibility/jazzy.json +++ b/compatibility/jazzy.json @@ -1,6 +1,604 @@ { "format_version": 1, "packages": { + "openamr_base_msgs": { + "interfaces": { + "msg/BaseAuxStatus": { + "constants": { + "msg/CONTRACT_VERSION": { + "type": "uint16", + "value": 1 + }, + "msg/HEAD_LIGHT_OFF": { + "type": "uint8", + "value": 1 + }, + "msg/HEAD_LIGHT_ON": { + "type": "uint8", + "value": 2 + }, + "msg/HEAD_LIGHT_UNKNOWN": { + "type": "uint8", + "value": 0 + }, + "msg/LIFT_HOMING_UNKNOWN": { + "type": "uint8", + "value": 0 + }, + "msg/LIFT_LINK_LOST": { + "type": "uint8", + "value": 2 + }, + "msg/LIFT_LINK_OK": { + "type": "uint8", + "value": 1 + }, + "msg/LIFT_LINK_UNKNOWN": { + "type": "uint8", + "value": 0 + }, + "msg/LIFT_MOTION_DOWN": { + "type": "uint8", + "value": 3 + }, + "msg/LIFT_MOTION_STOPPED": { + "type": "uint8", + "value": 1 + }, + "msg/LIFT_MOTION_UNKNOWN": { + "type": "uint8", + "value": 0 + }, + "msg/LIFT_MOTION_UP": { + "type": "uint8", + "value": 2 + }, + "msg/OBS_NO": { + "type": "uint8", + "value": 1 + }, + "msg/OBS_UNKNOWN": { + "type": "uint8", + "value": 0 + }, + "msg/OBS_YES": { + "type": "uint8", + "value": 2 + }, + "msg/SECOND_ESTOP_PRESSED": { + "type": "uint8", + "value": 2 + }, + "msg/SECOND_ESTOP_RELEASED": { + "type": "uint8", + "value": 1 + }, + "msg/SECOND_ESTOP_UNKNOWN": { + "type": "uint8", + "value": 0 + }, + "msg/STOP_L1000": { + "type": "uint8", + "value": 2 + }, + "msg/STOP_L1175": { + "type": "uint8", + "value": 3 + }, + "msg/STOP_L1350": { + "type": "uint8", + "value": 4 + }, + "msg/STOP_NONE": { + "type": "uint8", + "value": 1 + }, + "msg/STOP_UNKNOWN": { + "type": "uint8", + "value": 0 + } + }, + "type_hash": "RIHS01_fe993c816f75991ac226947a076c65c167fa9441fd6fb620ce31975defe93ecd" + }, + "msg/BaseFault": { + "constants": { + "msg/BASE_COMMAND_TIMEOUT": { + "type": "uint16", + "value": 18001 + }, + "msg/BASE_HOST_LINK_LOST": { + "type": "uint16", + "value": 18002 + }, + "msg/BMS_COMM_LOST": { + "type": "uint16", + "value": 18008 + }, + "msg/BMS_FAULT": { + "type": "uint16", + "value": 18009 + }, + "msg/CHARGER_FAULT": { + "type": "uint16", + "value": 18021 + }, + "msg/CHARGE_INTERLOCK_FAULT": { + "type": "uint16", + "value": 18022 + }, + "msg/CONTRACT_MISMATCH": { + "type": "uint16", + "value": 18013 + }, + "msg/DRIVER_COMM_LOST": { + "type": "uint16", + "value": 18003 + }, + "msg/DRIVER_FAULT": { + "type": "uint16", + "value": 18004 + }, + "msg/DRIVER_FEEDBACK_INVALID": { + "type": "uint16", + "value": 18005 + }, + "msg/DRIVE_CONFIG_MISMATCH": { + "type": "uint16", + "value": 18023 + }, + "msg/ENCODER_ODOMETRY_FAULT": { + "type": "uint16", + "value": 18006 + }, + "msg/ESTOP_DIAGNOSTIC_ACTIVE": { + "type": "uint16", + "value": 18018 + }, + "msg/ESTOP_DIAGNOSTIC_UNKNOWN": { + "type": "uint16", + "value": 18028 + }, + "msg/FAULT_LIST_OVERFLOW": { + "type": "uint16", + "value": 18015 + }, + "msg/IMU_FAULT": { + "type": "uint16", + "value": 18007 + }, + "msg/LIFECYCLE_ACKNOWLEDGED": { + "type": "uint8", + "value": 3 + }, + "msg/LIFECYCLE_ACTIVE": { + "type": "uint8", + "value": 1 + }, + "msg/LIFECYCLE_CLEARED": { + "type": "uint8", + "value": 4 + }, + "msg/LIFECYCLE_LATCHED": { + "type": "uint8", + "value": 2 + }, + "msg/LIFECYCLE_UNKNOWN": { + "type": "uint8", + "value": 0 + }, + "msg/NONE": { + "type": "uint16", + "value": 0 + }, + "msg/OBS_NO": { + "type": "uint8", + "value": 1 + }, + "msg/OBS_UNKNOWN": { + "type": "uint8", + "value": 0 + }, + "msg/OBS_YES": { + "type": "uint8", + "value": 2 + }, + "msg/PNOZ_DIAGNOSTIC_NOT_ENABLED": { + "type": "uint16", + "value": 18012 + }, + "msg/RESET_INPUT_HIGH": { + "type": "uint16", + "value": 18019 + }, + "msg/SAFETY_INPUT_CONTRADICTORY": { + "type": "uint16", + "value": 18011 + }, + "msg/SAFETY_INPUT_UNKNOWN": { + "type": "uint16", + "value": 18010 + }, + "msg/SEVERITY_FAULT": { + "type": "uint8", + "value": 2 + }, + "msg/SEVERITY_UNKNOWN": { + "type": "uint8", + "value": 0 + }, + "msg/SEVERITY_WARNING": { + "type": "uint8", + "value": 1 + }, + "msg/SOURCE_BMS": { + "type": "uint8", + "value": 6 + }, + "msg/SOURCE_COMMAND": { + "type": "uint8", + "value": 1 + }, + "msg/SOURCE_CONFIG": { + "type": "uint8", + "value": 10 + }, + "msg/SOURCE_ENCODER": { + "type": "uint8", + "value": 4 + }, + "msg/SOURCE_HOST_LINK": { + "type": "uint8", + "value": 2 + }, + "msg/SOURCE_IMU": { + "type": "uint8", + "value": 5 + }, + "msg/SOURCE_LIFT": { + "type": "uint8", + "value": 9 + }, + "msg/SOURCE_MOTOR_DRIVER": { + "type": "uint8", + "value": 3 + }, + "msg/SOURCE_RANGE_SENSOR": { + "type": "uint8", + "value": 8 + }, + "msg/SOURCE_RESET": { + "type": "uint8", + "value": 11 + }, + "msg/SOURCE_SAFETY_INPUT": { + "type": "uint8", + "value": 7 + }, + "msg/SOURCE_UNKNOWN": { + "type": "uint8", + "value": 0 + }, + "msg/TRANSPORT_FAILURE": { + "type": "uint16", + "value": 18014 + } + }, + "type_hash": "RIHS01_f799c6e06fecb7e3f0b3281d1cc26b809a01ac78aa4b30fa05c87641b1c7b665" + }, + "msg/BaseMotionConstraint": { + "constants": { + "msg/TYPE_LIFT_HOLD": { + "type": "uint8", + "value": 4 + }, + "msg/TYPE_SPEED_LIMIT": { + "type": "uint8", + "value": 1 + }, + "msg/TYPE_TRAVEL_INHIBIT_FORWARD": { + "type": "uint8", + "value": 2 + }, + "msg/TYPE_TRAVEL_INHIBIT_REVERSE": { + "type": "uint8", + "value": 3 + }, + "msg/TYPE_UNKNOWN": { + "type": "uint8", + "value": 0 + } + }, + "type_hash": "RIHS01_9dfdbc2bba5801be49c01b3ad4b8a486461427b0651f8e073cddc18074793455" + }, + "msg/BaseStatus": { + "constants": { + "msg/APPLIED_COMMAND_INHIBITED": { + "type": "uint8", + "value": 3 + }, + "msg/APPLIED_COMMAND_OK": { + "type": "uint8", + "value": 1 + }, + "msg/APPLIED_COMMAND_TIMEOUT": { + "type": "uint8", + "value": 2 + }, + "msg/APPLIED_COMMAND_UNKNOWN": { + "type": "uint8", + "value": 0 + }, + "msg/COMMAND_ACCEPTANCE_ACCEPTING": { + "type": "uint8", + "value": 2 + }, + "msg/COMMAND_ACCEPTANCE_REJECTING": { + "type": "uint8", + "value": 1 + }, + "msg/COMMAND_ACCEPTANCE_UNKNOWN": { + "type": "uint8", + "value": 0 + }, + "msg/CONTRACT_VERSION": { + "type": "uint16", + "value": 1 + }, + "msg/HOST_LINK_LOST": { + "type": "uint8", + "value": 2 + }, + "msg/HOST_LINK_OK": { + "type": "uint8", + "value": 1 + }, + "msg/HOST_LINK_UNKNOWN": { + "type": "uint8", + "value": 0 + }, + "msg/OBS_NO": { + "type": "uint8", + "value": 1 + }, + "msg/OBS_UNKNOWN": { + "type": "uint8", + "value": 0 + }, + "msg/OBS_YES": { + "type": "uint8", + "value": 2 + }, + "msg/OPERATING_STATE_CHARGER_FAULT": { + "type": "uint8", + "value": 5 + }, + "msg/OPERATING_STATE_CHARGING": { + "type": "uint8", + "value": 4 + }, + "msg/OPERATING_STATE_INHIBITED": { + "type": "uint8", + "value": 3 + }, + "msg/OPERATING_STATE_LOCKED": { + "type": "uint8", + "value": 1 + }, + "msg/OPERATING_STATE_RUN": { + "type": "uint8", + "value": 2 + }, + "msg/OPERATING_STATE_UNKNOWN": { + "type": "uint8", + "value": 0 + }, + "msg/POWERED_DEBUG_DISABLED": { + "type": "uint8", + "value": 1 + }, + "msg/POWERED_DEBUG_ENABLED": { + "type": "uint8", + "value": 2 + }, + "msg/POWERED_DEBUG_UNKNOWN": { + "type": "uint8", + "value": 0 + }, + "msg/READINESS_NOT_READY": { + "type": "uint8", + "value": 1 + }, + "msg/READINESS_READY": { + "type": "uint8", + "value": 2 + }, + "msg/READINESS_UNKNOWN": { + "type": "uint8", + "value": 0 + }, + "msg/REASON_BMS_FAULT": { + "type": "uint32", + "value": 8 + }, + "msg/REASON_CHARGER_FAULT": { + "type": "uint32", + "value": 32 + }, + "msg/REASON_CHARGE_INTERLOCK": { + "type": "uint32", + "value": 64 + }, + "msg/REASON_COMMS_LOST": { + "type": "uint32", + "value": 4 + }, + "msg/REASON_DRIVE_COMMS": { + "type": "uint32", + "value": 256 + }, + "msg/REASON_DRIVE_CONFIG": { + "type": "uint32", + "value": 512 + }, + "msg/REASON_DRIVE_FAULT": { + "type": "uint32", + "value": 128 + }, + "msg/REASON_ESTOP_DIAG_ACTIVE": { + "type": "uint32", + "value": 2 + }, + "msg/REASON_ESTOP_DIAG_UNKNOWN": { + "type": "uint32", + "value": 2048 + }, + "msg/REASON_INPUT_INVALID": { + "type": "uint32", + "value": 16 + }, + "msg/REASON_PNOZ_DIAGNOSTIC_NOT_ENABLED": { + "type": "uint32", + "value": 1 + }, + "msg/REASON_RESET_INPUT_HIGH": { + "type": "uint32", + "value": 1024 + }, + "msg/RECOVERY_NOT_REQUIRED": { + "type": "uint8", + "value": 1 + }, + "msg/RECOVERY_REQUIRED": { + "type": "uint8", + "value": 2 + }, + "msg/RECOVERY_UNKNOWN": { + "type": "uint8", + "value": 0 + }, + "msg/RESET_CAUSE_BROWNOUT": { + "type": "uint8", + "value": 2 + }, + "msg/RESET_CAUSE_PIN": { + "type": "uint8", + "value": 5 + }, + "msg/RESET_CAUSE_POWER_ON": { + "type": "uint8", + "value": 1 + }, + "msg/RESET_CAUSE_SOFTWARE": { + "type": "uint8", + "value": 4 + }, + "msg/RESET_CAUSE_UNKNOWN": { + "type": "uint8", + "value": 0 + }, + "msg/RESET_CAUSE_WATCHDOG": { + "type": "uint8", + "value": 3 + }, + "msg/STATE_DEGRADED": { + "type": "uint8", + "value": 3 + }, + "msg/STATE_FAULTED": { + "type": "uint8", + "value": 4 + }, + "msg/STATE_INITIALIZING": { + "type": "uint8", + "value": 1 + }, + "msg/STATE_READY": { + "type": "uint8", + "value": 2 + }, + "msg/STATE_UNKNOWN": { + "type": "uint8", + "value": 0 + } + }, + "type_hash": "RIHS01_05105510cbea27090feb2696cbfc859b0218d69d49865aa1ccb4093e7c9d091e" + }, + "msg/BaseSubsystemStatus": { + "constants": { + "msg/STATE_ABSENT": { + "type": "uint8", + "value": 1 + }, + "msg/STATE_DEGRADED": { + "type": "uint8", + "value": 3 + }, + "msg/STATE_OK": { + "type": "uint8", + "value": 4 + }, + "msg/STATE_STALE": { + "type": "uint8", + "value": 2 + }, + "msg/STATE_UNKNOWN": { + "type": "uint8", + "value": 0 + }, + "msg/SUBSYSTEM_BMS": { + "type": "uint8", + "value": 4 + }, + "msg/SUBSYSTEM_CLIFF_FRONT": { + "type": "uint8", + "value": 9 + }, + "msg/SUBSYSTEM_CLIFF_REAR": { + "type": "uint8", + "value": 10 + }, + "msg/SUBSYSTEM_ENCODERS": { + "type": "uint8", + "value": 2 + }, + "msg/SUBSYSTEM_IMU": { + "type": "uint8", + "value": 3 + }, + "msg/SUBSYSTEM_LIFT_NODE_LINK": { + "type": "uint8", + "value": 11 + }, + "msg/SUBSYSTEM_MOTOR_DRIVER": { + "type": "uint8", + "value": 1 + }, + "msg/SUBSYSTEM_RANGE_FRONT_LEFT": { + "type": "uint8", + "value": 5 + }, + "msg/SUBSYSTEM_RANGE_FRONT_RIGHT": { + "type": "uint8", + "value": 6 + }, + "msg/SUBSYSTEM_RANGE_REAR_LEFT": { + "type": "uint8", + "value": 7 + }, + "msg/SUBSYSTEM_RANGE_REAR_RIGHT": { + "type": "uint8", + "value": 8 + }, + "msg/SUBSYSTEM_UNKNOWN": { + "type": "uint8", + "value": 0 + } + }, + "type_hash": "RIHS01_c100efb61a24e2ebe9894e396bc5bb9bb0a43c4ca7e6b594cd1c1cc1caceae0d" + } + }, + "package_version": "0.0.0" + }, "openamr_nav_msgs": { "interfaces": { "msg/ActiveConstraint": { diff --git a/ros2/openamr_base_msgs/CMakeLists.txt b/ros2/openamr_base_msgs/CMakeLists.txt new file mode 100755 index 0000000..471ebed --- /dev/null +++ b/ros2/openamr_base_msgs/CMakeLists.txt @@ -0,0 +1,22 @@ +cmake_minimum_required(VERSION 3.8) +project(openamr_base_msgs) + +find_package(ament_cmake REQUIRED) +find_package(rosidl_default_generators REQUIRED) + +find_package(builtin_interfaces REQUIRED) +find_package(std_msgs REQUIRED) + +rosidl_generate_interfaces(${PROJECT_NAME} + "msg/BaseStatus.msg" + "msg/BaseAuxStatus.msg" + "msg/BaseFault.msg" + "msg/BaseSubsystemStatus.msg" + "msg/BaseMotionConstraint.msg" + DEPENDENCIES + builtin_interfaces + std_msgs +) + +ament_export_dependencies(rosidl_default_runtime) +ament_package() diff --git a/ros2/openamr_base_msgs/CONTRACT.md b/ros2/openamr_base_msgs/CONTRACT.md new file mode 100755 index 0000000..1138fd9 --- /dev/null +++ b/ros2/openamr_base_msgs/CONTRACT.md @@ -0,0 +1,292 @@ +# Runtime contract + +Status: **Proposed**, not approved. Source: I8 Base Controller Interface Proposal rev 4 +(10 Nov 2026), with the 6 Nov frozen fields preserved. E-01 rev4-derived field mappings, +message choices, enums, fault lifecycle and lift semantics remain proposals wherever Section 8 +of rev4 leaves a decision open. Nothing marked TODO or proposed in the .msg files is frozen. + +Scope: base-controller status only. This is not a whole-robot readiness or safety interface, +and it is not a command or session protocol. It reports what the base-controller firmware +observes and the state it is in. It does not actuate, reset or validate the E-stop, and it does +not claim the robot is safe. The hardwired chain (two E-stops, Pilz PNOZ s3, K1/K2, brake +release) and the recovery sequence are owned by E-01 +([openamr-platform-fw#17](https://github.com/openAMRobot/openamr-platform-fw/issues/17), +[#6](https://github.com/openAMRobot/openamr-platform-fw/issues/6)). Commands into the base +controller (UI Stop, UI Resume, Jetson Stop release, charge command, charger acknowledge) and the +session challenge and sequence rules (E-01 section 3) are part of the I8 firmware/host contract. +This package only reports their result. + +## Topics and producers + +| Topic | Message | Producer | Consumers | +|---|---|---|---| +| `/base/status` | `BaseStatus` | base-controller firmware (Teensy Gate A, STM32H723ZG Gate B), [openamr-platform-fw#10](https://github.com/openAMRobot/openamr-platform-fw/issues/10) | `navigation_status_node.py` in openamr-platform-sw, operator UI (openamrobot-ui #54), manipulation (openamrobot-manipulation #7), diagnostics, logging, tests | +| `/base/aux_status` | `BaseAuxStatus` | base-controller firmware, relayed from the lift node CTL-017 over CAN3 ([openamr-platform-fw#12](https://github.com/openAMRobot/openamr-platform-fw/issues/12), D17) | same as above | + +Owners for each producer and consumer are recorded in the PR description. + +## QoS and publish behavior + +The two frozen topics are /base/status and /base/aux_status. Both use reliable, +transient-local, depth-1 QoS. Publish on field change plus the agreed heartbeat: + +- /base/status: 10 Hz, stale after 0.5 s. +- /base/aux_status: 5 Hz, stale after 0.6 s. + +No separate /base/stopped topic, QoS, rate or timeout is included in this candidate. The source +and transport of fresh base-stopped evidence required by the lift interlock remain open under +Decisions 1 and 8; a retained status snapshot must never be treated as proof of current standstill. + +## Freshness and UNKNOWN rules + +- Freshness is computed from the consumer's **local receipt time** of the latest message. + `header.stamp` is ROS time when available and is diagnostic only. Use `monotonic_us` for + controller-local elapsed-time calculations; never compare it across boots. +- No stale value is published. Staleness is the absence of timely messages. +- A retained message received on subscription does not show the publisher is alive. Treat the + stream as live only after a further message arrives within the stale threshold. A further + message shows the publisher is producing messages, not that the controller is healthy. +- Every enum's `0` is `UNKNOWN` (or the conservative reading). An unset, stale or unavailable + value is never read as healthy, safe or as an observed E-stop. +- `UNKNOWN` (a valid message that cannot determine a value) is different from malformed (a + message that breaks the schema or contradicts itself). Malformed is a failure, never mapped + to `UNKNOWN` or nominal. A typed ROS publisher cannot emit a malformed message, so this is + tested with a validator on raw data. +- `boot_id` and `sequence` detect publisher restarts and sequence gaps. Consumers also check + `contract_version`. + +## E-01 operating state and latches (BaseStatus) + +The following E-01 rev4-derived operating-state and latch mapping is a proposal pending +Decision 2 approval. It must not be treated as an approved I8 consumer contract. + +| Field | Meaning | Not the same as | +|---|---|---| +| `operating_state` | `LOCKED`, `RUN`, `INHIBITED`, `CHARGING`, `CHARGER_FAULT`; `UNKNOWN` until determined. Boot lands in `LOCKED`; there is no `BOOT` state | `state` (generic health summary from fault severity) | +| `readiness` | the readiness latch `reset_seen`: set only by a qualified short physical RESET press; cleared by E-01 invalidation/recovery events | `reset_pressed` (the RESET input level, which also reads high for an open wire) | +| `ui_stop_active` | UI Stop software inhibit, held by the controller; survives host reconnection | `host_stop_active`, `host_link` | +| `host_stop_active` | Jetson Stop: asserted at boot and on session loss | `host_link` (a connected Jetson can still assert Stop) | +| `command_acceptance` | `ACCEPTING` only while motion commands are accepted (RUN, current session) | `readiness` | +| `recovery` | a physical RESET or other recovery is still required | a fault being cleared | +| `first_reason`, `reason_mask` | first fault reason for the current LOCKED/CHARGER_FAULT episode; `reason_mask` contains active fault reasons only | fault history or UI Stop state | +| `session_epoch_counter` | paired with `boot_id`; starts at 0 each boot and increments once per detected Jetson session loss; a fresh challenge-response establishes the current epoch | a command sequence number | + +`INHIBITED` is never reported as `SAFETY_STOPPED`; that term is reserved for the hardwired +chain. RUN needs `readiness` ready, `ui_stop_active` no, `host_stop_active` no and every other +RUN condition. Seeing `RUN` here is a report, not authority to command motion. + +### Fault and inhibit effects on operating state + +A recorded `BaseFault` does **not** automatically imply `LOCKED`. `operating_state` reports the +actual E-01 state after applying the transition table; `severity`, `faults` and `reason_mask` +are diagnostics and must not be used as a substitute state machine. + +| Condition | Required reporting / effect | +|---|---| +| Boot/reset | Enter `LOCKED`; report the reset cause in `reset_cause`, not as a `BOOT_*` fault. | +| Jetson session loss (`COMMS_LOST`) | Assert `host_stop_active`, clear readiness as specified by E-01, and enter `LOCKED`. | +| UI Stop | Report `ui_stop_active`; from RUN enter `INHIBITED`. It is an inhibit, not a `BaseFault`. | +| UI Resume in INHIBITED | Clear ui_stop_active; transition to RUN only when readiness is set, fresh valid base-stopped evidence is available from an approved source, SAFETY_OK and every other E-01 RUN condition are satisfied. Otherwise remain inhibited. The base-stopped source/transport is not defined by this package candidate. | +| WCM_FAULT while `LOCKED`, `RUN` or `INHIBITED` | Record the charger fault and refuse/block charging. It does not by itself force `RUN` to `LOCKED` or prevent RUN. | +| WCM_FAULT while `CHARGING` | Enter `CHARGER_FAULT` and apply the E-01 charging fault handling. | +| Charge-interlock failure while `CHARGING` (including SAFETY_OK high after the 500 ms window) | Enter `CHARGER_FAULT`; acknowledgement does not prove KCHG opened. | +| Fresh PNOZ Y32/SAFETY_OK low outside the expected CHARGING condition | Report the diagnostic and apply the E-01 transition to `LOCKED`; while CHARGING, low is expected and is not this fault. | +| Motion/drive, BMS, encoder, IMU or other input faults | Apply the specific E-01 Fault and Inhibit Matrix row. Do not infer a transition from the mere presence of a fault entry; where the matrix does not require a state transition, preserve the current state and report the fault. | + +The fault list may include active, latched, acknowledged and cleared entries. A fault being +present in history does not mean its condition is active or that it currently inhibits motion. +`inhibits_motion` is the entry's explicit effect, not a blanket consequence of `code != NONE`. + +Base-stopped evidence is not defined as a message in this candidate. The lift interlock must +consume fresh, valid evidence from an explicitly approved source; it must not infer standstill +from a retained /base/status or /base/aux_status snapshot. + +## Versioning + +BaseStatus.contract_version and BaseAuxStatus.contract_version are set by the producer +to their message's CONTRACT_VERSION. Both are 1, as required by the frozen I8 contract. +The v3 candidate's BaseStatus=2 was not adopted: contract version 1 is frozen. Additional +E-01-derived fields remain proposed under Decision 2; they do not silently change the frozen +version field. + +- Adding a fault code or enum constant does not require a version bump only after the registry + owner confirms that policy. +- Adding, removing, renaming, reordering or retyping a message field requires owner review and + the applicable interface versioning decision. +- Fault codes are append-only: never renumbered or reused. +- A consumer that sees an unsupported contract_version degrades safely. + +## Lift position provenance (Decision 13 — proposed) + +BaseAuxStatus carries two separate position values: + +- lift_measured_position_m: independent physical measurement. +- lift_declared_position_m: actuator/controller-declared position. + +Each has its own validity field. A declared position is never a substitute for a measured +position. The host adapter may publish lift_joint only from a valid independent measured +position. Homing state, source identity, freshness details, raw-device fault encoding, +mapping to the central fault registry, and the threshold/action for measured-versus-declared +disagreement remain unresolved. The fields in this draft are a working representation, not +approval of a particular sensor, encoder, CAN object or firmware owner. + +The lift interlock requirement is base confirmed stopped AND both arms in the approved safe +pose (stowed or carry). UNKNOWN, invalid or stale base/arm observations do not satisfy either +condition. The exact carry pose and the robot enforcement owner/handshake remain open. + +## Field validity + +- `applied_command_*`: the velocity sent to the motor driver after limits, ramp and timeout. + It is never a held or replayed command; on timeout the base stops. A stale `/cmd_vel` is + non-latching (E-01 R7): zero velocity, no state change. A lost Jetson session is latching + (T5) and shows as `LOCKED`, `host_stop_active`, and `readiness` not ready. +- lift_measured_position_m is the independent physical measurement and is meaningful only + when lift_measured_position_valid == OBS_YES. A host adapter may publish lift_joint only from + this valid measured value, never from lift_declared_position_m. +- lift_declared_position_m remains a separate controller/actuator declaration. Its source, + validity semantics and disagreement threshold against measured position remain open (Decision 13). +- lift_raw_device_fault_code and lift_fault_code are distinct: raw device code versus mapped + central registry code. Their exact encoding/mapping remains open (Decision 13). +- `second_estop` is `SECOND_ESTOP_UNKNOWN` whenever `lift_link != LIFT_LINK_OK`. +- `fault_code`, `reason` and `*_fault_code` are `NONE` exactly when the associated state is + nominal. +- `reset_flags_raw` is `0` when the MCU cannot provide it, and `reset_cause` is then `UNKNOWN`. +- `powered_debug` is `UNKNOWN` when the firmware cannot identify the running build. `UNKNOWN` + is never read as `DISABLED`. +- `reset_required` reports whether a qualified physical RESET is required before `readiness` + can be set. It is not the live RESET input and is not itself the readiness latch. A high RESET + input held for the E-01 two-second invalidation interval clears `reset_seen`, asserts the + software-detected reset-input fault/inhibit, and requires the input to be observed low before + another qualified reset press can set readiness. A short valid press is handled by the E-01 + reset qualification logic. +- `session_epoch_counter` is reset to 0 on each boot (the new `boot_id` distinguishes boots), + then increments exactly once on each detected Jetson session loss. Heartbeats and ordinary + supervisory commands do not increment it. Challenge-response wire fields and replay rejection + remain in the I8 firmware/host contract, not in this package. + +## Safety observations + +`safety_ok`, `base_estop_pressed`, `reset_pressed`, `reset_required`, `charge_inhibit_active` +and `charger_fault` are firmware observations. + +- `safety_ok` is the PNOZ s3 Y32 output read through the ISO1212 isolated input. It is + diagnostic feedback only. It is not a safety-rated input, not proof of K1, K2 or KCHG contact + state, and not proof the hardwired chain reached its intended safe state. The firmware does + not monitor K1 or K2 (E-01 R6). ISO1212 is an isolated observation interface, not a + substitute safety circuit. +- `safety_ok == OBS_NO` means the diagnostic reports the PNOZ output not enabled. It is **not** + used to derive `SAFETY_STOPPED`. SAFETY_OK low is the expected condition while `CHARGING`; + SAFETY_OK high while charging is the unsafe direction (E-01 5.6). +- `charge_inhibit_active` follows the controller's own output. Dropping `CHARGE_REQUEST` is not + evidence that charging power was removed. +- An E-stop is reported as observed only when fresh telemetry explicitly reports it. Missing, + stale or unknown telemetry is never an observed E-stop and never proof of safety. +- No firmware status field proves the physical state of K1, K2 or KCHG. No ROS 2 message is a + safety function. +- The second E-stop comes through the lift node and is reported in `BaseAuxStatus`. + +## Fault registry + +Base-controller codes are group `18001`, owned by openamr-platform-fw +([#10](https://github.com/openAMRobot/openamr-platform-fw/issues/10)). The constants in BaseFault.msg are a proposed in-package representation, not an approved +authoritative registry. Decision 5 must settle the registry file format and whether message +constants are generated or maintained alongside it. Consumers must not treat provisional +individual IDs as approved until the registry owner confirms them. + +E-01 reason/fault mapping is provisional and must be checked against the E-01 rev 4 Fault and +Inhibit Matrix. Codes `18018`, `18019`, `18021` to `18023` and `18028` are proposed additions; +all require central registry confirmation. The existing 18001–18017 block remains owned by +platform-fw #10; this package does not claim authorship of those existing IDs. + +| E-01 condition / reason | Registry / reporting | +|---|---| +| `HW_SAFETY_NOT_ENABLED` | `PNOZ_DIAGNOSTIC_NOT_ENABLED` (18012): fresh Y32 low diagnostic only; not proof the whole hardwired chain is open. State effect is conditional on E-01 state; low is expected while CHARGING. | +| `ESTOP_DIAG` positively active | `ESTOP_DIAGNOSTIC_ACTIVE` (18018) | +| E-stop diagnostic missing/stale/unreadable | `ESTOP_DIAGNOSTIC_UNKNOWN` (18028), distinct from a positively observed active E-stop | +| `COMMS_LOST` | `BASE_HOST_LINK_LOST` (18002) | +| `BMS_FAULT` | `BMS_FAULT` (18009) | +| `INPUT_INVALID` (missing/stale) | `SAFETY_INPUT_UNKNOWN` (18010), with source identifying the input | +| `INPUT_INVALID` (implausible encoder) | `ENCODER_ODOMETRY_FAULT` (18006) | +| `INPUT_INVALID` (`RESET_HIGH`) | `RESET_INPUT_HIGH` (18019) | +| `CHARGER_FAULT` / `CHARGE_INTERLOCK` | `CHARGER_FAULT` (18021) / `CHARGE_INTERLOCK_FAULT` (18022) | +| `DRIVE_FAULT` / `DRIVE_COMMS` / `DRIVE_CONFIG` | `DRIVER_FAULT` (18004) / `DRIVER_COMM_LOST` (18003) / `DRIVE_CONFIG_MISMATCH` (18023) | +| UI Stop | `ui_stop_active`; not a fault code | +| Charge ended | charging command/state lifecycle; not a fault code | +| T8 reboot requested | `reboot_request_pending`; not a fault code | +| Boot power-on / watchdog / software | `reset_cause` and `reset_flags_raw`; not `BOOT_*` fault codes | + +`BaseFault` contains faults/diagnostic fault conditions only. The `reason_mask` contains active +fault/inhibit reasons only; it excludes normal events, UI Stop itself, charge completion, and +boot/reset causes. ``first_reason` is the first fault reason for the current LOCKED/CHARGER_FAULT episode, +not a general event history. `PNOZ_DIAGNOSTIC_NOT_ENABLED` must not be raised merely because +SAFETY_OK is low during normal CHARGING. + +### Fault lifecycle combinations + +`BaseFault` keeps the live condition, retained latch, acknowledgement and recovery requirement +separate. The following combinations are intentional: + +| `lifecycle` | `condition_active` | Meaning | +|---|---|---| +| `ACTIVE` | `OBS_YES` | Non-latching condition is present now. | +| `LATCHED` | `OBS_YES` or `OBS_NO` | Latch is held; the live condition may still be present or may have cleared. | +| `ACKNOWLEDGED` | `OBS_YES` or `OBS_NO` | Acknowledgement was accepted; it does not assert that the condition cleared. | +| `CLEARED` | `OBS_NO` | No active condition and no retained latch. | + +`UNKNOWN` is never interpreted as cleared. `ACKNOWLEDGED + OBS_YES` is valid and required for +the charge-interlock case where SAFETY_OK may remain high (including a possible welded KCHG). +Acknowledgement records the operator/Jetson action only. It is not hardware verification, does +not prove KCHG or any contactor opened, does not clear `condition_active`, does not satisfy +`recovery_required`, and never grants motion authority. A charge-interlock acknowledgement may +be accepted while SAFETY_OK is high; every subsequent charge attempt reruns the full interlock +sequence. Do not require SAFETY_OK low as a precondition for acknowledging this fault. + +A producer restart never clears a latched fault. Boot lands in `LOCKED` with charging off and +re-reads live conditions. Command timeout is non-latching. UI Stop, charge completion, T8 reboot +request and boot/reset causes are not fault codes: they are represented by `ui_stop_active`, the +charging command/state lifecycle, `reboot_request_pending`, and `reset_cause` respectively. + +## Not covered + +- A separate base-stopped evidence message/topic, its producer, QoS, rate and timeout (Decisions 1 and 8). +- ResetBaseController.srv (Decision 11). +- MB7060 range topic names, rate and publisher (Decision 12). +- Drive configuration (2000h, 1017h), brakes and the robot lift-interlock enforcement owner. + The simulation-side guard is a mirror only, not the robot enforcement implementation. + +## Open decisions + +The following remain open in I8 rev4: + +- Decision 1: final message set; whether BaseFault, BaseSubsystemStatus and BaseMotionConstraint + are included in the first package; whether a separate base-stopped evidence interface is needed. +- Decision 2: controller state, readiness, command acceptance and recovery semantics. + E-01 rev4 supplies a working proposal, not I8 approval. +- Decision 3: non-latching STM32 command-timeout behaviour and its relationship to the + heartbeat/consumer timeout. +- Decision 4: fault lifecycle, active/latched/acknowledged/cleared semantics, retention, + deterministic ordering and bounded-list overflow. +- Decision 5: registry file format, generated versus maintained constants, and whether + BaseFault carries operator text or a registry key. Group 18001 ownership is frozen; + proposed individual IDs still need registry-owner review. +- Decision 6: reset-cause enum after STM32H723 reset-flag verification. +- Decision 7: direction-specific travel inhibit when floor coverage is lost, with Navigation. +- Decision 8: robot lift/auxiliary interlock enforcement owner and handshake. The requirement + is base confirmed stopped AND both arms in the approved safe pose (stowed or carry); + UNKNOWN, invalid or stale inputs do not satisfy it. The exact carry pose and robot control + owner remain unresolved. The simulation-side guard is not a substitute. +- Decision 11: whether ResetBaseController.srv belongs in the first package. +- Decision 12: MB7060 topic names, rate, publisher and consumer freshness contract. +- Decision 13: independent measured-position source, declared-position source, separate + validity/freshness, homing semantics, raw-device versus mapped-registry fault representation, + and measured/declared disagreement rule and threshold. + +Decisions 9 and 10 are frozen: the two status topics/types, QoS, rates, stale thresholds, +receipt-time freshness, boot ID, uint32 sequence, uint16 contract version starting at 1, +fault group 18001 ownership, restart-not-clearing-latched-fault rule, powered debug off by +default and watchdog-first ordering. These frozen items are not reopened by this draft. + +The four separate firmware decisions Alex requested by 11 Nov—ZLAC 2000h/heartbeat timeout, +robot lift-interlock owner, CTL-017 v1 object dictionary, and safety/IMU pin assignments—are +also still awaiting Evans' decision/recording. They are tracked separately from the I8 +message-schema decisions above. Any change to a frozen field requires a change request in #30. diff --git a/ros2/openamr_base_msgs/README.md b/ros2/openamr_base_msgs/README.md new file mode 100755 index 0000000..7ef58ea --- /dev/null +++ b/ros2/openamr_base_msgs/README.md @@ -0,0 +1,28 @@ +# openamr_base_msgs + +**Bundle revision:** v4 reconciliation candidate (10 November 2026). See [REVISION_NOTES.md](../../REVISION_NOTES.md). + +Base-controller (I8) status, auxiliary-device and fault messages for +OpenAMRobot 2.0, aligned to E-01 rev 4. **Proposed**, not approved: see +[CONTRACT.md](CONTRACT.md) for topics, QoS, freshness and UNKNOWN rules, versioning and the +open decisions. + +## Messages + +- BaseStatus on /base/status: controller-state/readiness proposal, identity, timing/freshness, + diagnostic observations, faults and proposed subsystem/constraint summaries. E-01-derived + state semantics remain open under Decision 2. +- `BaseAuxStatus` on `/base/aux_status`: lift measured and declared position (separate), position validity, proposed homing state, head light, Getac power-good, second E-stop. +- `BaseFault`: one fault/diagnostic entry. Normal events, reset causes and UI Stop are represented by state fields, not fault codes. +- `BaseSubsystemStatus`, `BaseMotionConstraint`: provisional nested messages (decision 1). + +The package contains only the two frozen status topics. Optional message definitions and E-01-derived field semantics remain proposed pending the decisions listed in the contract. No separate base-stopped topic is included. + +## Before you consume this + +- Every enum's `0` is `UNKNOWN`. An unset field never looks healthy. +- Freshness comes from your local receipt time. `header.stamp` is diagnostic only. +- These are firmware observations. They are not a safety function and not proof that the + hardwired safety path worked. `safety_ok` is diagnostic feedback, not proof of K1/K2/KCHG state; low is expected during CHARGING. WCM_FAULT outside CHARGING blocks/refuses charging but does not by itself block RUN. +- `readiness` is the readiness latch, not the RESET input level, and not permission to move. +- This package reports state. It does not carry commands or sessions. diff --git a/ros2/openamr_base_msgs/msg/BaseAuxStatus.msg b/ros2/openamr_base_msgs/msg/BaseAuxStatus.msg new file mode 100755 index 0000000..4702f7a --- /dev/null +++ b/ros2/openamr_base_msgs/msg/BaseAuxStatus.msg @@ -0,0 +1,78 @@ +# Auxiliary-device block on /base/aux_status. PROPOSED, not approved (I8 proposal rev 4). +# Includes lift measured and declared position as separate values, validity, homing, motion, +# stop sensors and faults; head light; Getac power-good; moving-adapter-plate E-stop. +# Reports observations only. It does not enforce the lift interlock or prove a safety function. +# Lift interlock enforcement owner and inter-controller handshake remain undecided. +# 0 is UNKNOWN. Freshness comes from consumer-local receipt time, never header.stamp. +# Decision 13: position sources, homing semantics, raw/mapped fault rules and disagreement +# threshold remain open. Do not interpret proposed fields/enums as an approved device map. + +std_msgs/Header header # stamp = base controller monotonic time base, diagnostic only + +uint16 CONTRACT_VERSION=1 +uint16 contract_version + +uint32 boot_id # same value as in the BaseStatus of this boot +uint32 sequence +uint64 monotonic_us + +uint8 OBS_UNKNOWN=0 +uint8 OBS_NO=1 +uint8 OBS_YES=2 + +# --- lift node link --- +uint8 LIFT_LINK_UNKNOWN=0 +uint8 LIFT_LINK_OK=1 +uint8 LIFT_LINK_LOST=2 +uint8 lift_link + +# --- lift --- +# The two values must never be substituted for one another. +float32 lift_measured_position_m # independent physical measurement; 0 to 0.350 m +uint8 lift_measured_position_valid # OBS_YES only when the independent measurement is trustworthy +float32 lift_declared_position_m # actuator/controller-declared position; not a measurement +uint8 lift_declared_position_valid # OBS_YES only when the declared value is trustworthy +uint8 LIFT_HOMING_UNKNOWN=0 +uint8 lift_homing_state # other values/semantics pending Decision 13 +uint8 LIFT_MOTION_UNKNOWN=0 +uint8 LIFT_MOTION_STOPPED=1 +uint8 LIFT_MOTION_UP=2 +uint8 LIFT_MOTION_DOWN=3 +uint8 lift_motion +float32 lift_motor_current_a + +uint8 STOP_UNKNOWN=0 +uint8 STOP_NONE=1 +uint8 STOP_L1000=2 +uint8 STOP_L1175=3 +uint8 STOP_L1350=4 +uint8 lift_target_stop +uint8 lift_at_stop + +uint8 lift_stop_sensor_l1000 # OBS_YES = sensor active +uint8 lift_stop_sensor_l1175 +uint8 lift_stop_sensor_l1350 +uint32 lift_raw_device_fault_code # raw CTL-017/device code; representation/mapping pending Decision 13 +uint16 lift_fault_code # mapped central registry code, 0=NONE; mapping pending Decision 13 +# A late or stale lift target halts the lift at its current position (interfaces #31, Q10). + +# --- head light --- +uint8 HEAD_LIGHT_UNKNOWN=0 +uint8 HEAD_LIGHT_OFF=1 +uint8 HEAD_LIGHT_ON=2 +uint8 head_light_state +uint8 head_light_dim_percent # proposed 0 to 100 percent; confirm encoding with device owner +uint16 head_light_fault_code # BaseFault code, 0=NONE + +# --- Getac --- +uint8 getac_power_good + +# --- second E-stop (moving adapter plate, in the same hardwired chain) --- +uint8 SECOND_ESTOP_UNKNOWN=0 # always UNKNOWN while lift_link != LIFT_LINK_OK +uint8 SECOND_ESTOP_RELEASED=1 +uint8 SECOND_ESTOP_PRESSED=2 +uint8 second_estop + +# --- reserved generic inputs for later arm and lift-body ToF and ultrasonic sensors --- +# No hardware yet; empty today. Adding entries later needs no field change. +BaseSubsystemStatus[<=8] reserved_inputs diff --git a/ros2/openamr_base_msgs/msg/BaseFault.msg b/ros2/openamr_base_msgs/msg/BaseFault.msg new file mode 100755 index 0000000..8bf7c7e --- /dev/null +++ b/ros2/openamr_base_msgs/msg/BaseFault.msg @@ -0,0 +1,103 @@ +# One active or latched base-controller fault. PROPOSED, not approved (I8 proposal, aligned to E-01 rev 4). +# Functional status only. Not a safety function and not evidence that the hardwired +# safety path operated (E-01: no bus carries a safety function). +# Operator text and clear/recovery conditions live in the fault registry (interfaces #30, +# decision 5), not in the message. Consumers resolve `code` against the registry. + +# code: group 18001, owned by openamr-platform-fw#10. 0=NONE, append-only, never renumbered or reused. +# Existing group ownership is frozen; individual proposed additions and lifecycle remain +# subject to central-registry and reviewer approval. Package merge alone does not approve them. +uint16 NONE=0 + +# command and host link +uint16 BASE_COMMAND_TIMEOUT=18001 # non-latching (decision 3): clears on the next fresh command +uint16 BASE_HOST_LINK_LOST=18002 + +# motor driver +uint16 DRIVER_COMM_LOST=18003 +uint16 DRIVER_FAULT=18004 +uint16 DRIVER_FEEDBACK_INVALID=18005 + +# encoders / odometry and IMU +uint16 ENCODER_ODOMETRY_FAULT=18006 +uint16 IMU_FAULT=18007 + +# BMS +uint16 BMS_COMM_LOST=18008 +uint16 BMS_FAULT=18009 + +# safety inputs (observations only) +uint16 SAFETY_INPUT_UNKNOWN=18010 # missing, stale or unreadable +uint16 SAFETY_INPUT_CONTRADICTORY=18011 +uint16 PNOZ_DIAGNOSTIC_NOT_ENABLED=18012 # fresh Y32/SAFETY_OK diagnostic is low; not proof the physical chain is open + +# configuration, transport, list +uint16 CONTRACT_MISMATCH=18013 +uint16 TRANSPORT_FAILURE=18014 +uint16 FAULT_LIST_OVERFLOW=18015 + +# Reset causes are reported through BaseStatus reset_cause/reset_flags_raw, not BaseFault. +# The v3 draft proposed reset fault constants at 18016/18017. Rev4 treats reset causes as +# status/reset-cause reporting; confirm any existing registry allocation with platform-fw #10 +# before exposing either identifier as a BaseFault constant. + +# E-01 rev 4 reason codes (section 4). PROVISIONAL numbers: final IDs are assigned with the +# central registry. Existing codes are reused where the meaning is the same: +# HW_SAFETY_NOT_ENABLED -> PNOZ_DIAGNOSTIC_NOT_ENABLED (18012) COMMS_LOST -> BASE_HOST_LINK_LOST (18002) +# BMS_FAULT -> BMS_FAULT (18009) DRIVE_FAULT -> DRIVER_FAULT (18004) +# INPUT_INVALID: MISSING or STALE -> SAFETY_INPUT_UNKNOWN (18010), +# IMPLAUSIBLE encoder -> ENCODER_ODOMETRY_FAULT (18006), RESET_HIGH -> 18019 +uint16 ESTOP_DIAGNOSTIC_ACTIVE=18018 # fresh diagnostic positively reports E-stop active +uint16 RESET_INPUT_HIGH=18019 # INPUT_INVALID sub-cause RESET_HIGH: RESET held high 2 s +uint16 CHARGER_FAULT=18021 # WCM_FAULT latched while charging +uint16 CHARGE_INTERLOCK_FAULT=18022 # SAFETY_OK not low within 500 ms of CHARGE_REQUEST, or high again while charging +uint16 DRIVE_CONFIG_MISMATCH=18023 # link-loss time or heartbeat interval read back differs from the D-24 values +uint16 ESTOP_DIAGNOSTIC_UNKNOWN=18028 # diagnostic input missing, stale or unreadable; distinct from active E-stop + +uint16 code + +uint8 SEVERITY_UNKNOWN=0 # unset field must never read as benign +uint8 SEVERITY_WARNING=1 # controller state DEGRADED +uint8 SEVERITY_FAULT=2 # controller state FAULTED +uint8 severity + +uint8 SOURCE_UNKNOWN=0 +uint8 SOURCE_COMMAND=1 +uint8 SOURCE_HOST_LINK=2 +uint8 SOURCE_MOTOR_DRIVER=3 +uint8 SOURCE_ENCODER=4 +uint8 SOURCE_IMU=5 +uint8 SOURCE_BMS=6 +uint8 SOURCE_SAFETY_INPUT=7 +uint8 SOURCE_RANGE_SENSOR=8 +uint8 SOURCE_LIFT=9 +uint8 SOURCE_CONFIG=10 +uint8 SOURCE_RESET=11 +uint8 source + +# TODO(decision 4): retention, list bound and overflow are not decided. The model below follows +# E-01 rev 4 and is still provisional: do not build consumers on it yet. +# +# Five things are kept apart (E-01 section 5.3 and 5.6): +# condition_active the fault condition is present now +# lifecycle ACTIVE, LATCHED, ACKNOWLEDGED or CLEARED latch/ack state +# acknowledgement ACKNOWLEDGED means accepted; it is not a sensor observation +# condition cleared condition_active == OBS_NO (independent of lifecycle) +# recovery_required a physical RESET or other recovery is still needed before RUN +# Acknowledgement is independent of condition_active: ACKNOWLEDGED may coexist with OBS_YES. +# It never clears the condition, verifies KCHG/contactors, or grants motion authority. A +# charge-interlock fault may be acknowledged while SAFETY_OK remains high. +uint8 LIFECYCLE_UNKNOWN=0 +uint8 LIFECYCLE_ACTIVE=1 # non-latching: present now, clears by itself (e.g. command timeout) +uint8 LIFECYCLE_LATCHED=2 # latch held; the condition may or may not still be present +uint8 LIFECYCLE_ACKNOWLEDGED=3 # acknowledgement accepted; condition may still be active and recovery may still be required +uint8 LIFECYCLE_CLEARED=4 # no latch and no condition +uint8 lifecycle + +uint8 OBS_UNKNOWN=0 +uint8 OBS_NO=1 +uint8 OBS_YES=2 +uint8 condition_active # OBS_*. ACKNOWLEDGED with OBS_YES is also valid +uint8 recovery_required # OBS_* + +bool inhibits_motion diff --git a/ros2/openamr_base_msgs/msg/BaseMotionConstraint.msg b/ros2/openamr_base_msgs/msg/BaseMotionConstraint.msg new file mode 100755 index 0000000..2673006 --- /dev/null +++ b/ros2/openamr_base_msgs/msg/BaseMotionConstraint.msg @@ -0,0 +1,12 @@ +# One active motion constraint reported by the base controller. PROVISIONAL (decision 1). +# Status reports constraints; enforcement stays in the designated control logic. + +uint8 TYPE_UNKNOWN=0 +uint8 TYPE_SPEED_LIMIT=1 # value in m/s +uint8 TYPE_TRAVEL_INHIBIT_FORWARD=2 # TODO(decision 7): policy when floor coverage is lost +uint8 TYPE_TRAVEL_INHIBIT_REVERSE=3 # TODO(decision 7) +uint8 TYPE_LIFT_HOLD=4 # lift moving, base held stopped +uint8 type + +float32 value # m/s for TYPE_SPEED_LIMIT, 0 otherwise +uint16 reason # BaseFault code, 0=NONE diff --git a/ros2/openamr_base_msgs/msg/BaseStatus.msg b/ros2/openamr_base_msgs/msg/BaseStatus.msg new file mode 100755 index 0000000..20c2222 --- /dev/null +++ b/ros2/openamr_base_msgs/msg/BaseStatus.msg @@ -0,0 +1,159 @@ +# I8 base controller status on /base/status. PROPOSED, not approved (I8 proposal, aligned to +# E-01 safety state machine rev 4, interfaces #30). Functional observations only: not a +# safety function, and not proof that the hardwired safety path (two E-stops, PNOZ s3, K1/K2, +# brake release) achieved a safe state (E-01: no bus carries a safety function). This message +# reports controller state. It is not a command or session protocol; commands and session +# rules live in the I8 firmware/host contract. +# +# Rules for every field below: +# - 0 is UNKNOWN. An unset, stale or unavailable value must never read as healthy, safe or +# as an observed E-stop. +# - Freshness comes from the consumer's local receipt time, never from header.stamp. + +# header.stamp is the ROS time stamp when available; diagnostic only. Use monotonic_us for +# controller-local elapsed-time calculations. Freshness is based on local receipt time. +std_msgs/Header header + +uint16 CONTRACT_VERSION=1 # frozen I8 contract version starts at 1; remaining field semantics are proposed under decision 2 +uint16 contract_version # producer sets this to CONTRACT_VERSION + +# --- identity, restart and ordering --- +string controller_id # e.g. "teensy_gate_a", "stm32h723_gate_b"; "" if unknown +string firmware_version # "" if unknown +uint32 boot_id # changes on every controller boot; uint32 is part of the frozen I8 identity contract +uint32 sequence # +1 per published message, wraps; a gap is a discontinuity +uint64 monotonic_us # 64-bit monotonic microsecond time base + +uint8 POWERED_DEBUG_UNKNOWN=0 # firmware cannot identify the running build +uint8 POWERED_DEBUG_DISABLED=1 +uint8 POWERED_DEBUG_ENABLED=2 # commissioning build (decision 10: off by default) +uint8 powered_debug + +# --- controller health summary (generic, kept) --- +# Derived from the severity of the active faults. It does not replace the E-01 operating +# state below: LOCKED, INHIBITED and CHARGING are not "faulted" and not "ready". +uint8 STATE_UNKNOWN=0 +uint8 STATE_INITIALIZING=1 +uint8 STATE_READY=2 +uint8 STATE_DEGRADED=3 +uint8 STATE_FAULTED=4 +uint8 state + +# --- E-01 rev 4 operating state --- +# Boot always lands in LOCKED (E-01 T1); there is no separate BOOT state. 0 means the +# controller has not yet determined its state. INHIBITED (software UI Stop) is never reported +# as SAFETY_STOPPED: that term is reserved for the hardwired chain. +uint8 OPERATING_STATE_UNKNOWN=0 +uint8 OPERATING_STATE_LOCKED=1 # boot state and state for faults/conditions that E-01 maps to LOCKED +uint8 OPERATING_STATE_RUN=2 # all run conditions valid, motion allowed +uint8 OPERATING_STATE_INHIBITED=3 # UI Stop asserted from RUN, readiness latch kept +uint8 OPERATING_STATE_CHARGING=4 # charge command accepted, interlock active +uint8 OPERATING_STATE_CHARGER_FAULT=5 # charger or charge-interlock fault latched +uint8 operating_state + +# --- E-01 rev 4 latches (three separate things, never merged) --- +# readiness is the readiness latch (reset_seen): set only by a qualified short physical RESET +# press, cleared by the events in E-01 section 2.2. It is NOT the RESET input level +# (reset_pressed) and does not mean the robot may move: RUN also needs ui_stop and host stop +# clear and every other run condition. +uint8 READINESS_UNKNOWN=0 +uint8 READINESS_NOT_READY=1 # reset_seen clear +uint8 READINESS_READY=2 # reset_seen set. Readiness is not hardware safety +uint8 readiness + +uint8 ui_stop_active # OBS_*. UI Stop software inhibit; UI Resume clears this latch only, subject to E-01 state rules +uint8 host_stop_active # OBS_*. Jetson Stop. Asserted at boot and on session loss; independent of host_link + +# Motion commands are accepted only in RUN, only from the current session. +uint8 COMMAND_ACCEPTANCE_UNKNOWN=0 +uint8 COMMAND_ACCEPTANCE_REJECTING=1 +uint8 COMMAND_ACCEPTANCE_ACCEPTING=2 +uint8 command_acceptance + +uint8 RECOVERY_UNKNOWN=0 +uint8 RECOVERY_NOT_REQUIRED=1 +uint8 RECOVERY_REQUIRED=2 # clearing the cause or a reset alone never authorizes motion +uint8 recovery + +# --- E-01 rev 4 lock episode and reasons --- +# A lock episode begins on a transition into LOCKED or CHARGER_FAULT and ends on entering RUN. +# first_reason is the first fault reason (BaseFault code, 0=NONE). reason_mask contains +# only currently active fault/inhibit conditions, never normal events, reset causes or UI Stop +# itself (UI Stop is reported by ui_stop_active). +uint32 REASON_PNOZ_DIAGNOSTIC_NOT_ENABLED=1 # fresh Y32 low outside expected CHARGING condition +uint32 REASON_ESTOP_DIAG_ACTIVE=2 +uint32 REASON_COMMS_LOST=4 # Jetson session lost +uint32 REASON_BMS_FAULT=8 +uint32 REASON_INPUT_INVALID=16 +uint32 REASON_CHARGER_FAULT=32 +uint32 REASON_CHARGE_INTERLOCK=64 +uint32 REASON_DRIVE_FAULT=128 +uint32 REASON_DRIVE_COMMS=256 +uint32 REASON_DRIVE_CONFIG=512 +uint32 REASON_RESET_INPUT_HIGH=1024 +uint32 REASON_ESTOP_DIAG_UNKNOWN=2048 +uint16 first_reason # BaseFault code, 0=NONE +uint32 reason_mask + +# --- E-01 rev 4 session epoch --- +# Epoch = (boot_id, session_epoch_counter). boot_id changes on every boot and the counter +# starts at 0 for that boot; it increments exactly once for each detected Jetson session loss +# (T5), not for heartbeats or ordinary commands. A new challenge-response establishes the +# current epoch; delayed traffic from an older epoch is rejected. Wire details live in I8. +uint32 session_epoch_counter +bool reboot_request_pending # T8 supervisory event/state; not a BaseFault code + +# --- command and host communication --- +uint8 HOST_LINK_UNKNOWN=0 +uint8 HOST_LINK_OK=1 +uint8 HOST_LINK_LOST=2 +uint8 host_link + +# The velocity actually sent to the motor driver after limits, ramp and timeout +# (platform-sw #116). Never a held or replayed command: on timeout the base stops. +uint8 APPLIED_COMMAND_UNKNOWN=0 +uint8 APPLIED_COMMAND_OK=1 +uint8 APPLIED_COMMAND_TIMEOUT=2 # non-latching (decision 3) +uint8 APPLIED_COMMAND_INHIBITED=3 # by a safety stop or a constraint +uint8 applied_command_state +float32 applied_linear_x_mps +float32 applied_angular_z_radps +builtin_interfaces/Duration applied_command_age + +# --- safety-chain observations (diagnostics only; E-01 rev 4, hardware baseline rev1.8) --- +uint8 OBS_UNKNOWN=0 # not determined, stale or unreadable: never read as NO +uint8 OBS_NO=1 +uint8 OBS_YES=2 + +# safety_ok is the PNOZ s3 Y32 output read through the ISO1212 isolated input. It is +# diagnostic feedback only: not a safety-rated input, not proof of K1/K2/KCHG contact state, +# and not proof the hardwired chain reached its intended safe state. OBS_NO means the +# diagnostic reports the PNOZ output not enabled. The firmware does not monitor K1 or K2 +# (E-01 R6). SAFETY_OK low is expected while CHARGING. +uint8 safety_ok +uint8 base_estop_pressed # base E-stop spare NO contact (diagnostic) +uint8 reset_pressed # RESET NC contact level. An open wire also reads pressed. Not the readiness latch +uint8 reset_required # a physical RESET is required before readiness can be set +uint8 charge_inhibit_active # follows the controller's own CHARGE_REQUEST/KCHG output. Not evidence charging power is removed +uint8 charger_fault # TZBOT charger fault line (WCM_FAULT) +uint16 safety_diagnosis # BaseFault code for a current diagnostic fault, 0=NONE + +# --- faults --- +# TODO(decision 4): bound, ordering and overflow behaviour are provisional. +BaseFault[<=16] faults +bool fault_list_overflow + +# --- subsystem health and motion constraints (decision 1: provisional nested messages) --- +BaseSubsystemStatus[<=16] subsystems +BaseMotionConstraint[<=8] constraints + +# --- reset cause --- +# TODO(decision 6): exhaustive mapping after the STM32H723ZG reset-flag check. +uint8 RESET_CAUSE_UNKNOWN=0 +uint8 RESET_CAUSE_POWER_ON=1 +uint8 RESET_CAUSE_BROWNOUT=2 +uint8 RESET_CAUSE_WATCHDOG=3 +uint8 RESET_CAUSE_SOFTWARE=4 +uint8 RESET_CAUSE_PIN=5 +uint8 reset_cause +uint32 reset_flags_raw # raw MCU reset flags captured before clearing; 0 if unavailable diff --git a/ros2/openamr_base_msgs/msg/BaseSubsystemStatus.msg b/ros2/openamr_base_msgs/msg/BaseSubsystemStatus.msg new file mode 100755 index 0000000..afb17e3 --- /dev/null +++ b/ros2/openamr_base_msgs/msg/BaseSubsystemStatus.msg @@ -0,0 +1,27 @@ +# Health and freshness of one base-controller subsystem. PROVISIONAL (decision 1): +# kept only if a nested message is justified over flat fields in BaseStatus. +# Mirrors openamr_nav_msgs/SensorStatus.state so consumers read both the same way. + +uint8 SUBSYSTEM_UNKNOWN=0 +uint8 SUBSYSTEM_MOTOR_DRIVER=1 +uint8 SUBSYSTEM_ENCODERS=2 +uint8 SUBSYSTEM_IMU=3 +uint8 SUBSYSTEM_BMS=4 +uint8 SUBSYSTEM_RANGE_FRONT_LEFT=5 # MaxBotix MB7060 +uint8 SUBSYSTEM_RANGE_FRONT_RIGHT=6 +uint8 SUBSYSTEM_RANGE_REAR_LEFT=7 +uint8 SUBSYSTEM_RANGE_REAR_RIGHT=8 +uint8 SUBSYSTEM_CLIFF_FRONT=9 # TF-Luna +uint8 SUBSYSTEM_CLIFF_REAR=10 +uint8 SUBSYSTEM_LIFT_NODE_LINK=11 +uint8 subsystem + +uint8 STATE_UNKNOWN=0 # unset field should never read as healthy +uint8 STATE_ABSENT=1 +uint8 STATE_STALE=2 +uint8 STATE_DEGRADED=3 +uint8 STATE_OK=4 +uint8 state + +builtin_interfaces/Duration data_age # 0 when STATE_ABSENT or STATE_UNKNOWN +uint16 fault_code # BaseFault code, 0=NONE exactly when state is OK diff --git a/ros2/openamr_base_msgs/package.xml b/ros2/openamr_base_msgs/package.xml new file mode 100755 index 0000000..3a3c43e --- /dev/null +++ b/ros2/openamr_base_msgs/package.xml @@ -0,0 +1,33 @@ + + + + openamr_base_msgs + 0.0.0 + I8 base controller status, auxiliary device and fault messages for OpenAMRobot 2.0 (Proposed) + + Botshare LTD + Evans Klenam Kwashie-Seyram + + MIT + + + ament_cmake + + + rosidl_default_generators + rosidl_default_runtime + + + builtin_interfaces + std_msgs + + + ament_lint_auto + ament_lint_common + + rosidl_interface_packages + + + ament_cmake + + diff --git a/tests/test_base_msgs.py b/tests/test_base_msgs.py new file mode 100755 index 0000000..078e93f --- /dev/null +++ b/tests/test_base_msgs.py @@ -0,0 +1,237 @@ +"""Static checks for ros2/openamr_base_msgs (no ROS needed). + +These check the contract rules that CONTRACT.md states: version constants, the UNKNOWN=0 +convention, fault-code uniqueness and group, and that CMakeLists lists every message. +They do not replace the colcon build in tools/verify.sh. +""" +from pathlib import Path +import re +import unittest + +ROOT = Path(__file__).resolve().parents[1] +PKG = ROOT / "ros2" / "openamr_base_msgs" +MSG = PKG / "msg" + +PRIMITIVES = { + "bool", "byte", "char", "float32", "float64", "int8", "uint8", "int16", "uint16", + "int32", "uint32", "int64", "uint64", "string", +} +EXTERNAL = {"std_msgs/Header", "builtin_interfaces/Duration"} +CONST_RE = re.compile(r"^(\w+)\s+([A-Z][A-Z0-9_]*)\s*=\s*(-?\d+)$") +FIELD_RE = re.compile(r"^([\w/]+(?:\[(?:<=)?\d*\])?)\s+([a-z][a-z0-9_]*)$") + + +def parse(path): + """Return (constants, fields) from a .msg file. Raises ValueError on a bad line.""" + constants, fields = [], [] + for number, raw in enumerate(path.read_text().splitlines(), 1): + line = raw.split("#", 1)[0].strip() + if not line: + continue + match = CONST_RE.match(line) + if match: + constants.append((match.group(1), match.group(2), int(match.group(3)))) + continue + match = FIELD_RE.match(line) + if match: + fields.append((match.group(1), match.group(2))) + continue + raise ValueError(f"{path.name}:{number}: cannot parse {raw!r}") + return constants, fields + + +def messages(): + return {p.stem: p for p in sorted(MSG.glob("*.msg"))} + + +class BaseMsgsTests(unittest.TestCase): + def test_messages_exist(self): + self.assertGreaterEqual(len(messages()), 5) + + def test_cmake_lists_every_message(self): + listed = set(re.findall(r'"msg/(\w+)\.msg"', (PKG / "CMakeLists.txt").read_text())) + self.assertEqual(listed, set(messages())) + + def test_every_line_parses_and_types_are_known(self): + names = set(messages()) + for name, path in messages().items(): + constants, fields = parse(path) + for ctype, _, _ in constants: + self.assertIn(ctype, PRIMITIVES, f"{name}: bad constant type {ctype}") + for ftype, fname in fields: + base = re.sub(r"\[.*\]$", "", ftype) + self.assertTrue( + base in PRIMITIVES or base in EXTERNAL or base in names, + f"{name}.{fname}: unknown type {ftype}", + ) + + def test_contract_version_constant_and_field(self): + for name in ("BaseStatus", "BaseAuxStatus"): + constants, fields = parse(messages()[name]) + versions = [v for t, n, v in constants if (t, n) == ("uint16", "CONTRACT_VERSION")] + self.assertEqual(len(versions), 1, name) + self.assertEqual(versions[0], 1, name) # frozen I8 contract version starts at 1 + self.assertIn(("uint16", "contract_version"), fields, name) + + def test_status_identity_and_timing_fields(self): + _, fields = parse(messages()["BaseStatus"]) + for expected in ( + ("std_msgs/Header", "header"), + ("uint32", "boot_id"), + ("uint32", "sequence"), + ("uint64", "monotonic_us"), + ("uint8", "powered_debug"), + ("uint8", "reset_cause"), + ): + self.assertIn(expected, fields) + + def test_unknown_is_zero_in_every_message(self): + for name, path in messages().items(): + constants, _ = parse(path) + # enum zeros: uint8 *_UNKNOWN, or NONE. A fault code that merely contains the + # word UNKNOWN (for example SAFETY_INPUT_UNKNOWN=18010) is a uint16 code. + unknown = [ + v for t, n, v in constants + if (t == "uint8" and n.endswith("UNKNOWN")) or n == "NONE" + ] + self.assertTrue(unknown, f"{name}: no UNKNOWN or NONE constant") + self.assertEqual(set(unknown), {0}, f"{name}: UNKNOWN/NONE must be 0") + + def test_powered_debug_unknown_is_not_disabled(self): + constants, _ = parse(messages()["BaseStatus"]) + values = {n: v for _, n, v in constants} + self.assertEqual(values["POWERED_DEBUG_UNKNOWN"], 0) + self.assertNotEqual(values["POWERED_DEBUG_DISABLED"], 0) + + def test_fault_codes_unique_and_in_group_18001(self): + constants, _ = parse(messages()["BaseFault"]) + codes = [(n, v) for t, n, v in constants if t == "uint16" and n != "NONE"] + self.assertTrue(codes) + values = [v for _, v in codes] + self.assertEqual(len(values), len(set(values)), "duplicate fault code") + self.assertEqual(len({n for n, _ in codes}), len(codes), "duplicate fault name") + self.assertEqual(min(values), 18001) + self.assertTrue(all(18001 <= v <= 18999 for v in values)) + + def test_codes_are_not_in_other_groups(self): + # groups 10001 to 17001 belong to other owners (interfaces #31, Q2) + constants, _ = parse(messages()["BaseFault"]) + for t, n, v in constants: + if t == "uint16" and n != "NONE": + self.assertGreaterEqual(v, 18001, n) + + def test_operating_states_match_e01_rev4(self): + constants, fields = parse(messages()["BaseStatus"]) + names = {n for _, n, _ in constants} + for state in ("LOCKED", "RUN", "INHIBITED", "CHARGING", "CHARGER_FAULT"): + self.assertIn(f"OPERATING_STATE_{state}", names) + self.assertNotIn("OPERATING_STATE_BOOT", names) # boot lands in LOCKED (T1) + values = {n: v for _, n, v in constants} + self.assertEqual(values["OPERATING_STATE_UNKNOWN"], 0) + self.assertEqual(len({v for n, v in values.items() if n.startswith("OPERATING_STATE_")}), 6) + self.assertIn(("uint8", "operating_state"), fields) + + def test_latches_are_separate_fields(self): + _, fields = parse(messages()["BaseStatus"]) + for expected in ( + ("uint8", "readiness"), # reset_seen + ("uint8", "reset_pressed"), # input level, a different thing + ("uint8", "ui_stop_active"), + ("uint8", "host_stop_active"), + ("uint8", "host_link"), # comms health, a different thing from host stop + ("uint16", "first_reason"), + ("uint32", "reason_mask"), + ("uint32", "session_epoch_counter"), + ): + self.assertIn(expected, fields) + + def test_reason_bits_are_distinct_single_bits(self): + constants, _ = parse(messages()["BaseStatus"]) + bits = [v for t, n, v in constants if n.startswith("REASON_")] + self.assertTrue(bits) + self.assertEqual(len(bits), len(set(bits))) + for v in bits: + self.assertTrue(v > 0 and v & (v - 1) == 0, f"not a single bit: {v}") + self.assertLessEqual(max(bits), 2 ** 31) + + def test_unfrozen_base_stopped_topic_is_not_in_candidate(self): + self.assertNotIn("BaseStopped", messages()) + contract = (PKG / "CONTRACT.md").read_text() + self.assertNotIn("| /base/stopped |", contract) + self.assertIn("No separate /base/stopped topic", contract) + + def test_lift_measured_and_declared_positions_are_separate(self): + _, fields = parse(messages()["BaseAuxStatus"]) + for expected in ( + ("float32", "lift_measured_position_m"), + ("uint8", "lift_measured_position_valid"), + ("float32", "lift_declared_position_m"), + ("uint8", "lift_declared_position_valid"), + ("uint8", "lift_homing_state"), + ("uint32", "lift_raw_device_fault_code"), + ("uint16", "lift_fault_code"), + ): + self.assertIn(expected, fields) + self.assertNotIn(("float32", "lift_position_m"), fields) + + def test_fault_lifecycle_separates_condition_ack_and_recovery(self): + constants, fields = parse(messages()["BaseFault"]) + names = {n for _, n, _ in constants} + self.assertIn("LIFECYCLE_ACKNOWLEDGED", names) + for expected in (("uint8", "condition_active"), ("uint8", "recovery_required")): + self.assertIn(expected, fields) + source = messages()["BaseFault"].read_text() + self.assertIn("ACKNOWLEDGED may coexist with OBS_YES", source) + contract = (PKG / "CONTRACT.md").read_text() + self.assertIn("ACKNOWLEDGED + OBS_YES", contract) + self.assertIn("does not prove KCHG", contract) + self.assertIn("Package merge alone does not approve them", messages()["BaseFault"].read_text()) + + def test_e01_reason_codes_exist(self): + constants, _ = parse(messages()["BaseFault"]) + names = {n for _, n, _ in constants} + for name in ( + "ESTOP_DIAGNOSTIC_ACTIVE", "ESTOP_DIAGNOSTIC_UNKNOWN", "RESET_INPUT_HIGH", + "CHARGER_FAULT", "CHARGE_INTERLOCK_FAULT", "DRIVE_CONFIG_MISMATCH", + ): + self.assertIn(name, names) + + def test_non_fault_events_and_reset_causes_are_not_fault_codes(self): + constants, _ = parse(messages()["BaseFault"]) + names = {n for _, n, _ in constants} + for forbidden in ("UI_STOP_ACTIVE", "CHARGE_ENDED", "REBOOT_REQUESTED", "BOOT_POWER_ON", "BOOT_SOFTWARE", "WATCHDOG_RESET", "BROWNOUT_RESET"): + self.assertNotIn(forbidden, names) + status_constants, status_fields = parse(messages()["BaseStatus"]) + self.assertIn(("bool", "reboot_request_pending"), status_fields) + self.assertIn(("uint8", "reset_cause"), status_fields) + + def test_wcm_fault_does_not_blanket_lock_run(self): + contract = (PKG / "CONTRACT.md").read_text() + self.assertIn("It does not by itself force `RUN` to `LOCKED`", contract) + self.assertIn("while `CHARGING`", contract) + + def test_fault_reason_mask_excludes_events(self): + constants, _ = parse(messages()["BaseStatus"]) + names = {n for _, n, _ in constants} + for forbidden in ("REASON_UI_STOP", "REASON_CHARGE_ENDED", "REASON_BOOT_POWER_ON", "REASON_REBOOT_REQUESTED"): + self.assertNotIn(forbidden, names) + bits = [v for t, n, v in constants if n.startswith("REASON_")] + self.assertTrue(all(v > 0 and v & (v - 1) == 0 for v in bits)) + + def test_safety_ok_is_not_used_to_derive_safety_stopped(self): + # SAFETY_OK is diagnostic feedback; it is not proof of contactor state (E-01 R6). + for path in (MSG / "BaseStatus.msg", PKG / "CONTRACT.md"): + text = path.read_text() + self.assertNotIn("SAFETY_STOPPED is derived", text, path.name) + self.assertNotIn("means the chain is OPEN", text, path.name) + + def test_no_command_or_session_messages(self): + # #30 reports status. Commands and sessions belong to the I8 firmware/host contract. + for name in messages(): + self.assertFalse( + name.endswith(("Command", "Challenge", "Hello", "Result")), name + ) + + +if __name__ == "__main__": + unittest.main() From 81deda42ca032ec309720334eb115951a10a42f1 Mon Sep 17 00:00:00 2001 From: Evans Klenam Kwashie-Seyram Date: Sun, 15 Nov 2026 11:02:09 +0000 Subject: [PATCH 02/23] fix(base_msgs): address PR 38 review feedback Signed-off-by: Evans Klenam Kwashie-Seyram --- STATE.md | 1 + ros2/openamr_base_msgs/CONTRACT.md | 15 ++++++++++++++- ros2/openamr_base_msgs/msg/BaseAuxStatus.msg | 2 +- tests/test_base_msgs.py | 16 ++++++++++++++++ 4 files changed, 32 insertions(+), 2 deletions(-) mode change 100755 => 100644 ros2/openamr_base_msgs/CONTRACT.md mode change 100755 => 100644 ros2/openamr_base_msgs/msg/BaseAuxStatus.msg mode change 100755 => 100644 tests/test_base_msgs.py diff --git a/STATE.md b/STATE.md index 5188553..2428294 100644 --- a/STATE.md +++ b/STATE.md @@ -36,4 +36,5 @@ The PR evidence check fails when STATE.md exists and a PR neither updates it nor ## Not verified - I8 verification is local ROS 2 Jazzy software verification only; firmware integration, physical robot, safety-chain and hardware validation are not established (2026-11-11). +- PR #38 review follow-up: corrected BaseAuxStatus header timestamp comment; added clock-contract and ownership-gap regression checks; named participant assignments remain TBD (2026-11-15). - No physical robot, safety-chain, released binary or cross-version deployment evidence is claimed. diff --git a/ros2/openamr_base_msgs/CONTRACT.md b/ros2/openamr_base_msgs/CONTRACT.md old mode 100755 new mode 100644 index 1138fd9..4387fdf --- a/ros2/openamr_base_msgs/CONTRACT.md +++ b/ros2/openamr_base_msgs/CONTRACT.md @@ -23,7 +23,20 @@ This package only reports their result. | `/base/status` | `BaseStatus` | base-controller firmware (Teensy Gate A, STM32H723ZG Gate B), [openamr-platform-fw#10](https://github.com/openAMRobot/openamr-platform-fw/issues/10) | `navigation_status_node.py` in openamr-platform-sw, operator UI (openamrobot-ui #54), manipulation (openamrobot-manipulation #7), diagnostics, logging, tests | | `/base/aux_status` | `BaseAuxStatus` | base-controller firmware, relayed from the lift node CTL-017 over CAN3 ([openamr-platform-fw#12](https://github.com/openAMRobot/openamr-platform-fw/issues/12), D17) | same as above | -Owners for each producer and consumer are recorded in the PR description. +The mapping below records the accountable repository/component and role known for this +proposal. Individual names are intentionally marked **TBD** where no assignment is recorded; +this table is not evidence that those assignments have been accepted. Resolve the TBD entries +before treating Issue #30's owner requirement as complete. + +| Interface participant | Accountable repository / component | Owner role | Named owner | +|---|---|---|---| +| `/base/status` producer (Teensy Gate A / STM32H723ZG Gate B) | `openamr-platform-fw` | Base-controller firmware maintainer | TBD — assignment required | +| `/base/aux_status` producer/relay | `openamr-platform-fw` (CTL-017 CAN3 integration) | Firmware / lift-interface maintainer | TBD — assignment required | +| Navigation consumer | `openamr-platform-sw` (`navigation_status_node.py`) | Platform software maintainer | TBD — assignment required | +| Operator UI consumer | `openamrobot-ui` (#54) | UI maintainer | TBD — assignment required | +| Manipulation consumer | `openamrobot-manipulation` (#7) | Manipulation maintainer | TBD — assignment required | +| Diagnostics and logging consumers | Owning runtime / observability components | Diagnostics / logging maintainer | TBD — component and owner assignment required | +| Interface regression tests | `openamrobot-interfaces` | Repository software lead / test maintainer | TBD — assignment required | ## QoS and publish behavior diff --git a/ros2/openamr_base_msgs/msg/BaseAuxStatus.msg b/ros2/openamr_base_msgs/msg/BaseAuxStatus.msg old mode 100755 new mode 100644 index 4702f7a..9d43ee8 --- a/ros2/openamr_base_msgs/msg/BaseAuxStatus.msg +++ b/ros2/openamr_base_msgs/msg/BaseAuxStatus.msg @@ -7,7 +7,7 @@ # Decision 13: position sources, homing semantics, raw/mapped fault rules and disagreement # threshold remain open. Do not interpret proposed fields/enums as an approved device map. -std_msgs/Header header # stamp = base controller monotonic time base, diagnostic only +std_msgs/Header header # ROS time when available; diagnostic only, never the freshness clock uint16 CONTRACT_VERSION=1 uint16 contract_version diff --git a/tests/test_base_msgs.py b/tests/test_base_msgs.py old mode 100755 new mode 100644 index 078e93f..e10c0fd --- a/tests/test_base_msgs.py +++ b/tests/test_base_msgs.py @@ -73,6 +73,22 @@ def test_contract_version_constant_and_field(self): self.assertEqual(versions[0], 1, name) # frozen I8 contract version starts at 1 self.assertIn(("uint16", "contract_version"), fields, name) + def test_header_stamp_clock_contract_is_consistent(self): + contract = (PKG / "CONTRACT.md").read_text() + expected = "`header.stamp` is ROS time when available and is diagnostic only. Use `monotonic_us` for" + self.assertIn(expected, contract) + for name in ("BaseStatus", "BaseAuxStatus"): + source = messages()[name].read_text() + self.assertRegex(source, r"(?im)(?:^#.*header\.stamp.*ROS time.*diagnostic only|^std_msgs/Header header.*ROS time.*diagnostic only)") + self.assertNotRegex(source, r"(?im)^\s*std_msgs/Header header.*monotonic") + self.assertRegex(source, r"(?m)^uint64 monotonic_us\b") + + def test_producer_consumer_ownership_gaps_are_explicit(self): + contract = (PKG / "CONTRACT.md").read_text() + self.assertIn("| Interface participant | Accountable repository / component | Owner role | Named owner |", contract) + self.assertIn("TBD — assignment required", contract) + self.assertNotIn("Owners for each producer and consumer are recorded in the PR description.", contract) + def test_status_identity_and_timing_fields(self): _, fields = parse(messages()["BaseStatus"]) for expected in ( From 5b8f5f55096a7eb48e768521c247f33e726e0d4d Mon Sep 17 00:00:00 2001 From: Evans Klenam Kwashie-Seyram Date: Tue, 17 Nov 2026 05:37:28 +0000 Subject: [PATCH 03/23] docs(i8): record confirmed interface ownership --- ros2/openamr_base_msgs/CONTRACT.md | 49 +++++++++++++++++++++--------- 1 file changed, 35 insertions(+), 14 deletions(-) diff --git a/ros2/openamr_base_msgs/CONTRACT.md b/ros2/openamr_base_msgs/CONTRACT.md index 4387fdf..25ea0e1 100644 --- a/ros2/openamr_base_msgs/CONTRACT.md +++ b/ros2/openamr_base_msgs/CONTRACT.md @@ -23,21 +23,39 @@ This package only reports their result. | `/base/status` | `BaseStatus` | base-controller firmware (Teensy Gate A, STM32H723ZG Gate B), [openamr-platform-fw#10](https://github.com/openAMRobot/openamr-platform-fw/issues/10) | `navigation_status_node.py` in openamr-platform-sw, operator UI (openamrobot-ui #54), manipulation (openamrobot-manipulation #7), diagnostics, logging, tests | | `/base/aux_status` | `BaseAuxStatus` | base-controller firmware, relayed from the lift node CTL-017 over CAN3 ([openamr-platform-fw#12](https://github.com/openAMRobot/openamr-platform-fw/issues/12), D17) | same as above | -The mapping below records the accountable repository/component and role known for this -proposal. Individual names are intentionally marked **TBD** where no assignment is recorded; -this table is not evidence that those assignments have been accepted. Resolve the TBD entries -before treating Issue #30's owner requirement as complete. +The mapping below records the accountable repository/component, role and named owner +where ownership has been confirmed in the PR #38 discussion. Remaining **TBD** entries are +genuine unassigned responsibilities; this table does not imply approval of the proposed message +schema or safety behaviour. | Interface participant | Accountable repository / component | Owner role | Named owner | |---|---|---|---| -| `/base/status` producer (Teensy Gate A / STM32H723ZG Gate B) | `openamr-platform-fw` | Base-controller firmware maintainer | TBD — assignment required | -| `/base/aux_status` producer/relay | `openamr-platform-fw` (CTL-017 CAN3 integration) | Firmware / lift-interface maintainer | TBD — assignment required | -| Navigation consumer | `openamr-platform-sw` (`navigation_status_node.py`) | Platform software maintainer | TBD — assignment required | -| Operator UI consumer | `openamrobot-ui` (#54) | UI maintainer | TBD — assignment required | -| Manipulation consumer | `openamrobot-manipulation` (#7) | Manipulation maintainer | TBD — assignment required | +| `/base/status` producer (Teensy Gate A / STM32H723ZG Gate B) | `openamr-platform-fw` | I8 base-controller firmware/electrical owner | @Evans-Kwashie | +| `/base/aux_status` producer/relay | `openamr-platform-fw` (CTL-017 CAN3 integration) | I8 firmware/electrical and lift-interface owner | @Evans-Kwashie | +| Navigation consumer | `openamr-platform-sw` (`navigation_status_node.py`) | Accountable platform software consumer owner | @skunal3318 (Mohamed reviewing) | +| Operator UI consumer | `openamrobot-ui` (#54) | UI consumer/integration owner | @panthera-momagdii | +| Manipulation consumer and authoritative arm-status producer | `openamrobot-manipulation` (#7) | Manipulation interface and consumer owner | @Brinex45, alongside @panthera-momagdii | | Diagnostics and logging consumers | Owning runtime / observability components | Diagnostics / logging maintainer | TBD — component and owner assignment required | | Interface regression tests | `openamrobot-interfaces` | Repository software lead / test maintainer | TBD — assignment required | +## Cross-repository lift-interlock ownership (working agreement) + +The PR #38 discussion records the following ownership direction: + +- I8/base-controller firmware is the sole producer of `lift_permit`. +- Manipulation owns the authoritative, validated measured `ArmStatus` producer and its separate interface. +- Platform software owns its `lift_permit` consumer integration. +- CTL-017 remains the final local enforcement point for the permit. +- Build 1 defines `STOWED` as the only safe arm configuration. No other safe pose is defined. + +This records the agreed ownership direction, not a completed wire contract or a safety approval. +The exact `ArmStatus` schema, freshness threshold and approved STOWED joint-space definition +still require manipulation-side definition and sign-off. The `BaseAuxStatus` permit fields, +reason mapping, maximum age, sequence/boot handling, withdrawal behaviour and restart +invalidation also remain to be specified and tested. The authoritative source and transport for +fresh base-stopped evidence remain unresolved. Until those details are agreed, consumers must +not infer permission from missing, stale, invalid or unknown inputs. + ## QoS and publish behavior The two frozen topics are /base/status and /base/aux_status. Both use reliable, @@ -143,9 +161,11 @@ mapping to the central fault registry, and the threshold/action for measured-ver disagreement remain unresolved. The fields in this draft are a working representation, not approval of a particular sensor, encoder, CAN object or firmware owner. -The lift interlock requirement is base confirmed stopped AND both arms in the approved safe -pose (stowed or carry). UNKNOWN, invalid or stale base/arm observations do not satisfy either -condition. The exact carry pose and the robot enforcement owner/handshake remain open. +The Build 1 lift interlock requires fresh, valid base-confirmed-stopped evidence AND both +arms in the approved `STOWED` configuration. No other safe arm pose, including CARRY, is +defined for Build 1. UNKNOWN, invalid or stale base/arm observations do not satisfy either +condition. CTL-017 is the final local enforcement point. The authoritative source/transport for +base-stopped evidence and the complete cross-controller permit wire semantics remain open. ## Field validity @@ -264,8 +284,9 @@ charging command/state lifecycle, `reboot_request_pending`, and `reset_cause` re - A separate base-stopped evidence message/topic, its producer, QoS, rate and timeout (Decisions 1 and 8). - ResetBaseController.srv (Decision 11). - MB7060 range topic names, rate and publisher (Decision 12). -- Drive configuration (2000h, 1017h), brakes and the robot lift-interlock enforcement owner. - The simulation-side guard is a mirror only, not the robot enforcement implementation. +- Drive configuration (2000h, 1017h), brakes, and the unresolved base-stopped evidence source/transport + and cross-controller lift-permit wire contract. CTL-017 is the local enforcement point; the + simulation-side guard is a mirror only, not the robot enforcement implementation. ## Open decisions From dd97b6cf8234b0ae76b0a1f42f364040c044d1a7 Mon Sep 17 00:00:00 2001 From: Evans Klenam Kwashie-Seyram Date: Tue, 17 Nov 2026 05:37:31 +0000 Subject: [PATCH 04/23] docs(i8): clarify lift permit ownership direction --- ros2/openamr_base_msgs/msg/BaseAuxStatus.msg | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/ros2/openamr_base_msgs/msg/BaseAuxStatus.msg b/ros2/openamr_base_msgs/msg/BaseAuxStatus.msg index 9d43ee8..3b6ff28 100644 --- a/ros2/openamr_base_msgs/msg/BaseAuxStatus.msg +++ b/ros2/openamr_base_msgs/msg/BaseAuxStatus.msg @@ -2,7 +2,8 @@ # Includes lift measured and declared position as separate values, validity, homing, motion, # stop sensors and faults; head light; Getac power-good; moving-adapter-plate E-stop. # Reports observations only. It does not enforce the lift interlock or prove a safety function. -# Lift interlock enforcement owner and inter-controller handshake remain undecided. +# Ownership direction: I8 produces lift_permit; manipulation provides authoritative ArmStatus; +# CTL-017 enforces the permit locally. Wire fields and freshness/withdrawal semantics remain open. # 0 is UNKNOWN. Freshness comes from consumer-local receipt time, never header.stamp. # Decision 13: position sources, homing semantics, raw/mapped fault rules and disagreement # threshold remain open. Do not interpret proposed fields/enums as an approved device map. From dc9178b7708f8924ce29e5f5018559801159d790 Mon Sep 17 00:00:00 2001 From: Evans Klenam Kwashie-Seyram Date: Tue, 17 Nov 2026 05:37:33 +0000 Subject: [PATCH 05/23] test(i8): assert confirmed interface ownership mapping --- tests/test_base_msgs.py | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/tests/test_base_msgs.py b/tests/test_base_msgs.py index e10c0fd..fb14ada 100644 --- a/tests/test_base_msgs.py +++ b/tests/test_base_msgs.py @@ -86,7 +86,11 @@ def test_header_stamp_clock_contract_is_consistent(self): def test_producer_consumer_ownership_gaps_are_explicit(self): contract = (PKG / "CONTRACT.md").read_text() self.assertIn("| Interface participant | Accountable repository / component | Owner role | Named owner |", contract) - self.assertIn("TBD — assignment required", contract) + self.assertIn("TBD — assignment required", contract) # diagnostics/logging and test ownership remain open + self.assertIn("| `/base/status` producer (Teensy Gate A / STM32H723ZG Gate B) | `openamr-platform-fw` | I8 base-controller firmware/electrical owner | @Evans-Kwashie |", contract) + self.assertIn("| Navigation consumer | `openamr-platform-sw` (`navigation_status_node.py`) | Accountable platform software consumer owner | @skunal3318 (Mohamed reviewing) |", contract) + self.assertIn("| Operator UI consumer | `openamrobot-ui` (#54) | UI consumer/integration owner | @panthera-momagdii |", contract) + self.assertIn("| Manipulation consumer and authoritative arm-status producer | `openamrobot-manipulation` (#7) | Manipulation interface and consumer owner | @Brinex45, alongside @panthera-momagdii |", contract) self.assertNotIn("Owners for each producer and consumer are recorded in the PR description.", contract) def test_status_identity_and_timing_fields(self): From 01679638a178b891d14c70617838ab2f29aeeea2 Mon Sep 17 00:00:00 2001 From: Evans Klenam Kwashie-Seyram Date: Tue, 17 Nov 2026 05:39:42 +0000 Subject: [PATCH 06/23] feat(i8): add proposed supervised lift permit fields --- ros2/openamr_base_msgs/msg/BaseAuxStatus.msg | 15 +++++++++++++-- 1 file changed, 13 insertions(+), 2 deletions(-) diff --git a/ros2/openamr_base_msgs/msg/BaseAuxStatus.msg b/ros2/openamr_base_msgs/msg/BaseAuxStatus.msg index 3b6ff28..7e68b3d 100644 --- a/ros2/openamr_base_msgs/msg/BaseAuxStatus.msg +++ b/ros2/openamr_base_msgs/msg/BaseAuxStatus.msg @@ -13,10 +13,21 @@ std_msgs/Header header # ROS time when available; diagnostic only, ne uint16 CONTRACT_VERSION=1 uint16 contract_version -uint32 boot_id # same value as in the BaseStatus of this boot -uint32 sequence +uint32 boot_id # same value as BaseStatus; identifies the lift-permit producer boot +uint32 sequence # BaseAuxStatus sequence; also orders the lift-permit observations uint64 monotonic_us +# --- supervised lift permit (I8 is the sole producer) --- +# These fields report the same permit that is enforced locally by CTL-017. +# boot_id and sequence above identify the permit producer boot and publication order. +# Consumers use local receipt time; they must not use header.stamp for permit freshness. +# A zero maximum age is invalid. The agreed non-zero limit and consumer-side ceiling remain open. +uint16 LIFT_PERMIT_REASON_NONE=0 +uint16 LIFT_PERMIT_REASON_UNKNOWN=1 +uint8 lift_permit # OBS_UNKNOWN/OBS_NO/OBS_YES; default and boot state are OBS_NO +uint16 lift_permit_reason_code # NONE only when permitted; non-zero when denied/unknown; mapping pending +uint32 lift_permit_max_age_ms # maximum accepted receipt age; 0 is invalid + uint8 OBS_UNKNOWN=0 uint8 OBS_NO=1 uint8 OBS_YES=2 From 7205da82f19b95754d0b54e26dafa45dbff60de4 Mon Sep 17 00:00:00 2001 From: Evans Klenam Kwashie-Seyram Date: Tue, 17 Nov 2026 05:39:45 +0000 Subject: [PATCH 07/23] docs(i8): specify proposed lift permit contract --- ros2/openamr_base_msgs/CONTRACT.md | 59 ++++++++++++++++++++++++++---- 1 file changed, 52 insertions(+), 7 deletions(-) diff --git a/ros2/openamr_base_msgs/CONTRACT.md b/ros2/openamr_base_msgs/CONTRACT.md index 25ea0e1..7a6cc52 100644 --- a/ros2/openamr_base_msgs/CONTRACT.md +++ b/ros2/openamr_base_msgs/CONTRACT.md @@ -48,13 +48,58 @@ The PR #38 discussion records the following ownership direction: - CTL-017 remains the final local enforcement point for the permit. - Build 1 defines `STOWED` as the only safe arm configuration. No other safe pose is defined. -This records the agreed ownership direction, not a completed wire contract or a safety approval. -The exact `ArmStatus` schema, freshness threshold and approved STOWED joint-space definition -still require manipulation-side definition and sign-off. The `BaseAuxStatus` permit fields, -reason mapping, maximum age, sequence/boot handling, withdrawal behaviour and restart -invalidation also remain to be specified and tested. The authoritative source and transport for -fresh base-stopped evidence remain unresolved. Until those details are agreed, consumers must -not infer permission from missing, stale, invalid or unknown inputs. +This records the agreed ownership direction, not a safety approval. The proposed +`BaseAuxStatus` representation now includes `lift_permit`, `lift_permit_reason_code` and +`lift_permit_max_age_ms`; the message's `boot_id` and `sequence` identify the permit +producer boot and publication order. A zero maximum age is invalid. The exact non-zero age +limit, reason-code mapping, sequence-wrap rule and consumer-side timeout still require agreement. + +The manipulation-side `ArmStatus` remains a separate cross-repository interface. Its exact +schema, freshness threshold and approved STOWED joint-space definition require manipulation-side +definition and sign-off. The authoritative source and transport for fresh base-stopped evidence +also remain unresolved. These are proposed interface fields and rules, not a completed safety +function or physical validation. + +## Lift-permit contract (proposed) + +The STM32H723 base controller is the sole authoritative producer of `lift_permit`. The permit +is an observation/functional interlock command to CTL-017; it is not a safety-rated signal and +does not replace the independent E-01 hardwired chain. + +- The permit defaults to `OBS_NO` at boot/reset. Permission may be asserted only when both + wheel encoders independently provide valid, fresh, current-session evidence that the base is + stopped, and both arms report the approved Build 1 `STOWED` configuration with no active + arm motion or trajectory. Relevant base faults, inhibits or loss of supervision deny permission. +- The D14 base-stopped candidate is absolute linear velocity below 0.01 m/s and absolute angular + velocity below 0.02 rad/s continuously for 500 ms, derived from both wheel encoders and actual + drivetrain geometry. This remains proposed pending the B5 bench measurement and owner approval; + it is not proof of physical standstill. +- `BaseAuxStatus.boot_id` identifies the permit-producing controller boot and + `BaseAuxStatus.sequence` orders permit publications. Consumers reject duplicate, out-of-order, + wrong-session and pre-reboot evidence. The exact uint32 wrap comparison rule remains open. +- Consumers calculate age from local receipt time. `lift_permit_max_age_ms` must be non-zero; + the consumer withdraws acceptance when that age expires or its independently configured + timeout is exceeded. The numerical maximum age, refresh rate and consumer timeout remain open. +- `lift_permit_reason_code` is `LIFT_PERMIT_REASON_NONE` only when permission is asserted. + Denied or unknown permission carries a non-zero reason. The complete deterministic reason map + and central fault-registry relationship remain open. +- Any prerequisite becoming false, invalid, stale or out of sequence withdraws permission + immediately. Permission is false after communication loss or restart of either controller + until fresh, valid evidence from the new sessions arrives. Restoration never replays a previous + lift command. +- CTL-017 is the final local actuator gate. It must reject both `MOVE_TO_STOP` and + `START_HOMING` without a current permit; while moving/homing, withdrawal or expiry requires + STOP, discarding the active target and rejecting subsequent motion until a new command. +- The permit must be continuously observable by CTL-017 independently of lift-command traffic. + A dedicated cyclic CAN permit PDO is preferred. Its COB-ID, PDO/OD mapping, receive timeout + and exact CTL-017 v1 object-dictionary representation must be agreed with the CTL-017 owner; + the emulator must use the same canonical mapping. + +The exact `ArmStatus` message fields, freshness threshold, active-trajectory representation and +STOWED joint-space definition are owned by manipulation and require sign-off from the responsible +joint-space owner. No heartbeat or generic readiness flag substitutes for measured arm status. +Missing, unsupported, stale, invalid, moving, trajectory-active or wrong-session arm feedback +denies permission. ## QoS and publish behavior From bfaaef60b0790c24d176e45b03f88c8c18dd0adc Mon Sep 17 00:00:00 2001 From: Evans Klenam Kwashie-Seyram Date: Tue, 17 Nov 2026 05:39:47 +0000 Subject: [PATCH 08/23] test(i8): cover proposed lift permit contract --- tests/test_base_msgs.py | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/tests/test_base_msgs.py b/tests/test_base_msgs.py index fb14ada..98d61d4 100644 --- a/tests/test_base_msgs.py +++ b/tests/test_base_msgs.py @@ -93,6 +93,32 @@ def test_producer_consumer_ownership_gaps_are_explicit(self): self.assertIn("| Manipulation consumer and authoritative arm-status producer | `openamrobot-manipulation` (#7) | Manipulation interface and consumer owner | @Brinex45, alongside @panthera-momagdii |", contract) self.assertNotIn("Owners for each producer and consumer are recorded in the PR description.", contract) + def test_lift_permit_fields_and_fail_closed_contract(self): + constants, fields = parse(messages()["BaseAuxStatus"]) + names = {name for _, name, _ in constants} + for expected in ( + ("uint8", "lift_permit"), + ("uint16", "lift_permit_reason_code"), + ("uint32", "lift_permit_max_age_ms"), + ("uint32", "boot_id"), + ("uint32", "sequence"), + ): + self.assertIn(expected, fields) + self.assertIn("LIFT_PERMIT_REASON_NONE", names) + self.assertIn("LIFT_PERMIT_REASON_UNKNOWN", names) + contract = (PKG / "CONTRACT.md").read_text() + for required in ( + "defaults to `OBS_NO` at boot/reset", + "duplicate, out-of-order", + "wrong-session and pre-reboot", + "withdraws permission immediately", + "CTL-017 is the final local actuator gate", + "`MOVE_TO_STOP`", + "`START_HOMING`", + "numerical maximum age, refresh rate and consumer timeout remain open", + ): + self.assertIn(required, contract) + def test_status_identity_and_timing_fields(self): _, fields = parse(messages()["BaseStatus"]) for expected in ( From b1a08cb9cb0c7e81ee4cc6e68edfb8f3ec36bafb Mon Sep 17 00:00:00 2001 From: Evans Klenam Kwashie-Seyram Date: Tue, 17 Nov 2026 05:39:49 +0000 Subject: [PATCH 09/23] docs(i8): list proposed lift permit in package README --- ros2/openamr_base_msgs/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ros2/openamr_base_msgs/README.md b/ros2/openamr_base_msgs/README.md index 7ef58ea..da37159 100755 --- a/ros2/openamr_base_msgs/README.md +++ b/ros2/openamr_base_msgs/README.md @@ -12,7 +12,7 @@ open decisions. - BaseStatus on /base/status: controller-state/readiness proposal, identity, timing/freshness, diagnostic observations, faults and proposed subsystem/constraint summaries. E-01-derived state semantics remain open under Decision 2. -- `BaseAuxStatus` on `/base/aux_status`: lift measured and declared position (separate), position validity, proposed homing state, head light, Getac power-good, second E-stop. +- `BaseAuxStatus` on `/base/aux_status`: lift measured and declared position (separate), position validity, proposed homing state, supervised `lift_permit` proposal, head light, Getac power-good, second E-stop. - `BaseFault`: one fault/diagnostic entry. Normal events, reset causes and UI Stop are represented by state fields, not fault codes. - `BaseSubsystemStatus`, `BaseMotionConstraint`: provisional nested messages (decision 1). From e1fdfd28cb3a2869f9cdfff0cae3a2f0b0bed73c Mon Sep 17 00:00:00 2001 From: Evans Klenam Kwashie-Seyram Date: Tue, 17 Nov 2026 05:42:43 +0000 Subject: [PATCH 10/23] chore(i8): regenerate Jazzy snapshot for lift permit fields --- compatibility/jazzy.json | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/compatibility/jazzy.json b/compatibility/jazzy.json index 3dad500..c6c3a5f 100644 --- a/compatibility/jazzy.json +++ b/compatibility/jazzy.json @@ -53,6 +53,14 @@ "type": "uint8", "value": 2 }, + "msg/LIFT_PERMIT_REASON_NONE": { + "type": "uint16", + "value": 0 + }, + "msg/LIFT_PERMIT_REASON_UNKNOWN": { + "type": "uint16", + "value": 1 + }, "msg/OBS_NO": { "type": "uint8", "value": 1 @@ -98,7 +106,7 @@ "value": 0 } }, - "type_hash": "RIHS01_fe993c816f75991ac226947a076c65c167fa9441fd6fb620ce31975defe93ecd" + "type_hash": "RIHS01_23dcaedd986387b6c111a52eed56866cc1a455f49895b3a93a851f5abff2cd6d" }, "msg/BaseFault": { "constants": { From 2a47f83ea48fd1c76352f912f411391f5682dc84 Mon Sep 17 00:00:00 2001 From: Evans Klenam Kwashie-Seyram Date: Tue, 17 Nov 2026 05:43:26 +0000 Subject: [PATCH 11/23] feat(i8): define proposed lift permit denial reasons --- ros2/openamr_base_msgs/msg/BaseAuxStatus.msg | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/ros2/openamr_base_msgs/msg/BaseAuxStatus.msg b/ros2/openamr_base_msgs/msg/BaseAuxStatus.msg index 7e68b3d..e3f4b19 100644 --- a/ros2/openamr_base_msgs/msg/BaseAuxStatus.msg +++ b/ros2/openamr_base_msgs/msg/BaseAuxStatus.msg @@ -24,6 +24,15 @@ uint64 monotonic_us # A zero maximum age is invalid. The agreed non-zero limit and consumer-side ceiling remain open. uint16 LIFT_PERMIT_REASON_NONE=0 uint16 LIFT_PERMIT_REASON_UNKNOWN=1 +uint16 LIFT_PERMIT_REASON_BASE_MOVING=2 +uint16 LIFT_PERMIT_REASON_BASE_FEEDBACK_INVALID=3 +uint16 LIFT_PERMIT_REASON_ARM_STATUS_MISSING=4 +uint16 LIFT_PERMIT_REASON_ARM_STATUS_STALE=5 +uint16 LIFT_PERMIT_REASON_ARM_POSE_UNSAFE=6 +uint16 LIFT_PERMIT_REASON_ARM_MOTION_ACTIVE=7 +uint16 LIFT_PERMIT_REASON_ARM_CONTROLLER_FAULT=8 +uint16 LIFT_PERMIT_REASON_BASE_FAULT=9 +uint16 LIFT_PERMIT_REASON_CTL017_LINK_LOST=10 uint8 lift_permit # OBS_UNKNOWN/OBS_NO/OBS_YES; default and boot state are OBS_NO uint16 lift_permit_reason_code # NONE only when permitted; non-zero when denied/unknown; mapping pending uint32 lift_permit_max_age_ms # maximum accepted receipt age; 0 is invalid From b10a4b94f97703b8116ebc74c9f1d94e45f70db5 Mon Sep 17 00:00:00 2001 From: Evans Klenam Kwashie-Seyram Date: Tue, 17 Nov 2026 05:43:29 +0000 Subject: [PATCH 12/23] docs(i8): document proposed lift permit denial reasons --- ros2/openamr_base_msgs/CONTRACT.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/ros2/openamr_base_msgs/CONTRACT.md b/ros2/openamr_base_msgs/CONTRACT.md index 7a6cc52..3f7bbf9 100644 --- a/ros2/openamr_base_msgs/CONTRACT.md +++ b/ros2/openamr_base_msgs/CONTRACT.md @@ -81,8 +81,12 @@ does not replace the independent E-01 hardwired chain. the consumer withdraws acceptance when that age expires or its independently configured timeout is exceeded. The numerical maximum age, refresh rate and consumer timeout remain open. - `lift_permit_reason_code` is `LIFT_PERMIT_REASON_NONE` only when permission is asserted. - Denied or unknown permission carries a non-zero reason. The complete deterministic reason map - and central fault-registry relationship remain open. + Denied or unknown permission carries a non-zero reason. The proposed reason values distinguish + base moving, invalid base feedback, missing/stale arm status, unsafe arm pose, active arm + motion, arm-controller fault, base fault and CTL-017 link loss. These are permit-diagnostic + reasons, not central `BaseFault` IDs; the final mapping and any registry relationship require + owner review. Consumer-detected permit expiry is reported by CTL-017 diagnostics, not inferred + as a producer-side reason. - Any prerequisite becoming false, invalid, stale or out of sequence withdraws permission immediately. Permission is false after communication loss or restart of either controller until fresh, valid evidence from the new sessions arrives. Restoration never replays a previous From 0a738a4229e23d956a7bbef66c1acdaeb6041249 Mon Sep 17 00:00:00 2001 From: Evans Klenam Kwashie-Seyram Date: Tue, 17 Nov 2026 05:43:32 +0000 Subject: [PATCH 13/23] test(i8): verify proposed lift permit reason codes --- tests/test_base_msgs.py | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/tests/test_base_msgs.py b/tests/test_base_msgs.py index 98d61d4..7d26ff2 100644 --- a/tests/test_base_msgs.py +++ b/tests/test_base_msgs.py @@ -106,6 +106,23 @@ def test_lift_permit_fields_and_fail_closed_contract(self): self.assertIn(expected, fields) self.assertIn("LIFT_PERMIT_REASON_NONE", names) self.assertIn("LIFT_PERMIT_REASON_UNKNOWN", names) + reason_values = { + name: value for _, name, value in constants + if name.startswith("LIFT_PERMIT_REASON_") + } + self.assertEqual(len(reason_values), len(set(reason_values.values()))) + for reason in ( + "LIFT_PERMIT_REASON_BASE_MOVING", + "LIFT_PERMIT_REASON_BASE_FEEDBACK_INVALID", + "LIFT_PERMIT_REASON_ARM_STATUS_MISSING", + "LIFT_PERMIT_REASON_ARM_STATUS_STALE", + "LIFT_PERMIT_REASON_ARM_POSE_UNSAFE", + "LIFT_PERMIT_REASON_ARM_MOTION_ACTIVE", + "LIFT_PERMIT_REASON_ARM_CONTROLLER_FAULT", + "LIFT_PERMIT_REASON_BASE_FAULT", + "LIFT_PERMIT_REASON_CTL017_LINK_LOST", + ): + self.assertIn(reason, reason_values) contract = (PKG / "CONTRACT.md").read_text() for required in ( "defaults to `OBS_NO` at boot/reset", From e171916bca1ae9f24ae7c733b5c200aef5cf0045 Mon Sep 17 00:00:00 2001 From: Evans Klenam Kwashie-Seyram Date: Tue, 17 Nov 2026 05:44:32 +0000 Subject: [PATCH 14/23] docs(i8): define proposed manipulation ArmStatus dependency --- ros2/openamr_base_msgs/CONTRACT.md | 29 +++++++++++++++++++++++++++++ 1 file changed, 29 insertions(+) diff --git a/ros2/openamr_base_msgs/CONTRACT.md b/ros2/openamr_base_msgs/CONTRACT.md index 3f7bbf9..e497cbd 100644 --- a/ros2/openamr_base_msgs/CONTRACT.md +++ b/ros2/openamr_base_msgs/CONTRACT.md @@ -60,6 +60,35 @@ definition and sign-off. The authoritative source and transport for fresh base-s also remain unresolved. These are proposed interface fields and rules, not a completed safety function or physical validation. +## Manipulation ArmStatus dependency (separate proposed interface) + +The lift-permit producer consumes a separate manipulation-owned runtime interface, proposed at +`openamrobot_manipulation_interfaces/msg/ArmStatus.msg` on `/manipulation/arm_status`. +This is not an extension of the already-approved I1 command/action schema. + +The proposed bimanual snapshot must provide: + +- Measured joint feedback for both arms, and measured end-effector pose where available. + Commanded targets and action goals are not evidence of actual pose. +- Stable per-arm identities matching the device manifest. +- A coordinated bimanual configuration classification. Build 1 accepts only the + manipulation-approved `STOWED` configuration; `CARRY`, `OTHER`, unsupported and + `UNKNOWN` do not grant lift permission in Build 1. +- Explicit motion state, including trajectory execution, jogging/direct motion, stopping and + idle/holding; active motion inhibits permission. +- Controller health, joint-feedback validity and explicit invalid/unavailable states. +- Snapshot timestamp, publisher boot/session identity and sequence number. + +Both arms must independently provide valid, fresh, current-session feedback. If either arm is +missing, stale, invalid, inconsistent, faulted, moving, trajectory-active or from an old session, +I8 denies or withdraws the permit. A heartbeat or generic readiness flag is not a substitute for +measured arm status. + +Manipulation owns the schema and publisher. The exact maximum feedback age, pose enum details, +STOWED joint-space values/tolerances/settling criteria, and the accountable joint-space approver +remain pending manipulation-side agreement. Until those are signed off, this dependency remains +Proposed and the lift permit must remain denied for an unapproved pose. + ## Lift-permit contract (proposed) The STM32H723 base controller is the sole authoritative producer of `lift_permit`. The permit From c065275a04af67707d10f32cf356999df3241240 Mon Sep 17 00:00:00 2001 From: Evans Klenam Kwashie-Seyram Date: Tue, 17 Nov 2026 05:44:34 +0000 Subject: [PATCH 15/23] test(i8): check proposed ArmStatus dependency contract --- tests/test_base_msgs.py | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/tests/test_base_msgs.py b/tests/test_base_msgs.py index 7d26ff2..8671bac 100644 --- a/tests/test_base_msgs.py +++ b/tests/test_base_msgs.py @@ -133,6 +133,10 @@ def test_lift_permit_fields_and_fail_closed_contract(self): "`MOVE_TO_STOP`", "`START_HOMING`", "numerical maximum age, refresh rate and consumer timeout remain open", + "separate manipulation-owned runtime interface", + "measured joint feedback for both arms", + "Build 1 accepts only the", + "publisher boot/session identity and sequence number", ): self.assertIn(required, contract) From 5b8efed328f802d31645d14f8005082ac3b1b5ba Mon Sep 17 00:00:00 2001 From: Evans Klenam Kwashie-Seyram Date: Tue, 17 Nov 2026 05:45:18 +0000 Subject: [PATCH 16/23] chore(i8): update Jazzy snapshot for permit reason constants --- compatibility/jazzy.json | 36 ++++++++++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) diff --git a/compatibility/jazzy.json b/compatibility/jazzy.json index c6c3a5f..1a9486f 100644 --- a/compatibility/jazzy.json +++ b/compatibility/jazzy.json @@ -104,6 +104,42 @@ "msg/STOP_UNKNOWN": { "type": "uint8", "value": 0 + }, + "msg/LIFT_PERMIT_REASON_BASE_MOVING": { + "type": "uint16", + "value": 2 + }, + "msg/LIFT_PERMIT_REASON_BASE_FEEDBACK_INVALID": { + "type": "uint16", + "value": 3 + }, + "msg/LIFT_PERMIT_REASON_ARM_STATUS_MISSING": { + "type": "uint16", + "value": 4 + }, + "msg/LIFT_PERMIT_REASON_ARM_STATUS_STALE": { + "type": "uint16", + "value": 5 + }, + "msg/LIFT_PERMIT_REASON_ARM_POSE_UNSAFE": { + "type": "uint16", + "value": 6 + }, + "msg/LIFT_PERMIT_REASON_ARM_MOTION_ACTIVE": { + "type": "uint16", + "value": 7 + }, + "msg/LIFT_PERMIT_REASON_ARM_CONTROLLER_FAULT": { + "type": "uint16", + "value": 8 + }, + "msg/LIFT_PERMIT_REASON_BASE_FAULT": { + "type": "uint16", + "value": 9 + }, + "msg/LIFT_PERMIT_REASON_CTL017_LINK_LOST": { + "type": "uint16", + "value": 10 } }, "type_hash": "RIHS01_23dcaedd986387b6c111a52eed56866cc1a455f49895b3a93a851f5abff2cd6d" From f6b76f9d00531afef74ec9244dede00f2a39ea4c Mon Sep 17 00:00:00 2001 From: Evans Klenam Kwashie-Seyram Date: Tue, 17 Nov 2026 05:45:26 +0000 Subject: [PATCH 17/23] docs(i8): update repository state for permit contract --- STATE.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/STATE.md b/STATE.md index a9bf204..ecec542 100644 --- a/STATE.md +++ b/STATE.md @@ -18,7 +18,7 @@ The PR evidence check fails when STATE.md exists and a PR neither updates it nor |---|---|---|---| | C10 dataset quality gate | PR #25 | draft / synthetic evidence only | Work-package owner reviews placement and supplies real-episode evidence | | Shared rules v2 (rollout step a, pilot) | PR #26 | in review | merge, then step (b) pin the harness | -| I8 base-controller interfaces | Issue #30 / `feat/i8-base-controller-msgs` | implementation and local verification passed (2026-11-11); contract remains proposed | owner review and resolution of open contract decisions | +| I8 base-controller interfaces | Issue #30 / PR #38 / `feat/i8-base-controller-msgs` | five-message implementation with proposed lift-permit fields and ArmStatus dependency documented; contract remains proposed (2026-11-17) | resolve three-vs-five scope, ArmStatus sign-off, permit timing/CAN mapping, diagnostics owner; rerun hosted verification | | StopState.msg for the stop-gate contract (platform-sw#119) | PR #35 | changes requested (panthera-momagdii) - rebased on main `14912e1`, hosted CI/DCO/CLA green at head `025ee28caf7e72b31e9b134d09e5fa3a8606aac0` | push, Mohamed approves same day; then platform-sw#90 repins nav-status-tests.yml from the fork pin to the merge SHA | ## Decisions this repository implements @@ -37,5 +37,6 @@ The PR evidence check fails when STATE.md exists and a PR neither updates it nor ## Not verified - I8 verification is local ROS 2 Jazzy software verification only; firmware integration, physical robot, safety-chain and hardware validation are not established (2026-11-11). -- PR #38 review follow-up: corrected BaseAuxStatus header timestamp comment; added clock-contract and ownership-gap regression checks; named participant assignments remain TBD (2026-11-15). +- PR #38 review follow-up: timestamp thread corrected and resolved; named I8/platform/UI/manipulation owners recorded; diagnostics/logging owner remains TBD (2026-11-17). +- PR #38 head `5b8efed328f802d31645d14f8005082ac3b1b5ba`: proposed `lift_permit`, reason-code candidates and maximum-age field added to `BaseAuxStatus`; `ArmStatus` dependency and fail-closed/restart/withdrawal semantics documented; 23 static checks; Jazzy compatibility snapshot regenerated. Hosted verification pending (2026-11-17). - No physical robot, safety-chain, released binary or cross-version deployment evidence is claimed. From 5169de21e4d9a824f556f830d0254833aac8932d Mon Sep 17 00:00:00 2001 From: Evans Klenam Kwashie-Seyram Date: Tue, 17 Nov 2026 05:45:56 +0000 Subject: [PATCH 18/23] docs(i8): correct regression test count --- STATE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/STATE.md b/STATE.md index ecec542..09785fa 100644 --- a/STATE.md +++ b/STATE.md @@ -38,5 +38,5 @@ The PR evidence check fails when STATE.md exists and a PR neither updates it nor - I8 verification is local ROS 2 Jazzy software verification only; firmware integration, physical robot, safety-chain and hardware validation are not established (2026-11-11). - PR #38 review follow-up: timestamp thread corrected and resolved; named I8/platform/UI/manipulation owners recorded; diagnostics/logging owner remains TBD (2026-11-17). -- PR #38 head `5b8efed328f802d31645d14f8005082ac3b1b5ba`: proposed `lift_permit`, reason-code candidates and maximum-age field added to `BaseAuxStatus`; `ArmStatus` dependency and fail-closed/restart/withdrawal semantics documented; 23 static checks; Jazzy compatibility snapshot regenerated. Hosted verification pending (2026-11-17). +- PR #38 head `5b8efed328f802d31645d14f8005082ac3b1b5ba`: proposed `lift_permit`, reason-code candidates and maximum-age field added to `BaseAuxStatus`; `ArmStatus` dependency and fail-closed/restart/withdrawal semantics documented; 24 static checks; Jazzy compatibility snapshot regenerated. Hosted verification pending (2026-11-17). - No physical robot, safety-chain, released binary or cross-version deployment evidence is claimed. From b8f1c1fd27a9f2c8ab47fa1b2319695da105e51c Mon Sep 17 00:00:00 2001 From: Evans Klenam Kwashie-Seyram Date: Tue, 17 Nov 2026 05:47:12 +0000 Subject: [PATCH 19/23] docs(i8): reconcile lift interlock ownership decisions --- ros2/openamr_base_msgs/CONTRACT.md | 20 ++++++++++++-------- 1 file changed, 12 insertions(+), 8 deletions(-) diff --git a/ros2/openamr_base_msgs/CONTRACT.md b/ros2/openamr_base_msgs/CONTRACT.md index e497cbd..f99c352 100644 --- a/ros2/openamr_base_msgs/CONTRACT.md +++ b/ros2/openamr_base_msgs/CONTRACT.md @@ -383,10 +383,13 @@ The following remain open in I8 rev4: proposed individual IDs still need registry-owner review. - Decision 6: reset-cause enum after STM32H723 reset-flag verification. - Decision 7: direction-specific travel inhibit when floor coverage is lost, with Navigation. -- Decision 8: robot lift/auxiliary interlock enforcement owner and handshake. The requirement - is base confirmed stopped AND both arms in the approved safe pose (stowed or carry); - UNKNOWN, invalid or stale inputs do not satisfy it. The exact carry pose and robot control - owner remain unresolved. The simulation-side guard is not a substitute. +- Decision 8: the enforcement ownership direction is now recorded in the cross-repository + working agreement: I8/base controller is the sole `lift_permit` producer, manipulation owns + the authoritative measured `ArmStatus` producer, and CTL-017 is the final local enforcement + point. Build 1 accepts only the approved `STOWED` configuration. Remaining open details are + the authoritative base-stopped evidence source/transport, ArmStatus schema/freshness and + STOWED joint-space sign-off, and the cyclic CAN permit PDO/OD mapping and timeout. The + simulation-side guard is not a substitute. - Decision 11: whether ResetBaseController.srv belongs in the first package. - Decision 12: MB7060 topic names, rate, publisher and consumer freshness contract. - Decision 13: independent measured-position source, declared-position source, separate @@ -398,7 +401,8 @@ receipt-time freshness, boot ID, uint32 sequence, uint16 contract version starti fault group 18001 ownership, restart-not-clearing-latched-fault rule, powered debug off by default and watchdog-first ordering. These frozen items are not reopened by this draft. -The four separate firmware decisions Alex requested by 11 Nov—ZLAC 2000h/heartbeat timeout, -robot lift-interlock owner, CTL-017 v1 object dictionary, and safety/IMU pin assignments—are -also still awaiting Evans' decision/recording. They are tracked separately from the I8 -message-schema decisions above. Any change to a frozen field requires a change request in #30. +The remaining separate firmware decisions Alex requested by 11 Nov—ZLAC 2000h/heartbeat +timeout, CTL-017 v1 object dictionary, and safety/IMU pin assignments—remain tracked separately +from the I8 message-schema decisions above. Lift-interlock ownership is no longer an open +assignment; its detailed wire contract and validation dependencies remain open. Any change to a +frozen field requires a change request in #30. From 9fe9df082944f531160895b475f6516c76ebc611 Mon Sep 17 00:00:00 2001 From: Evans Klenam Kwashie-Seyram Date: Tue, 17 Nov 2026 05:47:14 +0000 Subject: [PATCH 20/23] test(i8): guard against stale lift ownership wording --- tests/test_base_msgs.py | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/tests/test_base_msgs.py b/tests/test_base_msgs.py index 8671bac..7d3c685 100644 --- a/tests/test_base_msgs.py +++ b/tests/test_base_msgs.py @@ -139,6 +139,12 @@ def test_lift_permit_fields_and_fail_closed_contract(self): "publisher boot/session identity and sequence number", ): self.assertIn(required, contract) + self.assertNotIn("robot lift/auxiliary interlock enforcement owner and handshake", contract) + self.assertNotIn("the exact carry pose and robot control owner remain unresolved", contract) + return + # original + ): + self.assertIn(required, contract) def test_status_identity_and_timing_fields(self): _, fields = parse(messages()["BaseStatus"]) From 497a0f2716de9ad1f83e766447beb92965290601 Mon Sep 17 00:00:00 2001 From: Evans Klenam Kwashie-Seyram Date: Tue, 17 Nov 2026 05:47:22 +0000 Subject: [PATCH 21/23] fix(i8): correct permit contract regression assertions --- tests/test_base_msgs.py | 4 ---- 1 file changed, 4 deletions(-) diff --git a/tests/test_base_msgs.py b/tests/test_base_msgs.py index 7d3c685..3ed86e3 100644 --- a/tests/test_base_msgs.py +++ b/tests/test_base_msgs.py @@ -141,10 +141,6 @@ def test_lift_permit_fields_and_fail_closed_contract(self): self.assertIn(required, contract) self.assertNotIn("robot lift/auxiliary interlock enforcement owner and handshake", contract) self.assertNotIn("the exact carry pose and robot control owner remain unresolved", contract) - return - # original - ): - self.assertIn(required, contract) def test_status_identity_and_timing_fields(self): _, fields = parse(messages()["BaseStatus"]) From 2d54ab86d9901c911975dee38750389d8aeb2554 Mon Sep 17 00:00:00 2001 From: Evans Klenam Kwashie-Seyram Date: Tue, 17 Nov 2026 05:47:33 +0000 Subject: [PATCH 22/23] docs(i8): record current contract reconciliation --- STATE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/STATE.md b/STATE.md index 09785fa..ea3727e 100644 --- a/STATE.md +++ b/STATE.md @@ -38,5 +38,5 @@ The PR evidence check fails when STATE.md exists and a PR neither updates it nor - I8 verification is local ROS 2 Jazzy software verification only; firmware integration, physical robot, safety-chain and hardware validation are not established (2026-11-11). - PR #38 review follow-up: timestamp thread corrected and resolved; named I8/platform/UI/manipulation owners recorded; diagnostics/logging owner remains TBD (2026-11-17). -- PR #38 head `5b8efed328f802d31645d14f8005082ac3b1b5ba`: proposed `lift_permit`, reason-code candidates and maximum-age field added to `BaseAuxStatus`; `ArmStatus` dependency and fail-closed/restart/withdrawal semantics documented; 24 static checks; Jazzy compatibility snapshot regenerated. Hosted verification pending (2026-11-17). +- PR #38 (2026-11-17): proposed `lift_permit`, reason-code candidates and maximum-age field added to `BaseAuxStatus`; `ArmStatus` dependency and fail-closed/restart/withdrawal semantics documented; stale Decision 8 ownership wording corrected; 24 static checks; Jazzy compatibility snapshot regenerated. Hosted verification pending. - No physical robot, safety-chain, released binary or cross-version deployment evidence is claimed. From 04981e825c312f0b359d8dd1a44a0261c89ce354 Mon Sep 17 00:00:00 2001 From: Evans Klenam Kwashie-Seyram Date: Tue, 17 Nov 2026 05:49:07 +0000 Subject: [PATCH 23/23] docs(i8): clarify ROS permit reporting versus CAN enforcement --- ros2/openamr_base_msgs/msg/BaseAuxStatus.msg | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/ros2/openamr_base_msgs/msg/BaseAuxStatus.msg b/ros2/openamr_base_msgs/msg/BaseAuxStatus.msg index e3f4b19..8f6337c 100644 --- a/ros2/openamr_base_msgs/msg/BaseAuxStatus.msg +++ b/ros2/openamr_base_msgs/msg/BaseAuxStatus.msg @@ -1,9 +1,10 @@ # Auxiliary-device block on /base/aux_status. PROPOSED, not approved (I8 proposal rev 4). -# Includes lift measured and declared position as separate values, validity, homing, motion, -# stop sensors and faults; head light; Getac power-good; moving-adapter-plate E-stop. -# Reports observations only. It does not enforce the lift interlock or prove a safety function. -# Ownership direction: I8 produces lift_permit; manipulation provides authoritative ArmStatus; -# CTL-017 enforces the permit locally. Wire fields and freshness/withdrawal semantics remain open. +# Includes lift measured and declared position, the I8 lift-permit decision, validity, homing, +# motion, stop sensors and faults; head light; Getac power-good; moving-adapter-plate E-stop. +# This ROS status topic reports the permit; CTL-017 enforces it locally over the CAN interface. +# It is not a safety function and does not prove a safety function. +# Ownership: I8 produces lift_permit; manipulation provides authoritative ArmStatus; CTL-017 +# is the final local actuator gate. Numerical freshness limits and the CAN PDO/OD mapping remain open. # 0 is UNKNOWN. Freshness comes from consumer-local receipt time, never header.stamp. # Decision 13: position sources, homing semantics, raw/mapped fault rules and disagreement # threshold remain open. Do not interpret proposed fields/enums as an approved device map.