Troubleshooting
Find your problem in the list. Most things have a simple cause.
The web interface does not load
The browser shows "Not Found" or an empty page.
The web interface was not written to the ESP32. Do Step 2 of Install the firmware (Upload Filesystem Image, or pio run -t uploadfs).
hyperled.local is not found.
- On Windows use http://hyperled (without .local).
- Your phone or computer must be in the same network as the ESP32. A guest network or "client isolation" in your router blocks it.
- Look up the IP address of "hyperled" in your router and open http://<that address>.
- Does it not appear in the router at all? Then it is not connected to your Wi-Fi: see the next point.
I cannot connect it to my Wi-Fi.
- Use a 2.4 GHz network; 5 GHz is not supported.
- Check the password (letters in upper and lower case).
- If the ESP32 cannot join your Wi-Fi, it offers its own network HyperLED-AP again. Connect to it, open http://192.168.4.1 and enter the data again.
The LEDs do nothing
- Nothing lights up at all: Are strip and power supply connected, and is the ground of the ESP32 connected to the ground of the power supply? Is the data wire at DIN (the end with the arrow pointing away from it), and the pin the same as in Devices → LED hardware (default GPIO 4)?
- Is the segment switched on and the brightness above 0? Look at the Light page: select the segment and press its power button.
- Only the first LEDs light up, or too many: check the LED Count in Devices → LED hardware.
- Colours are wrong: pick the LED type that matches your strip.
The LEDs flicker or show random pixels
This is almost always the data signal or the power:
- Connect ground of the power supply and the ESP32.
- Add the 330 Ω resistor in the data line and keep the wire short.
- Add the capacitor (1000 µF) across the strip's power input.
- Use a level shifter (74AHCT125) from 3.3 V to 5 V.
- Feed the strip with a power supply that is strong enough, and from both ends for long strips.
If the strip and the ESP32 run from the same weak USB port, give the strip its own supply.
See Wiring and power.
The LEDs are dimmer than expected
HyperLED's Automatic Brightness Limiter lowers the brightness so your supply is not overloaded. Check Max Power Supply Current (mA) in Devices → LED hardware → Power supply. If your supply can deliver more, raise the value. Never set it higher than the supply and wires can take.
Colours at the end of a long strip are reddish or dim
That is voltage drop. Feed the power in at both ends (or in the middle) with thick wires.
A panel flickers or shows ghost images
Change the Driver chip in Devices → Connected devices for that device ("change if you see ghosting/flicker"). If the panel does not start, it may need more memory than the board has: choose a smaller panel.
A Slave is not found
- Does the Slave have power, and does it run the Slave firmware?
- Press Search for devices in Devices → Connected devices.
- Wired: TX of the Master goes to RX of the Slave (Master GPIO 17 → Slave GPIO 16), and the grounds must be connected.
- Wireless: Master and Slave must be close enough for the radio; the Slave finds the channel itself after a few seconds.
Home Assistant does not show HyperLED
- Open Settings → Wi-Fi & MQTT. Above the fields HyperLED says whether it is connected and why not.
- Press Test connection. Check the IP address, port, user and password.
- Press Announce to Home Assistant again.
- Is the MQTT integration set up in Home Assistant, and does the broker accept the user?
An update does not work
- Check the internet connection (Settings → System, Check for Update).
- If the update is refused because the firmware no longer fits into the update slot, flash the current version once over USB, see Updates, backup and reset.
A plugin does not work
Open the plugin's Live values (Settings → Plugins). They show the state and the reason, the values read and the beginning of the answer. Typical causes: a wrong address, the device is switched off, or another plugin already uses the segment.
Schedules do not run
The controller needs the time from the internet. Check Scenes → Schedules: the page shows the device time or tells you that it is not synchronised. Also check the Timezone.
Start fresh
- A backup saves everything first (Settings → System → Backup).
- Reset to factory settings erases all settings, see Updates, backup and reset.
Still stuck?
Open an issue and describe what you did and what you see. It helps to say which version you run (Settings → System), and which LEDs and board you use.
If you can connect a computer: the controller keeps the last minute of its log in memory. Open http://hyperled.local/api/log in a browser for the running controller, or http://hyperled.local/api/lastlog for the minute before the last crash or unexpected restart. Add it to your issue.