Troubleshooting
If you find there is a “ghost in the machine” or your system isn’t behaving as expected, don’t panic. Electronics can be finicky, but most issues can be resolved with a bit of systematic checking.
🔍 Living Document
This troubleshooting topic will be updated if common issues/workarounds are discovered over time. If you develop a problem or issue after you’ve been using the system for a while, be sure to check this topic again, as it may have been updated with new information
Before diving into the specific fixes below, first verify that you have reviewed the applicable sections throughout this document and the Build Guide to ensure a step wasn’t missed during the assembly or configuration process. In addition, you can often find helpful information or potential problems/fixes in the following areas of the repository:
🛑 The Golden Rule of Hardware
As emphasized throughout this project, the firmware is designed to work with specific hardware components.
❗ Support Disclaimer
I am unable to provide technical support for builds that use substituted hardware components or modified firmware. If you decide to go “off-book” with different functions, sensors, or controllers, you are officially the lead engineer for that version! Please don’t ask for support when using custom firmware modifications or unsupported hardware.
Triage: Where is the problem?
To help you find a solution without scrolling through pages of unrelated text, the troubleshooting guide is broken down into the following categories:
- Initial Setup & Connectivity – Issues with COM ports, USB drivers, flashing errors, and the initial onboarding hotspot.
- Daily Operation & Configuration – Problems with “Save & Reboot” persistence, firmware update failures, and reviewing Config Dumps.
- Home Assistant & MQTT – Discovery issues, “stuck” MQTT topics, and integration prerequisites.
- FAQ & Getting Help – Frequently Asked Questions and the proper etiquette for opening a GitHub Issue or starting a Discussion.