Building an IoT Sensor Node: Raspberry Pi 5 & MQTT Guide

Building a robust IoT edge node on a Raspberry Pi requires more than just copying a tutorial; it demands strict attention to logic levels, I2C bus capacitance, and network resilience. If you are setting up a node raspberry pi deployment for home automation or industrial telemetry, the Raspberry Pi 5 is the current benchmark. Its dedicated RP1 southbridge handles I2C clock stretching far better than the Pi 4, preventing the silent data corruption that plagues older models when reading environmental sensors.

This guide walks you through building an MQTT sensor node using a Raspberry Pi 5 and a BME280 environmental sensor. We will cover the exact hardware, the physical pin mapping, a production-ready Python script with error handling, and the specific debugging steps for when the I2C bus inevitably throws a fit.

Project Overview & Parts List

Before writing a single line of code, you need the right silicon. The BME280 is chosen over the cheaper DHT22 because it uses digital I2C (no bit-banging timing issues) and provides pressure, humidity, and temperature in a single package.

Hardware Wiring & Pin Mapping

The Raspberry Pi 5 GPIO header operates strictly at 3.3V logic. Feeding 5V into the SDA or SCL lines will instantly destroy the RP1 southbridge. Always verify your sensor breakout is configured for 3.3V operation before applying power.

Pin Mapping Table

Note: Do not use the 5V pin (Pin 2 or 4) to power the BME280 if your breakout board lacks a robust voltage regulator. Stick to Pin 1 (3.3V) to keep logic levels matched.

The Node Script: Python MQTT Publisher

This script targets Raspberry Pi OS Bookworm (64-bit). It uses Adafruit's Blinka library for I2C hardware abstraction and Eclipse Paho for MQTT. It includes automatic reconnection logic and graceful shutdown handling.

Prerequisites: Enable I2C via sudo raspi-config (Interface Options > I2C), then install the dependencies:

sudo apt update
sudo apt install python3-pip i2c-tools
pip3 install adafruit-circuitpython-bme280 paho-mqtt --break-system-packages

Complete Node Code (sensor_node.py):

import time
import signal
import sys
import board
import busio
import adafruit_bme280
import paho.mqtt.client as mqtt

# --- PIN & CONFIGURATION DEFINITIONS ---
# I2C uses physical Pin 3 (SDA) and Pin 5 (SCL) on the Pi 5 header
I2C_SDA_PIN = board.SDA
I2C_SCL_PIN = board.SCL

MQTT_BROKER = "192.168.1.100"
MQTT_PORT = 1883
MQTT_TOPIC = "home/lab/environment"
MQTT_KEEPALIVE = 60
POLL_INTERVAL = 10  # Seconds between sensor reads

# --- GLOBAL STATE ---
running = True

def signal_handler(sig, frame):
    global running
    print("\n[INFO] Shutdown signal received. Closing connections...")
    running = False

signal.signal(signal.SIGINT, signal_handler)
signal.signal(signal.SIGTERM, signal_handler)

# --- MQTT CALLBACKS ---
def on_connect(client, userdata, flags, rc, properties=None):
    if rc == 0 or rc == mqtt.MQTT_ERR_SUCCESS:
        print(f"[MQTT] Connected to broker {MQTT_BROKER}")
    else:
        print(f"[MQTT] Connection failed with code: {rc}")

def on_disconnect(client, userdata, rc, properties=None):
    print(f"[MQTT] Disconnected (code: {rc}). Attempting auto-reconnect...")

# --- MAIN EXECUTION ---
def main():
    # 1. Initialize I2C Bus
    try:
        i2c = busio.I2C(I2C_SCL_PIN, I2C_SDA_PIN)
        # BME280 default I2C address is 0x77 (Adafruit) or 0x76 (generic)
        bme280 = adafruit_bme280.Adafruit_BME280_I2C(i2c, address=0x77)
        print(f"[I2C] BME280 initialized. Chip ID: {bme280.chip_id}")
    except ValueError as e:
        print(f"[FATAL] BME280 not found on I2C bus. Check wiring and address. Error: {e}")
        sys.exit(1)

    # 2. Initialize MQTT Client
    client = mqtt.Client(mqtt.CallbackAPIVersion.VERSION2, client_id="pi5_env_node")
    client.on_connect = on_connect
    client.on_disconnect = on_disconnect
    
    try:
        client.connect(MQTT_BROKER, MQTT_PORT, MQTT_KEEPALIVE)
        client.loop_start()
    except Exception as e:
        print(f"[FATAL] Could not connect to MQTT broker: {e}")
        sys.exit(1)

    # 3. Telemetry Loop
    print(f"[INFO] Publishing to {MQTT_TOPIC} every {POLL_INTERVAL}s. Press Ctrl+C to stop.")
    while running:
        try:
            temp_c = bme280.temperature
            humidity = bme280.relative_humidity
            pressure = bme280.pressure
            
            payload = f'{{"temp_c": {temp_c:.2f}, "humidity": {humidity:.2f}, "pressure_hpa": {pressure:.2f}}}'
            
            result = client.publish(MQTT_TOPIC, payload, qos=1)
            if result.rc == mqtt.MQTT_ERR_SUCCESS:
                print(f"[TX] {payload}")
            else:
                print(f"[WARN] MQTT publish failed with code: {result.rc}")
                
        except OSError as e:
            print(f"[ERROR] I2C Read Failure: {e}")
            # Wait longer on I2C error to let the bus settle
            time.sleep(POLL_INTERVAL * 3)
            continue
            
        time.sleep(POLL_INTERVAL)

    # 4. Graceful Cleanup
    client.loop_stop()
    client.disconnect()
    print("[INFO] Node shut down cleanly.")

if __name__ == "__main__":
    main()

Debugging Common Node Failures

When your node fails, it usually happens at the hardware-software boundary. Here is how to diagnose the two most common errors you will encounter when deploying a sensor node on a Raspberry Pi.

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

This is the classic I2C bus failure. The Pi's kernel attempted to clock data out, but the sensor did not acknowledge (ACK) the address.

• Cause 1 (Most Likely): Incorrect I2C Address. Adafruit breakouts default to 0x77. Generic Amazon/eBay BME280 modules almost always default to 0x76. Change the address=0x77 parameter in the code to 0x76 if using a generic board.
• Cause 2: SDA and SCL Swapped. I2C is not bidirectional on a single line. If Pin 3 and Pin 5 are reversed, the bus will hang or throw Errno 121.
• Cause 3: Missing Pull-up Resistors. If you are using a raw BME280 chip rather than a breakout board, you must add 4.7kΩ pull-up resistors from SDA and SCL to 3.3V. The Pi's internal pull-ups are too weak (~50kΩ) for reliable I2C at 400kHz.

Error 2: ConnectionRefusedError: [Errno 111] Connection refused

This occurs during the client.connect() phase. The Pi can reach the network, but the MQTT broker is rejecting the TCP handshake.

• Cause 1: Broker Service Down. Mosquitto is not running on the target IP. Check with systemctl status mosquitto on the broker machine.
• Cause 2: Port Mismatch. You are targeting port 1883 (unencrypted), but the broker is configured to only accept TLS on port 8883.
• Cause 3: Firewall Rules. UFW or iptables on the broker host is blocking inbound traffic on port 1883.

Extending and Simplifying Your Build

How to Simplify: If you only need to push temperature data every 5 minutes and don't need local processing, a Raspberry Pi 5 is overkill. Downgrade to an ESP32-C3 or a Raspberry Pi Zero 2 W. The Zero 2 W uses the same Python codebase but draws roughly 1.2W at idle compared to the Pi 5's 2.5W-3W idle state, making it vastly superior for battery-powered nodes.

How to Extend: To make this node resilient to WiFi outages, add a Waveshare SX1262 LoRaWAN HAT. This allows the Pi to bypass local infrastructure and publish sensor payloads directly to The Things Network (TTN) via RF. Alternatively, wrap the Python script in a Docker container and use systemd to ensure the node automatically restarts if the Python interpreter crashes or the Pi loses power.

Frequently Asked Questions

How much power does a headless node raspberry pi consume on battery?

A headless Raspberry Pi 5 running Raspberry Pi OS Bookworm with WiFi enabled and an I2C sensor polling every 10 seconds will idle around 2.3W to 2.8W. On a standard 10,000mAh (37Wh) USB power bank, this yields roughly 13 to 16 hours of runtime. If you need a node raspberry pi setup to run for weeks on battery, you must use a Pi Zero 2 W (which idles at ~1.2W) or implement a hardware watchdog timer to cut power to the Pi between reads.

Why is my node dropping MQTT connections after exactly 60 seconds?

This is almost always caused by an aggressive router firewall or a NAT timeout dropping idle TCP connections. In the provided code, the MQTT_KEEPALIVE variable is set to 60 seconds. This tells the Paho client to send an MQTT PINGREQ packet every 60 seconds to keep the TCP socket alive. If your router drops idle connections in under 60 seconds, lower the MQTT_KEEPALIVE value in the script to 30 or 45 seconds.

Can I use a Raspberry Pi Zero 2 W instead of the Pi 5 for this node?

Yes, the code is 100% compatible with the Pi Zero 2 W. However, the physical pinout is identical, but the power delivery requirements are different. The Zero 2 W requires a solid 5V/2.5A micro-USB or USB-C supply. Furthermore, the Zero 2 W only has single-band 2.4GHz WiFi, so ensure your IoT VLAN is not isolated to 5GHz-only access points, or the node will fail to resolve the MQTT broker's IP address.