What you need
For a first setup with one LED strip you need very little. This page lists the parts, explains how to choose them, and how to work out the power supply.
The shopping list
| Part | What to look for | Why |
|---|---|---|
| Controller board | An ESP32-S3 with at least 4 MB flash. HyperLED is developed and tested on the Waveshare ESP32-S3-Zero (4 MB flash, 2 MB PSRAM). | This is the "brain". It runs HyperLED and its web interface. |
| LED strip | WS2812B, 5 V, individually addressable ("NeoPixel") is the easy start. Also fine: WS2813, WS2815 (12 V). | The lights. Many other types work too, see the full list below. |
| Power supply | The right voltage for your strip (5 V for WS2812B) and enough current (see below). | The LEDs need far more power than the ESP32 can give. |
| USB cable | A data cable (not "charge only"), matching your board. | To flash the firmware once. |
| Resistor | About 330 Ω (anything from 220 to 470 Ω is fine). | Protects the data pin. |
| Capacitor | 1000 µF, at least 6.3 V (use 10 V or 16 V if you like). Mind the polarity. | Absorbs the current spike when the strip switches on. |
| Wires | Thick enough for the current (the 5 V and GND wires carry the LED current). | |
| (optional) Level shifter | 74AHCT125, from 3.3 V to 5 V. | Only if the strip flickers; see Wiring and power. |
You also need a computer (Windows, macOS or Linux) for the first installation, and a 2.4 GHz Wi-Fi network. After that, a phone is enough for everything.
Tip: Buy a strip with a few more LEDs than you think you need - you can always set a lower LED count in HyperLED.
Which ESP32?
HyperLED is built for the ESP32-S3 and mostly tested on it. The Slave also runs on the ESP32-C6 (for example the ESP32-C6 Super Mini); that is new and still being tested, see Several devices. Other ESP32 chips could work in theory, but need changes in the code. If you want to know more, read Hardware setup in the repository. The requirements in short:
- Wi-Fi (2.4 GHz) and ESP-NOW
- at least 4 MB flash (two update slots plus a file system)
- enough RAM for the web server, encryption and radio at the same time
- for HUB75 panels: a chip that the panel library supports
Which LEDs?
You choose the type in the web interface under Devices → LED hardware → LED type (see First light). WS2812B (the "WS281x" entry) is the usual choice and the best one to start with: it is the type that has been tested on real hardware. HyperLED supports many more. This is the complete list, in the order of the drop-down list.
Digital LEDs (1-Wire): one data wire
| Entry in the list | Typical strips | Status |
|---|---|---|
| WS281x | WS2812B, WS2813, WS2815 (12 V), WS2811 and clones; RGB | ✅ tested |
| SK6812/WS2814 RGBW | strips with an extra white LED | ⚠️ not yet tested on hardware |
| TM1814 | RGBW strips | ⚠️ not yet tested on hardware |
| 400kHz | older strips with 400 kHz timing | ⚠️ not yet tested on hardware |
| TM1829 | RGB | ⚠️ not yet tested on hardware |
| UCS8903 | RGB | ⚠️ not yet tested on hardware |
| APA106/PL9823 | RGB pixel LEDs | ⚠️ not yet tested on hardware |
| TM1914 | RGB | ⚠️ not yet tested on hardware |
| FW1906 GRBCW | RGB plus cold and warm white | ⚠️ not yet tested on hardware |
| UCS8904 RGBW | RGBW | ⚠️ not yet tested on hardware |
| SM16825 RGBCW | RGB plus cold and warm white | ⚠️ not yet tested on hardware |
| WS2811 White | single-colour white strips | ⚠️ not yet tested on hardware |
| WS281x WWA | white strips with warm white, cold white and amber | ⚠️ not yet tested on hardware |
| WS2805 RGBCW | RGB plus cold and warm white (12 V) | ⚠️ not yet tested on hardware |
Digital LEDs (SPI / 2-Wire): a data and a clock wire
| Entry in the list | Typical strips | Status |
|---|---|---|
| WS2801 | older RGB strips | ⚠️ not yet tested on hardware |
| APA102 | APA102, SK9822 ("DotStar") | ⚠️ not yet tested on hardware |
| LPD8806 | RGB | ⚠️ not yet tested on hardware |
| LPD6803 | RGB | ⚠️ not yet tested on hardware |
| PP9813 | P9813 / PP9813 | ⚠️ not yet tested on hardware |
Analog / simple LEDs (PWM): no data signal; the ESP32 dims each colour channel itself, usually through a driver or MOSFETs
| Entry in the list | What it drives | Status |
|---|---|---|
| On/Off | a lamp or relay that only switches | ⚠️ not yet tested on hardware |
| PWM White | one channel, single-colour strips | ⚠️ not yet tested on hardware |
| PWM CCT | two channels: cold and warm white | ⚠️ not yet tested on hardware |
| PWM RGB | three channels | ⚠️ not yet tested on hardware |
| PWM RGBW | four channels | ⚠️ not yet tested on hardware |
| PWM RGB+CCT | five channels | ⚠️ not yet tested on hardware |
Scan matrix panels
| Entry in the list | What it drives | Status |
|---|---|---|
| HUB75 | HUB75 LED panels, for example 64 × 64; set the driver chip to Generic (most panels), FM6126A, ICN2038S, FM6124, MBI5124 or DP3246 if you see ghosting or flicker | ✅ tested (generic) |
"Not yet tested on hardware" means the driver was checked against the library and the data sheet, but nobody has run it on a real strip yet. If you try one, please tell us in an issue, with the exact strip you used.
For 12 V and 24 V strips in which several LEDs share one chip (for example WS2805), the setting LEDs per chip matters; see First light.
LED panels (HUB75, for example 64 × 64) are connected with a fixed pinout that the web interface shows you; see Panels and elements and Several devices (a panel can run on a board of its own, a Slave).
Working out the power supply
A single WS2812B LED can draw about 60 mA when it is fully white (red, green and blue at full brightness). So:
Current in amps = number of LEDs × 0.06
| LEDs | Worst case (all white, full brightness) |
|---|---|
| 30 | 1.8 A |
| 60 | 3.6 A |
| 144 | 8.6 A |
| 300 | 18 A |
You will rarely run all LEDs at full white, and HyperLED has a brightness limiter that keeps the current under the limit you set (see First light). Still, choose a supply that is at least as strong as your limit, and use thick wires and feed long strips from both ends.
HyperLED also works it out for you: under Devices → LED hardware → Power supply it shows the recommended supply for the number of LEDs you entered.
Important: The ESP32 must not power the LEDs. Use a proper power supply for the strip and connect only the data line and a common ground to the ESP32. How: Wiring and power.