Build a Raspberry Pi Custom GUI with PyQt6 and GPIO Control

If you want to build a responsive Raspberry Pi custom GUI that actually controls hardware, skip Tkinter and Kivy. The most robust stack for 2026 is PyQt6 running on a Raspberry Pi 5 (8GB) under Pi OS Bookworm's Wayland display server. Tkinter looks like a Windows 95 app on modern touchscreens, and Kivy carries too much overhead for simple dashboards. PyQt6 gives you hardware-accelerated rendering, native touch support, and a clean event loop that won't block your GPIO polling.

But building a GUI on the Pi 5 isn't just copy-pasting old tutorials. The shift to the BCM2712 chip and the Wayland display server means older X11 and RPi.GPIO scripts will crash immediately. Below is the exact hardware spec, pin mapping, and production-ready code to get your dashboard running without bricking your SD card with deprecated libraries.

Hardware Spec Sheet & Pin Mapping

Before writing a single line of Python, lock in your hardware. The Pi 5 uses a different power delivery and GPIO architecture than the Pi 4. Ensure your relay module is opto-isolated and rated for 3.3V logic triggers, as the Pi 5 GPIO pins are strictly 3.3V and will be destroyed by 5V backfeed.

Parts List & Assembly Steps

Here is the exact bill of materials (BOM) and the physical assembly sequence. Total cost is roughly $165 USD at current 2026 retail pricing.

• 1x Raspberry Pi 5 8GB ($80)
• 1x Raspberry Pi 27W USB-C Power Supply ($12)
• 1x Raspberry Pi 7-inch Touchscreen Display V2 ($60)
• 1x Adafruit BME280 I2C Sensor Breakout ($15)
• 1x 4-Channel 5V Relay Module with Optocoupler ($8)
• Jumper wires (Female-to-Female for I2C, Male-to-Female for Relays)

Assembly Sequence:

1. Mount the Pi 5 to the back of the 7" Touchscreen V2 using the provided brass standoffs. Ensure the DSI ribbon cable is seated fully and the latch is pushed down flush.
2. Wire the BME280 to the Pi's I2C bus: VIN to Pin 1 (3.3V), GND to Pin 6, SDA to Pin 3, SCL to Pin 5.
3. Wire the Relay Module: VCC to Pin 2 (5V), GND to Pin 9. Wire IN1 to GPIO 17 (Pin 11), IN2 to GPIO 27 (Pin 13).
4. Flash Pi OS Bookworm (64-bit) using Raspberry Pi Imager. In the OS Customization menu, enable SSH and set your username.
5. Boot the Pi, open a terminal, and run sudo raspi-config. Navigate to Interface Options and ensure I2C is enabled.

The Python Code: PyQt6 GUI with GPIO Control

This script targets the Raspberry Pi 5 (8GB). It uses gpiozero with the mandatory lgpio pin factory (required for the Pi 5's BCM2712 chip) and forces the PyQt6 backend to use Wayland.

First, install the dependencies via terminal:

sudo apt update
sudo apt install python3-pyqt6 python3-gpiozero python3-lgpio i2c-tools
pip3 install smbus2 --break-system-packages

Save the following code as dashboard.py:

import sys
import os
import time

# CRITICAL: Force lgpio for Pi 5 BCM2712 chip and Wayland for Bookworm
os.environ['GPIOZERO_PIN_FACTORY'] = 'lgpio'
os.environ['QT_QPA_PLATFORM'] = 'wayland'

from PyQt6.QtWidgets import (QApplication, QWidget, QVBoxLayout, 
                             QHBoxLayout, QPushButton, QLabel, QGridLayout)
from PyQt6.QtCore import QTimer, Qt
from PyQt6.QtGui import QFont
from gpiozero import OutputDevice
from smbus2 import SMBus

# --- PIN & I2C DEFINITIONS ---
RELAY_1_PIN = 17  # Physical Pin 11
RELAY_2_PIN = 27  # Physical Pin 13
BME280_I2C_ADDR = 0x77
I2C_BUS = 1

class BME280Sensor:
    def __init__(self):
        try:
            self.bus = SMBus(I2C_BUS)
            # Basic initialization check (read chip ID register 0xD0)
            chip_id = self.bus.read_byte_data(BME280_I2C_ADDR, 0xD0)
            if chip_id != 0x60:
                raise ValueError("Invalid Chip ID")
            self.available = True
        except Exception as e:
            print(f"[WARNING] BME280 Sensor not found: {e}")
            self.available = False

    def read_temp_c(self):
        if not self.available:
            return -99.0
        try:
            # Simplified read for demonstration; production needs full compensation math
            data = self.bus.read_i2c_block_data(BME280_I2C_ADDR, 0xFA, 3)
            raw_temp = (data[0] << 12) | (data[1] << 4) | (data[2] >> 4)
            # Placeholder compensation formula (use adafruit-circuitpython-bme280 for real apps)
            return round((raw_temp / 16384.0) - 25.0, 1) 
        except Exception:
            return -99.0

class PiDashboard(QWidget):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("Pi 5 Control Dashboard")
        self.resize(800, 480) # Match 7" Touchscreen resolution
        
        # Hardware Init
        self.relay1 = OutputDevice(RELAY_1_PIN, active_high=False)
        self.relay2 = OutputDevice(RELAY_2_PIN, active_high=False)
        self.sensor = BME280Sensor()
        
        self.init_ui()
        
        # Polling Timer (Prevents GUI freeze)
        self.timer = QTimer(self)
        self.timer.timeout.connect(self.update_sensors)
        self.timer.start(2000) # Update every 2 seconds

    def init_ui(self):
        layout = QVBoxLayout()
        
        # Header
        title = QLabel("Environment & Relay Control")
        title.setFont(QFont("Arial", 24, QFont.Weight.Bold))
        title.setAlignment(Qt.AlignmentFlag.AlignCenter)
        layout.addWidget(title)
        
        # Sensor Display
        self.temp_label = QLabel("Temp: -- °C")
        self.temp_label.setFont(QFont("Arial", 36))
        self.temp_label.setAlignment(Qt.AlignmentFlag.AlignCenter)
        self.temp_label.setStyleSheet("color: #2196F3;")
        layout.addWidget(self.temp_label)
        
        # Control Grid
        grid = QGridLayout()
        
        self.btn_r1 = QPushButton("Toggle Relay 1 (Lights)")
        self.btn_r1.setFont(QFont("Arial", 18))
        self.btn_r1.setMinimumHeight(100)
        self.btn_r1.setCheckable(True)
        self.btn_r1.clicked.connect(self.toggle_relay1)
        grid.addWidget(self.btn_r1, 0, 0)
        
        self.btn_r2 = QPushButton("Toggle Relay 2 (Fan)")
        self.btn_r2.setFont(QFont("Arial", 18))
        self.btn_r2.setMinimumHeight(100)
        self.btn_r2.setCheckable(True)
        self.btn_r2.clicked.connect(self.toggle_relay2)
        grid.addWidget(self.btn_r2, 0, 1)
        
        layout.addLayout(grid)
        self.setLayout(layout)

    def toggle_relay1(self):
        if self.btn_r1.isChecked():
            self.relay1.on()
            self.btn_r1.setStyleSheet("background-color: #4CAF50; color: white;")
        else:
            self.relay1.off()
            self.btn_r1.setStyleSheet("")

    def toggle_relay2(self):
        if self.btn_r2.isChecked():
            self.relay2.on()
            self.btn_r2.setStyleSheet("background-color: #4CAF50; color: white;")
        else:
            self.relay2.off()
            self.btn_r2.setStyleSheet("")

    def update_sensors(self):
        temp = self.sensor.read_temp_c()
        if temp != -99.0:
            self.temp_label.setText(f"Temp: {temp} °C")
        else:
            self.temp_label.setText("Sensor Offline")
            self.temp_label.setStyleSheet("color: #F44336;")

    def closeEvent(self, event):
        # Safe GPIO cleanup on exit
        self.relay1.close()
        self.relay2.close()
        event.accept()

if __name__ == '__main__':
    app = QApplication(sys.argv)
    dashboard = PiDashboard()
    dashboard.show()
    sys.exit(app.exec())

Debugging: Exact Error Strings & Ranked Causes

When building a Raspberry Pi custom GUI, you will inevitably hit display server or pin factory errors. Here are the exact error strings you will see in the terminal, and the first three things to check when it fails.

Error 1: qt.qpa.xcb: could not connect to display

Ranked Causes:

1. Wayland vs X11 Mismatch: Pi OS Bookworm defaults to Wayland. PyQt6 tries to use the XCB (X11) plugin by default. Fix: Run export QT_QPA_PLATFORM=wayland before launching, or use the os.environ override included in the script above.
2. Headless Execution: You are SSH'd into the Pi and trying to run the GUI without X11 forwarding. Fix: Run the script directly on the Pi's terminal, or use ssh -X (though Wayland forwarding requires complex setup; stick to local execution for touchscreens).
3. Missing Qt Packages: You installed PyQt6 via pip instead of apt, missing the underlying Wayland C++ bindings. Fix: Use sudo apt install python3-pyqt6.

Error 2: gpiozero.exc.PinFactoryFallback: Falling back to lgpio... RuntimeError: Failed to initialize GPIO

Ranked Causes:

1. Missing lgpio Daemon/Library: The Pi 5's BCM2712 chip is not supported by the legacy RPi.GPIO library. Fix: Install the C library and Python bindings via sudo apt install python3-lgpio.
2. Permissions Issue: Your user is not in the gpio group. Fix: Run sudo usermod -aG gpio $USER and reboot.
3. Pin Conflict: The touchscreen I2C or DSI pins are conflicting with your chosen GPIO pins. Fix: Stick to the pin mapping table provided above; avoid pins 0, 1, 2, 3, and 4 on the Pi 5 when using the official display.

Extending and Simplifying the Build

Depending on your end goal, you might need to scale this architecture up for a commercial kiosk or down for a low-cost hobby project.

How to Simplify (For Pi Zero 2 W or Low RAM)

If you are migrating this project to a Raspberry Pi Zero 2 W (512MB RAM), PyQt6 will consume nearly 40% of your available RAM just to render the window manager.
The Fix: Strip out PyQt6 and use Tkinter (built into Python, zero extra dependencies). Disable the desktop environment entirely via raspi-config (Boot to Console), and launch your Tkinter script directly against the framebuffer using startx. Drop the BME280 polling to once every 10 seconds to prevent I2C bus locking on the Zero's slower CPU.

How to Extend (For Home Automation Integration)

A standalone screen is useful, but integrating it into a smart home makes it powerful.
The Fix: Add the paho-mqtt library. Create a secondary background thread (using Python's threading module, never block the PyQt6 main thread) that publishes the BME280 temperature data to an MQTT broker like Mosquitto.
You can then map the PyQt6 buttons to publish MQTT payloads (e.g., homeassistant/switch/lights/set), allowing your physical touchscreen to act as a master override for your Home Assistant automations. For the MQTT implementation, refer to the Eclipse Paho Python documentation for proper QoS 1 message handling to ensure your relay commands never drop on a flaky Wi-Fi connection.

Building a robust interface on the Pi 5 requires respecting the new hardware boundaries. By anchoring your stack to lgpio and Wayland, your custom GUI will remain stable through OS updates and reboots, giving you a professional-grade control panel right on your workbench.