Top Projects for Raspberry Pi 5: Build an MQTT Environmental Hub

Why Environmental Monitoring Tops the Raspberry Pi Project Lists

When evaluating the top projects for Raspberry Pi in 2026, the community is split between heavy AI edge-computing (leveraging the Pi 5’s PCIe lane) and high-uptime home automation. While AI vision is flashy, the most reliable, universally useful build remains the Multi-Sensor MQTT Environmental Hub. It bridges raw hardware telemetry with platforms like Home Assistant, Node-RED, or custom cloud dashboards.

This guide targets the Raspberry Pi 5 (8GB variant) running Raspberry Pi OS Bookworm (64-bit). We will wire a BME280 environmental sensor and an SSD1306 OLED display over the I2C bus, poll the data, render it locally, and publish it to an MQTT broker. No pseudocode, no abstract theory—just bench-tested procedures.

Hardware Spec Sheet & Parts List

Before touching a jumper wire, verify your components against this exact bill of materials. Substituting generic, unbranded clone sensors often leads to I2C address conflicts and missing pull-up resistors, which will ruin your afternoon.

Pin Mapping & Wiring the I2C Bus

The Raspberry Pi 5 maintains the standard 40-pin header layout, but its I2C bus characteristics are slightly more sensitive to capacitance than the Pi 4. Keep your I2C jumper wires under 12 inches (30 cm) to avoid signal degradation.

Wiring Sequence

1. De-energize: Unplug the Pi 5 USB-C power supply. Never hot-swap I2C sensors; a momentary short on the SDA line can lock up the I2C controller until a hard reboot.
2. Daisy-chain Power: Connect Pin 1 (3.3V) to the BME280 VIN, then run a jumper from the BME280 VIN to the OLED VCC. (Do not use 5V for the OLED if it lacks an onboard voltage regulator; the Adafruit breakout has one, but generic raw modules do not).
3. Common Ground: Connect Pin 6 (GND) to both sensor GND pins. A missing common ground is the #1 cause of floating I2C logic levels.
4. Data Lines: Connect Pin 3 to both SDA pins, and Pin 5 to both SCL pins.
5. Verify: Power up the Pi, SSH in, and run sudo i2cdetect -y 1. You should see 3c (OLED) and 77 (BME280) in the grid.

Python Code: Sensor Polling, OLED Rendering, and MQTT Publishing

This script targets the exact hardware above. It uses smbus2 and RPi.bme280 for the environmental sensor, adafruit-circuitpython-ssd1306 for the display, and paho-mqtt for network telemetry. Install them in your venv via: pip install smbus2 RPi.bme280 adafruit-circuitpython-ssd1306 paho-mqtt Pillow.

#!/usr/bin/env python3
"""
Raspberry Pi 5 MQTT Environmental Hub
Target: Pi 5 (Bookworm), BME280 (0x77), SSD1306 (0x3C)
"""

import time
import json
import smbus2
import bme280
import board
import busio
from PIL import Image, ImageDraw, ImageFont
import adafruit_ssd1306
import paho.mqtt.client as mqtt

# --- HARDWARE PIN & ADDRESS DEFINITIONS ---
I2C_PORT = 1
BME280_ADDRESS = 0x77
OLED_ADDRESS = 0x3C
OLED_WIDTH = 128
OLED_HEIGHT = 64

# --- MQTT CONFIGURATION ---
MQTT_BROKER = "192.168.1.100"
MQTT_PORT = 1883
MQTT_TOPIC = "home/environment/livingroom"

def setup_i2c_devices():
    """Initialize I2C bus and connected peripherals."""
    # Initialize BME280
    bus = smbus2.SMBus(I2C_PORT)
    calibration_params = bme280.load_calibration_params(bus, BME280_ADDRESS)
    
    # Initialize SSD1306 OLED
    i2c = busio.I2C(board.SCL, board.SDA)
    oled = adafruit_ssd1306.SSD1306_I2C(OLED_WIDTH, OLED_HEIGHT, i2c, addr=OLED_ADDRESS)
    oled.fill(0)
    oled.show()
    
    return bus, calibration_params, oled

def setup_mqtt():
    """Configure and connect the MQTT client with error handling."""
    client = mqtt.Client(mqtt.CallbackAPIVersion.VERSION2)
    
    def on_connect(client, userdata, flags, reason_code, properties):
        if reason_code == 0:
            print("[MQTT] Connected to broker.")
        else:
            print(f"[MQTT] Connection failed with code: {reason_code}")

    client.on_connect = on_connect
    try:
        client.connect(MQTT_BROKER, MQTT_PORT, 60)
        client.loop_start()
    except Exception as e:
        print(f"[MQTT] Broker unreachable: {e}")
    return client

def main():
    bus, cal_params, oled = setup_i2c_devices()
    mqtt_client = setup_mqtt()
    
    # Load default font (fallback if custom .ttf is missing)
    try:
        font = ImageFont.truetype("/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf", 14)
    except IOError:
        font = ImageFont.load_default()

    print("[SYSTEM] Hub initialized. Polling every 5 seconds...")

    try:
        while True:
            # 1. Read Sensor Data
            data = bme280.sample(bus, BME280_ADDRESS, cal_params)
            temp_c = round(data.temperature, 2)
            humidity = round(data.humidity, 1)
            pressure = round(data.pressure, 1)

            # 2. Render to OLED
            image = Image.new("1", (OLED_WIDTH, OLED_HEIGHT))
            draw = ImageDraw.Draw(image)
            draw.text((0, 0), f"Temp: {temp_c} C", font=font, fill=255)
            draw.text((0, 20), f"Hum:  {humidity} %", font=font, fill=255)
            draw.text((0, 40), f"Pres: {pressure} hPa", font=font, fill=255)
            oled.image(image)
            oled.show()

            # 3. Publish to MQTT
            payload = json.dumps({
                "temperature": temp_c,
                "humidity": humidity,
                "pressure": pressure,
                "timestamp": time.time()
            })
            mqtt_client.publish(MQTT_TOPIC, payload, qos=1)
            
            time.sleep(5)

    except KeyboardInterrupt:
        print("\n[SYSTEM] Shutting down gracefully...")
    except Exception as e:
        print(f"[ERROR] Unexpected failure in main loop: {e}")
    finally:
        mqtt_client.loop_stop()
        mqtt_client.disconnect()
        oled.fill(0)
        oled.show()

if __name__ == "__main__":
    main()

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

If you run the script and immediately hit a crash, you will likely see this exact traceback:

OSError: [Errno 121] Remote I/O error
Traceback (most recent call last):
File "hub.py", line 42, in setup_i2c_devices
calibration_params = bme280.load_calibration_params(bus, BME280_ADDRESS)

This is the Linux kernel’s way of telling you that the I2C controller sent an address byte to 0x77 and received a NACK (No Acknowledge) from the bus. The hardware physically cannot see the sensor.

The First Three Things to Check

1. Run i2cdetect -y 1: If the grid is entirely empty, your SDA/SCL wires are swapped or broken. If you see UU instead of 77, another kernel driver (like bmp280) has already claimed the device. Blacklist the conflicting driver in /boot/firmware/config.txt.
2. Measure VCC at the Sensor Pins: Use a multimeter to check the voltage between the sensor's VCC and GND pins. It must read 3.2V to 3.4V. If it reads 0V, your jumper wire is dead. If it reads 5V, you wired it to Pin 2 (5V) by mistake, and you may have already fried the BME280's internal voltage regulator.
3. Verify Pull-Up Resistors: The I2C spec requires pull-up resistors on SDA and SCL. The Pi 5 has internal 50kΩ pull-ups, but they are often too weak for long wire runs or multiple devices. The Adafruit BME280 breakout includes 10kΩ onboard pull-ups. If you are using a raw, cheap eBay module without pull-ups, the bus will float, causing Errno 121.

Ranked Causes for Errno 121

Scaling the Build: Extensions vs. Simplifications

A hallmark of the top projects for Raspberry Pi is modularity. You shouldn't build a monolithic script that breaks if one sensor is missing. Here is how to adapt this hub to your specific bench constraints.

How to Extend the Hub

• Add Air Quality (VOC/CO2): Wire an Adafruit SCD-41 to the same I2C bus. It operates at address 0x62, avoiding conflicts with the BME280 and OLED. Add its polling loop to the while True block and append the CO2 ppm value to the MQTT JSON payload.
• Add LoRaWAN Telemetry: If your Pi is in a shed or greenhouse without WiFi, connect a Dragino LoRa/GPS HAT via SPI. You will need to disable the I2C OLED to free up header space, or use a Pi 5 PCIe-to-USB adapter for the LoRa dongle.
• Prometheus Metrics: Instead of (or alongside) MQTT, expose a Flask web server on port 8000 that formats the sensor data as Prometheus metrics. This allows Grafana to scrape the Pi directly without an intermediate MQTT-to-InfluxDB bridge.

How to Simplify the Build

• Headless Mode (Drop the OLED): If you only care about Home Assistant integration, remove the SSD1306 entirely. Delete the adafruit_ssd1306 and Pillow dependencies. This reduces CPU overhead and eliminates I2C bus contention, making the MQTT publishing loop microsecond-accurate.
• Switch to DHT22 (1-Wire/GPIO): If I2C is giving you grief, swap the BME280 for a DHT22 wired to a standard GPIO pin (e.g., GPIO 4). You will need to install the libgpiod2 library and use the adafruit-circuitpython-dht package. Note that DHT22 is significantly slower and less accurate than the BME280, but it requires zero bus configuration.

By anchoring your build on the Pi 5’s robust I2C controller and structuring your Python environment to respect modern OS constraints, this environmental hub will run for months without a watchdog reset. Wire it clean, handle your exceptions, and let the MQTT broker do the heavy lifting.