> Documentation index: https://nao-rs.lukaloehr.com/llms.txt, a list of every page in this documentation. # Install, flash and rollback > Flashing HULKs-OS, what the nao-rs installer changes, its health check, the automatic rollback, and the planned flashable image. nao-rs installs on top of HULKs-OS 9.0.1, the robot operating system of the RoboCup team HULKs (kernel 6.12 with PREEMPT_RT). It changes a handful of systemd units and one directory; the operating system itself stays as it is. ## Flash HULKs-OS Skip this if the robot already runs HULKs-OS 9.0.1. > **Error:** This replaces the robot's operating system > > NAOqi, Choregraphe and Aldebaran's apps are gone after flashing. To go back, > flash the official NAOqi image the same way. 1. Download `nao-image-HULKs-OS-9.0.1.ext3.gz.opn` from the [HULKs/meta-nao 9.0.1 release](https://github.com/HULKs/meta-nao/releases/tag/9.0.1). 2. Write it onto a USB stick of at least 8 GB, for example with balenaEtcher. 3. Switch the NAO off and plug the stick into the USB port on the back of its head. 4. Hold the chest button for about 5 seconds, until it glows blue, then let go. The robot flashes itself, which takes about 5 minutes, and restarts on its own. Remove the stick. 5. Connect the robot by Ethernet and check that it answers: `ssh nao@` (password `nao`). ## What the installer changes `cargo nao-rs robot install ` streams the bundle over SSH, unpacks it into `/home/nao/hulk.new` and runs the installer from the bundle (`etc/nao-rs-install.sh`) on the robot as the `nao` user. - /home/nao/ - hulk/ - bin/ - hulk - nao-rs-guard - naoctl - etc/ - systemd/ - network/ - 50-nao-rs-wired.network - hulk.service - nao-rs-guard.service - nao-rs-mixer.service - nao-rs-tmpfiles.conf - nao-rs-install.sh - nao-rs-mixer.sh - hulk.prev/ | Change | Why | | --- | --- | | `hal`, `lola` and `hula` stopped and masked | nao-rs owns the chest board and the head bus; only one program may | | `/etc/tmpfiles.d/nao-rs.conf`: `/run/nao-rs`, owner `root:hal`, mode `2770` | Home of the death switch page, created at every boot | | `/etc/systemd/system/nao-rs-guard.service`, enabled | The guard, at real-time priority 40, restarted 200 ms after it exits | | `/etc/systemd/system/nao-rs-mixer.service`, enabled | Sets the audio levels at every boot: speakers 50 %, microphones 100 % | | `/etc/systemd/system/hulk.service` | `hulk` on the nao-rs runtime. It replaces HULKs-OS's unit, because a drop-in can't remove that unit's dependency on LoLA and HULA. It starts early (after the file systems, the guard and the chest board, not after `basic.target`), waits up to 10 s for the sound card, and is restarted one second after a failure | | `/etc/systemd/network/50-nao-rs-wired.network` | The wired network, see below | | `network-config` and `network-fallback-notification` masked | HULKs-OS's network script needs a HULKs `team.toml` and plays a recording when it fails; nao-rs owns the wired network instead | | `/home/nao/hulk` | The new installation; the previous one becomes `/home/nao/hulk.prev` | | Units from before the rename (`nao-eph-guard.service`, `/etc/tmpfiles.d/nao-eph.conf`) | Removed; the `nao-rs` ones replace them | ## Health check and automatic rollback After switching, the installer checks the robot every 0.5 seconds for up to 30 seconds. The installation counts as healthy when all of these hold at once: - `hulk` is active, and so is `nao-rs-guard`; - `naoctl status` names `hulk`'s process as the registered driver; - the driver's last heartbeat is less than 200 ms old. If the check passes, the installer exits with code 0 and keeps the previous installation in `/home/nao/hulk.prev`. If it fails, it prints the last 30 journal lines of both services and rolls back on its own: 1. the failed installation moves to `/home/nao/hulk.failed`; 2. `/home/nao/hulk.prev` becomes `/home/nao/hulk` again; 3. the stack that ran before comes back: the original HAL, LoLA and HULA, or the previous nao-rs installation. | Exit code | Meaning | | --- | --- | | `0` | nao-rs runs and is healthy | | `1` | The health check failed and the previous installation runs again | | `2` | The rollback failed too: `hulk` doesn't run. Run `nao-rs robot restore` or reflash | Run the same install command again to update; the running installation then becomes the one a failed update rolls back to. ## Go back to the original stack ```bash cargo nao-rs robot restore ``` This disables the guard and the mixer, deletes the nao-rs units, the tmpfiles entry and the wired network file, unmasks HULKs-OS's network units, unmasks HAL, LoLA and HULA and starts HAL, LoLA, HULA and `hulk` in that order, three seconds apart. ## Network nao-rs configures the wired port itself, with `/etc/systemd/network/50-nao-rs-wired.network`, on every Ethernet interface: | Address | When | | --- | --- | | DHCP | On a network with a DHCP server, such as a router | | `172.28.28.28/24` | Always. Connect a computer with a direct cable, give it an address such as `172.28.28.1/24`, and reach the robot at `172.28.28.28` | | Link-local (`169.254.x.x`, `fe80::`) | Always | Wi-Fi is left as HULKs-OS configures it. ## Planned: a flashable release Today nao-rs is installed on top of HULKs-OS. The release format being planned is a USB image you flash the way you flash HULKs-OS: - **Planned:** a NAO6 image (`.opn`) with nao-rs preinstalled and HAL, LoLA and HULA left out. - **Planned:** two system slots (A/B). An update writes the inactive slot and boots it once; a health check like the installer's above decides whether it stays. If it fails, the robot boots the previous slot again. - **Planned:** signed releases. The robot checks the signature before it installs or boots an update. - **Planned:** a faster boot path (see [Boot time](https://nao-rs.lukaloehr.com/architecture/boot.md)). ## Related topics - [What nao-rs is](https://nao-rs.lukaloehr.com/get-started.md) - [Quick start](https://nao-rs.lukaloehr.com/get-started/quickstart.md) - [What the robot says](https://nao-rs.lukaloehr.com/get-started/voice.md) - Previous: [Quick start](https://nao-rs.lukaloehr.com/get-started/quickstart.md) - Next: [What the robot says](https://nao-rs.lukaloehr.com/get-started/voice.md)