Skip to content

Troubleshooting ​

Start with the symptom below. Have your screen model, hardware revision, and firmware version ready; use the matching screen guide to confirm the installed firmware.

Web Configuration Changes Won't Save ​

The web editor can load a compatible hosted update independently of the display's firmware. Reload the page to pick up a published fix; reflashing is usually unnecessary for a hosted editor problem.

If saving or importing a backup fails, try opening http://YOUR-DISPLAY-IP/?espcontrol_fallback=1 to use the editor embedded in the firmware. Replace YOUR-DISPLAY-IP with the display's address. On builds with an embedded editor, this bypasses the hosted editor for that page load. Save one setting and reload to check that it persisted. Reopen the normal device address to return to the hosted editor.

The Screen Doesn't Respond to Commands ​

  • If the display shows your Home Assistant devices but nothing happens when you tap controls, such as turning lights on, Home Assistant actions probably need to be enabled for the display.
  • Follow the Enable Actions guide and make sure Allow the device to perform Home Assistant actions is turned on.

The Install Button Doesn't Detect My Device ​

  • Make sure you're using Chrome or Edge on a desktop computer. Mobile browsers and Safari/Firefox don't support the required browser feature (WebSerial).
  • Try a different USB-C cable. Charge-only cables won't work.
  • Try a different USB port on your computer.
  • On Windows, you may need to install drivers — check Device Manager for an unrecognised device.

The Display Is Stuck on the Loading Screen ​

  • Give it up to 60 seconds after first boot. It needs time to connect to WiFi and download resources.
  • If it stays on the loading screen, power-cycle it and check whether the WiFi hotspot appears. If it does, the display couldn't connect to your network — go through the WiFi setup again.
  • If you need to report the problem, collect a startup log with the USB log guide and include it in the GitHub issue.

Home Assistant Doesn't Discover the Device ​

  • Make sure the display and Home Assistant are on the same WiFi network (not a guest network or a different VLAN).
  • In Home Assistant, go to Settings > Devices & Services > Add Integration and search for ESPHome. Enter the device's IP address manually.

The Screen Shows "Home Assistant disconnected" ​

On an already configured display, this warning appears after 60 seconds with a network connection but no Home Assistant connection. It stays visible at reduced brightness instead of entering the screensaver and clears automatically when Home Assistant reconnects.

Open Settings > Devices & Services > ESPHome in Home Assistant and check the display for an encryption key or connection alert. Complete any repair prompt shown there. The warning can also appear while Home Assistant is offline; it does not specifically diagnose an incorrect key. If the network drops, the usual network reconnect screen takes over.

Home Assistant Says "Connection Requires Encryption" ​

  • Update both Home Assistant and ESPHome Device Builder to 2026.8 or newer. These versions pass a display's unique API encryption key between Home Assistant and Device Builder when the display is adopted or rebuilt.
  • If you already rebuilt the display and Home Assistant asks for a key, open its YAML in ESPHome Device Builder and use the existing api.encryption.key value in Home Assistant's reauthentication prompt. Do not generate a different key.
  • Normal OTA updates retain the key stored on the display. Erasing the whole display during a USB install can remove it and may require pairing the display with Home Assistant again.
  • See Manual Setup for more about automatic API encryption.

A P4 Panel Has Unreliable WiFi ​

  • P4 panels use a separate ESP32-C6 WiFi processor. Mismatched or outdated C6 firmware can cause repeated disconnects, failed initial setup, or a panel that disappears from Home Assistant after restarting.
  • If the panel stays reachable, check WiFi firmware updates in System > Firmware.
  • If it cannot stay connected, collect a USB startup log and open a GitHub issue with the panel model, hardware revision, and firmware version.

The Web Page Looks Broken or Unstyled ​

  • The setup page loads hosted web resources through your browser. Check that the browser can reach them, even if the panel itself is on a restricted IoT network.
  • The WiFi hotspot setup page works entirely offline. If it does not open automatically, browse to http://192.168.4.1 while connected to the hotspot.
  • Force-refresh the page or try a private window. If loading still fails, try the embedded-editor fallback.

WiFi Does Not Connect ​

  • Use 2.4 GHz WiFi, check the password, and move closer to the access point during setup.
  • If saved WiFi cannot reconnect, wait up to 90 seconds for the EspControl_XXXX setup hotspot, then repeat WiFi setup.
  • Ethernet-only custom builds have no WiFi hotspot. Check the wired connection and DHCP lease instead.
  • For repeated P4 disconnections, use the P4 WiFi checks.

Stripes, Haze, or a Halo on the Screen ​

Confirm the firmware matches the exact panel revision and use a known-good power supply and cable that meet its specifications. If the fault remains, include photos, the power setup, model, and firmware version in a report. A hardware fault may need the seller's help.

I Want to Start Over ​

  • Save a backup, then use System > Factory Reset. Partial reset keeps WiFi and the Home Assistant encryption key; Complete reset clears those saved credentials too and keeps any WiFi networks compiled into the firmware disabled, so newly provisioned credentials remain selected after reboot.
  • To complete a full reset, type RESET in the confirmation dialog. It explains that saved WiFi and the Home Assistant API key will be erased. Reconnect through the setup hotspot to save your network again.
  • Both keep installed firmware and compiled defaults. A normal reflash is not a guaranteed reset. Follow Reset the display for the full procedure and older-firmware limitations.

I Need Help With a Bug ​

  • Open a GitHub issue and describe the display model, firmware version, and what happened.
  • For startup, WiFi, loading screen, or Home Assistant connection problems, include a USB log from the Collect USB Logs guide.

Next: Setup