Troubleshooting
If you find there is a “ghost in the machine” or your lamp isn’t behaving as expected, don’t panic. Electronics can be finicky, but most issues can be resolved with a bit of systematic checking.
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.
🛑 The Golden Rule of Hardware
As emphasized throughout this project, the firmware is designed to work with very specific hardware components.
❗ Support Disclaimer
I am unable to provide technical support for builds that use substituted hardware components. If you decide to go “off-book” with different screens, sensors, or controllers, you are officially the lead engineer for that version! Please don’t ask for custom firmware modifications for unsupported hardware.
A Note on the Kauf Bulb: The RGBW light bulb uses its own factory-installed firmware. If your issues are specific to the bulb’s internal software (and not how the lamp talks to it), please consult the Kauf Bulb GitHub for assistance.
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.