A RPi Image Gen project for configuring a custom image for the MLL CV series of workshops
  • Python 84.6%
  • Shell 15.4%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
2026-11-04 14:33:27 -05:00
config auto-setup and first boot with wifi hotspot 2026-11-03 12:04:05 -05:00
layer added desktop branding and fixed boot branding 2026-11-04 14:33:27 -05:00
scripts added desktop branding and fixed boot branding 2026-11-04 14:33:27 -05:00
tests added desktop branding and fixed boot branding 2026-11-04 14:33:27 -05:00
vendor first commit 2026-11-03 11:07:31 -05:00
.gitignore fix first empty password login 2026-11-04 12:05:28 -05:00
README.md added desktop branding and fixed boot branding 2026-11-04 14:33:27 -05:00

MLL computer vision workshop image

This external rpi-image-gen project targets Raspberry Pi 5 with a Hailo-8 PCIe accelerator and an Argon ONE V5 case. It uses 64-bit Bookworm and the Raspberry Pi X11 desktop (LXDE-pi). The desktop includes PiXflat themes and icons, Piboto fonts, the Pi greeter, and Pi panel plugins. The MLL logo is the boot image and desktop wallpaper. The UGA shield is the menu button.

Included setup

  • hailo-all, the Pi 5 kernel headers, DKMS, camera tools, Picamera2, OpenCV, and Python virtual environment tools.
  • Argon fan, power button, OLED, shutdown, and configuration helpers. The image enables argononed.service.
  • The supplied MLL PNG as the Plymouth boot screen. Firmware rainbow and kernel logos are hidden.
  • The supplied arch.png as the LXPanel menu button, including the new primary user configuration.
  • The workshop source in /etc/skel/pecan-vision-workshop. Account creation copies it into the primary user's home.
  • An autoconnecting Ethernet profile on eth0, with IPv4 DHCP and automatic IPv6.
  • An open NetworkManager hotspot on wlan0. Its SSID matches the hostname. The Pi uses 10.0.10.1 and provides DHCP.
  • One interactive, empty-password SSH login as setup, restricted to a terminal account-creation wizard.
  • Raspberry Pi Imager hostname customization through a generated local manifest.

The boot screen starts when Plymouth starts. It cannot replace the earliest EEPROM boot diagnostics. The supplied branding files are copied without changing their pixels. Plymouth scales the logo to fit the display. The desktop fits the full logo on a black background without cropping it. The MLL icon theme replaces start-here, which the Pi menu plugin uses, and inherits the other PiXflat icons.

To apply desktop branding to an existing Pi, copy the helper from this checkout:

scp layer/workshop.d/customize.overlay/usr/local/sbin/mll-brand-desktop engr-ugaif@10.0.10.1:/tmp/

Then run this on the Pi and log out of the graphical desktop and back in:

sudo python3 /tmp/mll-brand-desktop / --user engr-ugaif

Replace engr-ugaif with your primary username. The helper also updates defaults for new accounts. It uses the logo and shield already installed in the workshop image.

Build

Use an up-to-date 64-bit Raspberry Pi OS or Debian Bookworm/Trixie Linux build host, preferably a Raspberry Pi 5. The macOS workspace can hold this project, but cannot run the native image build. Allow enough free storage for the desktop packages, build tree, and disk image. The build downloads Debian and Raspberry Pi packages. First boot does not need network access for Argon or workshop source.

  1. Copy this project to the Linux build host.

  2. Download the pinned image builder and install its host dependencies:

    git clone https://github.com/raspberrypi/rpi-image-gen.git .build/rpi-image-gen
    git -C .build/rpi-image-gen checkout --detach "$(cat vendor/rpi-image-gen-revision)"
    sudo .build/rpi-image-gen/install_deps.sh
    
  3. Run ./scripts/build.sh as your regular user. No build-time password is required.

  4. Copy the resulting .img to the computer that runs Raspberry Pi Imager.

  5. Generate the local manifest on that computer:

    python3 scripts/make-imager-manifest.py work/image-mll-pecan-workshop/mll-pecan-workshop.img
    
  6. Open the generated .rpi-imager-manifest in Imager 2, or select it as the custom repository in Imager settings.

  7. Select the MLL image from that repository. Set a unique hostname in customization, then flash the card.

Imager 2 disables customization for an image selected with Use Custom alone. The manifest declares init_format: systemd. The image supplies a kernel-command-line boot target that waits for /boot/firmware and runs Imager's firstrun.sh there. It applies the requested hostname directly, updates /etc/hosts, and verifies the result before cleanup. It removes the customization boot arguments from the actual firmware cmdline.txt, then reboots. The same service also runs on a normal boot if firstrun.sh is pending, before the hotspot starts. Imager script failures retain the customization inputs for recovery. A persistent record at /var/lib/mll-imager/result.json contains the requested and observed hostname and completion status. It does not include account passwords or SSH keys. This handles Imager versions that still generate /boot/firstrun.sh paths. The manifest contains local absolute image and icon URLs. Regenerate it if you move the image or project. Use a hostname with 1-32 ASCII letters, digits, or hyphens. It must start and end with a letter or digit. Wi-Fi limits the SSID to 32 bytes. An invalid hostname prevents the hotspot from starting and appears in its service log. Without Imager customization, the image builder assigns a hostname. The hotspot uses that hostname.

Configure only the hostname in Imager. Skip user, SSH, Wi-Fi client, and Connect configuration. Clear saved Imager settings for those steps. This image manages bootstrap SSH and creates the primary user during setup. config/local.yaml remains an optional build-default override. Remove any previous user1passhash or user1pass setting. Do not override the setup bootstrap username or its UID. config/local.yaml.example shows a hostname override.

First connection

  1. Boot the Pi. Imager customization can cause an initial reboot.

  2. Join the open Wi-Fi network named after the Pi's hostname.

  3. Request an interactive SSH terminal:

    ssh -tt -o PreferredAuthentications=password -o PubkeyAuthentication=no setup@10.0.10.1
    
  4. SSH normally logs into the empty-password account without a prompt. If prompted, press Enter without typing a password.

  5. Complete the terminal UI to create an unused primary username and a password with at least eight characters.

  6. Reconnect as the new user, or log into the desktop. Sudo requires the new password.

The first interactive setup session checks the terminal and displays the welcome screen before creating a persistent claim. Continuing from that screen locks the setup password. The UI uses a private result descriptor while keeping its display attached to the SSH terminal. Unknown terminal types fall back to installed terminfo. A failed graphical dialog falls back to plain-text prompts. Concurrent sessions cannot claim setup again. Reboots do not rearm it. The account has no general shell, file transfer, forwarding, or unrestricted sudo access. A command without a terminal fails without claiming the interactive setup session. On completion, the wizard removes the SSH exception and its sudo permission, and expires the setup account. Bootstrap SSH uses direct shadow-password authentication for the empty setup password. It permits OpenSSH's initial none check as well as explicit empty-password authentication. An explicit password-only authentication-method list causes a first-attempt disconnect on OpenSSH 9.2 and is not used. Nonempty passwords, public keys, keyboard-interactive, GSSAPI, and host-based authentication cannot authenticate setup. The wizard restores normal PAM authentication after creating the primary user. All other users reject empty SSH passwords before and after setup.

Complete the first session before disconnecting. If it fails after claiming setup, recover through local root access or use the boot reset procedure below. From a local root recovery environment, run /usr/local/sbin/mll-setup-wizard --recover in a terminal. If an interrupted attempt already created a partial account, choose another username or repair that account as root. The local --recover option does not reopen SSH access. Completed setup cannot run again.

Recover a failed setup

For an image built with these fixes, shut down the Pi and mount its FAT boot partition on another computer. Create an empty file named mll-reset-setup at the partition root, then boot again. The boot service removes an incomplete claim, deletes the reset file, and rearms blank-password setup access. It refuses to reset completed setup. Reboots without this explicit file never rearm a claimed session.

The previous image does not recognize this reset file. Repair that SD card on a Linux computer, or rebuild and reflash. Mount its root and boot partitions, then run:

sudo python3 scripts/repair-rootfs.py /mnt/pi-root /mnt/pi-boot --reset-setup --hostname usda-vision3

Replace the mount paths with your actual mount points. The tool checks both partitions and refuses a completed installation. It installs the corrected runtime files, sets the hostname, and requests one explicit bootstrap reset. Unmount both partitions before returning the SD card to the Pi. Reconnect to the usda-vision3 hotspot and run ssh -tt setup@10.0.10.1. SSH may log in without a password prompt. If prompted, press Enter with no text. A nonempty password is rejected.

The hotspot stays open after setup. Anyone nearby can join it and attempt the first setup connection before you do. SSH encrypts the setup session. The Wi-Fi network itself has no password. The hotspot uses 2.4 GHz channel 6 and defaults to the US regulatory country. Set /etc/mll-wifi-country to the local two-letter country code for workshops elsewhere. Ethernet remains available. The onboard Wi-Fi radio operates as the hotspot, rather than joining another Wi-Fi network.

Use a power supply suitable for the Pi, accelerator, and case. The case configuration enables the upstream USB current setting. PCIe runs at its default speed. This project does not force PCIe Gen 3 or change EEPROM settings.

SSD and SD first-boot expansion

The image stays compact when built. It does not produce a 256 GB image file. On first boot, mll-grow-root.service expands the root partition and ext4 filesystem to fill the flashed drive. It discovers the mounted root device and its parent disk at runtime, including NVMe, USB SSD, and SD partition names. It runs before Imager customization and the setup-account service. No storage device name or 256 GB capacity is hardcoded. A marketed 256 GB SSD contains about 238 GiB before filesystem overhead and reserved space.

The service permits only a plain ext4 root partition that is the last partition on its disk. It refuses layouts with overlapping or later partitions. It does not format a filesystem or change the boot partition. It records success in /var/lib/mll-grow-root/complete only after resize2fs succeeds. If expansion fails, it leaves the marker absent and retries on the next boot. SSH remains available for diagnosis when an expansion attempt fails.

Check expansion on the Pi:

systemctl status mll-grow-root.service --no-pager
sudo journalctl -u mll-grow-root.service --no-pager
lsblk -o NAME,SIZE,FSTYPE,MOUNTPOINTS
df -h /

To add expansion to an already flashed Pi, copy these files from the project on your computer:

scp layer/workshop.d/customize.overlay/usr/local/sbin/mll-grow-root \
    layer/workshop.d/customize.overlay/etc/systemd/system/mll-grow-root.service \
    engr-ugaif@10.0.10.1:/tmp/

Then run on the Pi:

sudo apt-get update
sudo apt-get install -y cloud-guest-utils gdisk e2fsprogs
sudo install -m 755 /tmp/mll-grow-root /usr/local/sbin/mll-grow-root
sudo install -m 644 /tmp/mll-grow-root.service /etc/systemd/system/mll-grow-root.service
sudo systemctl daemon-reload
sudo systemctl enable --now mll-grow-root.service
df -h /

Use your primary username if it differs. The Pi needs access to its package repositories.

Check one Pi before the workshop

Run these commands after a cold boot:

systemctl --failed
systemctl status argononed.service
hailortcli scan
hailortcli fw-control identify
lsmod | grep hailo
rpicam-hello --list-cameras
sudo argon-config

Confirm that Hailo reports Hailo-8 and that the driver and runtime versions match. Confirm the fan, OLED, power button, clean shutdown, boot logo, and desktop menu button on the actual case. Open ~/pecan-vision-workshop as the primary user and confirm that the supplied content is present. Test an inference workload with a model compiled for Hailo-8 before making copies for the class.

The pinned workshop revision currently contains only a README and license. It has no exercises, models, or dependency installer. This project does not invent workshop dependencies. Add them when the workshop repository provides them.

Ethernet recovery

The image includes the mll-ethernet NetworkManager profile for eth0. It requests an IPv4 address, gateway, and DNS from the connected network's DHCP server. It reconnects automatically when the cable is connected and retries failed activation without a fixed attempt limit.

On an existing Pi, first inspect nmcli device status and ip -br link. If the Ethernet interface is named eth0, create and activate its DHCP profile:

sudo nmcli device set eth0 managed yes
sudo nmcli connection add type ethernet ifname eth0 con-name mll-ethernet ipv4.method auto ipv6.method auto connection.autoconnect yes connection.autoconnect-retries 0
sudo nmcli connection up mll-ethernet

If mll-ethernet already exists, modify it with nmcli connection modify instead of adding another copy. A NO-CARRIER link needs a working cable and active switch port before DHCP can succeed. Check nmcli -f GENERAL,IP4 device show eth0 after activation. This does not require installing packages or restarting the Wi-Fi hotspot.

Display recovery

The image installs gldriver-test explicitly because the build disables APT recommendations. Its RP1 test selects the display GPU for Xorg, rather than the Pi 5 render-only GPU. LightDM waits for the graphics configuration services and retries if its X server fails. This allows the login screen to recover when a monitor becomes available after boot. The image uses the Raspberry Pi greeter and includes Mesa drivers and the X11 D-Bus launcher.

The boot command line includes console=tty7 and plymouth.ignore-serial-consoles. The image overrides Plymouth's initramfs startup script to pass --tty=/dev/tty7 from its first launch. The root-system Plymouth startup uses tty7 too. LightDM keeps its minimum VT at 7 and owns tty7 rather than a text getty. LightDM launches Xorg with -background none to avoid clearing the retained splash before the greeter draws. This does not prevent an HDMI modeset or monitor signal resynchronization. The initramfs is rebuilt after these settings are installed. These keep the MLL graphical splash from being replaced by details on the UART console. Connect and power the monitor before boot to see the boot splash. A monitor connected after boot cannot display a splash that has already finished.

To move Plymouth to tty7 on an existing Pi, copy and run its configuration helper:

scp layer/workshop.d/customize.overlay/usr/local/sbin/mll-configure-plymouth engr-ugaif@10.0.10.1:/tmp/
ssh -tt engr-ugaif@10.0.10.1
sudo python3 /tmp/mll-configure-plymouth /
sudo systemctl daemon-reload
sudo update-initramfs -u -k all
sudo reboot

The initramfs rebuild is required. Changing only console=tty7 does not override Plymouth's compiled default tty.

To repair an existing Pi, copy and run the repair script from this project on your computer:

scp scripts/repair-display.sh engr-ugaif@10.0.10.1:/tmp/
ssh -tt engr-ugaif@10.0.10.1 'sudo bash /tmp/repair-display.sh'

Use your primary username if it differs. The Pi needs access to its package repositories, for example through Ethernet. The script installs the graphics packages, configures LightDM startup, and updates the boot arguments. It restarts LightDM. Reboot afterward with the monitor connected to check the splash.

If Xorg still fails, inspect /var/log/Xorg.0.log and /var/log/lightdm/lightdm.log. The missing /var/lib/lightdm/data message is separate from Xorg's fatal no screens found error.

Inputs and updates

vendor/rpi-image-gen-revision pins the image builder. vendor/workshop-revision records the source revision in vendor/workshop.tar. The archive is included locally, so image builds do not need GitHub access for the workshop content. To refresh it from a trusted local checkout:

git -C /path/to/pecan-vision-workshop archive HEAD -o "$PWD/vendor/workshop.tar"
git -C /path/to/pecan-vision-workshop rev-parse HEAD > vendor/workshop-revision
sha256sum vendor/workshop.tar > vendor/workshop.sha256

vendor/argon/manifest.json records source URLs and SHA-256 hashes for all included Argon files. Run python3 scripts/fetch-argon.py to refresh them, then review the changes. The original argon1v5.sh is included for reference. The build does not execute it. The project installs its payloads directly and provides a small argon-config menu. It does not run the upstream blanket package upgrade, service starts, or EEPROM changes during image creation. Argon configuration files remain root-owned. Use sudo argon-config to change them.

Run python3 scripts/verify-inputs.py to check the vendored input hashes. APT package versions are resolved at build time. The image is not bit-for-bit reproducible without package snapshots.

Validation

Run the local state-machine, input validation, and open hotspot profile tests:

python3 -m unittest discover -s tests -v

On a host with Docker running, run the disposable Debian Bookworm integration tests:

docker run --rm --volume "$PWD:/project:ro" debian:bookworm bash /project/tests/integration-debian.sh

These tests use real OpenSSH, PAM, the dialog UI, account commands, and NetworkManager profile loading. They check empty-only setup authentication, forced-command restrictions, an unknown terminal type, claim persistence, primary login, and setup removal. They do not exercise a physical Wi-Fi radio.

Verify the generated Plymouth startup script in a real Debian initramfs:

docker run --rm --volume "$PWD:/project:ro" debian:bookworm bash /project/tests/integration-plymouth-tty.sh

This test builds and unpacks an initramfs, then checks its tty7 daemon invocation and MLL logo. It does not test a physical display.

Local unit tests, shell syntax, vendored checksums, and upstream layer metadata checks passed. Root expansion tests cover NVMe, USB, and SD names, a full partition with a smaller filesystem, failure retries, and later-partition rejection. These tests simulate partition commands. Expansion on an actual SSD still requires Linux/Pi validation. The host OpenSSH configuration expansion confirms the empty-password exception applies only to setup. The Debian Bookworm integration test passed with real OpenSSH, the setup UI, account commands, and NetworkManager. It verified a fresh empty-password attempt, automatic empty-account authentication, and wrong-then-empty authentication on one connection. A full Linux image build, Imager flash, and physical Pi validation remain required. After flashing, confirm the chosen hostname matches the open SSID and that DHCP assigns a local address. If the hostname is wrong, read sudo cat /var/lib/mll-imager/result.json. A missing record means this handler has not recorded a customization attempt on that installation. A null requested_hostname means the script did not contain a recognized hostname setting. Before booting a freshly flashed card, confirm that its boot partition contains firstrun.sh with the intended hostname. Do not paste the complete script into support messages because it can contain credentials. Confirm a second empty-password setup login fails, including after reboot, and that the primary account can log in.

Sources

Argon payloads retain their upstream notices. The workshop license is inside its archive. Brand assets were supplied by the user.