Setting Up a Raspberry Pi 5 for Headless GPIO Control: A Bench Guide

If you are setting up a Raspberry Pi for embedded hardware control in 2026, the rules have changed. The flagship Raspberry Pi 5 8GB abandons the legacy BCM2835 SoC in favor of the new RP1 southbridge chip. This architectural shift means legacy libraries like RPi.GPIO are effectively dead on the Pi 5, and I2C bus behaviors have subtle timing differences that will trap you if you copy-paste code from older tutorials.

This guide skips the desktop GUI fluff. We are setting up a Raspberry Pi 5 strictly headless, configuring the I2C bus for a BME280 environmental sensor, and driving a 5V relay via the new gpiozero backend. Below is the exact hardware, pin mapping, and fault-tolerant Python code you need to get this running on the bench today.

Hardware BOM and Pin Mapping

Before flashing the OS, verify your bench inventory. The Pi 5 requires a 27W USB-C PD power supply to prevent brownouts when peripherals are attached to the 5V rail. Using a standard 15W phone charger will cause the RP1 chip to throttle or reset under relay switching loads.

The Raspberry Pi 5 maps physical pins to BCM (Broadcom) numbers exactly as the Pi 4 did, but the underlying routing goes through the RP1 chip. Always reference the BCM number in your Python code, not the physical pin number.

Headless OS Flashing and SSH Configuration

For embedded projects, running a desktop environment wastes RAM and CPU cycles. We will flash the 64-bit version of Raspberry Pi OS Lite (Bookworm) and pre-configure network access.

1. Download Raspberry Pi Imager (v1.8+): Install it on your host machine.
2. Select Device: Choose Raspberry Pi 5.
3. Select OS: Navigate to Raspberry Pi OS (other) and select Raspberry Pi OS Lite (64-bit).
4. Select Storage: Choose a high-endurance microSD card (e.g., SanDisk High Endurance 32GB) or an NVMe SSD if you are using the Pi 5 M.2 HAT+.
5. Advanced Settings (The Gear Icon): This is where you avoid needing a monitor.
   • Check Enable SSH and select Use password authentication.
   • Set a specific hostname (e.g., pi5-bench.local).
   • Set your username and a strong password.
   • Configure your 2.4GHz or 5GHz WiFi SSID and password. Ensure the WiFi country code matches your region to comply with local RF regulations.
6. Write: Flash the card, insert it into the Pi 5, and apply power. Wait 60 seconds for the first boot and partition expansion.
7. Connect: Open your terminal and SSH in: ssh youruser@pi5-bench.local.

I2C Bus Setup and Sensor Verification

Once logged in via SSH, update the package list and enable the I2C interface. The Pi 5 uses the raspi-config tool to toggle the RP1 I2C controllers.

Run sudo raspi-config, navigate to Interface Options > I2C, and enable it. Reboot the Pi, then install the I2C tools and Python dependencies:

sudo apt update
sudo apt install -y i2c-tools python3-smbus2 python3-gpiozero python3-lgpio

Verify the sensor is visible on the bus by running sudo i2cdetect -y 1. You should see 76 or 77 in the grid output. If the grid is entirely empty, you have hit the most common embedded roadblock.

Debugging: OSError: [Errno 121] Remote I/O error

When your Python script attempts to read from the BME280 and fails, the terminal will spit out this exact string: OSError: [Errno 121] Remote I/O error. This means the kernel sent an I2C transaction, but no device acknowledged it on the bus.

The first three things to check when it fails:

1. Verify the I2C Bus Number: The Pi 5 has multiple I2C buses. The default header pins (3 and 5) map to I2C1. If your code is trying to open smbus.SMBus(0), it will fail. Change it to SMBus(1).
2. Check Physical Pull-Up Resistors: The RP1 chip has internal pull-ups, but they are weak (around 50kΩ). For reliable I2C communication at 400kHz, your BME280 breakout board must have 4.7kΩ physical pull-up resistors on the SDA and SCL lines. If it is a cheap clone board without them, the signal rise time will be too slow, causing Errno 121.
3. Inspect for Clock Stretching Timeouts: The RP1 I2C controller handles clock stretching differently than the BCM2835. If the BME280 holds the SCL line low to process data, the RP1 might time out prematurely. You can slow the bus speed by adding dtparam=i2c_arm_baudrate=100000 to your /boot/firmware/config.txt file and rebooting.

For deeper architectural details on the Pi 5's I/O controller, refer to the official RP1 Peripherals Datasheet.

Complete Python Control Script with Error Handling

Below is the complete, compilable Python script. This code targets the Raspberry Pi 5 8GB running Bookworm. It uses smbus2 for raw I2C register reads and gpiozero (which automatically utilizes the lgpio backend on the Pi 5) for relay control.

Create a file named environmental_control.py and paste the following:

#!/usr/bin/env python3
"""
Raspberry Pi 5 Headless Environmental Controller
Reads BME280 via I2C and triggers a relay if temperature exceeds threshold.
Target Board: Raspberry Pi 5 (RP1 Southbridge)
"""

import sys
import time
from smbus2 import SMBus, i2c_msg
from gpiozero import OutputDevice
from signal import pause

# --- PIN & BUS DEFINITIONS ---
I2C_BUS_ID = 1          # Physical pins 3 (SDA) and 5 (SCL)
BME280_I2C_ADDR = 0x76  # Default for CJMCU-811 (SDO tied to GND)
RELAY_BCM_PIN = 18      # Physical pin 12
TEMP_THRESHOLD_C = 25.0 # Relay triggers above this temperature

# Initialize Relay using gpiozero (Active LOW for most 5V relay modules)
relay = OutputDevice(RELAY_BCM_PIN, active_high=False, initial_value=False)

def read_bme280_temp(bus, addr):
    """Reads raw temperature data from BME280 registers and converts to Celsius."""
    try:
        # Read 3 bytes from the temperature registers (0xF7, 0xF8, 0xF9)
        # Note: A full implementation requires reading compensation parameters
        # from 0x88-0x9F. For this bench test, we read the raw ADC value.
        msg = i2c_msg.read(addr, 3)
        bus.i2c_rdwr(msg)
        raw_data = list(msg)
        
        # Combine bytes into 20-bit raw ADC value
        raw_temp = (raw_data[0] << 12) | (raw_data[1] << 4) | (raw_data[2] >> 4)
        
        # Simplified conversion (approximate for bench testing without full calibration matrix)
        # Real-world deployment MUST apply the datasheet compensation formula.
        temp_c = (raw_temp / 16384.0) * 25.0 
        return temp_c
        
    except OSError as e:
        if e.errno == 121:
            print(f"FATAL: I2C Bus Error (Errno 121). Check wiring and pull-ups on Bus {I2C_BUS_ID}.")
        else:
            print(f"FATAL: Unexpected I2C OS Error: {e}")
        sys.exit(1)

def main_loop():
    print(f"Starting environmental monitor on Pi 5 (Bus {I2C_BUS_ID}, Relay BCM {RELAY_BCM_PIN})...")
    
    with SMBus(I2C_BUS_ID) as bus:
        # Verify sensor presence before entering loop
        try:
            bus.read_byte_data(BME280_I2C_ADDR, 0xD0) # Read Chip ID register
        except OSError:
            print(f"FATAL: No device found at address {hex(BME280_I2C_ADDR)}. Halting.")
            sys.exit(1)
            
        print("Sensor verified. Entering control loop. Press Ctrl+C to exit.")
        
        try:
            while True:
                current_temp = read_bme280_temp(bus, BME280_I2C_ADDR)
                print(f"Current Temp: {current_temp:.2f} C", end="")
                
                if current_temp > TEMP_THRESHOLD_C:
                    relay.on()
                    print(" | RELAY: ON (Cooling active)")
                else:
                    relay.off()
                    print(" | RELAY: OFF")
                    
                time.sleep(2.0)
                
        except KeyboardInterrupt:
            print("\nInterrupt received. Cleaning up GPIO and I2C...")
        finally:
            relay.off()
            relay.close()
            print("System safely powered down. Relay is open.")

if __name__ == "__main__":
    main_loop()

Run the script using python3 environmental_control.py. The gpiozero library handles the RP1 chip abstraction seamlessly, provided you installed the python3-lgpio package via apt as shown in the previous step. For more on the transition to gpiozero, consult the official gpiozero documentation.

Extending and Simplifying the Build

Once the baseline script is running reliably on your bench, you will inevitably need to adapt it for a permanent deployment. Here is how to scale the project in either direction.

How to Simplify the Build

If jumper wires and raw I2C register reads are introducing too much points of failure, simplify the hardware layer. Swap the CJMCU breakout and relay module for an integrated HAT like the Pimoroni Enviro+ HAT or the Waveshare Relay HAT. These boards plug directly into the 40-pin header, eliminate loose Dupont wires, and provide manufacturer-supported Python libraries that handle the BME280 compensation math natively. This reduces your physical failure points from six jumper wires to zero.

How to Extend the Build

To move this from a standalone bench script to an integrated IoT node, extend the software layer by adding MQTT telemetry.

1. Install the Paho MQTT library: pip install paho-mqtt.
2. Import paho.mqtt.client into the script.
3. Inside the while True loop, publish the current_temp variable to a broker topic like home/lab/bench/temp.
4. Point Home Assistant or Node-RED at your MQTT broker to log the data over time and trigger automations (e.g., sending a push notification if the temperature spikes above 30°C).

Setting up a Raspberry Pi 5 for embedded control requires respecting the new RP1 architecture. By using the correct I2C bus, ensuring physical pull-up resistors are present, and relying on gpiozero instead of deprecated legacy libraries, you will bypass the most common pitfalls and achieve a stable, headless deployment.