Skip to content

[I8] Add the openamr_base_msgs package (base status, aux devices, E-stop diagnostics) #30

Open

Description

@BotshareAI

Why

P-03 rev20.1 item 24 and WP-UI-VERIFICATION-01 (R8) require the I8 message package openamr_base_msgs. It is not on main of this repository yet. Until it exists:

  • navigation_status_node.py in openamr-platform-sw reports NOT_READY with BASE_LINK_LOST, because no I8 adapter can be written.
  • The UI Reporting Mode (openamrobot-ui #54) and the planned whole-robot status cannot show base, lift, head light, Getac power-good or chest E-stop state.

Scope (from P-03 rev20.1 item 24 and the I8 review in openamr-platform-fw #10)

  • Base controller status, including reset reason and the monotonic microsecond time base.
  • The generic aux-device block: lift, head light, Getac power-good, chest E-stop status.
  • E-stop and SAFETY_OK as diagnostics only. E-01 rev1.5: no bus carries a safety function.
  • Fault codes in the central fault registry here, base-controller codes owned by platform-fw.
  • CONTRACT.md with version, freshness and UNKNOWN rules, in the style of openamr_nav_msgs.

Related

Done when

  • The package builds in CI with message tests and a CONTRACT.md.
  • Producers (platform-fw) and consumers (platform-sw navigation status, openamrobot-ui) are listed with owners.
  • The date for the package is agreed with the platform lead and recorded in P-03.

Owner: Evans (I8, base controller). Reviewers: tech lead, platform lead.


Generated by Claude Code

Activity

  1. Evans-Kwashie commented on Oct 30, 2026

    @Evans-Kwashie

    I8 message plan (proposal, under review): I8 Base Controller Interface Proposal. It covers BaseControllerStatus, BaseFault, the fault registry and the fixture states. Open decisions are in Section 8. The aux-device block and chain diagnostics will follow PR #31 sections 2.3–2.6.

  2. Evans-Kwashie commented on Nov 4, 2026

    @Evans-Kwashie

    I8 design freeze, 6 Nov: proposal rev 3 (dated 4 Nov)
    https://drive.google.com/file/d/13kjNTuKc2QxGmEzMwOUjGek08DWnfh1u/view

    Supersedes the version linked above. Aligned with my interfaces #31 answers (4 Nov), E-01 rev1.6 and the reviews from Alex (27 Oct) and Nikolai (2 Nov). Covers the fault registry (Section 4) and the freshness/UNKNOWN rules (Sections 3 and 6).

    Frozen with this revision:

    • Topics /base/status and /base/aux_status; reliable, transient-local depth 1
    • Message types: BaseStatus (on /base/status) and BaseAuxStatus (on /base/aux_status); BaseControllerStatus is renamed to BaseStatus
    • Heartbeat and stale: /base/status 10 Hz, stale 0.5 s; /base/aux_status 5 Hz, stale 0.6 s; freshness from local receipt time, header stamp diagnostic only
    • Boot ID and uint32 sequence in every message; contract_version uint16 starting at 1
    • Base fault codes in group 18001 (owned by openamr-platform-fw#10), registry in this repo; a restart never clears a latched fault
    • Powered debug off by default (decision 10)

    Still open (Section 8):

    • Decision 1: final message set (BaseStatus, BaseAuxStatus, BaseFault; whether subsystem/constraint messages are needed)
    • Decision 2: controller-state, readiness, command-acceptance and recovery-required semantics
    • Decision 3: command timeout non-latching on STM32
    • Decision 4: fault lifecycle, retention, clearing and list overflow
    • Decision 5: registry file format and generated vs maintained constants
    • Decision 6: reset-cause enum after STM32H723 reset-flag check
    • Decision 7: travel inhibit when floor coverage is lost (with Navigation)
    • Decision 8: ownership of the remaining aux constraints (the lift interlock itself is in firmware)
    • Decision 11: whether ResetBaseController.srv is in the first package
    • Decision 12: MB7060 range topic names, rate and publisher (with Navigation)

    Any change to a frozen field after Friday goes through a change request here. Draft PR with the .msg files and CONTRACT.md by 10 Nov.

  3. Evans-Kwashie commented on Nov 10, 2026

    @Evans-Kwashie

    I8 Base Controller Interface Proposal — rev 4

    The revised proposal is available here:

    [I8_Base_Controller_Interface_Proposal_rev4.docx](https://docs.google.com/document/d/1jgLb4CldMg7eqCC1dRfsk2b3fjoJYJod/edit)

    Rev 4 reflects the 6 November interface design-freeze baseline and documents the base status and auxiliary status contracts, freshness and UNKNOWN handling, fault-registry ownership, lift-state reporting, and the corrected physical location of the second E-stop.

    The frozen interface items have been retained. Remaining decisions are explicitly identified in the proposal as open and are not presented as approved.

    @BotshareAI @panthera-momagdii — Please review and confirm whether this revision is accepted, or identify any changes required before implementation proceeds.

  4. Evans-Kwashie commented on Nov 11, 2026

    @Evans-Kwashie

    Lift-interlock interface follow-up

    Following the firmware ownership decision in "platform firmware issue #20" (openAMRobot/openamr-platform-fw#20), the base controller is the authoritative producer of lift permission, and CTL-017 must enforce that permission locally.

    The I8 contract needs to define the explicit permit signal and its producer/consumer, validity, freshness, sequence and boot-ID semantics. Unknown, stale, invalid or pre-reboot status must fail closed.

    Please treat the proposed less-than-1-rpm-for-500-ms stopped threshold as provisional pending bench validation.

  5. Evans-Kwashie commented on Nov 12, 2026

    @Evans-Kwashie

    Lift-permit contract requirements from platform-fw #20

    Following the #20 firmware-owner decision and the D14 proposal, I8 must carry an explicit, continuously supervised lift-permit contract. The STM32H723 base controller is the sole producer; CTL-017 is the local consumer and final actuator gate.

    Please add/agree the following contract semantics before freezing the wire mapping:

    • Permit state: default false; asserted only when both wheel encoders independently provide valid, fresh, current-session stopped evidence and both arms are in explicitly approved stowed/carry poses with no active arm motion/trajectory.
    • Base-stopped candidate (D14): |linear velocity| < 0.01 m/s and |angular velocity| < 0.02 rad/s continuously for 500 ms. Thresholds remain proposed pending owner approval and B5 measurement.
    • Arm source: identify the authoritative producer, message fields, pose enum, both-arm aggregation rule, freshness limit and representation of active motion/trajectory. Do not infer arm-safe state from heartbeat or a generic ready flag.
    • Identity/order: include producer boot/session identity and monotonically increasing sequence; reject duplicate, out-of-order, previous-session and pre-reboot evidence.
    • Freshness/withdrawal: define the consumer-side permit timeout and refresh rate; loss, invalidity or expiry must withdraw permission. CTL-017 must STOP during an active move and reject subsequent motion commands.
    • Command gating: CTL-017 must check permit locally before both MOVE_TO_STOP and START_HOMING. Permit restoration must not replay a previous command.
    • Diagnostics: define deterministic rejection/withdrawal reason reporting for base-moving, arm-unsafe/active, stale/invalid evidence, wrong session and expired permit.

    Wire-format decision still required: choose the exact PDO/OD mapping and COB-ID in coordination with CTL-017 #15. A dedicated cyclic permit PDO is preferred so withdrawal is observable independently of lift-command traffic. The emulator #39 must use the identical mapping. Until these fields and mappings are agreed across I8, #15 and #39, R4 remains PROPOSED and #20 is not implementation-complete.

  6. BotshareAI commented on Nov 13, 2026

    @BotshareAI
    ContributorAuthor

    I8 rev 4, my review as one of the three reviewers. I sign off the frozen fields.

    Positions on the open decisions: three messages only (BaseStatus, BaseAuxStatus, BaseFault); five states; non-latching 200 ms command timeout; separate active and latched fault flags, latched clears only by deliberate reset; one YAML fault registry with generated constants; raw reset flags plus a derived enum with UNKNOWN; travel inhibit report-only in Build 1; no reset service in v1; four sensor_msgs/Range topics from firmware; lift position valid only after homing.

    Two requirements for #38:

    1. Lift permit, mandatory. BaseAuxStatus carries lift_permit, a reason code, the producer boot identifier, a sequence number and a stated maximum age. A consumer treats a missing, stale, repeated, out-of-sequence or pre-reboot permit as "no permit". The permit is invalid after communication loss and after a restart of either controller until a new one arrives. The contract text says this, and the tests cover each case.
    2. Latch visibility. BaseStatus exposes the three latches of the safety state machine (readiness, UI stop, host session stop), so the UI can show why motion is refused.

    Everything stays Proposed until Mohamed and Anushka have recorded their positions.


    Generated by Claude Code

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

No labels
No labels

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions