Skip to content

Capability 001: Forward Drive Commands and Status Queries

Status: Accepted

Context

The robot and its Drive are described in the mission statement. The Drive consists of two Motor Controller Boards with two motor outputs each. They speak UART only, in a fixed binary format, and run their released firmware unchanged. The Bridge therefore relays the CAN messages of the Drive to the boards. It is passive: it translates and distributes, but decides nothing.

References

Mapping

CAN message Board 1 Board 2
DriveCommand (motor 1, 2, 3) Command: left = motor 1, right = motor 2 Command: left = motor 3, right = 0
StatusQuery Query Query

Functional Requirements

  1. The Bridge splits each Drive Command across the boards as mapped.
  2. It translates each message into the UART format, including start marker and checksum.
  3. It passes values on unchanged: no checking, limiting, or scaling.
  4. Messages of other subsystems never reach the software; the acceptance filter of the CAN controller drops them.

Non-Functional Requirements

  1. At most 10 ms from the complete reception of a CAN message to the start of the UART transmission, measured with a logic analyzer.
  2. Load: one Drive Command every 250 ms, Status Queries on demand.

Error Handling

  1. CAN errors (error flags, bus-off) are reported as plain text over USB serial, at most once per second.
  2. When the transmit buffer of a board is full, the new message evicts the oldest one, and the eviction is reported over USB serial.
  3. Before its initialization is complete, the Bridge sends nothing.

Solution Constraints

  1. The CAN receive interrupt translates the message, puts the result into the transmit buffers (one per board), and starts the transmission.
  2. UART transmission is interrupt-driven.
  3. Interrupts never write to USB serial. They count errors, and the main loop reports them.
  4. The transmit buffers hold two frames each. Eviction moves the read index, so it runs with interrupts disabled.

Out of Scope

  • Checking, limiting, or scaling values
  • Repeating or refreshing commands (mission statement, principle Safe when silent)
  • Timeout supervision: each board stops on its own after about 800 ms without a command
  • The direction from the boards to the CAN bus

Acceptance Criteria

  1. DriveCommand (300, −300, 100): board 1 receives Command (300, −300), board 2 receives Command (100, 0), both with a valid checksum.
  2. DriveCommand (5000, 0, 0): board 1 receives 5000 unchanged.
  3. StatusQuery: each board receives one Query.
  4. CAN bus error: reported over USB serial, no UART frame is sent.
  5. Full transmit buffer: the oldest message is evicted, and the eviction is reported over USB serial.
  6. Under the load of NFR 2: at most 10 ms delay.

Test vectors for criteria 1 to 3, in hexadecimal bytes as they appear on the wire:

Criterion CAN (identifier: payload) Board 1 (UART) Board 2 (UART)
1 08200001: 2c 01 d4 fe 64 00 cd ab 2c 01 d4 fe 35 54 cd ab 64 00 00 00 a9 ab
2 08200001: 88 13 00 00 00 00 cd ab 88 13 00 00 45 b8 cd ab 00 00 00 00 cd ab
3 08200002: (no payload) c1 ab c1 ab c1 ab c1 ab

Decisions

  1. The robot sees one Drive, not two boards: one Drive Command and one Status Query for the whole Drive. A later CAN board with three motor outputs can replace the Bridge without a change to drive.dbc.
  2. Motor 3 is connected to the left output of board 2; the right output receives 0.
  3. The Superordinate Controller computes the kinematics; the Bridge receives motor speeds.
  4. The Bridge deviates from the CAN bus guideline to keep it small:
  5. The encode and decode code is written by hand, because drive.dbc has two messages only. Round-trip tests check it against the values in drive.dbc.
  6. The receive interrupt translates instead of only enqueuing, because translation is short and bounded and saves a second buffer.
  7. The Bridge supervises no timeouts; the boards do.