Headless Setup: How to Install OS Raspberry Pi 5 & 4 for Embedded Projects

When you need to install OS Raspberry Pi boards for reliable embedded projects, the standard desktop tutorial falls short. Embedded deployments demand headless operation, predictable storage I/O, and strict GPIO subsystem validation. The direct answer: use Raspberry Pi Imager v1.8+ to flash the 64-bit Raspberry Pi OS (Bookworm), pre-configure headless SSH via the OS Customisation menu, and validate the hardware with an lgpio-backed Python script immediately upon first boot.

This guide targets the Raspberry Pi 5 (8GB) and Raspberry Pi 4 Model B (4GB). We will bypass the GUI, optimize your storage matrix, and debug the exact kernel panics that derail embedded deployments.

Storage & Board Compatibility Matrix

Before you flash, you must select your boot media. MicroSD cards are the default, but they are the leading cause of field failures in embedded Pi deployments due to write-wear and SPI bus latency. Below is the performance and reliability matrix for Pi 5 and Pi 4 storage configurations running Bookworm.

Step-by-Step Headless OS Installation

Bookworm fundamentally changed network management, replacing wpa_supplicant with NetworkManager. Dropping a wpa_supplicant.conf file into the boot partition no longer works. You must use the Imager's advanced menu.

1. Download & Launch: Install Raspberry Pi Imager (v1.8.5 or newer) on your host PC.
2. Select Device: Choose Raspberry Pi 5 or Raspberry Pi 4.
3. Select OS: Navigate to Raspberry Pi OS (other) and select Raspberry Pi OS (64-bit). Do not select the Desktop version for embedded nodes; the Lite version saves ~1.2GB of RAM and removes Wayland/X11 overhead.
4. Select Storage: Choose your target microSD or USB SSD.
5. OS Customisation (Crucial Step): Click Next, then select Edit Settings when prompted to apply OS customisation.
6. General Tab:
   • Set hostname (e.g., node-sensor-01.local).
   • Set username and a strong password (or pre-load your RSA SSH public key for passwordless auth).
   • Configure WiFi SSID and password. Check your exact country code; 5GHz channels are disabled if the regulatory domain is incorrect.
7. Services Tab: Enable SSH and select Use password authentication (or key-based).
8. Flash & Verify: Click Save, then Yes to apply. The Imager will write and verify the checksum automatically.

Hardware Validation: Pin Mapping & Test Code

Once the Pi boots and you SSH in, you must verify that the OS correctly interfaces with the BCM2712 (Pi 5) or BCM2711 (Pi 4) GPIO controller. Bookworm deprecated the legacy RPi.GPIO library. The supported path is gpiozero utilizing the lgpio backend.

Target Board Variant: Raspberry Pi 5 (8GB) and Raspberry Pi 4 Model B (4GB) running 64-bit Bookworm Lite.

GPIO Pin Mapping Table

Validation Script

First, install the required backend. The Pi 5 requires the rpi-lgpio package to talk to the new RP1 southbridge chip:

sudo apt update
sudo apt install python3-gpiozero python3-rpi-lgpio -y

Create hw_validate.py and paste the following complete, compilable code:

#!/usr/bin/env python3
"""
Hardware Validation Script for Pi 4 / Pi 5 (Bookworm)
Tests GPIO output (LED) and input (Button) using gpiozero + lgpio backend.
"""
import sys
import time
from gpiozero import LED, Button
from signal import pause

# Pin definitions matching the physical wiring table
LED_PIN = 17
BUTTON_PIN = 27

def main():
    try:
        # Initialize components
        # pull_up=True means the pin is held HIGH, and pressing the button connects it to GND (LOW)
        status_led = LED(LED_PIN)
        test_button = Button(BUTTON_PIN, pull_up=True, bounce_time=0.05)
        
        print(f"[INFO] GPIO {LED_PIN} (LED) and GPIO {BUTTON_PIN} (Button) initialized.")
        print("[INFO] Press the button to toggle the LED. Press Ctrl+C to exit.")
        
        # Start with LED off
        status_led.off()
        
        # Define callback functions
        def on_button_pressed():
            status_led.toggle()
            state = "ON" if status_led.is_lit else "OFF"
            print(f"[EVENT] Button pressed. LED is now {state}.")

        # Bind callbacks
        test_button.when_pressed = on_button_pressed
        
        # Keep script running
        pause()
        
    except ImportError as e:
        print(f"[FATAL] Missing library. Run: sudo apt install python3-gpiozero python3-rpi-lgpio")
        print(f"[DEBUG] Import error details: {e}")
        sys.exit(1)
    except KeyboardInterrupt:
        print("\n[INFO] Interrupt received. Cleaning up GPIO states.")
    except Exception as e:
        print(f"[ERROR] Unexpected failure during GPIO operation: {e}")
        sys.exit(1)
    finally:
        # gpiozero handles cleanup automatically on exit, but explicit close is good practice
        try:
            status_led.close()
            test_button.close()
        except NameError:
            pass

if __name__ == "__main__":
    main()

Debugging Boot & Network Failures

When an embedded Pi fails to boot after a fresh OS install, the most common and cryptic error string you will see on a connected HDMI monitor (or via serial console) is:

Kernel panic - not syncing: VFS: Unable to mount root fs on unknown-block(179,2)

This means the kernel loaded, but it cannot read the root filesystem partition on the storage media. Here are the ranked causes and fixes:

1. Corrupt Flash / Bad Checksum (60% of cases): The Imager verification step was skipped, or the microSD card has bad sectors. Fix: Re-flash the OS and strictly allow the Imager to verify the write. If it fails verification, discard the SD card.
2. Power Supply Brownout (25% of cases): The Pi 5 requires a 27W USB-C PD power supply. If you use a standard 15W phone charger, the voltage drops under load during the boot sequence, causing the SD controller or PCIe bus to drop offline before the rootfs mounts. Fix: Use the official 27W Pi 5 PSU or a verified 3A+ USB-C PD brick.
3. USB Enclosure UAS Incompatibility (15% of cases): If booting from a USB SSD, the JMicron or ASMedia bridge chip in the enclosure may not support USB Attached SCSI (UAS) properly on the ARM kernel. Fix: Add a USB quirks string to /boot/firmware/cmdline.txt to disable UAS for that specific device ID, or switch to a known-good enclosure like the Sabrent EC-SSGP.

The First Three Things to Check When It Fails

If your headless Pi is not responding to SSH or pinging on the network after installation, do not re-flash immediately. Check these three items first:

1. Power and Thermal Throttling: Check the power LED. A blinking red LED on the Pi 5 indicates a brownout. Ensure your power cable is high-quality (20AWG or thicker); thin cables cause voltage drop.
2. NetworkManager Configuration: If you forgot to enter WiFi credentials in the Imager, the Pi will not connect. Connect a monitor and keyboard, log in, and run sudo nmcli device wifi connect YOUR_SSID password YOUR_PASSWORD to configure it post-boot.
3. mDNS Resolution: If ssh user@raspberrypi.local fails, your router may be blocking mDNS (Multicast DNS). Try pinging the IP address directly, or check your router's DHCP client list for the assigned IP.

Extending or Simplifying the Build

Once your baseline OS is installed and the GPIO subsystem is validated, you have two paths for project evolution:

How to Extend the Build

• Add I2C Sensor Buses: Enable the I2C interface via sudo raspi-config (Interface Options). Wire a BME280 temperature/humidity sensor to GPIO 2 (SDA) and GPIO 3 (SCL). Bookworm handles I2C permissions cleanly via the i2c user group.
• Implement Watchdog Timers: For remote embedded nodes, enable the hardware watchdog. Add dtparam=watchdog=on to /boot/firmware/config.txt and install the watchdog daemon to auto-reboot the Pi if your Python script hangs.
• Move to Compute Module 5 (CM5): If you need custom PCB integration, migrate your Bookworm image to a CM5. The OS and GPIO mappings remain identical, but you gain native USB 2.0 ports and more PCIe lanes on your custom carrier board.

How to Simplify the Build

• Switch to DietPi: If Raspberry Pi OS Bookworm is too bloated (it runs ~40 background services by default), flash DietPi instead. It strips the OS down to ~1GB, disables swap by default, and offers a text-based menu to install only the exact packages you need.
• Downgrade to Pi Zero 2 W: For simple sensor-logging tasks that don't require the Pi 5's quad-core Cortex-A76, use a Pi Zero 2 W. It draws under 1.5W at idle, making it viable for solar-powered or battery-backed embedded enclosures.

For deeper documentation on Bookworm's architectural changes, refer to the official Raspberry Pi OS release notes and the Raspberry Pi OS documentation. Always verify your specific HAT or sensor compatibility against the Bookworm changelog before deploying to production.