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.
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.
Download nao-image-HULKs-OS-9.0.1.ext3.gz.opn from the
HULKs/meta-nao 9.0.1 release.
Write it onto a USB stick of at least 8 GB, for example with balenaEtcher.
Switch the NAO off and plug the stick into the USB port on the back of its head.
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.
Connect the robot by Ethernet and check that it answers:
ssh nao@<robot-address> (password nao).
What the installer changes
cargo nao-rs robot install <robot-address> 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.
| 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:
hulkis active, and so isnao-rs-guard;naoctl statusnameshulk'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:
- the failed installation moves to
/home/nao/hulk.failed; /home/nao/hulk.prevbecomes/home/nao/hulkagain;- 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
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).