Skip to main content

Usage Guide

This guide shows you how to add OS images to HOFI and use it to install or update the operating system on your robot’s Single Board Computer (SBC).

Prerequisite: HOFI Image Setup

This guide assumes that your HOFI image is already set up and ready to use. If you haven’t configured it yet, follow the HOFI setup guide.

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.:

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

1. Add OS Images to HOFI​

Step 1: Connect the HOFI USB Drive to Your Computer​

After connecting the HOFI USB drive, your system may display multiple mounted partitions. The exact layout depends on the HOFI variant you are using (x64, tegra for NVIDIA Jetson, or rpi for Raspberry Pi). These include system partitions used internally by HOFI’s Yocto-based OS — you can safely ignore them.

The only partition you need to interact with is:

  • os_images – This is where you store your target OS images for flashing.

All other partitions are required for HOFI to operate and should not be modified.

Step 2: Copy the OS Image​

HOFI supports only uncompressed .img files.

If your OS image is in .img.xz format, you must extract it first.

  • On Linux/macOS, run:

    xz -dv /path/to/os/image.img.xz  # This will produce /path/to/os/image.img

  • On Windows (using PowerShell + 7-Zip):

    7z e C:\path\to\os\image.img.xz -oC:\output\
📌 Where to Find OS Images for Husarion Robots?

If you need an OS image for your Husarion robot, check the official sources below:

1️⃣ Husarion OS

A customized Ubuntu Desktop with setup scripts for:

  • Panther User Computer
  • Lynx User Computer
  • ROSbot XL
  • ROSbot 3 / 3 PRO
  • ROSbot 2R / 2 PRO

🔗 Download: Husarion OS

2️⃣ Panther / Lynx Built-in (Embedded) Computer Image

OS images specifically for Panther and Lynx Built-in Computers based on real-time Linux kernel with running husarion_ugv_ros ROS 2 Driver.

🔗 Download: Panther & Lynx Built-in Computer OS

Once you've extracted your .img file, copy it to the os_images partition. You can simply drag and drop the file using your file manager — this works on Linux, macOS, and Windows:

copy the OS image to the os_images partition

Alternatively, you can copy the file using the terminal. For example, on Linux:

cd /media/$USER/os_images  # Adjust if needed for non-Ubuntu systems
sudo cp /path/to/os/image.img .
sync
Safe USB Removal

Do not unplug the USB drive until the copy process is fully completed.

Before physically removing the drive, always unmount the os_images partition to avoid data corruption.

2. Flash an OS Using HOFI​

Step 1: Connect and Boot​

  1. Insert the HOFI USB drive into your SBC.
  2. Power on the SBC.
  3. Connect an Ethernet cable between the SBC and your laptop. Alternatively, you can connect an HDMI display and a USB keyboard directly to the SBC (Ethernet and user's laptop is not required in this case).
Built-in DHCP Server

HOFI automatically assigns your laptop an IP address in the 192.168.77.0/24 subnet, so no manual network configuration is needed.

Step 2: Open the HOFI Interface​

Choose one of the following access methods:

Open http://192.168.77.2:8080 in the web browser on your laptop.

Regardless of whether you access HOFI through a web browser, an SSH session, or an HDMI display, the user interface looks the same (screenshot below shows the Web UI version).

HOFI Web User Interface

Step 3: Select and Flash the OS​

  1. Choose the target drive (usually only one available).

  2. Pick the OS image you want to flash.

  3. Start flashing by pressing ENTERor clicking the Flash Image button.

    Flashing over HOFI

  4. Wait for the flashing to complete.

🎥 Here’s a demo of HOFI in action (option over SSH connection):

hofi

3. Final Steps​

  1. Power off the SBC. Press and hold the ESC key in the HOFI interface to safely shut down the system.
  2. Remove the HOFI USB drive.
  3. Boot your robot with the new OS! 🚀