Installing Home Assistant on Raspberry Pi 5: GPIO Integration & Debugging

Installing Home Assistant on Raspberry Pi hardware remains the most popular entry point for local smart home control in 2026. However, the transition to the Raspberry Pi 5 and its new RP1 southbridge chip has fundamentally changed how we handle physical GPIO integrations. If you install the standard Home Assistant OS (HAOS), the host OS is locked down, making custom Python GPIO scripts impossible without complex container mapping. To bridge the gap between physical workbench sensors and your dashboard, this guide targets Raspberry Pi OS (64-bit) running Home Assistant as a Docker container. This gives you full, native access to the Pi 5’s GPIO headers for direct sensor integration.

Hardware Selection: Pi 5 vs Alternatives for Home Assistant

Before flashing an SD card, you need to select the right single-board computer (SBC). The Pi 5’s PCIe interface and RP1 chip offer massive I/O improvements over the Pi 4, but it requires specific power and thermal management. Below is a data-dense comparison of the most viable boards for a Home Assistant build this year.

Parts List & GPIO Pin Mapping

For this build, we are integrating a waterproof DS18B20 1-Wire temperature sensor (ideal for monitoring a water heater or outdoor ambient temp) and a 5V relay module to control a local 12V DC fan or pump.

Bill of Materials:

• Raspberry Pi 5 (8GB variant)
• Official Raspberry Pi 27W USB-C PD Power Supply
• Raspberry Pi Active Cooler (PWM fan + heatsink)
• 64GB MicroSD Card (Must be Application Class A2 rated for database write endurance)
• DS18B20 Waterproof Temperature Sensor
• 4.7kΩ Pull-up Resistor
• 5V Single-Channel Relay Module (Opto-isolated)

Because the Pi 5 uses the RP1 southbridge chip, the physical pin numbers remain identical to the Pi 4, but the underlying software addressing has changed. Here is the exact pin mapping for this project:

Step-by-Step: Installing Home Assistant on Raspberry Pi 5

We are installing Home Assistant Container. This method provides the core Home Assistant experience while leaving the host Raspberry Pi OS accessible for our Python sensor scripts.

1. Flash the OS: Download Raspberry Pi Imager. Select Raspberry Pi 5 as the device, Raspberry Pi OS (64-bit) Lite as the OS (no desktop environment needed), and your A2 microSD card as storage.
2. Pre-configure Network: In the Imager’s advanced settings (Ctrl+Shift+X), set your hostname to homeassistant, enable SSH, and input your WiFi credentials or note your Ethernet setup.
3. Boot and Update: Insert the SD card, apply power, and SSH into the Pi. Run sudo apt update && sudo apt upgrade -y.
4. Enable 1-Wire Interface: Run sudo raspi-config, navigate to Interface Options -> 1-Wire, and enable it. Reboot the Pi.
5. Install Docker: Run the official convenience script:
   curl -fsSL https://get.docker.com -o get-docker.sh && sudo sh get-docker.sh
6. Pull Home Assistant: Create a directory for your config and launch the container using the official Home Assistant installation documentation for Docker:

   mkdir -p /home/pi/homeassistant/config
   sudo docker run -d \
     --name homeassistant \
     --restart=unless-stopped \
     --privileged \
     --network=host \
     -v /home/pi/homeassistant/config:/config \
     ghcr.io/home-assistant/home-assistant:stable

7. Access the UI: Open a browser and navigate to http://homeassistant.local:8123. The first boot will take 5-10 minutes to compile dependencies.

Python MQTT Sensor Integration

With Home Assistant running, we need to read the DS18B20 sensor and control the relay. We will use a local MQTT broker (install Mosquitto via sudo apt install mosquitto mosquitto-clients) to bridge the Python script and Home Assistant.

Target Board: Raspberry Pi 5 (8GB) running Pi OS 64-bit.
Dependencies: Install the modern GPIO library and sensor tools via pip3 install gpiozero w1thermsensor paho-mqtt rpi-lgpio.

#!/usr/bin/env python3
"""
Home Assistant GPIO Bridge for Raspberry Pi 5
Reads DS18B20 temp and controls a relay via MQTT.
"""
import time
import paho.mqtt.client as mqtt
from w1thermsensor import W1ThermSensor
from gpiozero import OutputDevice
import signal
import sys

# --- PIN DEFINITIONS & CONFIG ---
RELAY_PIN = 17  # Physical Pin 11, BCM GPIO 17
MQTT_BROKER = "127.0.0.1"
MQTT_PORT = 1883
MQTT_TOPIC_TEMP = "homeassistant/sensor/workbench/temp"
MQTT_TOPIC_RELAY = "homeassistant/switch/workbench/relay/set"

# Initialize Hardware
# Note: gpiozero automatically uses rpi-lgpio backend on Pi 5
relay = OutputDevice(RELAY_PIN, active_high=False, initial_value=False)
sensor = W1ThermSensor()

def on_connect(client, userdata, flags, rc, properties=None):
    if rc == 0:
        print("Connected to MQTT Broker")
        client.subscribe(MQTT_TOPIC_RELAY)
    else:
        print(f"MQTT Connection failed with code {rc}")

def on_message(client, userdata, msg):
    payload = msg.payload.decode()
    if payload == "ON":
        relay.on()
        print("Relay Engaged")
    elif payload == "OFF":
        relay.off()
        print("Relay Disengaged")

def graceful_exit(sig, frame):
    print("\nShutting down safely...")
    relay.off()
    client.disconnect()
    sys.exit(0)

signal.signal(signal.SIGINT, graceful_exit)

# MQTT Setup
client = mqtt.Client(mqtt.CallbackAPIVersion.VERSION2)
client.on_connect = on_connect
client.on_message = on_message

try:
    client.connect(MQTT_BROKER, MQTT_PORT, 60)
    client.loop_start()
except Exception as e:
    print(f"Fatal MQTT Error: {e}")
    sys.exit(1)

# Main Loop
while True:
    try:
        temp_c = sensor.get_temperature()
        client.publish(MQTT_TOPIC_TEMP, f"{temp_c:.2f}")
        print(f"Published Temp: {temp_c:.2f}C")
        time.sleep(10)
    except Exception as e:
        print(f"Sensor read error: {e}")
        time.sleep(5)

Debugging: Fixing `RuntimeError: Cannot determine SoC type`

If you copy legacy Python scripts from a Pi 4 to a Pi 5, your script will immediately crash. The exact error string you will see in the terminal is:

RuntimeError: Cannot determine SoC type

This happens because the legacy RPi.GPIO library looks for the BCM2711 chip in the /proc/cpuinfo file, but the Pi 5 uses the new RP1 southbridge architecture.

Ranked Causes & Fixes:

1. Using Legacy Libraries (Most Likely): You imported RPi.GPIO. Fix: Uninstall it (pip3 uninstall RPi.GPIO) and refactor your code to use gpiozero, which natively supports the Pi 5 via the rpi-lgpio backend.
2. Outdated Python Environment: Your virtual environment is caching old dependencies. Fix: Delete the venv folder, recreate it, and install rpi-lgpio explicitly.
3. 1-Wire Kernel Module Not Loaded: If the DS18B20 throws a SensorNotReadyError, the 1-Wire overlay failed to load. Fix: Run sudo dtoverlay w1-gpio in the terminal and verify lsmod | grep w1 returns active modules.

Extending and Simplifying Your Build

Once you have the baseline Raspberry Pi configuration and Python script running, you will inevitably want to scale your smart home. Here is how to pivot based on your reliability needs.

How to Simplify (The ESPHome Route):
Running Python scripts on the main Home Assistant host is fragile; a bad script update can crash your GPIO bus. To simplify, move the physical sensors off the Pi entirely. Buy an ESP32-WROOM-32 DevKit v1 ($6 USD) and flash it with ESPHome. ESPHome handles the WiFi-to-MQTT bridge, deep sleep, and sensor polling natively, and integrates directly into Home Assistant via the native API without requiring a local MQTT broker.

How to Extend (The Zigbee Route):
WiFi sensors drain batteries and congest your router. To extend this build into a whole-home mesh network, purchase the Sonoff Zigbee 3.0 USB Dongle Plus (P-Version). Plug it into the Pi 5’s USB 2.0 port (using a 1-meter USB extension cable to avoid 2.4GHz WiFi interference from the Pi’s board). Install the Zigbee2MQTT add-on in Home Assistant. This allows you to bypass custom Python scripts entirely and connect hundreds of low-power Aqara, IKEA, and Sonoff sensors directly to your dashboard.