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
# Install KAS build tool
pip3 install kas# 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# 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 /mntbmaptool 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 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 is enabled by default in this distribution.
# 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
⚠️ 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-keysSee kas/local.yml.example for configuration template.
| 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-prodPartitioning details and WKS variants are documented in Partition Layouts.
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:
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
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 —
/etcdrift-control architecture, policy model, and OTA tradeoffs
| 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/ |
MIT License — See LICENSE for details.
Individual components retain their respective licenses.