Build a DIY Raspberry Pi Environmental Data Logger (BME280 + OLED)

If you want to build a reliable, headless environmental monitor, a DIY Raspberry Pi setup using the I2C bus is the most robust path forward. This guide walks through building a temperature, humidity, and pressure data logger with a local OLED readout. The code and wiring below specifically target the Raspberry Pi 5 (4GB variant) running Raspberry Pi OS (64-bit, Bookworm or newer), utilizing the modern RP1 southbridge chip's I2C controllers.

You will leave this bench with a working Python script, a physical wiring map, and a debugging framework for the inevitable I2C bus collisions.

Decision Path: Choosing Your DIY Raspberry Pi Hardware

Before buying parts, match your project constraints to the correct board. The Raspberry Pi ecosystem is vast, but picking the wrong compute module for a simple sensor logger leads to wasted power and thermal throttling.

Parts List & Hardware Specifications

Do not buy generic, unbranded sensor breakout boards if you are a beginner; they often lack the necessary 3.3V voltage regulators and pull-up resistors, leading to immediate bus failures. Use Adafruit or SparkFun breakouts for guaranteed 3.3V logic compatibility.

Pin Mapping & Physical Wiring

The Raspberry Pi 5 uses the RP1 southbridge chip, which changes the underlying GPIO addressing compared to the Pi 4, though the physical 40-pin header layout remains identical. We are using I2C1 (the default hardware I2C bus on pins 3 and 5).

Wiring Steps:

1. Power down the Pi 5 and disconnect the USB-C cable. Never hot-plug I2C sensors; the 3.3V rail is sensitive to inductive spikes.
2. Connect the 3.3V rail (Pin 1) to the positive breadboard rail, and GND (Pin 6) to the negative rail.
3. Daisy-chain the SDA and SCL lines from the Pi to the BME280, and then from the BME280 to the OLED.
4. Double-check that no bare wire strands are bridging Pin 1 (3.3V) and Pin 5 (SCL). A short here will instantly blow the RP1 I2C pad fuse.

Python Code: Logging and Displaying Sensor Data

This script uses the Adafruit Blinka compatibility layer and CircuitPython libraries. It initializes the I2C bus, reads the BME280, updates the OLED, and appends the data to a local CSV file. It includes explicit error handling for I2C dropouts.

Prerequisites: Run sudo apt install python3-pip i2c-tools, then pip3 install adafruit-circuitpython-bme280 adafruit-circuitpython-ssd1306 pillow.

import time
import board
import busio
import adafruit_bme280
import adafruit_ssd1306
from PIL import Image, ImageDraw, ImageFont
import csv
import os
from datetime import datetime

# --- Pin & Hardware Definitions ---
I2C_SDA = board.SDA
I2C_SCL = board.SCL
OLED_WIDTH = 128
OLED_HEIGHT = 64
OLED_ADDRESS = 0x3C
BME_ADDRESS = 0x77
CSV_FILE = 'env_log.csv'

# Initialize I2C Bus (Pi 5 RP1 default I2C1)
try:
    i2c = busio.I2C(I2C_SCL, I2C_SDA)
except ValueError as e:
    print(f'Fatal: I2C bus initialization failed. Check /boot/firmware/config.txt. Error: {e}')
    exit(1)

# Initialize Sensors with Error Handling
try:
    bme280 = adafruit_bme280.Adafruit_BME280_I2C(i2c, address=BME_ADDRESS)
    bme280.sea_level_pressure = 1013.25
except ValueError:
    print(f'Fatal: BME280 not found at 0x{BME_ADDRESS:02x}. Run i2cdetect -y 1 to verify.')
    exit(1)

try:
    oled = adafruit_ssd1306.SSD1306_I2C(OLED_WIDTH, OLED_HEIGHT, i2c, addr=OLED_ADDRESS)
except ValueError:
    print(f'Warning: OLED not found at 0x{OLED_ADDRESS:02x}. Continuing headless.')
    oled = None

# Setup CSV if it doesn't exist
if not os.path.exists(CSV_FILE):
    with open(CSV_FILE, 'w', newline='') as f:
        writer = csv.writer(f)
        writer.writerow(['Timestamp', 'Temp_C', 'Humidity_%', 'Pressure_hPa'])

# Main Loop
print('Logging started. Press Ctrl+C to stop.')
try:
    while True:
        timestamp = datetime.now().strftime('%Y-%m-%d %H:%M:%S')
        temp_c = bme280.temperature
        humidity = bme280.relative_humidity
        pressure = bme280.pressure

        # Log to CSV
        with open(CSV_FILE, 'a', newline='') as f:
            writer = csv.writer(f)
            writer.writerow([timestamp, f'{temp_c:.2f}', f'{humidity:.2f}', f'{pressure:.2f}'])

        # Update OLED
        if oled:
            oled.fill(0)
            draw = ImageDraw.Draw(Image.new('1', (OLED_WIDTH, OLED_HEIGHT)))
            # Using default font for compatibility
            draw.text((0, 0), f'T: {temp_c:.1f} C', fill=255)
            draw.text((0, 16), f'H: {humidity:.1f} %', fill=255)
            draw.text((0, 32), f'P: {pressure:.1f} hPa', fill=255)
            draw.text((0, 48), timestamp[11:], fill=255) # Just the time
            oled.image(draw.im)
            oled.show()

        time.sleep(10) # 10-second polling interval

except KeyboardInterrupt:
    print('\nLogging stopped by user.')
except OSError as e:
    print(f'\nI2C Bus Error during runtime: {e}. Check physical connections.')
finally:
    if oled:
        oled.fill(0)
        oled.show()

Debugging I2C Failures on the Pi

When working with the DIY Raspberry Pi I2C bus, you will eventually hit the most notorious Linux I2C error. If your script crashes with the following exact string:

OSError: [Errno 121] Remote I/O error

This means the Linux kernel sent an I2C transaction, but the slave device NACK'd (did not acknowledge) it, or the clock line was held low. Here are the first three things to check when this happens:

1. Run sudo i2cdetect -y 1: If the output shows -- at address 77, the Pi cannot see the sensor. If it shows UU, another process (like a leftover systemd service) has already claimed the device.
2. Measure the 3.3V Rail: Put your multimeter probes on Pin 1 and Pin 6. You must read between 3.25V and 3.35V. If it reads below 3.1V, the Pi's power supply is browning out, or you are drawing too much current from the 3.3V LDO (the Pi 5's 3.3V rail is limited to ~300mA total).
3. Check Wire Capacitance: If your jumper wires exceed 30cm, the signal edges degrade. The RP1 chip expects sharp square waves. Swap to shorter wires or add a dedicated I2C level shifter/buffer (like the PCA9600).

Extending or Simplifying the Build

Once your baseline DIY Raspberry Pi logger is stable, you will likely want to adapt it to your specific environment. Here is how to scale the project without rewriting the core logic.

How to Simplify (Headless / Low Power)

If you are deploying this in an attic or crawl space, the OLED is a liability—it draws ~20mA and generates localized heat that skews the BME280 temperature readings by up to 1.5°C.

• Action: Physically disconnect the SSD1306.
• Code Change: Delete the adafruit_ssd1306 and PIL imports. The script's try/except block for the OLED will gracefully handle its absence and continue logging to CSV headlessly.
• OS Tweak: Disable HDMI output via sudo raspi-config to save an additional 30mA of idle current.

How to Extend (Networked & Time-Resilient)

A standard Pi loses its system clock when power is removed. If your Pi reboots during a power outage, your CSV timestamps will default to 1970 until NTP syncs, ruining your data integrity.

• Add a DS3231 RTC: Wire a DS3231 Real Time Clock module to the same I2C bus (Address 0x68). It draws microamps from a CR2032 coin cell and keeps perfect time offline.
• Add MQTT Publishing: Install paho-mqtt. Inside the main loop, publish the temp_c and humidity variables to a local Mosquitto broker topic like home/lab/environment for integration with Home Assistant.
• Switch to SQLite: Replace the CSV append logic with the built-in sqlite3 Python library. This prevents file corruption if the Pi loses power exactly when the CSV is being written to disk.

By starting with the Pi 5 and high-quality 3.3V breakouts, you eliminate 90% of the hardware-level debugging that plagues embedded projects, leaving you free to focus on the data pipeline.