Skip to content

Pi Image Setup Guide

Jump to bottom
Jasper van Loenen edited this page Apr 29, 2026 · 29 revisions

Little Printer Zigbee Bridge - Pi Image Setup Guide

This page describes how I create the image file used on the Raspberry Pi. Regular users don't need this, but I've put this here for reference and because others might find this useful.

All steps are performed on a Linux machine with the Raspberry Pi SD card mounted via a card reader. The root partition is assumed to be mounted at /media/$USER/rootfs and the boot partition at /media/$USER/bootfs.

1. Find The SD Card Mount Points

lsblk

Identify the device (e.g. /dev/sda) and note where the partitions are mounted, for example:

  • Root partition → /media/$USER/rootfs
  • Boot partition → /media/$USER/bootfs

2. Add the Required Files

2a. WiFi config template (user-editable)

The user can add/edit this file to setup their wiFi without having to log into the Pi. A service will look for this file on boot and update the WiFi settings accordingly.

Create /media/$USER/bootfs/wifi.txt:

# Enter your WiFi credentials below, then save the file.
# This file will be deleted automatically on first boot for security.

SSID=YourNetworkName
PASSWORD=YourPassword

# Optional: set your country code (default: GB)
# COUNTRY=GB

2b. WiFi setup script

Create /media/$USER/rootfs/usr/local/bin/wifi-setup.sh:

#!/bin/bash
set -e

WIFI_CONFIG="/boot/wifi.txt"
FLAG="/etc/wifi-configured"

# Only run once
if [ -f "$FLAG" ]; then
    exit 0
fi

# Check config file exists
if [ ! -f "$WIFI_CONFIG" ]; then
    echo "No wifi.txt found, skipping WiFi setup."
    exit 1
fi

# Parse credentials
SSID=$(grep -E "^SSID=" "$WIFI_CONFIG" | cut -d= -f2-)
PASSWORD=$(grep -E "^PASSWORD=" "$WIFI_CONFIG" | cut -d= -f2-)
COUNTRY=$(grep -E "^COUNTRY=" "$WIFI_CONFIG" | cut -d= -f2-)
COUNTRY=${COUNTRY:-GB}

if [ -z "$SSID" ] || [ -z "$PASSWORD" ]; then
    echo "SSID or PASSWORD missing in wifi.txt"
    exit 1
fi

# Set country
raspi-config nonint do_wifi_country "$COUNTRY"

# Write wpa_supplicant config
wpa_passphrase "$SSID" "$PASSWORD" > /etc/wpa_supplicant/wpa_supplicant.conf

cat >> /etc/wpa_supplicant/wpa_supplicant.conf <<EOF

country=$COUNTRY
ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev
update_config=1
EOF

# Shred and remove the config file for security
shred -u "$WIFI_CONFIG"

# Mark as done
touch "$FLAG"

echo "WiFi configured for SSID: $SSID"

Make it executable:

sudo chmod +x /media/$USER/rootfs/usr/local/bin/wifi-setup.sh

2c. WiFi setup systemd service

Create /media/$USER/rootfs/etc/systemd/system/wifi-setup.service:

[Unit]
Description=First-boot WiFi configuration
Before=network.target
ConditionPathExists=!/etc/wifi-configured

[Service]
Type=oneshot
ExecStart=/usr/local/bin/wifi-setup.sh
RemainAfterExit=yes
SuccessExitStatus=0 1

[Install]
WantedBy=multi-user.target

2d. Little Printer bridge systemd service

Create /media/$USER/rootfs/etc/systemd/system/little-printer-zigbee-bridge.service:

[Unit]
Description=Little Printer Zigbee Bridge Script
After=network-online.target wifi-setup.service
Wants=network-online.target
Requires=wifi-setup.service

[Service]
Type=simple
User=pi
WorkingDirectory=/home/pi/little-printer-zigbee-bridge
ExecStartPre=/bin/sh -c 'until ping -c1 1.1.1.1 > /dev/null 2>&1; do sleep 2; done'
ExecStart=/usr/bin/env python3 -m bridge.main --sirius
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target

2e. SSH key regeneration service

Create /media/$USER/rootfs/etc/systemd/system/regen-ssh-keys.service:

[Unit]
Description=Regenerate SSH host keys on first boot
Before=ssh.service
ConditionPathExists=!/etc/ssh/ssh_host_rsa_key

[Service]
Type=oneshot
ExecStart=/usr/bin/ssh-keygen -A
ExecStartPost=/bin/systemctl disable regen-ssh-keys.service

[Install]
WantedBy=multi-user.target

3. Enable All Services

Use --root to enable services on the mounted filesystem without a running Pi:

sudo systemctl --root=/media/$USER/rootfs enable wifi-setup.service
sudo systemctl --root=/media/$USER/rootfs enable little-printer-zigbee-bridge.service
sudo systemctl --root=/media/$USER/rootfs enable regen-ssh-keys.service
sudo systemctl --root=/media/$USER/rootfs enable systemd-networkd.service
sudo systemctl --root=/media/$USER/rootfs enable systemd-networkd-wait-online.service

Verify the services are linked:

ls /media/$USER/rootfs/etc/systemd/system/multi-user.target.wants/

4. Clean private data before creating image

This is only needed if you've been logged in to the device.

Wipe existing WiFi credentials

sudo bash -c 'cat > /media/$USER/rootfs/etc/wpa_supplicant/wpa_supplicant.conf' <<EOF
country=GB
ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev
update_config=1
EOF

Restore wifi.txt to the blank template (or confirm it only contains placeholder values - see step 2a).

First-boot flag

sudo rm -f /media/$USER/rootfs/etc/wifi-configured

This ensures WiFi setup runs again on first boot for the new user.

SSH host keys

sudo rm -f /media/$USER/rootfs/etc/ssh/ssh_host_*

The regen-ssh-keys.service will generate fresh keys on first boot.

Shell history

sudo rm -f /media/$USER/rootfs/root/.bash_history
sudo rm -f /media/$USER/rootfs/home/pi/.bash_history

Machine ID

sudo rm -f /media/$USER/rootfs/etc/machine-id
sudo rm -f /media/$USER/rootfs/var/lib/dbus/machine-id
sudo touch /media/$USER/rootfs/etc/machine-id

An empty /etc/machine-id triggers a fresh ID to be generated on first boot.

Logs

sudo rm -rf /media/$USER/rootfs/var/log/journal/*
sudo rm -rf /media/$USER/rootfs/var/log/*.log
sudo rm -rf /media/$USER/rootfs/tmp/*
sudo rm -rf /media/$USER/rootfs/var/tmp/*

6. Install Python dependencies

# Install QEMU
sudo apt install qemu-user-static binfmt-support

# Copy the QEMU ARM binary into the image so it can be used inside chroot
sudo cp /usr/bin/qemu-arm-static /media/javl/rootfs/usr/bin/

# Mount required virtual filesystems
sudo mount --bind /dev /media/javl/rootfs/dev
sudo mount --bind /proc /media/javl/rootfs/proc
sudo mount --bind /sys /media/javl/rootfs/sys

# Chroot in
sudo chroot /media/javl/rootfs

# Now we're inside the Pi's filesystem - first do an update
apt update
apt upgrade 

# then install our deps
cd /home/pi/little-printer-zigbee-bridge
apt install python3-pip
pip3 install -r bridge/requirements.txt --break-system-packages

# Exit and clean up
exit
sudo umount /media/javl/rootfs/dev
sudo umount /media/javl/rootfs/proc
sudo umount /media/javl/rootfs/sys
sudo rm /media/javl/rootfs/usr/bin/qemu-arm-static

5. Create the .img File

Unmount the SD card partitions (keep the card inserted)

sudo umount /media/$USER/rootfs
sudo umount /media/$USER/bootfs

Image the SD card with dd

Replace /dev/sda with your actual device from lsblk:

sudo dd if=/dev/sda of=~/little-printer-zigbee-bridge.img bs=4M status=progress

This copies the full card. For a 16GB card it will produce a 16GB file - shrink it in the next step.

Shrink and compress with PiShrink

wget https://raw.githubusercontent.com/Drewsif/PiShrink/master/pishrink.sh
chmod +x pishrink.sh
sudo ./pishrink.sh -z ~/little-printer-zigbee-bridge.img

This creates little-printer-zigbee-bridge.img.gz, compressed and shrunk to the minimum size needed (from SD card size to about 800Mb).

6. User Instructions

  1. Download little-printer-zigbee-bridge.img.gz and flash it to an SD card using Raspberry Pi Imager or balenaEtcher
  2. After flashing, open the boot partition of the SD card (visible on Windows, Mac, and Linux as a small FAT drive)
  3. Open wifi.txt and fill in your WiFi SSID and PASSWORD
  4. Save the file, eject the SD card, and insert it into the Raspberry Pi
  5. Power on - the Pi will configure WiFi on first boot and start the bridge automatically

Troubleshooting

Service fails with "dependency" error Check whether wifi-setup.service succeeded:

sudo journalctl -b | grep wifi-setup

WiFi never comes up Check systemd-networkd-wait-online:

sudo systemctl status systemd-networkd-wait-online.service

Script starts before network is ready The ExecStartPre ping loop should make the script wait until internet is reachable.

Clone this wiki locally