Installing Raspberry Pi OS on Pi 5: Headless Setup and I2C Verification

Getting a new board on the network without a monitor is a rite of passage, but the transition to the Raspberry Pi 5 and its RP1 southbridge chip has changed a few underlying hardware behaviors. If you are installing Raspberry Pi OS for a headless embedded project, the old 'flash and pray' method won't cut it when you need to verify I2C sensor communication on the bench.

This guide targets the Raspberry Pi 5 (8GB variant) running Raspberry Pi OS (64-bit, Debian Bookworm). We will cover the exact headless flashing procedure, map the I2C pins for the new RP1 architecture, and deploy a fault-tolerant Python script to verify your bus communication before you solder anything.

Hardware Spec Sheet & Parts List

Before we touch the software, let's lock in the bill of materials. The Pi 5 has stricter power requirements than the Pi 4; using a standard 5V/3A phone charger will trigger peripheral brownouts and throttle the CPU when you enable I2C and WiFi simultaneously.

Flashing and Headless Configuration Steps

We are using the official Raspberry Pi Imager (v1.8 or newer). The UI has been updated recently to make OS customisation more prominent, but the underlying configuration files remain the same.

1. Insert the SD Card: Use a dedicated USB 3.0 SD reader. Internal laptop readers often bottleneck at USB 2.0 speeds.
2. Select Device & OS: Choose Raspberry Pi 5 -> Raspberry Pi OS (64-bit). Do not use the 'Lite' version for this build; we need the standard kernel modules pre-loaded for I2C debugging tools.
3. Open OS Customisation: Click Edit Settings when prompted (or press Ctrl+Shift+X on older versions).
4. Configure Network & Identity:
   • Hostname: pi5-sensor-node
   • Username: pi (or your preferred user)
   • Password: Set a strong bcrypt-friendly password.
   • WiFi: Enter your 2.4GHz SSID and PSK. (The Pi 5 supports 5GHz, but 2.4GHz penetrates enclosures better for bench testing).
5. Enable Services: Go to the Services tab and check Enable SSH. Select Use password authentication.
6. Flash & Verify: Click Save, then Write. Wait for the verification pass to hit 100%. Do not skip verification; a single flipped bit in the kernel image will cause a silent boot loop.

First Boot Verification & I2C Pin Mapping

Once the Pi 5 boots and connects to your network, SSH into it via ssh pi@pi5-sensor-node.local. The Pi 5 routes its peripherals through the custom RP1 southbridge chip, not the main BCM2712 CPU. This means the I2C controllers are technically mapped differently at the silicon level, but the device tree abstracts this to the standard /dev/i2c-1 interface for user-space applications.

Here is the exact pin mapping for the primary I2C bus (I2C1) on the 40-pin header. This layout is backward-compatible with the Pi 4, but the electrical characteristics differ slightly.

Python I2C Verification Script

To verify the install and the hardware connection, we will use the smbus2 library. It is lightweight, requires no heavy Adafruit dependencies, and allows us to catch specific I/O errors. This code explicitly targets the Raspberry Pi 5 8GB (though it runs fine on Pi 4/Zero 2 W) and reads the BME280 chip ID register to confirm communication.

First, install the required system and Python packages:

sudo apt update
sudo apt install -y i2c-tools python3-smbus2 python3-pip
pip3 install smbus2 --break-system-packages

Create a file named verify_i2c.py and paste the following complete, error-handled script:

#!/usr/bin/env python3
import sys
import time
from smbus2 import SMBus, i2c_msg

# --- Pin & Bus Definitions ---
I2C_BUS_ID = 1          # Maps to /dev/i2c-1 (Physical pins 3 & 5)
BCM_SDA_PIN = 2         # For documentation/reference
BCM_SCL_PIN = 3         # For documentation/reference
BME280_I2C_ADDR = 0x76  # Default address (SDO pin tied to GND)
BME280_CHIP_ID_REG = 0xD0
EXPECTED_CHIP_ID = 0x60 # Bosch BME280 hardcoded ID

def verify_sensor():
    try:
        with SMBus(I2C_BUS_ID) as bus:
            # Read 1 byte from the Chip ID register
            msg = i2c_msg.read(BME280_I2C_ADDR, 1)
            bus.i2c_rdwr(msg)
            chip_id = list(msg)[0]
            
            if chip_id == EXPECTED_CHIP_ID:
                print(f'[SUCCESS] BME280 found at 0x{BME280_I2C_ADDR:02X}. Chip ID: 0x{chip_id:02X}')
                return True
            else:
                print(f'[WARNING] Device responded, but Chip ID is 0x{chip_id:02X} (Expected 0x60). Wrong sensor?')
                return False
                
    except FileNotFoundError as e:
        print(f'[FATAL] {e}')
        print('-> I2C bus not found. Is the interface enabled in raspi-config?')
        sys.exit(1)
        
    except OSError as e:
        if e.errno == 121:
            print(f'[ERROR] Remote I/O error (Errno 121) on bus {I2C_BUS_ID}.')
            print('-> Check physical wiring, pull-up resistors, or sensor power.')
        elif e.errno == 16:
            print(f'[ERROR] Device or resource busy (Errno 16).')
            print('-> Another process is holding the I2C bus.')
        else:
            print(f'[ERROR] Unexpected OS Error: {e}')
        sys.exit(1)

if __name__ == '__main__':
    print(f'Scanning I2C Bus {I2C_BUS_ID} (SDA: BCM{BCM_SDA_PIN}, SCL: BCM{BCM_SCL_PIN})...')
    verify_sensor()

Troubleshooting Boot and I2C Errors

When installing Raspberry Pi OS for embedded sensor nodes, things rarely work perfectly on the first boot. If your script fails, here is the exact decision path based on the terminal output.

The First Three Things to Check

1. Verify the Kernel Module: Run lsmod | grep i2c. You must see i2c_brcmstb or i2c_designware_platform loaded. If it's missing, the device tree overlay failed to apply.
2. Scan the Bus: Run i2cdetect -y 1. If you see 76 in the grid, the hardware is fine and your Python address is wrong. If the grid is empty, you have a physical layer issue.
3. Multimeter Continuity: Power down the Pi. Use your multimeter in continuity mode to check for shorts between SDA/SCL and GND. A single stray strand of 28 AWG wire touching the ground plane will pull the bus low and brick communication.

Exact Error Strings and Ranked Causes

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

• Cause A (Most Likely): I2C is disabled in the OS. Fix: Run sudo raspi-config and enable it, or add dtparam=i2c_arm=on to /boot/firmware/config.txt.
• Cause B: You are targeting the wrong bus ID in Python. The Pi 5 defaults to bus 1 for the main header. Change I2C_BUS_ID = 1.

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

• Cause A (Most Likely): The BME280 SDO pin is floating. Fix: Tie the SDO pin explicitly to GND (for address 0x76) or VCC (for 0x77).
• Cause B: RP1 Clock Stretching Timeout. The Pi 5's RP1 chip is notoriously strict about I2C clock stretching. If your sensor holds the SCL line low for too long, the RP1 drops the transaction. Fix: Add external 4.7kΩ pull-up resistors to 3.3V on both SDA and SCL lines to sharpen the rise times.
• Cause C: Under-voltage throttling. If you used a 15W charger instead of the 27W PD supply, the Pi 5 will drop the 3.3V rail under load. Fix: Check dmesg | grep voltage and upgrade your power supply.

Extending or Simplifying the Build

Depending on your final deployment, you might need to scale this setup up or down.

How to Simplify

If you are building a simple network probe or a headless Docker host and don't need I2C sensors, drop the Pi 5 and use a Raspberry Pi Zero 2 W. It costs roughly $15, sips power, and uses the exact same Raspberry Pi OS image. You can simplify the verification script to a basic bash ping test or an MQTT heartbeat, eliminating the need for smbus2 entirely.

How to Extend

For a robust environmental monitoring node, extend the I2C bus by adding a DS3231 Real Time Clock (RTC). The DS3231 shares the same I2C bus (address 0x68) and provides hardware timekeeping when the Pi loses network NTP sync. To integrate it, add dtoverlay=i2c-rtc,ds3231 to your config.txt. You can also extend the software by wrapping the Python script in a systemd service that pushes the BME280 payload to an MQTT broker every 60 seconds, complete with a watchdog timer to reboot the Pi if the I2C bus locks up.

For more details on the RP1 peripheral architecture, refer to the official Raspberry Pi silicon documentation. Always consult the Bosch BME280 datasheet when calculating oversampling rates for your specific environmental noise floor.