Initial Setup Guide

This guide prepares a HOFI USB stick. You only do it once; after that the same stick installs or updates the operating system on your robot whenever you need it.

HOFI is a small operating system of its own. On its first start it turns the rest of the stick into the hofi_drive partition, which holds the OS images you want to install.

Step 1: Download the right image

Choose the image for your robot's computer:

• Raspberry Pi 4 / 5 / CM4 / CM5: hofi-rpi-v1.3.0.img.xz (~90 MB)
• x64-based computers: hofi-x64-v1.3.0.img.xz (~90 MB)
• NVIDIA Jetson Orin computers: hofi-jetson-v1.3.0.img.xz (~180 MB)

The images are xz-compressed, and you do not need to extract them: Etcher flashes .img.xz files directly.

💡 Which image do I need?

Robot	Robot computer	HOFI image
Panther, Lynx	Built-in Computer (Raspberry Pi)	hofi-rpi
	User Computer (ASUS NUC, Lenovo ThinkStation)	hofi-x64
	User Computer (Jetson Orin)	hofi-jetson
ROSbot XL	Raspberry Pi 5 / Raspberry Pi 4	hofi-rpi
	Intel NUC	hofi-x64
	Jetson Orin Nano	hofi-jetson
ROSbot 3 / 3 PRO	Raspberry Pi 5	hofi-rpi

Step 2: Create a bootable USB stick

1. Download and install Etcher.
2. Flash the downloaded image onto a USB stick with Etcher. This erases everything on the stick.

Any stick of 16 GB or more works. A bigger one just holds more OS images; a compressed OS image takes roughly 2-10 GB.

Choosing a USB stick

Many embedded boards load their bootloader and kernel through a very small, legacy USB stack. That firmware only sees drives that:

• enumerate as USB Mass Storage, Bulk-Only Transport (BOT), and
• report 512-byte logical sectors (or "512e").

🔍 How do I check my stick?

Plug the stick into a Linux computer and run lsusb -t. If it shows up as Class=Mass Storage, Driver=usb-storage, it will work.

🤔 Why does this matter?

Fast modern sticks such as the Kingston DataTraveler Max ship in UASP-only mode with native 4 KiB sectors. The boot firmware has no UASP driver and can't address 4 K sectors, so the stick is invisible at boot time, even though it works fine once Linux is running.

Sticks that fall back to BOT and 512 B sectors:

Capacity	Proven models	Notes
16-64 GB	SanDisk Ultra Fit USB 3.2 Gen 1, Samsung Fit Plus	Small and cheap, good for installer sticks
64-128 GB	SanDisk Extreme Pro (USB-A), Transcend JetFlash 920	Much better sustained writes than "nano" drives
128-256 GB	SanDisk Extreme Pro USB 3.2, Samsung Bar Plus	Largest size that still presents BOT/512e on most batches

Sticks to avoid as boot media:

• Kingston DataTraveler Max (all capacities): UASP only, 4 K sectors
• most "USB SSD" sticks advertised at 600 MB/s or more, for the same reason
• anything sold as "NVMe over USB"

Any of the recommended models above boots on every board we support.

Step 3: First 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

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

x64-Based SBCs

During boot, press the key required to enter BIOS or UEFI settings — commonly ESC, F2, or F12 depending on the board. Then change the boot order to prefer USB devices.

Jetson Orin Nano

USB boot is usually enabled by default. If HOFI doesn't boot:

• Connect an HDMI display and USB keyboard to the Jetson
• Power it on and press ESC during boot
• Select Boot Manager and set USB as the first boot device

⚠️ Jetson Orin Boot Firmware (QSPI) — required for L4T R39.2

HOFI for Jetson and the Husarion OS images built on top of it require the board's QSPI boot firmware (UEFI) to be at L4T R39.2 / JetPack 7.2. Older firmware (for example 36.5.x) fails in non-obvious ways: the display engine does not start (black HDMI output), and an R39.2 kernel/userland may not boot at all.

This procedure flashes only the QSPI firmware — the internal NVMe drive is left untouched.

Applies to the Orin Nano 4GB and 8GB modules on the NVIDIA devkit carrier board, the Seeed reComputer J401 / J3010 and the ROSbot XL. The stock devkit QSPI configuration reads the module SKU and boots all of them correctly, so no carrier-specific firmware is needed.

1. Prepare the host computer (x86_64 Linux, ~1.3 GB download)

Any working directory will do — the BSP unpacks into a self-contained Linux_for_Tegra/ subdirectory:

mkdir -p jetson-qspi-r39.2 && cd jetson-qspi-r39.2
curl -sLO https://developer.nvidia.com/downloads/embedded/L4T/r39_Release_v2.1/release/release_sha_hashes.txt
curl -LO  https://developer.nvidia.com/downloads/embedded/L4T/r39_Release_v2.1/release/Jetson_Linux_R39.2.1_aarch64.tbz2
grep Jetson_Linux release_sha_hashes.txt   # compare with: sha1sum Jetson_Linux_R39.2.1_aarch64.tbz2
tar xf Jetson_Linux_R39.2.1_aarch64.tbz2   # unpacks to Linux_for_Tegra/

2. Put the board into Force Recovery (RCM) mode

Connect the board's USB-C port to the host PC first, then use either method:

• Software (the board still boots Linux):

  sudo reboot --force forced-recovery

• Hardware (the board is off or does not boot): power it off, short FC REC ↔ GND on the button header (on the devkit it is J14, pin labels are on the silkscreen), then connect power. The jumper can be removed right after power-on — only the state at power-up matters. The screen stays black in recovery mode, which is expected.

Verify from the host that the board enumerates as NVIDIA APX:

lsusb | grep -i "0955.*NVIDIA\|APX"
# Bus ... ID 0955:7623 NVIDIA Corp. APX   (Orin Nano 4GB)
# Bus ... ID 0955:7523 NVIDIA Corp. APX   (Orin Nano 8GB)

3. Flash the QSPI (~5–10 minutes)

cd Linux_for_Tegra
sudo ./tools/l4t_flash_prerequisites.sh      # first run only, installs apt packages
sudo ./flash.sh jetson-orin-nano-devkit-qspi internal

⛔ Do not interrupt the flashing process — do not disconnect power or the USB cable while flashing, as an interrupted QSPI write can brick the board.

The last two lines of a successful run are:

*** The target generic has been flashed successfully. ***
Reset the board to boot from internal eMMC.

The "generic" target name and the "internal eMMC" wording are flash.sh boilerplate — nothing was written to any storage other than the QSPI.

4. Verify

Remove the recovery jumper if it is still fitted, disconnect the USB-C cable and power-cycle the board. Then check the firmware version:

cat /sys/devices/virtual/dmi/id/bios_version   # expected: 39.2.x-gcid-...

Troubleshooting

• lsusb shows nothing — recovery mode was not entered (check the jumper timing and make sure the USB-C cable carries data, not just power), or the host USB port/hub is at fault.
• ERROR: might be timeout in USB write, followed by cvm.bin does not exist — the board's recovery mode is stuck after a previous failed or interrupted attempt. The error that matters is the USB timeout; the missing cvm.bin is only its consequence. Disconnect power completely (a reset is not enough), enter recovery mode again and rerun flash.sh. If it persists, connect the board directly to a different host USB port with a different cable, without a hub.
• The board keeps returning to the UEFI Boot Manager after reflashing — this is not a QSPI problem. Either the UEFI locked itself into Recovery Boot after three failed boot attempts (HOFI clears that counter automatically on every successful boot), or the UEFI did not enumerate the USB stick on that particular port — Boot Manager entries are port-specific, so try a different USB port.

1. Plug the USB stick into the robot's computer.

2. Turn the robot on. On this first start HOFI creates the hofi_drive partition from all the free space on the stick. On Raspberry Pi and x64 this takes well under a minute. NVIDIA Jetson boards start noticeably slower, so give them a few minutes. HOFI does not touch the robot's own disk until you press Flash.

3. Check that HOFI is up by opening the HOFI screen in one of these ways:

   • Monitor: connect a monitor (HDMI) to the robot's computer and the HOFI screen appears on it.
   • Browser: connect the robot to your router, or straight to your laptop with an Ethernet cable, and open http://hofi-rpi.local (hofi-x64.local / hofi-jetson.local on the other computers). On a direct cable the page can take up to a minute to open. A Linux laptop needs a one-time setup first, described in Open the HOFI screen.

   

4. You can go straight on to the usage guide and install a system. If you're done for now, select ⏻ Power Off (press it twice to confirm) and unplug the stick.

What is on the stick now

The hofi_drive partition takes up all the remaining space. It is formatted as exFAT, so Windows, macOS and Linux can all open it when you plug the stick into your computer, and while HOFI runs the same partition is shared on the network.

Next step 🎉

Your HOFI stick is ready. Continue with installing an OS image on your robot.