A Scarthgap image line with custom meta-parhelion, staged WIC artifacts, and an OS-vs-app release split. Build and final-WIC hardware checks are documented. End-to-end flight app smoke is still deferred. OS integration directed by Piotr; flight application by the DanSTAR team.
This post is the OS foundation for the Parhelion flight computer. The project summary is in Parhelion Yocto.
Problem
DanSTAR Parhelion flight hardware runs on a Raspberry Pi CM4 with eMMC on a Waveshare carrier. The team had shipped DietPi-based image exports — boot, hand-tweak, shrink, compress, distribute as parhelion_vX.Y.img. That worked on the bench. It was hard to reproduce, review, or hand off. It also did not match how the team wants to operate flight computers later.
The goal was a reproducible Yocto Scarthgap image line for the same target: a custom layer, a Dockerized BitBake workflow, operator documentation, and a release model that keeps rare OS rebakes apart from day-to-day application tag updates.
Scope and ownership
| Scope | Owner |
|---|---|
meta-parhelion, build/flash/staging scripts, OS operator docs, bench evidence | Piotr (DanSTAR software team lead context) |
Flight application — main.py, engine, nodes, MCLink, state machine, hardware-facing logic | DanSTAR team (DanSTAR-DTU/parhelion) |
| Operator checklists and procedure PDFs | DanSTAR team |
| Kernel and BSP base (6.6.63-v8) | Upstream (meta-raspberrypi on Scarthgap) |
This repo integrates and ships a pinned application tag into the image. It does not own flight-computer application logic.
Architecture
Yocto Scarthgap with machine raspberrypi4-64 (CM4 device tree). Custom layer meta-parhelion adds an image recipe with peripheral kernel modules and SSH hardening; application bake at tag v1.1.0 with checksum-locked Python wheels; pigpio 1.78 from source (same upstream version as the DietPi baseline); systemd/udev/tmpfiles; first-boot rootfs grow; OS identity at /etc/parhelion-os-release.
Build host: Ubuntu 22.04 Docker on Arch Linux; rpiboot and eMMC flash on the host. A dedicated ext4 loop mount holds BitBake’s TMPDIR so builds survive reboot and avoid btrfs permission failures inside Docker.
Two-layer versioning: OS changes need a rare eMMC reflash. Application changes sync via parhelion-update <tag> over SSH with agent forwarding.
Release artifacts are staged with WIC, bmap, manifest, SPDX, testdata, and SHA-256 checksums. Guarded flash-cm4.sh handles CM4 USB mass-storage flashing.
Integration work
The useful work sat between “build succeeded” and “hardware behaves correctly.”
Machine selection and build host. raspberrypi-cm4 does not exist in meta-raspberrypi Scarthgap. CM4 on a Pi-4-class carrier maps to raspberrypi4-64. Early builds also hit patch permission denied when work directories sat on btrfs-backed paths inside Docker. Fix: explicit machine in local.conf, persistent ext4 TMPDIR, cleanup script for orphan trees.
SSH hardening and PAM trap. Images inheriting debug-tweaks allow empty-password root SSH. The recipe removes it, locks root, and sets PermitRootLogin no. Without UsePAM no, Scarthgap sshd falls back to pam_deny and non-root logins fail. Final-flash bench confirmed root denied, parhelion user OK.
Peripheral modules and boot enablement. config.txt enables I2C, SPI, and UART at firmware level. That is not enough for userspace /dev/spidev* and /dev/i2c-* with the right group access. The image installs kernel modules, modules-load.d, udev rules, and group membership for the flight-app user. Nodes showing up in ls without this wiring are a false positive.
systemd policy and flash tooling. parhelion.service is installed but disabled. pigpiod and ACT LED setup enable at boot — package-specific SYSTEMD_AUTO_ENABLE overrides. udisksctl inhibit --block-automount keeps desktop automount from corrupting eMMC during WIC streaming.
Rootfs growth and Git bake policy. The grow script resolves /dev/root by major:minor before parted/resize2fs. BitBake git fetch left alternates pointing at the build host. do_materialize_git repacks objects, and a policy script gates artifacts. An intermediate flash exposed the alternates defect. The final WIC bakes detached, sanitized .git metadata, verified live after reflash.
Verification
Independent clean rebuild (2026-07-14): bitbake parhelion-image completed 4,055 tasks with no failures. Artifact Git/poweroff policy checks passed.
Staged WIC SHA-256: 974fcc2d54a9ddb76acc1faa6ff0937c7860283af679cbe8310ba67542d65fb5
Live CM4 platform checks (2026-07-14, final WIC 974fcc2d…): CM4 Rev 1.1 on Waveshare carrier — non-hazardous OS/integration checks PASS: OS identity, zero failed units, rootfs grow, network/mDNS/SSH hardening, I2C and SPI device nodes, UART boot enablement in config.txt, ACT LED sysfs readback, pigpiod active, Python 3.12 runtime imports, detached baked Git, hardened parhelion-update, restricted shutdown policy (behavioral; poweroff not invoked).
Bench sign-off: OS/image integration PASS. Team application hardware smoke deferred.
Scope limits
This work covers one CM4 bench unit, with documented build artifacts and final-WIC hardware verification. It does not claim custom kernel or BSP authorship, flight qualification, DanSTAR production fleet cutover, or end-to-end application smoke on live hardware. The --desktop path is a known team-app import bug (not rerun). Normal hardware mode stays deferred until actuation can be isolated.
What this shows
For embedded-Linux and robotics-platform hiring contexts:
- Layer and recipe integration under real hardware constraints — wiring the upstream kernel stack to the team’s Python flight application, not BSP authorship
- Release discipline — checksum-staged artifacts, manifest and SPDX outputs, explicit OS-vs-app versioning, documented bench sign-off with deferred app smoke
- Bring-up debugging across build host, BitBake policy, systemd, udev, SSH, and flash tooling
- Operator boundary — the flight app stays team-owned; the image adds identity and an update path without collapsing the two release stories
It does not show flight-software authorship, kernel development, or fleet production operations.
Operator checklists and PDF release flow are in parhelion-procedures.