RAKPiOS Quick Start Guide

Get the OS

The latest version of RAKPiOS is available from the RAK downloads center or the RAKPiOS repository.

The image is distributed as an xz-compressed disk image, named after the build date and version:

20260807-rakpios-1.0.0-arm64-lite.img.xz

There is a single image for every supported board. RAKPiOS identifies the carrier it is running on at boot and configures itself accordingly, so you do not need a per-product download.

Choose Where to Flash It

Where the image goes depends on which Compute Module your gateway is fitted with:

Module	Target	How
CM4 / CM5 Lite (no onboard storage)	Micro SD card	Flash to a Micro SD card
CM4 / CM5 with eMMC	Onboard eMMC	Flash to the eMMC
Raspberry Pi 5	Micro SD card or NVMe	Flash to a Micro SD card

NOTE

On a module with eMMC, the image must go to the onboard storage because the Micro SD slot is not read. On a Lite module, there is no onboard storage, so the SD card is the only option.

Flashing Tools

Two tools can write the image, on Windows, macOS, and Linux alike:

• Raspberry Pi Imager: The official Raspberry Pi tool and the one the rpiboot documentation assumes. Choose Use custom under Operating System, pick the .img.xz file, and select your target. It decompresses on the fly, so there is no need to unpack the archive.
• balenaEtcher: A cross-platform alternative that also reads the compressed archive directly.

Either one works for both the SD card and the eMMC. The rest of this guide uses balenaEtcher for the screenshots; the steps in Imager are equivalent.

Flash to a Micro SD Card

Use a Micro SD card of 8 GB or greater with a good-quality, fast card reader. Insert the card into the reader, make sure it is properly connected to the host, then:

1. Open balenaEtcher and select the OS image (no need to unzip the archive).
2. Select the target (your Micro SD card).
3. Press the Flash! button to begin.

Figure 1: balenaEtcher flashing window

Wait for the flashing process to complete, followed by the verification phase. You can then remove the card from the reader and insert it into the device's Micro SD slot, on the bottom side of the board next to the three SIM slots.

Figure 1: Micro SD slot

Flash to the eMMC

To reach the eMMC of a Compute Module you first have to make the module present itself to your computer as a USB mass-storage device. That is what the Raspberry Pi rpiboot tool does. Once it has run, the eMMC appears as an ordinary removable drive and you flash it exactly as you would an SD card.

The procedure is the same for CM4 and CM5.

Put the Gateway Into Flash Mode

Before installing anything, put the gateway into flash mode so the host can see it as removable storage:

1. Connect the Type-C port to a USB port on your computer with a suitable cable. Do not power on the gateway yet.

Figure 1: Type-C port and Flash button location

2. Press and hold the Flash button, or bridge the eMMC Flash jumper, and power the gateway.

Figure 1: eMMC flash jumper location

Install and Run rpiboot

Windows

Use the official stand-alone installer: the Windows installer installs both the driver and the boot tool. Run it once, then launch rpiboot from the Start menu. Refer to the Raspberry Pi Compute Module documentation for details.

Linux

Install the build dependencies, clone the repository, and build:

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

On Raspberry Pi OS you can install the packaged tool instead of building it, and simply run sudo rpiboot.

macOS

All operations are done in the Terminal application.

1. Install Homebrew, if you do not have it:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

2. Clone the repository and build it:

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

3. If the build cannot find libusb.h, point pkg-config at it and build again:

export PKG_CONFIG_PATH="$(brew --prefix libusb)/lib/pkgconfig"

Confirm the Storage Is Mounted

A few seconds after rpiboot runs, the Compute Module's storage appears on your computer as a removable drive. The tool prints its progress as it loads the boot firmware onto the module:

$ sudo ./rpiboot
RPIBOOT: build-date ... version ...
Waiting for BCM2835/6/7/2711...
Loading embedded: bootcode4.bin
Sending bootcode.bin
Second stage boot server
Loading embedded: start4.elf
File read: start4.elf
Second stage boot server done

NOTE

If nothing appears, the gateway is most likely not in flash mode. Power it down, hold the Flash button or bridge the jumper, and power it back up with the Type-C cable connected. Then run rpiboot again.

Flash the Image File

With the eMMC mounted, the rest is identical to flashing an SD card. Launch balenaEtcher or Raspberry Pi Imager, select the image file, choose the Compute Module drive, and flash.

Figure 1: eMMC as seen in balenaEtcher

When it is done, remove the Type-C cable, release the Flash button or jumper, and power the gateway normally.

First Boot

The first boot does more work than later ones, and takes longer as a result:

• The root filesystem is expanded to fill the storage, so the whole card or eMMC is available.
• The carrier board is detected and the device tree overlays for it are written into config.txt. Overlays only take effect at boot, so the gateway reboots once by itself to load them. This is expected, happens only on the first boot after flashing, and takes a few seconds.

Give the gateway a minute or so to settle before expecting to reach it.

First Login

Connect the gateway to your network with an Ethernet cable for its first-time setup. RAKPiOS runs as a DHCP client by default, so it will pick up an address from your router automatically.

To find the gateway:

• In your router's client list: It appears as rakpios.
• By name: It appears as rakpios.local if your computer supports mDNS.
• On the OLED screen: If one is fitted, the network page shows the active addresses.

Log in with your preferred SSH tool:

ssh rak@rakpios.local

The default username is rak and the password is changeme. You are required to change the password on first login: SSH asks for the default password, then for a new one, twice.

NOTE

sudo on RAKPiOS asks for your password, unlike stock Raspberry Pi OS. The password you set at first login is the one to use.

No Ethernet Available?

If the gateway boots with no working connection and has WiFi, it brings up its own access point so you can configure the real network from a phone or laptop. Refer to WiFi Access Point Fallback for the SSID, the password, and how the captive portal works.

Starting Over

To put the login back to its factory state, with password changeme and the change-on-next-login prompt armed again, run reset_password. It is meant for handing a gateway on to someone else rather than for recovering a lost password, since it asks for the password, it is about to replace. Refer to Password Reset.

Next Steps

• Command Line Utility - configure Ethernet, WiFi, or cellular connectivity.
• Service Management - deploy a packet forwarder, a network server, or any of the other services.
• Tools - the OLED panel, board detection, the hardware test suite, and the rest of the image.