Skip to content

Capability 006: Health Report

Status: Accepted

Context

Errors alone make silence on USB serial ambiguous: it may mean a healthy Bridge, a stopped one, or a Motor Controller Board that no longer answers. Without a watchdog, a stopped Bridge recovers only by a manual reset.

Following the principle Safe when silent of the mission statement, silence must never pass for health. With this capability, the Bridge reports its state on its own, notices a board that has fallen silent, bounds every UART transmission, and restarts itself when it stops making progress. Like the CAN Adapter of the Superordinate Controller, it does so in a Status Report.

References

Details

Status Report

One line over USB serial:

# Status: uptime <s> s, can rx <n>, can errors <n>, bus-offs <n>, can tx discarded <n>, board 1: tx <n>, evictions <n>, tx aborts <n>, rx <n>, discarded frames <n>, feedback <age>; board 2: <same fields>; usb drops <n>, last reset <cause>.
Field Meaning
uptime Seconds since the start
can rx CAN messages received that pass the acceptance filter
can errors, bus-offs, can tx discarded As counted for capabilities 001 and 003
tx UART frames sent to the board
evictions Frames evicted from the transmit buffer of the board (capability 001, Error Handling 2)
tx aborts UART transmissions aborted because they did not complete in time
rx Valid frames received from the board
discarded frames As counted for capability 003
feedback Age of the last valid frame from the board in seconds with one decimal, e.g. 0.0 s ago; silent once it exceeds the Silence Timeout; never before the first one
usb drops Status Reports dropped because USB serial could not take them
last reset Cause of the last start: power-on, reset pin, watchdog, or software

Every counter starts at 0 at the start and wraps around at 2^32.

Timing

Name Value
Status Interval 5 s
Minimum interval between two Status Reports 1 s
Silence Timeout 2 s
UART transmission timeout 10 ms; a frame takes under 1 ms at 115200 bps
Watchdog timeout 500 ms

Functional Requirements

  1. The Bridge sends a Status Report every Status Interval.
  2. It sends a Status Report at once when an error counter increases or a board becomes silent or answers again, but never two within the minimum interval; the next periodic one follows the Status Interval after it. It is the report of the errors of capabilities 001 and 003.
  3. A board is silent when no valid frame has arrived from it for the Silence Timeout. The Bridge only reports it; it sends nothing on CAN and nothing to the board because of it.
  4. A UART transmission that has not completed within the UART transmission timeout is aborted and counted; the Bridge goes on with the next frame for that board.
  5. When the main loop makes no progress for the watchdog timeout, the Bridge restarts, and its Status Reports name the cause of the last start.

Non-Functional Requirements

  1. A Status Report arrives every 5 s ± 0.1 s, measured by the receive time of 10 consecutive reports on the host, without errors in between.

Technical Requirements

  1. Interrupts never write to USB serial; they count, and the main loop reports (capability 001, Solution Constraints 3).
  2. A Status Report never overwrites one that USB serial is still transmitting; when USB serial is busy or no host listens, the new report is dropped and counted.
  3. The watchdog is the independent watchdog (IWDG), enabled in STM32CubeMX; generated code is changed only between its USER CODE markers (ADR-001). It pauses while a debugger halts the core.
  4. Time comes from the system tick, as for capability 002.

Error Handling

  1. A Status Report that USB serial cannot take is dropped and counted in usb drops.
  2. An aborted UART transmission is counted in tx aborts; it triggers a Status Report like any other error.

Out of Scope

  • Acting on a silent board, e.g. resending, stopping the other board, or reporting it on CAN: the boards supervise their own timeouts (capability 001, Decision 4)
  • Reporting the health of the Bridge on CAN
  • Resending an aborted UART frame; the next Board Command follows within 250 ms

Acceptance Criteria

All criteria except the last two run in the host harness of ADR-002, with the mocked clock.

  1. Started by power-on, 3 Drive Commands received, boards answering, 5 s elapsed: the Status Report shows uptime 5 s, can rx 3, tx 3 for each board, and last reset power-on.
  2. A CAN error 2 s after the last Status Report: a Status Report with can errors 1 follows at once.
  3. Another CAN error 0.5 s after that: the next Status Report follows 1 s after the previous one.
  4. Board 1 sends no frame for 2 s while board 2 does: a Status Report with board 1 feedback silent follows at once; when board 1 sends a frame again, another one with the age of that frame follows within the minimum interval.
  5. A UART transmission to board 1 without completion for 10 ms: it is aborted, the next frame for board 1 is sent, and the next Status Report shows tx aborts 1 for board 1.
  6. USB serial busy when a Status Report is due: the report is dropped, and the next one shows usb drops 1.
  7. Before its initialization is complete, the Bridge sends no Status Report.
  8. On the bridge test fixture, with a USB host listening: a Status Report every 5 s; the reset button yields last reset reset pin. (manual test test/manual/bridge_test_fixture.md).
  9. On the bridge test fixture, a test build whose main loop stops 10 s after the start: the Bridge restarts, and its next Status Report ends with last reset watchdog. (manual test test/manual/bridge_test_fixture.md).

Decisions

  1. Reporting a silent board is no timeout supervision. The Bridge stays passive: it neither repeats nor withholds a message because of it (capability 001, Decision 4). It only tells the developer at the USB serial why a Motor may not move. The USB output is a developer instrument meant for debugging purposes. Consequence: the Superordinate Controller learns nothing about a silent board from the Bridge; it has to judge the feedback on CAN itself.
  2. The Status Report follows the one of the CAN Adapter. Both devices sit in the same chain and are watched by the same developer, often side by side. Consequence: the same prefix # Status:, the same rhythm, and the same reset causes.
  3. A UART transmission is bounded by a timeout, not only by its interrupt. A lost transmit-complete interrupt would otherwise block the board for good, as a lost CAN outcome blocked the CAN Adapter before demo-v1.0.1. Consequence: a transmission that legitimately takes longer than 10 ms would be aborted; at 115200 bps it never does.