IoT Gateway OS for Raspberry Pi 5

A Yocto-based Linux distribution for IoT gateway applications

📋 Overview

A hardened, embedded Linux distribution for IoT gateway deployments on Raspberry Pi 5. Built on Yocto Project with KAS tooling.

Key Features:

🔄 A/B OTA Updates — Rootfs A/B updates with RAUC slot rollback semantics (enabled by default)
🔒 Security Hardened — KSPP-aligned kernel, compiler flags, runtime hardening
📦 Container Runtime — Podman, Buildah, and Skopeo for containerized workloads
🛠️ Developer-Friendly — Tooling for debugging and development

🚀 Quick Start

Prerequisites

# Install KAS build tool
pip3 install kas

Build Images

# Copy example config and edit with your keys/WiFi
cp kas/local.yml.example kas/local.yml
# Edit kas/local.yml - set RAUC key paths and WiFi credentials

# Build images (using Makefile - recommended)
make dev         # Development image
make prod        # Production image
make bundle-dev-full-fit   # OTA bundle with signed FIT boot assets

# OR using KAS directly
kas build kas/local.yml --target iot-gw-image-dev
kas build kas/local.yml --target iot-gw-image-prod
kas build kas/local.yml --target iot-gw-bundle-full-fit

Flash to SD Card

# Full write (recommended, especially for previously used cards)
zstdcat build/tmp/deploy/images/raspberrypi5/iot-gw-image-dev-raspberrypi5.rootfs.wic.zst \
  | sudo dd of=/dev/sdX bs=4M conv=fsync status=progress

# Fast path: sparse-aware copy, then drop any stale U-Boot env file
sudo bmaptool copy \
  build/tmp/deploy/images/raspberrypi5/iot-gw-image-dev-raspberrypi5.rootfs.wic.zst \
  /dev/sdX
sudo mount /dev/sdX2 /mnt && sudo rm -f /mnt/uboot.env && sudo umount /mnt

bmaptool alone skips unmapped regions, so a reused card can keep its old U-Boot environment (uboot.env on the ubootenv partition, p2). Remove the file — do NOT zero the partition: the vfat filesystem and its ubootenv label must survive or the /uboot-env mount fails at boot. See Operations.

Default Accounts

Default users: root, devel. Override at build time with hashed passwords in kas/local.yml or build/conf/local.conf:

IOTGW_ROOT_PASSWORD_HASH = "$6$<hash>"
IOTGW_DEVEL_PASSWORD_HASH = "$6$<hash>"

Generate hashes with openssl passwd -6 or mkpasswd -m sha-512. For dev builds, SSH key bake-in workflow is documented in Operations.

🔄 RAUC Over-The-Air Updates

RAUC is enabled by default in this distribution.

Deploy an Update

# 1. Copy bundle to device
scp build/tmp/deploy/images/raspberrypi5/iot-gw-bundle-full-fit.raucb root@<device-ip>:/tmp/

# 2. Install via project wrapper (handles preflight/cert checks)
iotgw-rauc-install /tmp/iot-gw-bundle-full-fit.raucb
reboot

# 3. Verify after reboot
rauc status

Generate RAUC Signing Keys

⚠️ Required: Generate your own keys before building bundles!

# Generate keys
./meta-iot-gateway/scripts/generate-rauc-certs.sh

# Move to secure location
mkdir -p ~/rauc-keys
mv dev-key.pem dev-cert.pem ca.cert.pem ~/rauc-keys/

# Configure in kas/local.yml
# Set IOTGW_RAUC_KEY_DIR to ~/rauc-keys

See kas/local.yml.example for configuration template.

📦 Image Variants

Image	Purpose	Includes	Size
`iot-gw-image-base`	Minimal production	Core system, RAUC	Small
`iot-gw-image-dev`	Development	+Debug tools, compilers	Medium
`iot-gw-image-prod`	Production	Lean runtime, hardened	Minimal
`iot-gw-image-desktop`	Desktop variant	+Weston/graphical stack	Large

Build commands:

make dev       # or kas build kas/local.yml --target iot-gw-image-dev
make prod      # or kas build kas/local.yml --target iot-gw-image-prod

Partitioning details and WKS variants are documented in Partition Layouts.

🎨 Customization

Use these docs to customize the gateway image and runtime behavior:

Operations for host build workflow, provisioning, and OTA runtime operations
Partition Layouts for storage sizing and WKS selection
Persistent State Architecture for writable/persistent state and what survives updates

Subsystem deep dives:

🛠️ Common Tasks

For practical runbooks and command workflows:

Build, flash, and OTA validation: Operations
RAUC update lifecycle checks: RAUC Update Runbook
Overlay drift-control behavior after updates: Overlay Reconciliation

📚 Documentation

Detailed documentation is available in the docs/ directory:

Operations — Host build, networking, dev SSH keys, OTA runtime workflows
Security Hardening — Kernel hardening, compiler flags, audit framework, validation
SELinux — Active MAC: concept primer, local wiring, refpolicy-mcs, and bring-up-to-enforcing roadmap
Kernel Configuration — Feature sets, fragments, runtime parameters
Partition Layouts — RAUC A/B partitions, WKS variants, sizing
Persistent State Architecture — volatile /var, /data-backed persistent state, and what survives A/B updates
OpenThread Border Router — OTBR setup, configuration, commissioning
OTA Updates — RAUC workflow, bundles, rollback
RAUC Update Runbook — Slot validation and adaptive update checks
FIT Boot and Signing — FIT flow, signing setup, and verification workflow
Overlay Reconciliation — /etc drift-control architecture, policy model, and OTA tradeoffs

📚 References

Resource	URL
Yocto Project	https://docs.yoctoproject.org
KAS Build Tool	https://kas.readthedocs.io
RAUC Framework	https://rauc.readthedocs.io
Raspberry Pi 5	https://www.raspberrypi.com/documentation/

📄 License

MIT License — See LICENSE for details.

Individual components retain their respective licenses.

FilesExpand file tree

README.md

Latest commit

History