Updated for Bookworm Lite Legacy 64 bit with no desktop. Moved some threads out of Tkinter that may have been an issue. Found if you use wifi on channel 1, wifi will drop out and lockout. I switched my wifi channel to 11 and have very few issues. What I used: Raspberry Pi Zero2W, 3.5" 320x480 touchscreen, Pi Zero UPS Hat, BME280 humidity and temp board, esp-32S, G3MB-202P solid state relays.
Touchscreen and Webpage view.
Settings page on webpage.
Separate Heat and A/C Schedules.
Humidifier setting.
| Physical Pin | Function | Purpose |
|---|---|---|
| 36 | Fan | HVAC fan relay |
| 38 | AC | Air-conditioning relay |
| 40 | Heater | Heating relay |
| 32 | ESP32 Feedback | Feedback signal from the ESP32 |
| Physical Pin | GPIO / Function | Purpose |
|---|---|---|
| 19 | GPIO10 / MOSI | SPI display data |
| 23 | GPIO11 / SCLK | SPI clock |
| 24 | GPIO8 / CE0 | SPI chip select for display |
| 16 | GPIO23 | Display reset |
| 18 | GPIO24 | Display data/command |
| 22 | GPIO25 | Touch interrupt (if configured for this overlay) |
| Physical Pin | GPIO / Function | Purpose |
|---|---|---|
| 1 | 3.3 V | Sensor power |
| 3 | GPIO2 / SDA | I²C data |
| 5 | GPIO3 / SCL | I²C clock |
| 6 | Ground | Ground |
Bookworm(Legacy) lite 64 bit.
Install the operating system with ssh access and user as pi.
- sudo apt update then sudo apt upgrade
- sudo raspi-config enable Spi, I2C and VNC in Interface Options and Disable Screen Blanking in Display Options.
- sudo apt install git and sudo apt install -y fontconfig fonts-quicksand fonts-liberation
- cd /home/pi then git clone https://github.com/Fishrider24/PiThermOS.git
- Create a Virtual Environment to run the program in. cd /home/pi/PiThermOS then python3 -m venv --system-site-packages venv
- Upgrade pip. ./venv/bin/python -m pip install --upgrade pip
- Install Requirments. ./venv/bin/python -m pip install -r requirements.txt
- Install touchscreen drivers. sudo apt update sudo apt install xserver-xorg xinit x11-xserver-utils xinput sudo apt install xserver-xorg-video-fbdev xserver-xorg-input-evdev
- Install the custom display overlay. sudo cp ~/mpi3501-kernel-6.12-driver/mpi3501-custom.dtbo /boot/firmware/overlays/
- Edit the boot configuration sudo nano /boot/firmware/config.txt Then add dtoverlay=mpi3501-custom and comment out #dtoverlay=vc4-kms-v3d
- Create the service that runs the autostart script. sudo nano /etc/systemd/system/tft-desktop.service
- Paste the following into tft-desktop.service [Unit] Description=TFT Desktop After=network.target
[Service] Type=simple User=pi Environment=DISPLAY=:0 ExecStart=/home/pi/PiThermOS/start-tft-desktop-noxfce.sh Restart=on-failure
[Install] WantedBy=multi-user.target
-
Save the file then run the following to activate it. sudo systemctl daemon-reload sudo systemctl enable tft-desktop.service sudo systemctl start tft-desktop.service
This is currently setup to turn on/off relay on a esp32 to turn on/off whole house humidifier. mqtthum program is setup for turning on/off Heat, A/C and Fan also.
sudo apt install -y mosquitto mosquitto-clients, sudo systemctl enable mosquitto.service
To make password file, go to cd /etc/mosquitto, type sudo mosquitto_passwd -c pwfile.txt user, with user being the username you want. It will ask twice for the password you want.
Edit this file, sudo nano /etc/mosquitto/mosquitto.conf
At the bottom of the file add two lines, listener 1883 and allow_anonymous true(if not using password)
If you want a password on Mqtt, set allow_anonymous false add password_file /etc/mosquitto/pwfile.txt to mosquitto.conf
ESP32 NodeMCU-32S pins humPin = 23, heatPin =22, coolPin = 19, fanPin = 18. Heat, Cool and Fan not recommended due to router failure would stop your Furnace from working...
If no monitor is connected, you can test by connecting over VNC, opening a terminal window. For the webserver go to your pi's ip address:8080 and see the Browser window.
PiThermOS original source code is released under the MIT License.
Copyright (c) 2026 Evan Potts
See the LICENSE file for the complete license text.
PiThermOS includes and uses third-party software and source code. Third-party components remain under their respective licenses. The PiThermOS MIT License does not replace or modify the licenses of third-party components.
PiThermOS uses open-source software including:
- Python
- Flask
- gevent
- Paho MQTT Python Client
- Matplotlib
- SQLite
- smbus
Each component remains subject to its respective license.
PiThermOS includes and uses third-party software and source code. Third-party components remain under their respective licenses.
PiThermOS includes a modified version of the INA219 Python code originally provided by Waveshare as part of the Waveshare UPS-Power-Module project.
Original source: https://github.com/waveshare/UPS-Power-Module/blob/master/ups_display/ina219.py
Copyright (c) 2020 waveshare
The original Waveshare code is licensed under the MIT License. The version included in PiThermOS has been modified for integration with PiThermOS, including UPS battery monitoring and automatic shutdown functionality.
The Waveshare MIT License and copyright notice are retained for the portions derived from the original code.
Parts of the PiThermOS ESP32 MQTT code are based on the "ESP32 MQTT – Publish and Subscribe with Arduino IDE" tutorial by Rui Santos / Random Nerd Tutorials.
Original source: https://randomnerdtutorials.com/esp32-mqtt-publish-subscribe-arduino-ide/
The original code was modified substantially for use with PiThermOS, including thermostat control, MQTT topics, GPIO assignments, and other PiThermOS-specific functionality.
Original code is provided under the terms stated in the source project. The original attribution and applicable license terms are retained.