> Documentation index: https://nao-rs.lukaloehr.com/llms.txt, a list of every page in this documentation. # What nao-rs is > What nao-rs replaces on a NAO6, why it exists, and what works today. nao-rs is a software stack for the Aldebaran (SoftBank) NAO6 robot, written in Rust. It replaces the layer between the robot's control software and its hardware: Aldebaran's HAL and LoLA, and HULKs' HULA on HULKs-OS. Everything above that layer, such as walking, balance and the robot API, keeps running unchanged. ## What it replaces On a NAO6 with HULKs-OS 9.0.1, four programs sit between the control software and the hardware today: | Today | Role | nao-rs | | --- | --- | --- | | HAL (Aldebaran) | Talks USB to the chest board, which reaches the 13 motor boards, the 2 foot boards, the IMU, sonar and battery | `body`, `chestlink`, `sensors` crates | | LoLA (Aldebaran) | Drives the head over I2C (LEDs, touch, power monitor, temperature) and serves the RoboCup socket | `head` crate | | HULA (HULKs) | Translates LoLA's socket for HULKs' `hulk` | not needed: `hulk` links the runtime directly | | `alfand` (Aldebaran) | Head fan control | `fan` crate. HULKs-OS doesn't start `alfand`, so on HULKs-OS the fan is not controlled at all | nao-rs puts all of this into one process, the robot runtime, plus one small watchdog process, the guard. The firmware on the chest board and the motor boards stays as it is, and so do the Linux kernel's own drivers (USB, cameras, audio, the head's USB-I2C bridge, Wi-Fi). ## Why - **The motors of newer robots don't start under HULKs-OS.** A NAO6 that once ran NAOqi 2.8.7 has motor board firmware with configuration version 11. The HAL that HULKs-OS ships (NAOqi 2.8.5) accepts only version 10, so it rejects every motor board and the robot can't move. nao-rs reads version 11 directly. - **A stop that always works.** In the original stack, stopping the motors depends on the controller and HAL being alive: HAL lowers the stiffness over 5 seconds when its client goes quiet, and when HAL itself hangs, the last resort is holding the chest button until the robot powers off. nao-rs checks a latched death switch before every frame it sends, and a separate guard process takes over the chest board when the runtime hangs. See [Safety model](https://nao-rs.lukaloehr.com/safety.md). - **Fewer moving parts.** Three processes and two sockets become one process. Boot gets shorter and there is no shared memory between programs that can disappear. See [Boot time](https://nao-rs.lukaloehr.com/architecture/boot.md). - **Open and checked.** Every driver is ported 1:1 on the wire and tested against recordings of the real robot. See [Verification](https://nao-rs.lukaloehr.com/verification.md). ## Where it lives nao-rs is developed by Luka Löhr. The control software, the robot API, the brain and the CLI are in the public repository [luka-loehr/nao-rs](https://github.com/luka-loehr/nao-rs) (GPL-3.0, based on HULKs' `hulk`). The drivers described in these docs are developed in a separate repository that is not public yet. ## Status What works today, measured on our NAO6 with HULKs-OS 9.0.1 on 2026-11-06: | Part | State | | --- | --- | | USB link to the chest board | Works: start-up and the 4,635-byte preference read in 275 ms | | Body preferences (serial numbers, calibration) | Works: values identical to HAL's | | Body sensors: IMU, battery, foot pressure, sonar, buttons, bumpers | Works: values identical to LoLA's | | Head: eye, ear and skull LEDs, head touch, power monitor, temperature | Works | | Head fan control | Works: read and set on the robot | | Death switch: latch, guard, UDP stop, CLI, chest and head triggers | Works: a frozen runtime is taken over within about 100 ms | | `hulk` (HULKs' control software) on the nao-rs runtime, robot API on port 7700 | Works | | Installer with health check and automatic rollback | Exists; see [Install](https://nao-rs.lukaloehr.com/get-started/install.md) | | Motor boards: handshake | Done the way HAL 2.8.5 does it, so version 11 boards are rejected | | Motors: stiffness and position commands | **Planned**: accepting version 11 boards and the first movement need the motor session on the robot | | Joint positions, currents and temperatures with real data | **Planned**: they need accepted motor boards | | HAL's safety plugins | Controller lost, cycle stall and battery over-current in every frame, identical to HAL; motor temperature model and diagnosis **planned** | | The brain on a Mac: voice agent, camera, memory, party mode | Works over the robot API; see [The brain](https://nao-rs.lukaloehr.com/brain.md) | | Brain modes "live" (talking with subtle head movement) and "agent" (tool calls), your own ElevenLabs agent, config file | Exists; see [The brain](https://nao-rs.lukaloehr.com/brain.md) | | REST API on port 7702: token, LAN-only, control leases, state, hardware readings, LEDs with animations, audio, cameras, stop | Works: health, identity, safety, state and LEDs (per group and per single LED) checked on the robot; see [REST API](https://nao-rs.lukaloehr.com/reference/rest-api.md) | | Chest button as the stop, with the robot saying its IP address; spoken system messages in English or German | Works; see [What the robot says](https://nao-rs.lukaloehr.com/get-started/voice.md) | | Boot | 13.1 s instead of 19.6 s (`systemd-analyze`); see [Boot time](https://nao-rs.lukaloehr.com/architecture/boot.md) | | A flashable image with A/B rollback, signed releases | **Planned** | > **Info:** What this means for you > > On nao-rs today a NAO6 senses, lights up, cools itself and can be stopped, > but its motors stay limp. A NAO6 whose motor boards report version 10 moves > under the original stack (HULKs-OS's HAL, LoLA and HULA), and > `nao-rs robot restore` brings that stack back. A NAO6 with version 11 boards > moves under neither until nao-rs drives the motors. ## Related topics - [Quick start](https://nao-rs.lukaloehr.com/get-started/quickstart.md) - [Install, flash and rollback](https://nao-rs.lukaloehr.com/get-started/install.md) - [What the robot says](https://nao-rs.lukaloehr.com/get-started/voice.md) - Previous: [Home](https://nao-rs.lukaloehr.com/index.md) - Next: [Quick start](https://nao-rs.lukaloehr.com/get-started/quickstart.md)