RAKPiOS
RAKPiOS is a custom operating system for RAKwireless gateways built on the Raspberry Pi Compute Module. It is Raspberry Pi OS Lite with the drivers, device tree overlays, security defaults, helper tools, and Docker that a headless IoT gateway needs, so that a freshly flashed board is ready to run services rather than ready to be configured.
Everything that is not stock Raspberry Pi OS is built by a single additional stage in the RAKPiOS repository, which is a fork of the official pi-gen image builder.
Figure 1: What RAKPiOS adds to Raspberry Pi OSWhat It Is Based On
| Attribute | Value |
|---|---|
| Current version | 1.0.0 |
| Base | Raspberry Pi OS Lite 64-bit, upstream image 2026-06-18-raspios-trixie-arm64 |
| Debian release | 13 (trixie) |
| Kernel | 6.12, the official Raspberry Pi kernel |
| Architecture | arm64 |
| Network stack | NetworkManager |
The major version tracks the Debian base: every image built on trixie is 1.x, and the first release on the next Debian version becomes 2.0.0. Minor and patch numbers follow semantic versioning within a base.
A new Debian release always brings changes that are outside RAK's control and cannot be called backwards compatible, so tying the major version to the base is what keeps the semantic versioning promise honest.
Supported Hardware
RAKPiOS runs on RAK carrier boards fitted with a Raspberry Pi Compute Module 4 or 5, and on the Raspberry Pi 5.
| Product | Module |
|---|---|
| RAK7391 WisGate Connect | CM4 / CM5 |
| RAK7392 WisGate Connect Router | CM4 |
| RAK7393 WisGate Connect Outdoor | CM4 |
| RAK7394 WisGate Developer CM4 | CM4 |
A single image covers all of them. On boot, RAKPiOS identifies the carrier it is running on and loads the appropriate device tree overlays. Refer to the RAKPiOS Board Detection to learn how this works and how to override it.
What RAKPiOS Adds
Hardware support
- Carrier board auto-detection: The GPIO expanders, GPS UART, and SPI chip-select layout differ between carriers. RAKPiOS detects which one it is on and writes the matching overlays into
config.txt. - RAK7391 device tree overlay: Gives its GPIO expander lines their real names, so scripts can refer to
IO0_1rather than a bare pin number. - Onboard RTC, I2C, and SPI: Enabled out of the box.
- WisBlock serial ports: Exposed at stable
/dev/ttyWB*paths and kept away from ModemManager so that probing does not corrupt a session. - Intel WiFi 6 firmware: Includes AX200, AX201, and AX210 firmware, along with Realtek USB Ethernet firmware.
- Cellular modem support: Includes automatic raw IP mode for BG96 modules.
Networking
- NetworkManager: Manages every interface, including Ethernet, WiFi, and cellular.
- WiFi access point fallback: If the gateway boots with no working connection, it brings up an access point with a captive portal so you can configure the real network from a phone or laptop.
- SSH enabled by default: Allows a headless board to be reached on first boot.
Tools
rakpios-cli: Configures network connections and deploys IoT services from a curated catalogue of Docker containers.mioty-cli: Configures and manages the Miromico Miro EdgeCard for mioty®.- OLED status panel: Displays the address, system stats, running containers, and power supply warnings on an attached SSD1306 screen.
- Hardware test suite: Verifies every peripheral on the board.
reset_password: Returns the login to its factory state before handing a gateway on.- Custom MOTD: Summarizes the host, its addresses, disk usage, and running containers at login.
Services
- Docker CE and the Compose plugin: Pre-installed, with the default user added to the
dockergroup. - Nearly 40 ready-to-run services: Includes LoRaWAN packet forwarders and network servers, MQTT brokers, databases, dashboards, VPNs, and home automation, all deployable from a menu. Refer to Service Management.
Security defaults
- Default user: The username is
rakwith passwordchangeme, and the password must be changed on first login. sudo: Requires the user's password, unlike stock Raspberry Pi OS.
Get Started
- Quick Start Guide - download the image, flash it to an SD card or to the onboard eMMC, and log in for the first time.
- Command Line Utility - set up Ethernet, WiFi, or cellular connectivity with
rakpios-cli. - Service Management - deploy your first container.
- Tools - everything else that ships in the image.
- Release Notes - what changed in each version.
