Skip to content

Capability 001: Heartbeat

Status: Accepted

Context

Following the principle Safe when silent of the mission statement, the Drive stops when it receives no Drive Command for longer than its timeout. The Superordinate Controller keeps the Drive operational by sending a Drive Command at its cycle time. As long as the controller has nothing to drive, that command is the Neutral Drive Command: all target speeds zero.

Important to know: The robot is a mashup of dedicated and hacked hardware. We need to take that hardware as is. For example, the hacked motor controller does not have a dedicated heartbeat message. Therefore, the system has no dedicated heartbeat message.

References

Details

Message CAN identifier Payload Cycle time Timeout of the Drive
Neutral Drive Command: DriveCommand (0, 0, 0) 08200001 00 00 00 00 00 00 250 ms 800 ms

On the serial line of the CAN Adapter, the Neutral Drive Command is the CAN Frame Line <08200001:00 00 00 00 00 00\n.

Functional Requirements

  1. From its start until it shuts down, the Superordinate Controller runs its own cycle: it sends a Drive Command at the cycle time of DriveCommand. As long as it has no other target speeds to send, that is the Neutral Drive Command.

Non-Functional Requirements

  1. The first Drive Command is sent at most 312 ms after the start: one cycle time plus 25 % for starting the process on an operating system without real-time guarantees. The interval between consecutive ones of the own cycle is 250 ms ± 25 ms. Both are measured by the receive time of 40 consecutive CAN Frame Lines on the serial line.

Technical Requirements

  1. The Superordinate Controller runs on Linux on a Raspberry Pi without a CAN interface of its own. It reaches the CAN bus through the CAN Adapter, a USB serial device at 115200 bps 8N1.
  2. A later hardware extension of the Raspberry Pi provides a CAN interface (SocketCAN). Replacing the CAN Adapter by it changes only the access to the CAN bus, not the sending of the Neutral Drive Command.
  3. The serial device is configurable, so that tests run against a pseudo-terminal.

Error Handling

  1. The CAN Adapter sends a frame that fails on the bus only once; its automatic retransmission is disabled. The Superordinate Controller does not resend it either: the next cycle follows within 250 ms, and the timeout of the Drive tolerates two lost frames in a row.
  2. A failed write to the CAN Adapter is logged, at most once per second; the next cycle sends again.
  3. If the serial device does not exist at the start, the Superordinate Controller logs it and exits with a non-zero status.

Out of Scope

  • Determining the health of the system and withholding the Drive Command when it is unhealthy
  • Computing target speeds other than zero
  • Receiving messages of the Drive

Acceptance Criteria

  1. Started against a pseudo-terminal: the line <08200001:00 00 00 00 00 00 arrives as required by Non-Functional Requirement 1.
  2. Shut down: no further CAN Frame Line within 1 s.
  3. Started with a serial device that does not exist: exits with a non-zero status and a log message naming the device.
  4. On the robot, with the CAN Adapter and the Drive connected: no serial timeout alarm of the motor controller boards for 1 minute (manual test test/manual/robot.md).

Decisions

  1. The heartbeat is the Neutral Drive Command, not a StatusQuery. Only a valid command resets the timeout of the motor controller boards; a query does not (hoverboard-firmware v1.0.0, command_api.md, section Safety timeout). Consequence: no dedicated heartbeat message is needed; the later drive capability sends its target speeds in the same cycle instead of zeros.
  2. The heartbeat is sent unconditionally. The Superordinate Controller cannot determine the health of the system yet.
  3. The CAN bus is accessed through a port with one implementation per access. The first implementation writes CAN Frame Lines to the CAN Adapter; a SocketCAN implementation follows with the hardware extension. Consequence: the heartbeat sees CAN frames only, never the line format.