Mastering Wi-Fi on Raspberry Pi 5: Configuration, Debugging, and MQTT IoT Build

Getting reliable Wi-Fi on Raspberry Pi 5 requires shifting away from legacy configuration methods. If you are running Raspberry Pi OS Bookworm (the current standard for 2026), the underlying network stack has moved from dhcpcd and direct wpa_supplicant management to NetworkManager. Attempting to edit /etc/wpa_supplicant/wpa_supplicant.conf on a modern Bookworm install will result in silent failures or overwritten configurations. The direct, correct method to configure Wi-Fi on Raspberry Pi 5 is via the nmcli command-line tool.

This guide provides a hardware-level breakdown of the Pi's Wi-Fi capabilities, a complete sensor-to-MQTT build, and a debugging matrix for the exact RF and handshake errors you will encounter on the bench.

Raspberry Pi Wi-Fi Hardware & RF Specifications

Before debugging software, you must understand the physical layer. The Raspberry Pi 5 uses the same core Infineon silicon as the Pi 4, but with improved PCB trace routing and a dedicated power delivery network that reduces RF brownouts. Below is the data-dense specification matrix for current Pi variants.

IoT Build: Parts List & Hardware Pin Mapping

We are building a headless environmental monitor that reads sensor data and publishes it over Wi-Fi via MQTT. This build targets the Raspberry Pi 5 (8GB) running Raspberry Pi OS Bookworm (64-bit, Lite).

Parts List

• MCU: Raspberry Pi 5 (8GB variant)
• Sensor: Adafruit BME280 I2C Breakout (Product ID: 2652)
• Power: Official Raspberry Pi 27W USB-C PD Power Supply
• Wiring: 4-pin JST-SH to female jumper wires
• Software: Python 3.11+, paho-mqtt v2.0, adafruit-circuitpython-bme280

Hardware Pin Mapping (I2C Bus 1)

The BME280 communicates via I2C. On the Pi 5, the default I2C bus is exposed on the 40-pin GPIO header. Ensure your BME280 breakout has the I2C pull-up resistors populated (most Adafruit/SparkFun boards do).

Step-by-Step Wi-Fi Configuration via NetworkManager

With Bookworm, nmcli is your primary tool. Do not install wicd or attempt to mask NetworkManager.

1. Scan for available networks:
   sudo nmcli device wifi list
   Look for your SSID and note the CHANNEL and SIGNAL strength. If your 2.4GHz network is on channel 6 with a signal below -70 dBm, expect MQTT TLS handshake timeouts.
2. Connect to the Wi-Fi network:
   sudo nmcli device wifi connect 'Your_SSID_Name' password 'Your_WPA_Password' ifname wlan0
   This automatically creates a persistent connection profile in /etc/NetworkManager/system-connections/.
3. Set the connection to auto-connect on boot:
   sudo nmcli connection modify 'Your_SSID_Name' connection.autoconnect yes
4. Verify the IP assignment and routing:
   ip -4 addr show wlan0
ip route show default

Debugging Wi-Fi Failures: Exact Errors & Fixes

When Wi-Fi on Raspberry Pi fails, the OS logs the exact reason. Use journalctl -u NetworkManager -f to tail the live logs. Here are the first three things to check when a connection drops, followed by the exact error strings you will see.

The First 3 Things to Check

1. Physical Layer (RSSI & Interference): Run iwconfig wlan0. If the Link Quality is below 40/70 or Signal level is worse than -75 dBm, the Pi's PCB antenna is being detuned by a metal enclosure or USB 3.0 interference. Move the Pi or switch to 5GHz.
2. WPA3-SAE Transition Mode: Modern routers use WPA3-SAE. The CYW43455 supports WPA3, but older wpa_supplicant configs often fail the SAE handshake. NetworkManager handles this natively, but ensure your router isn't forcing a pure WPA3 mode if your Pi is running a legacy OS.
3. Power Supply Brownouts: Check dmesg | grep -i voltage. If you see 'Under-voltage detected!', the Wi-Fi chip is resetting during TX bursts. Upgrade to a 27W PD supply.

Exact Error Strings & Ranked Causes

Complete Python MQTT Sensor Script

This script reads the BME280 via I2C and publishes the data to an MQTT broker over the Wi-Fi connection. It uses the Paho MQTT v2.0 API (standard for 2026) and includes robust error handling for both the I2C bus and the network socket.

Prerequisites: sudo apt install python3-pip i2c-tools followed by pip3 install paho-mqtt adafruit-circuitpython-bme280

import time
import json
import board
import busio
import adafruit_bme280
import paho.mqtt.client as mqtt
from paho.mqtt.enums import CallbackAPIVersion

# --- Hardware & Network Configuration ---
I2C_ADDRESS = 0x76  # BME280 default (0x77 if CSB pin is tied high)
MQTT_BROKER = '192.168.1.100'
MQTT_PORT = 1883
MQTT_TOPIC = 'pi5/environmental/node_01'
CLIENT_ID = 'RaspberryPi5_BME280'

# --- Callback Definitions (Paho v2.0 API) ---
def on_connect(client, userdata, flags, reason_code, properties):
    if reason_code == 0:
        print(f'[MQTT] Connected to broker {MQTT_BROKER}')
    else:
        print(f'[MQTT] Connection failed with reason code: {reason_code}')

def on_publish(client, userdata, mid, reason_code, properties):
    print(f'[MQTT] Message {mid} published successfully.')

# --- Initialization ---
def init_sensor():
    try:
        i2c = busio.I2C(board.SCL, board.SDA)
        sensor = adafruit_bme280.Adafruit_BME280_I2C(i2c, address=I2C_ADDRESS)
        sensor.sea_level_pressure = 1013.25
        print('[I2C] BME280 initialized successfully.')
        return sensor
    except ValueError as e:
        print(f'[I2C ERROR] Failed to find BME280 at 0x{I2C_ADDRESS:02X}. Check wiring. Details: {e}')
        return None

def init_mqtt():
    # Using CallbackAPIVersion.VERSION2 for Paho MQTT 2.0+ compatibility
    client = mqtt.Client(CallbackAPIVersion.VERSION2, client_id=CLIENT_ID)
    client.on_connect = on_connect
    client.on_publish = on_publish
    
    try:
        client.connect(MQTT_BROKER, MQTT_PORT, keepalive=60)
        client.loop_start()  # Non-blocking network loop
        return client
    except Exception as e:
        print(f'[MQTT ERROR] Could not connect to {MQTT_BROKER}. Is Wi-Fi up? Details: {e}')
        return None

# --- Main Execution Loop ---
if __name__ == '__main__':
    sensor = init_sensor()
    mqtt_client = init_mqtt()

    if not sensor or not mqtt_client:
        print('[FATAL] Hardware or Network initialization failed. Exiting.')
        exit(1)

    print('[SYSTEM] Starting telemetry loop. Press Ctrl+C to stop.')
    try:
        while True:
            payload = {
                'temperature_c': round(sensor.temperature, 2),
                'humidity_pct': round(sensor.humidity, 2),
                'pressure_hpa': round(sensor.pressure, 2),
                'altitude_m': round(sensor.altitude, 2),
                'timestamp': time.time()
            }
            
            json_data = json.dumps(payload)
            result = mqtt_client.publish(MQTT_TOPIC, json_data, qos=1)
            
            # Check if the message was queued successfully
            if result.rc != mqtt.MQTT_ERR_SUCCESS:
                print(f'[MQTT WARN] Publish failed to queue. RC: {result.rc}')
            
            time.sleep(10) # 10-second telemetry interval
            
    except KeyboardInterrupt:
        print('\n[SYSTEM] Shutting down gracefully.')
        mqtt_client.loop_stop()
        mqtt_client.disconnect()

Extending and Simplifying the Build

Once your Wi-Fi on Raspberry Pi 5 is stable and the MQTT script is running as a systemd service, you have two distinct paths for scaling the project.

How to Extend (Scale Up)

• Add TLS Encryption: Wi-Fi encrypts the local link, but MQTT traffic is plaintext by default. Extend the Python script to use client.tls_set() with Let's Encrypt certificates to secure the payload across the internet.
• Implement Home Assistant Discovery: Instead of raw JSON topics, format your MQTT payloads to match the Home Assistant MQTT Discovery schema. This allows the Pi to automatically register as a climate entity in your smart home dashboard without manual YAML configuration.
• External Antenna Mod: If deploying in a metal enclosure, purchase a u.FL to SMA pigtail. You must carefully desolder the 0-ohm resistor at R142 on the Pi 5 PCB to route the RF signal to the external u.FL connector instead of the PCB trace.

How to Simplify (Scale Down)

• Switch to ESP32 for Pure Sensor Nodes: The Pi 5 is overkill if you only need to read I2C and push MQTT. If your processing needs are minimal, migrate this exact logic to an ESP32-C3 or ESP32-S3. An ESP32 draws ~80mA during Wi-Fi TX, whereas the Pi 5 idles at ~2.5A. For battery-powered or dense sensor deployments, the ESP32 is the correct tool.
• Use Telegraf instead of Python: If you want to eliminate custom Python scripts entirely, install telegraf via apt. Telegraf has a native [[inputs.i2c]] plugin and an [[outputs.mqtt]] plugin, allowing you to configure the entire pipeline via a simple TOML file.

For further reading on the underlying NetworkManager architecture in Bookworm, refer to the official Raspberry Pi NetworkManager documentation. For deep-dive RF characteristics of the chipset, consult the Infineon CYW43455 Datasheet.