Headless Raspberry Pi Configuration: SSH, WiFi, and GPIO Setup

The Headless Raspberry Pi Configuration Decision Tree

Before flashing an SD card, you must select the right hardware for an embedded, headless node. The transition to Raspberry Pi OS (Bookworm) and the release of the Pi 5 changed the power and I/O landscape. Use this decision matrix to select your board.

Exact Parts List and BOM for the Embedded Node

A failed headless boot is often traced back to marginal power supplies or slow SD cards. This Bill of Materials (BOM) guarantees stable operation under the Pi 5's strict USB-C PD negotiation requirements.

Step-by-Step Headless Boot and NetworkManager Setup

Raspberry Pi OS Bookworm completely overhauled networking, replacing dhcpcd and wpa_supplicant with NetworkManager. Dropping a wpa_supplicant.conf file into the boot partition no longer works. Follow these exact steps for a headless configuration.

1. Flash with Raspberry Pi Imager: Download the official Imager. Select Raspberry Pi 5 as the device, Raspberry Pi OS (64-bit) as the OS, and your A2 microSD card as storage.
2. Inject Headless Credentials: Click the gear icon (or press Ctrl+Shift+X) to open OS Customization.
   • Check Enable SSH and select Use password authentication.
   • Set a specific username (e.g., piuser) and a strong password. The default pi user is deprecated.
   • Configure your WiFi SSID and password. Ensure the country code matches your regulatory domain to unlock correct 5GHz channels.
3. Boot and Connect: Insert the SD card, connect the 27W PSU, and wait 60 seconds. The Pi 5 will connect to WiFi and start the SSH daemon.
4. Verify NetworkManager Status: SSH into the Pi (ssh piuser@raspberrypi.local). Verify the network stack by running:

   nmcli device status

   You should see your wlan0 interface listed as connected.
5. Update the System: Run sudo apt update && sudo apt upgrade -y to pull the latest kernel and lgpio backend patches.

GPIO Pin Mapping and I2C Sensor Wiring

The Pi 5 utilizes the new RP1 southbridge chip for GPIO, which changes the underlying memory addresses but maintains the standard 40-pin physical header layout. The BME280 sensor communicates via I2C. We will also wire an LED to verify GPIO output states.

Compilable Python Code with Error Handling

Legacy libraries like RPi.GPIO are broken on Bookworm and the Pi 5. This code targets the Raspberry Pi 5 8GB running Bookworm 64-bit, utilizing gpiozero (which uses the lgpio backend under the hood) and smbus2 for raw I2C register reading.

Prerequisites: sudo apt install python3-gpiozero python3-smbus2 i2c-tools

import time
import sys
from gpiozero import LED
from smbus2 import SMBus

# --- Pin and Bus Definitions ---
LED_PIN = 18          # BCM GPIO 18 (Physical Pin 12)
I2C_BUS_ID = 1        # /dev/i2c-1
BME280_ADDR = 0x76    # Default I2C address for Adafruit BME280
CHIP_ID_REG = 0xD0    # BME280 register containing the chip ID
EXPECTED_CHIP_ID = 0x60

# Initialize GPIO
status_led = LED(LED_PIN)

def verify_i2c_sensor():
    """Attempts to read the BME280 Chip ID to verify wiring and I2C bus."""
    try:
        with SMBus(I2C_BUS_ID) as bus:
            chip_id = bus.read_byte_data(BME280_ADDR, CHIP_ID_REG)
            if chip_id == EXPECTED_CHIP_ID:
                print(f"[SUCCESS] BME280 detected. Chip ID: {hex(chip_id)}")
                return True
            else:
                print(f"[WARNING] Device found at {hex(BME280_ADDR)}, but Chip ID is {hex(chip_id)}. Check sensor model.")
                return False
                
    except FileNotFoundError:
        print("[FATAL] /dev/i2c-1 not found. I2C interface is disabled in config.")
        sys.exit(1)
    except OSError as e:
        if e.errno == 121:
            print(f"[FATAL] Remote I/O error (Errno 121). No ACK received from {hex(BME280_ADDR)}.")
            print("Check physical wiring, pull-up resistors, and I2C address.")
        else:
            print(f"[FATAL] Unexpected I2C OS Error: {e}")
        sys.exit(1)

def main():
    print("Starting Raspberry Pi 5 Embedded Node...")
    
    # Verify hardware before entering main loop
    if not verify_i2c_sensor():
        print("Sensor verification failed. Blinking LED in error pattern.")
        while True:
            status_led.blink(on_time=0.1, off_time=0.1, background=False)
    
    print("Hardware verified. Entering main polling loop.")
    try:
        while True:
            # Pulse LED to indicate healthy I2C read cycle
            status_led.on()
            time.sleep(0.5)
            status_led.off()
            time.sleep(2.5)
            
    except KeyboardInterrupt:
        print("\nShutdown signal received. Cleaning up GPIO.")
        status_led.off()
        sys.exit(0)

if __name__ == "__main__":
    main()

Debugging: First Three Checks and Exact Error Strings

When the script above crashes, do not guess. Follow this ranked troubleshooting sequence based on the exact error string thrown by the Python interpreter.

1. The "FileNotFoundError" (I2C Disabled)

Exact Error String: FileNotFoundError: [Errno 2] No such file or directory: '/dev/i2c-1'

Cause: The I2C kernel overlay is not loaded. In Bookworm, the configuration file moved from /boot/config.txt to /boot/firmware/config.txt.

Fix: Run sudo raspi-config, navigate to Interface Options > I2C, and enable it. Alternatively, manually add dtparam=i2c_arm=on to the bottom of /boot/firmware/config.txt and reboot.

2. The "Remote I/O Error" (Wiring or Address Mismatch)

Exact Error String: OSError: [Errno 121] Remote I/O error

Ranked Causes & Fixes:

1. Wrong I2C Address: Some BME280 breakouts default to 0x77 instead of 0x76. Run i2cdetect -y 1 in the terminal. If you see 77 in the grid, update BME280_ADDR = 0x77 in the Python script.
2. Missing Pull-up Resistors: If using a raw BME280 chip instead of an Adafruit/SparkFun breakout, you must add 4.7kΩ pull-up resistors between SDA/SCL and 3.3V. The Pi 5 internal pull-ups are often too weak for long wire runs.
3. Power Starvation: Ensure the sensor VIN is connected to Pin 1 (3.3V), not Pin 2 (5V), and that the Pi 5 is using the official 27W PSU to prevent brownouts on the 3.3V rail.

3. The "ModuleNotFoundError" (Missing Dependencies)

Exact Error String: ModuleNotFoundError: No module named 'smbus2'

Cause: Bookworm enforces PEP 668, marking the system Python as "externally managed" to prevent pip from breaking OS packages.

Fix: Do not use pip install --break-system-packages. Instead, install the OS-maintained apt package: sudo apt install python3-smbus2. If you must use pip, create a virtual environment (python3 -m venv venv).

Scaling the Build: Simplify or Extend

Once the baseline configuration is stable, you can adapt the node to your specific project constraints.