> Documentation index: https://nao-rs.lukaloehr.com/llms.txt, a list of every page in this documentation.

# The cycle in HAL's order

> The body start-up and the per-cycle order of reads, broadcasts, writes and the USB exchange, kept exactly as Aldebaran's HAL runs them.

nao-rs runs the body in the same order as Aldebaran's HAL (NAOqi 2.8.5), down
to which message goes into which frame. The chest board and the motor boards
have only ever seen HAL, so nao-rs gives them nothing else: the full HAL
start-up of two recordings, 23,904 USB calls, replays byte for byte.

## Start-up

1. **Link.** Open the chest board (USB `ffff:0006`), select configuration 1,
   send the start request, claim interface 0, read the chest board version.
2. **Preferences.** Read the 4,635-byte preference block from the chest board
   and check its CRC: body id, every board's stored serial number, joint zero
   positions, foot pressure gains and offsets, IMU offsets. This and the link
   take 275 ms on the robot.
3. **Bootloader versions.** Three id reads of the chest board.
4. **Device start-up.** The sonar board, the chest board and the two EEPROMs,
   then the motor temperature tracking and the inertial unit.
5. **Motor board handshake.** Each motor and foot board is asked for its
   configuration, up to three times. A board is accepted only when its
   configuration version is in the accepted list. The runtime's default is
   `[10]`, as in HAL 2.8.5, so the robot's version 11 boards are rejected and
   get no motor commands beyond HAL's idle broadcasts. Accepting 11 is the
   motor session's step (**planned**). The handshake runs on the cycle
   thread after the runtime has returned the robot's identity, so the program
   using the runtime starts in parallel (2.2 s with version 11 boards).

The guard's takeover skips steps 2 to 5: it starts the link and sends
stiffness 0 to both motor buses in its first frame.

## Every cycle

Devices are visited in HAL's order: inertial unit, battery, sonar board, chest
board, the 13 joint boards, the 2 foot boards, the 2 EEPROMs.

1. **Before the exchange:** the motor temperature step, the step that holds
   every joint without stiffness at its measured position (a joint with
   stiffness 0 is commanded to where it is), and HAL's stiffness safety:
   controller lost, cycle stall and battery over-current scale every joint's
   stiffness down ([details](https://nao-rs.lukaloehr.com/safety.md#hals-safety-layer-in-every-frame)).
2. **Build the frame:** every device's read request, then the four joint
   broadcasts (positions and stiffness for both motor buses), then every
   device's write request: chest LED, foot LEDs, sonar enable.
3. **Client state:** when the chest board's client state changes, a vendor
   request goes out first, and the chest LED is not sent in that cycle. nao-rs
   reports "client connected" (`0x24`), as HAL does when LoLA connects.
4. **USB exchange:** read the answer to the *previous* frame, write the new
   frame, then hand the answer to the devices. Each answer belongs to the frame
   before, exactly as in HAL.
5. **Reconnect:** after more than 10 failed exchanges in a row, the link is
   closed and opened again.

## Timing

HAL's configuration asks for a 10 ms cycle with at least 8 ms of waiting. On
the robot, HAL's cycles take 12.1 ms on average, alternating about 9.6 and
14.6 ms between reads. nao-rs runs a fixed 12 ms period on an absolute-deadline
ticker; a live run of the whole runtime did 1,043 cycles in 15 seconds with
the slowest at 12.4 ms.

`hulk`'s clock, which walking and motion interpolation use for cycle
durations, runs on the full-precision time since start. HULKs' interface went
through seconds as a 32-bit float, which after about 9 hours of uptime can
only step in 3.9 ms units, a third of a cycle.

## What nao-rs changes

The bytes on the wire and their order are HAL's, with one omission: HAL
writes a motor temperature log into the two EEPROMs behind the chest board
every 10 seconds. nao-rs never writes board-stored data, so these writes are
off; the start-up still reads the EEPROMs.

Three things are added in front of HAL's logic, as deliberate safety
deviations:

- the [death switch](https://nao-rs.lukaloehr.com/safety.md) check before every frame;
- non-finite positions and stiffness values made limp
  ([details](https://nao-rs.lukaloehr.com/safety/death-switch.md#safety-deviations-from-hal));
- stiffness limited to 0..1.

Positions are not limited to the joint's range: as on HAL, they go to the
boards as commanded while the joint is stiff, and a joint at stiffness 0
follows its sensor.

## Related topics

- [Architecture](https://nao-rs.lukaloehr.com/architecture.md)
- [Boot time](https://nao-rs.lukaloehr.com/architecture/boot.md)
- Previous: [Architecture](https://nao-rs.lukaloehr.com/architecture.md)
- Next: [Boot time](https://nao-rs.lukaloehr.com/architecture/boot.md)