Raspberry Pi Simple Projects: Build an I2C BME280 Environmental Logger

Why the BME280 is the Ultimate Raspberry Pi Simple Project

If you are searching for raspberry pi simple projects that actually yield useful, real-world data, skip the blinking LED tutorials. The Bosch BME280 environmental sensor is the gold standard for bench and home automation builds. It reads temperature, relative humidity, and barometric pressure over a shared I2C bus, requiring only four wires to interface with your Pi.

This guide targets the Raspberry Pi 5 (4GB) running Raspberry Pi OS (Bookworm/64-bit), though the hardware wiring and Python code are 100% backward-compatible with the Raspberry Pi 4 Model B. The Pi 5 utilizes the RP1 southbridge chip, which handles I2C clock stretching differently than the Pi 4's BCM2711. We will use hardware-accelerated I2C via the busio library to ensure stable polling without triggering bus lockups.

Parts List & Hardware Spec Sheet

Before you start stripping wires, verify your bill of materials. Using a 5V sensor breakout on the Pi's 3.3V GPIO pins is a common way to permanently damage the SoC. The Adafruit BME280 breakout (Product ID 2652) includes an onboard 3.3V LDO regulator and level-shifters, making it safe and reliable.

Note: If you buy generic $3 BME280 clone boards from online marketplaces, verify the chip marking. Many clones actually ship with the BMP280 chip, which lacks the humidity sensor. You can verify this in software by reading the Chip ID register (0xD0); a true BME280 returns 0x60, while a BMP280 returns 0x58.

Pin Mapping & Wiring Steps

The Raspberry Pi's primary I2C bus (I2C1) is hardcoded to GPIO 2 (SDA) and GPIO 3 (SCL). These pins feature onboard 1.8kΩ pull-up resistors tied to 3.3V. Never connect 5V to the SDA or SCL lines, even if your breakout board claims to be "5V tolerant." The Pi's GPIO pins are strictly 3.3V.

Numbered Wiring Procedure

1. De-energize the Pi: Unplug the USB-C power supply. Never wire GPIO pins while the board is powered.
2. Connect Power: Run a jumper from Pi Pin 1 (3.3V) to the BME280 VIN pin. (Do not use Pin 2/4 which are 5V).
3. Connect Ground: Run a jumper from Pi Pin 6 (GND) to the BME280 GND pin.
4. Connect I2C Data: Connect Pi Pin 3 (SDA) to the BME280 SDA pin.
5. Connect I2C Clock: Connect Pi Pin 5 (SCL) to the BME280 SCL pin.
6. Verify: Use a multimeter in continuity mode to ensure SDA and SCL are not shorted to each other or to ground.

The Python Code: I2C Polling with Error Handling

Before running the code, enable the I2C interface on your Pi by running sudo raspi-config, navigating to Interface Options > I2C, and selecting Yes. Reboot the Pi, then install the required Adafruit Blinka and BME280 libraries:

sudo apt update
sudo apt install python3-pip python3-venv
python3 -m venv env
source env/bin/activate
pip3 install adafruit-circuitpython-bme280

The following script targets the Pi's hardware I2C bus, includes a fallback address check (since some clone boards tie the SDO pin high, shifting the address from 0x76 to 0x77), and implements robust error handling.

import time
import board
import busio
import adafruit_bme280

# Target Board: Raspberry Pi 5 (4GB) / Pi 4 Model B
# Pin Definitions (BCM Numbering mapped to physical board pins)
SDA_PIN = board.SDA  # Physical Pin 3, BCM GPIO 2
SCL_PIN = board.SCL  # Physical Pin 5, BCM GPIO 3

# Initialize hardware I2C bus at default 100kHz
i2c = busio.I2C(SCL_PIN, SDA_PIN)

# BME280 I2C Addresses: 0x76 (Default/Adafruit) or 0x77 (Clones with SDO high)
PRIMARY_ADDR = 0x76
FALLBACK_ADDR = 0x77

def initialize_sensor():
    """Attempts to connect to the BME280 on primary, then fallback I2C address."""
    try:
        sensor = adafruit_bme280.Adafruit_BME280_I2C(i2c, address=PRIMARY_ADDR)
        print(f"Sensor initialized at primary address 0x{PRIMARY_ADDR:02X}")
        return sensor
    except ValueError:
        print(f"No device at 0x{PRIMARY_ADDR:02X}, trying fallback 0x{FALLBACK_ADDR:02X}...")
        try:
            sensor = adafruit_bme280.Adafruit_BME280_I2C(i2c, address=FALLBACK_ADDR)
            print(f"Sensor initialized at fallback address 0x{FALLBACK_ADDR:02X}")
            return sensor
        except ValueError as e:
            raise SystemExit(f"Fatal: BME280 not found on either address. Check wiring. ({e})")

def main():
    sensor = initialize_sensor()
    
    # Configure sensor settings for indoor environmental monitoring
    sensor.sea_level_pressure = 1013.25 # hPa, adjust to your local elevation
    sensor.mode = adafruit_bme280.MODE_NORMAL
    sensor.standby_period = adafruit_bme280.STANDBY_TC_500
    sensor.filter = adafruit_bme280.FILTER_X16
    
    print("Starting data logging... Press CTRL+C to stop.")
    
    try:
        while True:
            temp_c = sensor.temperature
            humidity = sensor.relative_humidity
            pressure = sensor.pressure
            altitude = sensor.altitude
            
            print(f"Temp: {temp_c:0.1f} C | Hum: {humidity:0.1f} % | Press: {pressure:0.2f} hPa | Alt: {altitude:0.1f} m")
            time.sleep(2.0)
            
    except KeyboardInterrupt:
        print("\nLogging stopped by user.")
    except OSError as e:
        print(f"\nHardware I/O Error during read: {e}")
        print("Check I2C connections and pull-up resistors.")

if __name__ == "__main__":
    main()

Debugging: "Remote I/O Error" and First Three Checks

When working with I2C on the Raspberry Pi, the most dreaded failure is the OSError: [Errno 121] Remote I/O error. This occurs when the Pi's I2C controller attempts to clock data out, but receives no ACK (acknowledge) bit from the sensor, or the bus gets stuck in a low state.

The First Three Things to Check When It Fails

1. Run the I2C Detection Tool: Open your terminal and run sudo i2cdetect -y 1. You should see a single number (76 or 77) in the grid. If the grid is entirely empty, your Pi is not seeing the sensor at all (wiring fault). If you see UU, the kernel driver has already claimed the device, which means your Python script will fail to open it.
2. Verify VCC Voltage with a Multimeter: Probe the VIN and GND pins on the breakout board while the Pi is powered. You must read between 3.2V and 3.4V. If you read 5V, you wired it to Pin 2/4 and have likely destroyed the sensor's internal LDO. If you read 0V, your jumper wire is broken or not fully seated in the breadboard.
3. Inspect Breakout Header Solder Joints: Cheap generic BME280 breakouts frequently ship with "cold" or dry solder joints on the header pins. Even if i2cdetect works intermittently, a slight vibration will cause the Remote I/O error. Reflow the header pins with a soldering iron and a touch of rosin-core flux.

Ranked Causes for I2C Bus Lockups

• Cause 1: Parallel Pull-Up Resistor Conflict. The Pi has 1.8kΩ pull-ups on GPIO 2/3. Many Adafruit and SparkFun breakouts also include 4.7kΩ pull-ups. Wired in parallel, the net resistance drops to ~1.3kΩ. While usually fine for 100kHz I2C, if your jumper wires exceed 30cm, the capacitance of the wire combined with the strong pull-ups will ruin the signal rise-time, causing bit-errors and the Errno 121 fault. Keep I2C wires under 20cm.
• Cause 2: SDA and SCL Swapped. I2C is not hot-swappable or auto-polarized. Swapping data and clock will result in an immediate ValueError during initialization.
• Cause 3: Pi 5 RP1 Southbridge Bit-Banging. If you are using older libraries that attempt to "bit-bang" I2C via standard GPIO toggling instead of using the hardware I2C peripheral, it will fail on the Pi 5. The RP1 chip handles GPIO timing differently than the BCM2711. Always use busio.I2C to force hardware I2C routing.

Extending and Simplifying the Build

Once your environmental logger is polling data reliably to the console, you have two paths forward depending on your project goals.

How to Simplify the Hardware

If breadboard jumper wires are causing intermittent Remote I/O faults due to loose contacts, eliminate the breadboard entirely. Upgrade to a STEMMA QT / Qwiic ecosystem. By purchasing the Adafruit BME280 with the STEMMA QT connector and a matching STEMMA QT to Pi GPIO cable, you use a keyed, locking 4-pin JST-SH connector. This guarantees correct pinout, prevents 5V/3.3V mixing, and provides a rock-solid mechanical connection that survives being moved around a workshop.

How to Extend the Software

Console logging is just the beginning. To turn this into a permanent home automation node:

• MQTT Integration: Install Mosquitto on your Pi or home server. Use the paho-mqtt Python library to publish the temperature and humidity JSON payloads to an MQTT topic (e.g., home/livingroom/climate). This allows Home Assistant to ingest the data instantly.
• InfluxDB & Grafana: For long-term trend analysis (like tracking barometric pressure drops before a storm), write the Python script to push data to a local InfluxDB time-series database. You can then spin up a Grafana container to visualize the 30-day humidity trends in your server room or greenhouse.
• Altitude Calibration: The script currently uses a hardcoded sea-level pressure of 1013.25 hPa. To get accurate altitude readings, look up your local airport's METAR report for the current QNH (altimeter setting) and update the sensor.sea_level_pressure variable dynamically via an API call.

For more details on configuring the Raspberry Pi's hardware interfaces, refer to the official Raspberry Pi configuration documentation. You can also review the Bosch Sensortec BME280 datasheet for deep-dive register maps and oversampling configurations.