Skip to main content

Raspberry Pi 5

This guide walks you through building and deploying Avocado OS to a Raspberry Pi 5. You can provision to an SD card with a reader, or flash the Pi's storage in place over USB.

Prerequisites​

  • Raspberry Pi 5
  • microSD card (8 GB+), or an NVMe SSD installed in the Pi
  • An SD card reader (for SD card provisioning) or a USB-C data cable (for USB provisioning)
  • macOS 10.12+ or Linux (Ubuntu 22.04+, Fedora 39+)
  • 8 GB available disk space
Choose your setup

Serial console (optional)​

Optional: serial console

A UART-to-USB serial console adapter is optional. You only need one if you want a serial console to the target — useful for watching early boot output or recovering a device that isn't reachable on the network. If the device is on your network, you can skip the adapter and SSH into it instead (see the SSH section below).

A serial console adapter (for example, this 3.3V USB adapter) lets you watch the device boot. If you have one connected, use a terminal program like tio:

tio -b 115200 /dev/ttyUSB0

Replace /dev/ttyUSB0 with the appropriate device path for your adapter.

Initialize​

Create a new project targeting the Raspberry Pi 5.

avocado init --target raspberrypi5 raspberrypi5
cd raspberrypi5

Install​

Install the SDK toolchain, extension dependencies, and runtime packages.

avocado install -f

Build​

Build the system image.

avocado build

Provision​

Provision the dev runtime to the Pi's storage. Choose whichever option fits your setup — writing an SD card with a reader, or flashing the Pi's storage in place over USB.

Provisioning on a Linux host

If your Linux desktop auto-mounts removable media, disable it first — see Linux Auto-Mounting.

Option A — SD card​

Insert your SD card into a reader on your host, then run the sd profile, which writes the image directly to the SD card:

avocado provision -r dev --profile sd

Option B — USB (no card reader)​

You can flash the Pi's storage in place over USB, without removing the SD card or using a reader. The Pi 5's bootloader can start in USB device mode, in which it presents its storage to your host as a USB mass storage device. This works for the SD card left in the Pi, or an NVMe SSD installed in the Pi.

The Pi is powered over the same USB-C cable used for provisioning, so your host port and cable have to meet the Pi 5's power needs.

Power the Pi over USB-C

The Raspberry Pi 5 is designed for a 5 V/5 A (27 W) USB-C PD supply. When it doesn't detect a 5 A PD source it falls back to 5 V/3 A and caps total USB peripheral current at ~600 mA. A typical host USB-C port supplies well below this (often 5 V/0.9–3 A), so a marginal port or a thin/charge-only cable can cause under-voltage or a failed flash — especially with an NVMe SSD installed, which adds to the draw.

Use a data-capable USB-C cable and a host port that can source adequate current. If USB provisioning is unreliable, use the SD-card method above instead (the reader draws power from the host, not the Pi).

Check the LED. The Pi 5 has a single bi-color status LED: it shows red in standby, then turns steady green once it's powered and running with enough current (it flashes green during storage activity). If the LED won't turn green, stays red, or flickers/drops out, the supply is too weak — use a stronger host port and cable, or fall back to the SD-card method.

  1. With the Pi powered off, leave the target storage in place (SD card inserted, or NVMe installed).
  2. Press and hold the Pi's power button.
  3. While still holding the button, connect a USB-C data cable from the Pi's USB-C port to your host — this applies power. Release the button once it's connected.
  4. The Pi boots into USB device mode and your host detects it as a USB mass storage device. Provision with the usb profile:
avocado provision -r dev --profile usb

In either case, the CLI detects the available block devices and prompts you to select the target. Verify you select the correct device — this operation overwrites the target disk.

Run​

  1. If you provisioned over USB, disconnect the USB-C data cable.
  2. Make sure the provisioned storage is in place — the SD card inserted, or the NVMe SSD installed.
  3. Apply power to the Raspberry Pi 5.

The device will boot from its storage with the provisioned system. Log in as root with an empty password.

SSH access​

Once booted, you can SSH into the device if you know its IP address:

ssh root@<device-ip>

The dev runtime includes an SSH server with passwordless root login for development purposes.