How to Use USB Device Boot Code

USB device boot code is an application provided by Raspberry Pi to push firmware to Compute Modules. Raspberry Pi does not provide precompiled binaries for the software so it must be compiled.

Installation

Linux / Cygwin / WSL

warning

The git repository uses symlinks. For Windows builds clone the repository under Cygwin or use Windows Subsystem for Linux (WSL)

1. Install software from package manager git, libusb-1.0-0-dev, pkg-config, build-essential
2. Clone the usbboot repository
3. Build using make
4. Run the binary

sudo apt install git libusb-1.0-0-dev pkg-config build-essential
git clone --recurse-submodules --shallow-submodules --depth=1 https://github.com/raspberrypi/usbboot
cd usbboot
make
sudo ./rpiboot

tip

sudo isn't required if you have write permissions for the /dev/bus/usb device.

Connect USB devices to WSL

If using WSL additional setups are required to connect USB devices.

This is outside the scope of this guide, see Microsoft's documentation. For a graphical user interface see WSL USB Manager by Andrew Leech.

MacOS

1. Clone the usbboot repository
2. Install libusb (brew install libusb)
3. Install pkg-config (brew install pkg-config)
4. (Optional) Export the PKG_CONFIG_PATH so that it includes the directory enclosing libusb-1.0.pc
5. Build using make
6. Run the binary

git clone --recurse-submodules --shallow-submodules --depth=1 https://github.com/raspberrypi/usbboot
cd usbboot
brew install libusb
brew install pkg-config
make
sudo ./rpiboot

tip

If the build is unable to find the header file libusb.h then most likely the PKG_CONFIG_PATH is not set properly. This should be set via export PKG_CONFIG_PATH="$(brew --prefix libusb)/lib/pkgconfig".

If the build fails on an ARM-based Mac with a linker error

If the build fails on an ARM-based Mac with a linker error such as ld: warning: ignoring file /usr/local/Cellar/libusb/1.0.26/lib/libusb-1.0.dylib, building for macOS-arm64 but attempting to link with file built for macOS-x86_64 then you may need to build and install libusb-1.0 yourself:

wget https://github.com/libusb/libusb/releases/download/v1.0.26/libusb-1.0.26.tar.bz2
tar -xf libusb-1.0.26.tar.bz2
cd libusb-1.0.26
./configure
make
make check
sudo make INSTALL_PREFIX=/usr/local install

Running make again should now succeed.

Updating the rpi-eeprom submodule

After updating the usbboot repo (git pull --rebase origin master) update the submodules by running

git submodule update --init

Editing the config

The firmware configurations can be edited in the file /usbboot/<firmware directory>/config.txt

Boot Order

The BOOT_ORDER field allows the configuration of which boot device is used.

# Tries to boot from NVMe, then SD Card, then network, then loops to the start
BOOT_ORDER=0xf216

Value	Mode	Description
0x0	SD CARD DETECT	Try SD then wait for card-detect to indicate that the card has changed. Deprecated now that 0xf (RESTART) is available.
0x1	SD CARD	SD card (or eMMC on Compute Module 4).
0x2	NETWORK	Network boot - See Network boot server tutorial.
0x3	RPIBOOT	RPIBOOT - See usbboot.
0x4	USB-MSD	USB mass storage boot - See USB mass storage boot.
0x5	BCM-USB-MSD	USB 2.0 boot from USB Type C socket (CM4: USB type A socket on CM4IO board). Not available on Raspberry Pi 5.
0x6	NVME	CM4 and Pi 5 only: boot from an NVMe SSD connected to the PCIe interface. See NVMe boot for more details.
0x7	HTTP	HTTP boot over ethernet. See HTTP boot for more details.
0xe	STOP	Stop and display error pattern. A power cycle is required to exit this state.
0xf	RESTART	Restart from the first boot-mode in the BOOT_ORDER field i.e. loop.

Table from Raspberry Pi documentation

Additional Resources

If you are having difficulty here are some more resources to help:

• How to update the Raspberry Pi Compute Module 4 Bootloader / EEPROM | Jeff Geerling
• Flash Compute Module bootloader EEPROM | Raspberry Pi Documentation