Running Python on Raspberry Pi 5: I2C Sensor Debugging and Setup

The Verdict: Which Raspberry Pi and Library Stack to Choose

When running Python on Raspberry Pi for hardware interfacing, the biggest bottleneck isn't processing power; it's I2C bus reliability and library overhead. The transition to Raspberry Pi OS Bookworm (64-bit) changed the underlying Python environment, breaking many legacy GPIO scripts.

Our Concrete Pick: For this guide, we are targeting the Raspberry Pi 5 (4GB RAM) running Raspberry Pi OS Bookworm 64-bit, using the smbus2 library. We choose smbus2 over Blinka for raw I2C debugging because it exposes the exact underlying Linux ioctl errors without masking them in Adafruit's abstraction layer, which is critical when diagnosing bus failures.

Hardware BOM and Pin Mapping

This build creates a robust environmental node. We are using native 3.3V I2C devices to avoid frying the Pi 5's GPIO pins, which are strictly 3.3V tolerant (unlike the 5V-tolerant pins on an Arduino Uno).

Pin Mapping Table

The Raspberry Pi 5 maintains the standard 40-pin header layout. We are using the primary hardware I2C bus (Bus 1).

Wiring and Physical Setup

1. De-energize the board: Unplug the USB-C power supply from the Raspberry Pi 5 before making any physical connections.
2. Seat the Pi: Mount the Pi 5 on its active cooler and secure it to your workbench or case. Ensure the 40-pin header is accessible.
3. Connect Power and Ground: Plug the red Dupont wire from Pi Pin 1 (3V3) to the BME280 VIN. Plug the black wire from Pi Pin 6 (GND) to the BME280 GND.
4. Connect the I2C Data Lines: Connect Pi Pin 3 (SDA) to the BME280 SDA. Connect Pi Pin 5 (SCL) to the BME280 SCL.
5. Verify Pull-up Resistors: If using the genuine Adafruit 2652 breakout, skip this step (it has 10kΩ pull-ups onboard). If using a bare generic BME280 module, solder a 4.7kΩ resistor between SDA and 3V3, and another between SCL and 3V3.
6. Power up and SSH: Plug in the power supply, boot the Pi, and SSH into your terminal.

The Python Code: I2C Polling with Error Handling

Before running the code, install the required package in your virtual environment: pip install smbus2. This script targets the Raspberry Pi 5 4GB and reads the BME280's hard-coded Chip ID register (0xD0). This is the gold-standard method for verifying I2C communication before attempting complex temperature/pressure calibration math.

import smbus2
import time
import sys

# TARGET BOARD: Raspberry Pi 5 4GB (Raspberry Pi OS Bookworm 64-bit)
# SENSOR: Adafruit BME280 (Product ID: 2652)
# I2C BUS: 1 (Default hardware I2C on Pi 4/5)

I2C_BUS = 1
BME280_ADDR = 0x77  # Default for Adafruit breakout. Use 0x76 for generic clones.
CHIP_ID_REG = 0xD0
EXPECTED_CHIP_ID = 0x60  # Bosch BME280 hardcoded ID

def verify_sensor_connection():
    """Attempts to read the Chip ID register to verify I2C connectivity."""
    try:
        # Initialize the I2C bus
        with smbus2.SMBus(I2C_BUS) as bus:
            # Read a single byte from the Chip ID register
            chip_id = bus.read_byte_data(BME280_ADDR, CHIP_ID_REG)
            
            if chip_id == EXPECTED_CHIP_ID:
                print(f"[SUCCESS] BME280 detected at {hex(BME280_ADDR)}. Chip ID: {hex(chip_id)}")
                return True
            else:
                print(f"[WARNING] Device found, but wrong Chip ID. Expected {hex(EXPECTED_CHIP_ID)}, got {hex(chip_id)}")
                return False
                
    except OSError as e:
        # This catches the exact Linux I2C driver failure
        if "[Errno 121] Remote I/O error" in str(e):
            print(f"[CRITICAL] I2C Bus Failure: {e}")
            print("-> The sensor did not ACK the address. Check wiring and pull-ups.")
        elif "[Errno 121]" in str(e) or "[Errno 110]" in str(e):
            print(f"[CRITICAL] I2C Timeout/Bus Error: {e}")
            print("-> Clock stretching timeout. Try reducing I2C baudrate in /boot/firmware/config.txt")
        else:
            print(f"[ERROR] Unexpected OS Error: {e}")
        return False
        
    except FileNotFoundError:
        print("[ERROR] I2C Bus /dev/i2c-1 not found.")
        print("-> Did you enable I2C via 'sudo raspi-config'? Reboot required.")
        return False

if __name__ == "__main__":
    print("Starting I2C Bus Verification...")
    max_retries = 3
    
    for attempt in range(1, max_retries + 1):
        print(f"\nAttempt {attempt} of {max_retries}:")
        if verify_sensor_connection():
            print("Hardware verified. Safe to proceed with full sensor library initialization.")
            sys.exit(0)
        
        if attempt < max_retries:
            print("Waiting 2 seconds before retry...")
            time.sleep(2)
            
    print("\n[FATAL] Failed to verify sensor after 3 attempts. Halting execution.")
    sys.exit(1)

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

If you spend enough time running Python on Raspberry Pi hardware, you will eventually hit OSError: [Errno 121] Remote I/O error. This is not a Python bug; it is the Linux kernel's i2c-bcm2835 driver telling you that it sent an address byte over the wire and never received an Acknowledge (ACK) bit back from the slave device.

The First Three Things to Check When It Fails

1. Run i2cdetect -y 1 in the terminal: If the output grid shows -- at address 0x77, the Pi cannot see the hardware at the OS level. If it shows UU, another kernel driver (like bmp280) has already claimed the device, and Python cannot access it.
2. Measure the 3.3V Rail with a Multimeter: Put your multimeter probes directly on the sensor breakout's VCC and GND pins. You must read between 3.2V and 3.4V. If you read 0V or 1.8V, you have a broken Dupont wire or a blown Pi polyfuse.
3. Verify Pull-Up Resistors: I2C is an open-drain protocol. Without pull-up resistors to 3.3V, the SDA/SCL lines float, causing garbage data and Errno 121. Measure the resistance between SDA and 3.3V with the power off; it should read roughly 4.7kΩ to 10kΩ.

Extending or Simplifying the Build

Once the raw I2C bus is verified using the script above, you have a stable foundation. Here is how to scale the project based on your end goal.

How to Simplify (The Minimalist Route)

If you just need local terminal logging and want to strip out all complexity:

• Drop the custom smbus2 register reads and install the high-level wrapper: pip install adafruit-circuitpython-bme280.
• Remove the OLED display entirely; rely on systemd journal logs for output.
• Power the Pi via a standard 5V/5A USB-C wall wart rather than building a custom DC-DC buck converter power supply.

How to Extend (The Production IoT Route)

To turn this bench prototype into a deployed environmental node:

• Add MQTT: Install paho-mqtt and publish the parsed temperature/humidity JSON payload to a local Mosquitto broker or Home Assistant instance.
• Daemonize: Write a systemd service file (/etc/systemd/system/env-sensor.service) with Restart=on-failure and RestartSec=10 to ensure the script recovers automatically if the I2C bus temporarily locks up.
• Add Galvanic Isolation: If deploying in an industrial environment with long wire runs, place an Adafruit I2C Isolator (Product ID: 4845) between the Pi and the sensor to protect the Pi's SoC from ground loops and voltage spikes.

For deeper reading on Linux I2C protocol mechanics, refer to the official Linux Kernel I2C Protocol documentation, and for hardware specifics, consult the Raspberry Pi Configuration Guide.