Skip to main content

Usage Guide

This guide shows how to install or update the operating system on your robot with the HOFI USB stick.

You need:

  • a HOFI USB stick, prepared with the HOFI setup guide
  • a way to see the HOFI screen: a laptop or phone on the same network as the robot (or a laptop connected to it with an Ethernet cable), or a monitor and USB keyboard
  • internet access for the robot (Ethernet or Wi-Fi), but only if you want HOFI to download the OS image itself
Flashing erases the robot's disk

Installing a new system deletes everything on the robot's disk or SD card. Back up anything you want to keep.

Step 1: Start HOFI on the robot​

  1. Turn the robot off.
  2. Plug the HOFI USB stick into the robot's computer.
  3. Turn the robot on. HOFI starts in about a minute (a few minutes on NVIDIA Jetson).

If the robot starts its usual system instead, see The robot does not start HOFI.

Step 2: Open the HOFI screen​

Connect the robot with an Ethernet cable, either to your router or straight to your laptop. HOFI needs no network settings. Behind a router it takes an address from the router, and on a direct cable HOFI and the laptop pick addresses by themselves. Either way, you reach it by name:

Robot's computerAddress
Raspberry Pi (ROSbot 3, XL; Panther / Lynx built-in)http://hofi-rpi.local
x64 (ROSbot XL; Panther / Lynx user)http://hofi-x64.local
NVIDIA Jetson (ROSbot XL; Panther / Lynx user)http://hofi-jetson.local

Open the address in your browser. Tab and the arrow keys move around, Enter selects and Esc goes back. You can also just click.

On a direct cable the page can take up to a minute to open, because macOS (about 30 s) and Windows (about 1 min) first wait for a router before picking an address on their own. Linux needs a one-time setup, described under The address does not open below the tabs.

HOFI main screen in a web browser

One screen, everywhere

The browser, the phone, the monitor and SSH all show the same live screen. You can start a flash on your laptop, close it, and check the progress later on your phone.

HOFI also appears in your file manager's network view. Finder and GNOME Files list it directly, and Windows shows it under Network.

🔌 The address does not open

Linux laptop on a direct cable: a regular "DHCP" connection waits for a router that isn't there. Create a link-local connection once (replace enp0s31f6 with your port name from ip link) and select it in the network menu:

nmcli connection add type ethernet ifname enp0s31f6 con-name hofi ipv4.method link-local ipv6.method link-local

Switch back to your normal connection after installing the system. The freshly installed robot OS hands out addresses itself, and a link-local connection doesn't pick them up.

Network blocks .local addresses (some company networks and VPNs): plug the HOFI USB stick into your computer and open Open HOFI Web UI.html on the hofi_drive partition. It checks whether the name works on your network and, if it doesn't, lists HOFI's last known IP addresses.

The name answers as hofi-rpi-2.local: another device on the network, for example a second HOFI stick, already uses the name, so HOFI took the next free one. Try the -2 address, or give each stick its own name as described in Network settings.

HOFI is open to everyone on the network

Anyone who can reach HOFI can open its screen, including Flash and Power Off, and read or change the files on its network share. Use HOFI on a network you trust, connect it straight to your laptop, or lock it to your SSH keys.

Step 3: Get the operating system image​

HOFI installs images in .img, .img.xz and .img.zst format. Copy them as they are, without unpacking. There are three ways to get an image onto the stick.

The robot needs internet access, through its Ethernet cable or Wi-Fi.

  1. In the Image list, select Download from Internet.

  2. If there is no internet, HOFI opens the Wi-Fi screen. Pick your network and enter its password; HOFI remembers it and reconnects by itself next time. See Wi-Fi for details.

  3. Pick your robot:

    Choosing the robot in HOFI

    ChoiceImages
    ROSbotROSbot 3 and ROSbot XL (Raspberry Pi, x64, Jetson)
    UGVPanther and Lynx built-in computer
    Generic OSHusarion OS without robot configuration, and the Panther / Lynx user computer images

  4. Pick the image. The newest is at the top. The list shows images for this robot's computer; press A to see all of them.

    HOFI image catalogue

  5. Wait for the download. HOFI checks it against the published checksum, then goes back to the main screen with the new image selected and marked Integrity: verified.

    Downloading an image in HOFI

If the connection drops, select the same image again and the download continues where it stopped. Esc cancels it, and a second Esc deletes the partial file.

Image not in the list?

If HOFI doesn't offer the image you need, download it from Husarion OS images on your computer and copy it to HOFI over the network or with the stick in your computer.

Step 4: Flash the image ⚡​

  1. In the Device list, select the robot's disk. HOFI never lists its own USB stick, so you can't pick it by mistake.

  2. In the Image list, select the image.

  3. Select Flash. HOFI shows which image will go to which disk; select Flash again to confirm.

    HOFI asking to confirm the flash

  4. Wait until the log shows flashed successfully. The line under the buttons shows progress, speed and time left.

    Flashing over HOFI

Before writing, HOFI checks that the image fits on the disk and clears the disk's old partition table, so nothing of the previous system is left behind. Compressed images are unpacked on the fly.

Do not interrupt flashing

Do not turn the robot off or unplug the USB stick while flashing. To stop, use Abort.

Closing the browser or SSH window is safe. The flash keeps running on the robot, and only one flash can run at a time.

Step 5: Start the new system​

  1. Select ⏻ Power Off, press it again to confirm, and wait until the computer turns off.
  2. Unplug the HOFI USB stick and turn the robot on 🚀
  3. Complete the robot-specific configuration.

Wi-Fi 📶​

HOFI can join a Wi-Fi network, both to download OS images and so you can open its screen without a cable. The robot's computer needs a Wi-Fi adapter; the Raspberry Pi's built-in Wi-Fi works.

Join a network​

  1. Open the HOFI screen with a monitor and keyboard, or in a browser over an Ethernet cable. The first time, HOFI isn't on Wi-Fi yet, so you need one of these.
  2. Press W on the main screen. HOFI also opens this screen by itself when you select Download from Internet and it has no internet.
  3. Pick your network from the list (strongest first; R scans again) and press Enter.
  4. Enter the password and press Enter. On a phone, the ⌨ button opens the keyboard.

Once connected, HOFI is reachable on that Wi-Fi under the same .local name, so you can open its screen from a phone or laptop on the same network.

What HOFI remembers​

HOFI remembers one Wi-Fi network and reconnects to it every time it starts. Joining another network replaces it.

The password stays in HOFI's own system partition, never on hofi_drive. For the same reason you can't set up Wi-Fi from a file: hofi_drive is shared on the network, and anyone on it could read a password stored there.

Supported networks​

NetworkWorks?
WPA2 or WPA with a password✅
Open network (no password)✅
WPA3-only❌
Enterprise networks (username and password, 802.1X)❌
WEP❌ Listed, but HOFI can't join it

If the Wi-Fi screen says Wi-Fi is not available, it also says why: usually the computer has no Wi-Fi adapter, or its radio is switched off.

The network profiles below apply only to Ethernet. On Wi-Fi, HOFI always takes its address from the router.

Network settings​

The defaults suit almost every setup. For special cases, the hofi_drive partition holds ready-made network profiles. HOFI uses the one whose name ends in -active.yaml. To switch, rename the files so that exactly one ends in -active.yaml, then restart HOFI.

ProfileWhat it does
network-zeroconf-active.yamlDefault. Takes an address from a router, or picks one itself on a direct cable. Reachable by .local name; never hands out addresses.
network-auto.yamlPrevious default. Takes an address from a router, or hands one out to a directly connected laptop. Also always reachable at 192.168.77.5.
network-rosbot.yamlFixed address 192.168.77.2 with an address server on eth0. That is the robot's own address, so don't use this profile next to a ROSbot.
network-production.yamlRouter address on eth0; fixed 192.168.77.2 with an address server on eth1.
network-husarion-ugv.yamlFixed address 10.15.20.2 on eth0, the Panther / Lynx internal network.

Several HOFI sticks on one network? Give each one its own name by adding a hostname to the active profile:

network:
  mode: zeroconf             # already in the file
  hostname: hofi-panther-1   # reachable as hofi-panther-1.local

The name may contain lowercase letters, digits and -. It takes effect at the next start and travels with the stick.

The robot does not start HOFI​

Raspberry Pi: unplug USB hubs

If a Raspberry Pi looks completely dead with the HOFI stick in (no network, no hofi-*.local), unplug any external USB hub and power it on again. While the Pi's bootloader reads HOFI from the stick, a hub can make the read fail. On a monitor, the boot screen then ends in lines such as xHC-CMD err and FAT read failed.

The stick can go in any USB port, and you can plug the hub back in once HOFI is running. Only the start is affected.

If the robot starts its usual system instead of HOFI, change the order in which it looks for a system to start:

Preparing Your SBC for USB Boot

To boot HOFI, you need to configure your device to prioritize USB storage during startup. This ensures the board will attempt to boot from the HOFI USB drive before falling back to internal storage (e.g., microSD card, eMMC, or NVMe).

The method for setting USB boot priority depends on the target platform, eg.:

Raspberry Pi 4 for ROS

Edit the bootloader configuration using:

sudo -E rpi-eeprom-config --edit

Set BOOT_ORDER so that 4 (USB) comes first. For example:

  • BOOT_ORDER=0xf164 → USB → NVMe → SD card (repeat)
  • BOOT_ORDER=0xf14 → USB → SD card (repeat)

Save the changes and reboot the Pi.

👉 Learn more in the Raspberry Pi bootloader configuration guide

Raspberry Pi

Once HOFI runs, you can also change the start order from HOFI: pick a preset in the EEPROM list and select Config EEPROM.