## 1. Project Overview & Quickstart (wled/WLED)
## File: images/Readme.md
### Additional Logos
Additional awesome logos for WLED can be found here [Aircoookie/Akemi](https://github.com/Aircoookie/Akemi).
---
## File: usermods/quinled-an-penta/readme.md
# QuinLED-An-Penta
The (un)official usermod to get the best out of the QuinLED-An-Penta (https://quinled.info/quinled-an-penta/), e.g. using the OLED and the SHT30 temperature/humidity sensor.
## Requirements
* "u8g2" by olikraus, v2.28 or higher: https://github.com/olikraus/u8g2
* "SHT85" by Rob Tillaart, v0.2 or higher: https://github.com/RobTillaart/SHT85
## Some words about the (optional) OLED
This mod has been optimized for an SSD1306 driven 128x64 OLED. Using a smaller OLED or an OLED using a different driver will result in unexpected results.
I highly recommend using these "two color monochromatic OLEDs", which have the first 16 pixels in a different color than the other 48, e.g. a yellow/blue OLED.
Note: you _must_ use an **SPI** driven OLED, **not an i2c one**!
### Limitations combined with Ethernet
The initial development of this mod was done with a beta version of the QuinLED-An-Penta, which had a different IO layout for the OLED: The CS pin _was_ IO_0, but has been changed to IO27 with the first v1 public release. Unfortunately, IO27 is used by Ethernet boards, so WLED will not let you enable the OLED screen, if you're using it with Ethernet. Unfortunately, that makes the development I've done to support/show Ethernet information invalid, as it cannot be used.
However, (and I've not tried this, as I don't own a v1 board) you can modify this usermod and try to use IO27 for the OLED and share it with the Ethernet board. It is "just" the chip select pin, so there is a chance that both can coexist and use the same IO. You need to skip WLEDs PinManager for the CS pin, so WLED will not block using it. If you don't know how this works, don't change it. If you know what I'm talking about, try it and please let me know on the Intermit.Tech (QuinLED) Discord server: https://discord.gg/WdbAauG
### My OLED flickers after some time, what should I do?
That's a tricky one. During development I saw that the OLED sometimes starts to "drop out" / flicker and won't work anymore. This seems to be caused by the high PWM interference the board produces. It seems to lose its settings then doesn't know how to draw anymore. Turns out the only way to fix this is to call the libraries `begin()` method again which re-initializes the display.
If you're facing this issue, you can enable a setting which will call the `begin()` roughly every 60 seconds between page changes. This will make the page change take ~500ms, but will fix the display.
## Configuration
Navigate to the "Config" and then to the "Usermods" section. If you compiled WLED with `-D QUINLED_AN_PENTA`, you will see the config for it there:
* Enable-OLED:
* What it does: Enables the optional SPI driven OLED that can be mounted to the 7-pin female header. Won't work with Ethernet, read above.
* Possible values: Enabled/Disabled
* Default: Disabled
* OLED-Use-Progress-Bars:
* What it does: Toggle between showing percentage numbers or a progress-bar-like visualization for overall brightness and each LED channels brightness level
* Possible values: Enabled/Disabled
* Default: Disabled
* OLED-Flip-Screen-180:
* What it does: Flips the screen 180°
* Possible values: Enabled/Disabled
* Default: Disabled
* OLED-Seconds-Per-Page:
* What it does: Number of seconds the OLED should stay on one page before changing pages
* Possible values: Enabled/Disabled
* Default: 10
* OLED-Fix-Bugged-Screen:
* What it does: Enable this if your OLED flickers after some time. For more info read above under ["My OLED flickers after some time, what should I do?"](#My-OLED-flickers-after-some-time-what-should-I-do)
* Possible values: Enabled/Disabled
* Default: Disabled
* Enable-SHT30-Temp-Humidity-Sensor:
* What it does: Enables the onboard SHT30 temperature and humidity sensor
* Possible values: Enabled/Disabled
* Default: Disabled
## Change log
2021-12
* Adjusted IO layout to match An-Penta v1r1
2021-10
* First implementation.
## Credits
ezcGman | Andy: Find me on the Intermit.Tech (QuinLED) Discord server: https://discord.gg/WdbAauG
---
## File: usermods/pwm_outputs/readme.md
# PWM outputs
v2 Usermod to add generic PWM outputs to WLED. Usermode could be used to control servo motors, LED brightness or any other device controlled by PWM signal.
## Installation
Add the compile-time option `-D USERMOD_PWM_OUTPUTS` to your `platformio.ini` (or `platformio_override.ini`). By default upt to 3 PWM outputs could be configured, to increase that limit add build argument `-D USERMOD_PWM_OUTPUT_PINS=10` (replace 10 by desired amount).
Currently only ESP32 is supported.
## Configuration
By default PWM outputs are disabled, navigate to Usermods settings and configure desired PWM pins and frequencies.
## Usage
If PWM output is configured, it starts to publish its duty cycle value (0-1) both to state JSON and to info JSON (visible in UI info panel). To set PWM duty cycle, use JSON api (over HTTP or over Serial)
```json
{
"pwm": {
"0": {"duty": 0.1},
"1": {"duty": 0.2},
...
}
}
```
---
## File: usermods/PWM_fan/readme.md
# PWM fan
v2 Usermod to to control PWM fan with RPM feedback and temperature control
This usermod requires the Dallas Temperature usermod to obtain temperature information. If it's not available, the fan will run at 100% speed.
If the fan does not have _tachometer_ (RPM) output you can set the _tachometer-pin_ to -1 to disable that feature.
You can also set the threshold temperature at which fan runs at lowest speed. If the measured temperature is 3°C greater than the threshold temperature, the fan will run at 100%.
If the _tachometer_ is supported, the current speed (in RPM) will be displayed on the WLED Info page.
## Installation
Add the `PWM_fan` to `custom_usermods` in your `platformio.ini` (or `platformio_override.ini`)
You will also need `Temperature` or `sht`.
### Define Your Options
All of the parameters are configured during run-time using Usermods settings page.
This includes:
* PWM output pin (can be configured at compile time `-D PWM_PIN=xx`)
* tachometer input pin (can be configured at compile time `-D TACHO_PIN=xx`)
* sampling frequency in seconds
* threshold temperature in degrees Celsius
_NOTE:_ You may also need to tweak Dallas Temperature usermod sampling frequency to match PWM fan sampling frequency.
### PlatformIO requirements
No special requirements.
## Control PWM fan speed using JSON API
e.g. you can use `{"PWM-fan":{"speed":30,"lock":true}}` to lock fan speed to 30 percent of maximum. (replace 30 with an arbitrary value between 0 and 100)
If you include `speed` property you can set fan speed as a percentage (%) of maximum speed.
If you include `lock` property you can lock (_true_) or unlock (_false_) the fan speed.
If the fan speed is unlocked, it will revert to temperature controlled speed on the next update cycle. Once fan speed is locked it will remain so until it is unlocked by the next API call.
## Change Log
2021-10
* First public release
2022-05
* Added JSON API call to allow changing of speed
---
## File: usermods/project_cars_shiftlight/readme.md
# Shift Light for Project Cars
Turn your WLED lights into a rev light and shift indicator for Project Cars.
It's easy to use.
_1._ Make sure your WLED device and your PC/console are on the same network and can talk to each other
_2._ Go to the gameplay settings menu in PCARS and enable UDP. There are 9 numbers you can choose from. This is the refresh rate. The lower the number, the better. However, you might run into problems at faster rates.
| Number | Updates/Second |
| ------ | -------------- |
| 1 | 60 |
| 2 | 50 |
| 3 | 40 |
| 4 | 30 |
| 5 | 20 |
| 6 | 15 |
| 7 | 10 |
| 8 | 05 |
| 9 | 1 |
_3._ Once you enter a race, WLED should automatically shift to PCARS mode.
_4._ Done.
---
## File: usermods/pixels_dice_tray/README.md
# A mod for using Pixel Dice with ESP32S3 boards
A usermod to connect to and handle rolls from [Pixels Dice](https://gamewithpixels.com/). WLED acts as both an display controller, and a gateway to connect the die to the Wifi network.
High level features:
* Several LED effects that respond to die rolls
* Effect color and parameters can be modified like any other effect
* Different die can be set to control different segments
* An optional GUI on a TFT screen with custom button controls
* Gives die connection and roll status
* Can do basic LED effect controls
* Can display custom info for different roll types (ie. RPG stats/spell info)
* Publish MQTT events from die rolls
* Also report the selected roll type
* Control settings through the WLED web
See for a write up of the design process of the hardware and software I used this with.
I also set up a custom web installer for the usermod at for 8MB ESP32-S3 boards.
## Table of Contents
* [Demos](#demos)
+ [TFT GUI](#tft-gui)
+ [Multiple Die Controlling Different Segments](#multiple-die-controlling-different-segments)
* [Hardware](#hardware)
* [Library used](#library-used)
* [Compiling](#compiling)
+ [platformio_override.ini](#platformio_overrideini)
+ [Manual platformio.ini changes](#manual-platformioini-changes)
* [Configuration](#configuration)
+ [Controlling Dice Connections](#controlling-dice-connections)
+ [Controlling Effects](#controlling-effects)
- [DieSimple](#diesimple)
- [DiePulse](#diepulse)
- [DieCheck](#diecheck)
* [TFT GUI](#tft-gui-1)
+ [Status](#status)
+ [Effect Menu](#effect-menu)
+ [Roll Info](#roll-info)
* [MQTT](#mqtt)
* [Potential Modifications and Additional Features](#potential-modifications-and-additional-features)
* [ESP32 Issues](#esp32-issues)
## Demos
### TFT GUI
[](https://youtu.be/VNsHq1TbiW8)
### Multiple Die Controlling Different Segments
[](https://youtu.be/oCDr44C-qwM)
## Hardware
The main purpose of this mod is to support [Pixels Dice](https://gamewithpixels.com/). The board acts as a BLE central for the dice acting as peripherals. While any ESP32 variant with BLE capabilities should be able to support this usermod, in practice I found that the original ESP32 did not work. See [ESP32 Issues](#esp32-issues) for a deeper dive.
The only other ESP32 variant I tested was the ESP32-S3, which worked without issue. While there's still concern over the contention between BLE and WiFi for the radio, I haven't noticed any performance impact in practice. The only special behavior that was needed was setting `noWifiSleep = false;` to allow the OS to sleep the WiFi when the BLE is active.
In addition, the BLE stack requires a lot of flash. This build takes 1.9MB with the TFT code, or 1.85MB without it. This makes it too big to fit in the `tools/WLED_ESP32_4MB_256KB_FS.csv` partition layout, and I needed to make a `WLED_ESP32_4MB_64KB_FS.csv` to even fit on 4MB devices. This only has 64KB of file system space, which is functional, but users with more than a handful of presets would run into problems with 64KB only. This means that while 4MB can be supported, larger flash sizes are needed for full functionality.
The basic build of this usermod doesn't require any special hardware. However, the LCD status GUI was specifically designed for the [LILYGO T-QT Pro](https://www.lilygo.cc/products/t-qt-pro).
It should be relatively easy to support other displays, though the positioning of the text may need to be adjusted.
## Library used
[axlan/pixels-dice-interface](https://github.com/axlan/arduino-pixels-dice)
Optional: [Bodmer/TFT_eSPI](https://github.com/Bodmer/TFT_eSPI)
## Compiling
### platformio_override.ini
Copy and update the example `platformio_override.ini.sample` to the root directory of your particular build (renaming it `platformio_override.ini`).
This file should be placed in the same directory as `platformio.ini`. This file is set up for the [LILYGO T-QT Pro](https://www.lilygo.cc/products/t-qt-pro). Specifically, the 8MB flash version. See the next section for notes on setting the build flags. For other boards, you may want to use a different environment as the basis.
### Manual platformio.ini changes
Using the `platformio_override.ini.sample` as a reference, you'll need to update the `build_flags` and `lib_deps` of the target you're building for.
If you don't need the TFT GUI, you just need to add
```ini
...
build_flags =
...
-D USERMOD_PIXELS_DICE_TRAY ;; Enables this UserMod
lib_deps =
...
ESP32 BLE Arduino
axlan/pixels-dice-interface @ 1.2.0
...
```
For the TFT support you'll need to add `Bodmer/TFT_eSPI` to `lib_deps`, and all of the required TFT parameters to `build_flags` (see `platformio_override.ini.sample`).
Save the `platformio.ini` file, and perform the desired build.
## Configuration
In addition to configuring which dice to connect to, this mod uses a lot of the built in WLED features:
* The LED segments, effects, and customization parameters
* The buttons for the UI
* The MQTT settings for reporting the dice rolls
### Controlling Dice Connections
**NOTE:** To configure the die itself (set its name, the die LEDs, etc.), you still need to use the Pixels Dice phone App.
The usermods settings page has the configuration for controlling the dice and the display:
* Ble Scan Duration - The time to look for BLE broadcasts before taking a break
* Rotation - If display used, set this parameter to rotate the display.
The main setting here though are the Die 0 and 1 settings. A slot is disabled if it's left blank. Putting the name of a die will make that slot only connect to die with that name. Alteratively, if the name is set to `*` the slot will use the first unassociated die it sees. Saving the configuration while a wildcard slot is connected to a die will replace the `*` with that die's name.
**NOTE:** The slot a die is in is important since that's how they're identified for controlling LED effects. Effects can be set to respond to die 0, 1, or any.
The configuration also includes the pins configured in the TFT build flags. These are just so the UI recognizes that these pins are being used. The [Bodmer/TFT_eSPI](https://github.com/Bodmer/TFT_eSPI) requires that these are set at build time and changing these values is ignored.
### Controlling Effects
The die effects for rolls take advantage of most of the normal WLED effect features: .
If you have different segments, they can have different effects driven by the same die, or different dice.
#### DieSimple
Turn off LEDs while rolling, than light up solid LEDs in proportion to die roll.
* Color 1 - Selects the "good" color that increases based on the die roll
* Color 2 - Selects the "background" color for the rest of the segment
* Custom 1 - Sets which die should control this effect. If the value is greater then 1, it will respond to both dice.
#### DiePulse
Play `breath` effect while rolling, than apply `blend` effect in proportion to die roll.
* Color 1 - See `breath` and `blend`
* Color 2 - Selects the "background" color for the rest of the segment
* Palette - See `breath` and `blend`
* Custom 1 - Sets which die should control this effect. If the value is greater then 1, it will respond to both dice.
#### DieCheck
Play `running` effect while rolling, than apply `glitter` effect if roll passes threshold, or `gravcenter` if roll is below.
* Color 1 - See `glitter` and `gravcenter`, used as first color for `running`
* Color 2 - See `glitter` and `gravcenter`
* Color 3 - Used as second color for `running`
* Palette - See `glitter` and `gravcenter`
* Custom 1 - Sets which die should control this effect. If the value is greater then 1, it will respond to both dice.
* Custom 2 - Sets the threshold for success animation. For example if 10, success plays on rolls of 10 or above.
## TFT GUI
The optional TFT GUI currently supports 3 "screens":
1. Status
2. Effect Control
3. Roll Info
Double pressing the right button goes forward through the screens, and double pressing left goes back (with rollover).
### Status
Shows the status of each die slot (0 on top and 1 on the bottom).
If a die is connected, its roll stats and battery status are shown. The rolls will continue to be tracked even when viewing other screens.
Long press either button to clear the roll stats.
### Effect Menu
Allows limited customization of the die effect for the currently selected LED segment.
The left button moves the cursor (blue box) up and down the options for the current field.
The right button updates the value for the field.
The first field is the effect. Updating it will switch between the die effects.
The DieCheck effect has an additional field "PASS". Pressing the right button on this field will copy the current face up value from the most recently rolled die.
Long pressing either value will set the effect parameters (color, palette, controlling dice, etc.) to a default set of values.
### Roll Info
Sets the "roll type" reported by MQTT events and can show additional info.
Pressing the right button goes forward through the rolls, and double pressing left goes back (with rollover).
The names and info for the rolls are generated from the `usermods/pixels_dice_tray/generate_roll_info.py` script. It updates `usermods/pixels_dice_tray/roll_info.h` with code generated from a simple markdown language.
## MQTT
See for general MQTT configuration for WLED.
The usermod produces two types of events
* `$mqttDeviceTopic/dice/roll` - JSON that reports each die roll event with the following keys.
- name - The name of the die that triggered the event
- state - Integer indicating the die state `[UNKNOWN = 0, ON_FACE = 1, HANDLING = 2, ROLLING = 3, CROOKED = 4]`
- val - The value on the die's face. For d20 1-20
- time - The uptime timestamp the roll was received in milliseconds.
* `$mqttDeviceTopic/dice/roll_label` - A string that indicates the roll type selected in the [Roll Info](#roll-info) TFT menu.
Where `$mqttDeviceTopic` is the topic set in the WLED MQTT configuration.
Events can be logged to a CSV file using the script `usermods/pixels_dice_tray/mqtt_client/mqtt_logger.py`. These can then be used to generate interactive HTML plots with `usermods/pixels_dice_tray/mqtt_client/mqtt_plotter.py`.
## Potential Modifications and Additional Features
This usermod is in support of a particular dice box project, but it would be fairly straightforward to extend for other applications.
* Add more dice - There's no reason that several more dice slots couldn't be allowed. In addition LED effects that use multiple dice could be added (e.g. a contested roll).
* Better support for die other then d20's. There's a few places where I assume the die is a d20. It wouldn't be that hard to support arbitrary die sizes.
* TFT Menu - The menu system is pretty extensible. I put together some basic things I found useful, and was mainly limited by the screen size.
* Die controlled UI - I originally planned to make an alternative UI that used the die directly. You'd press a button, and the current face up on the die would trigger an action. This was an interesting idea, but didn't seem to practical since I could more flexibly reproduce this by responding to the dice MQTT events.
## ESP32 Issues
I really wanted to have this work on the original ESP32 boards to lower the barrier to entry, but there were several issues.
First there are the issues with the partition sizes for 4MB mentioned in the [Hardware](#hardware) section.
The bigger issue is that the build consistently crashes if the BLE scan task starts up. It's a bit unclear to me exactly what is failing since the backtrace is showing an exception in `new[]` memory allocation in the UDP stack. There appears to be a ton of heap available, so my guess is that this is a synchronization issue of some sort from the tasks running in parallel. I tried messing with the task core affinity a bit but didn't make much progress. It's not really clear what difference between the ESP32S3 and ESP32 would cause this difference.
At the end of the day, its generally not advised to run the BLE and Wifi at the same time anyway (though it appears to work without issue on the ESP32S3). Probably the best path forward would be to switch between them. This would actually not be too much of an issue, since discovering and getting data from the die should be possible to do in bursts (at least in theory).
---
## File: usermods/PIR_sensor_switch/readme.md
# PIR sensor switch
This usermod-v2 modification allows the connection of a PIR sensor to switch on the LED strip when motion is detected. The switch-off occurs ten minutes after no more motion is detected.
_Story:_
I use the PIR Sensor to automatically turn on the WLED analog clock in my home office room when I am there.
The LED strip is switched [using a relay](https://kno.wled.ge/features/relay-control/) to keep the power consumption low when it is switched off.
## Web interface
The info page in the web interface shows the remaining time of the off timer. Usermod can also be temporarily disbled/enabled from the info page by clicking PIR button.
## Sensor connection
My setup uses an HC-SR501 or HC-SR602 sensor, an HC-SR505 should also work.
The usermod uses GPIO13 (D1 mini pin D7) by default for the sensor signal, but can be changed in the Usermod settings page.
[This example page](http://www.esp8266learning.com/wemos-mini-pir-sensor-example.php) describes how to connect the sensor.
Use the potentiometers on the sensor to set the time delay to the minimum and the sensitivity to about half, or slightly above.
You can also use usermod's off timer instead of sensor's. In such case rotate the potentiometer to its shortest time possible (or use SR602 which lacks such potentiometer).
## Usermod installation
**NOTE:** Usermod has been included in master branch of WLED so it can be compiled in directly just by defining `-D USERMOD_PIRSWITCH` and optionally `-D PIR_SENSOR_PIN=16` to override default pin. You can also change the default off time by adding `-D PIR_SENSOR_OFF_SEC=30`.
## API to enable/disable the PIR sensor from outside. For example from another usermod
To query or change the PIR sensor state the methods `bool PIRsensorEnabled()` and `void EnablePIRsensor(bool enable)` are available.
When the PIR sensor state changes an MQTT message is broadcasted with topic `wled/deviceMAC/motion` and message `on` or `off`.
Usermod can also be configured to send just the MQTT message but not change WLED state using settings page as well as responding to motion only at night
(assuming NTP and latitude/longitude are set to determine sunrise/sunset times).
### There are two options to get access to the usermod instance
_1._ Include `usermod_PIR_sensor_switch.h` **before** you include other usermods in `usermods_list.cpp'
or
_2._ Use `#include "usermod_PIR_sensor_switch.h"` at the top of the `usermod.h` where you need it.
**Example usermod.h :**
```cpp
#include "wled.h"
#include "usermod_PIR_sensor_switch.h"
class MyUsermod : public Usermod {
//...
void togglePIRSensor() {
#ifdef USERMOD_PIR_SENSOR_SWITCH
PIRsensorSwitch *PIRsensor = (PIRsensorSwitch::*) UsermodManager::lookup(USERMOD_ID_PIRSWITCH);
if (PIRsensor != nullptr) {
PIRsensor->EnablePIRsensor(!PIRsensor->PIRsensorEnabled());
}
#endif
}
//...
};
```
### Configuration options
Usermod can be configured via the Usermods settings page.
* `PIRenabled` - enable/disable usermod
* `pin` - dynamically change GPIO pin where PIR sensor is attached to ESP
* `PIRoffSec` - number of seconds after PIR sensor deactivates when usermod triggers Off preset (or turns WLED off)
* `on-preset` - preset triggered when PIR activates (if this is 0 it will just turn WLED on)
* `off-preset` - preset triggered when PIR deactivates (if this is 0 it will just turn WLED off)
* `nighttime-only` - enable triggering only between sunset and sunrise (you will need to set up _NTP_, _Lat_ & _Lon_ in Time & Macro settings)
* `mqtt-only` - send only MQTT messages, do not interact with WLED
* `off-only` - only trigger presets or turn WLED on/off if WLED is not already on (displaying effect)
* `notifications` - enable or disable sending notifications to other WLED instances using Sync button
* `HA-discovery` - enable automatic discovery in Home Assistant
* `override` - override PIR input when WLED state is changed using UI
* `domoticz-idx` - Domoticz virtual switch ID (used with MQTT `domoticz/in`)
Have fun - @gegu & @blazoncek
## Change log
2021-04
* Adaptation for runtime configuration.
2021-11
* Added information about dynamic configuration options
* Added option to temporary enable/disable usermod from WLED UI (Info dialog)
2022-11
* Added compile time option for off timer.
* Added Home Assistant autodiscovery MQTT broadcast.
* Updated info on compiling.
2023-??
* Override option
* Domoticz virtual switch ID (used with MQTT `domoticz/in`)
2024-02
* Added compile time option to expand number of PIR sensors (they are logically ORed) `-D PIR_SENSOR_MAX_SENSORS=3`
---
## File: usermods/photoresistor_sensor_mqtt_v1/README.md
# Photoresister sensor with MQTT
Enables attaching a photoresistor sensor like the KY-018 and publishing the readings as a percentage, via MQTT. The frequency of MQTT messages is user definable.
A threshold value can be set so significant changes in the readings are published immediately vice waiting for the next update. This was found to be a good compromise between excessive MQTT traffic and delayed updates.
I also found it useful to limit the frequency of analog pin reads, otherwise the board hangs.
This usermod has only been tested with the KY-018 sensor though it should work for any other analog pin sensor.
Note: this does not control the LED strip directly, it only publishes MQTT readings for use with other integrations like Home Assistant.
## Installation
Copy and replace the file `usermod.cpp` in wled00 directory.
---
## File: usermods/multi_relay/readme.md
# Multi Relay
This usermod-v2 modification allows the connection of multiple relays, each with individual delay and on/off mode.
Usermod supports PCF8574 I2C port expander to reduce GPIO use.
PCF8574 supports 8 outputs and each output corresponds to a relay in WLED (relay 0 = port 0, etc). I you are using more than 8 relays with multiple PCF8574 make sure their addresses are set in sequence (e.g. 0x20 and 0x21). You can set address of first expander in settings.
(**NOTE:** Will require Wire library and global I2C pins defined.)
## HTTP API
All responses are returned in JSON format.
* Status Request: `http://[device-ip]/relays`
* Switch Command: `http://[device-ip]/relays?switch=1,0,1,1`
The number of values behind the switch parameter must correspond to the number of relays. The value 1 switches the relay on, 0 switches it off.
* Toggle Command: `http://[device-ip]/relays?toggle=1,0,1,1`
The number of values behind the parameter switch must correspond to the number of relays. The value 1 causes the relay to toggle, 0 leaves its state unchanged.
Examples:
1. total of 4 relays, relay 2 will be toggled: `http://[device-ip]/relays?toggle=0,1,0,0`
2. total of 3 relays, relay 1&3 will be switched on: `http://[device-ip]/relays?switch=1,0,1`
## JSON API
You can toggle the relay state by sending the following JSON object to: `http://[device-ip]/json`
Switch relay 0 on: `{"MultiRelay":{"relay":0,"on":true}}`
Switch relay 3 and 4 off: `{"MultiRelay":[{"relay":2,"on":false},{"relay":3,"on":false}]}`
## MQTT API
* `wled`/_deviceMAC_/`relay`/`0`/`command` `on`|`off`|`toggle`
* `wled`/_deviceMAC_/`relay`/`1`/`command` `on`|`off`|`toggle`
When a relay is switched, a message is published:
* `wled`/_deviceMAC_/`relay`/`0` `on`|`off`
## Usermod installation
Add `multi_relay` to the `custom_usermods` of your platformio.ini environment.
You can override the default maximum number of relays (which is 4) by defining MULTI_RELAY_MAX_RELAYS.
Some settings can be defined (defaults) at compile time by setting the following defines:
```cpp
// enable or disable HA discovery for externally controlled relays
#define MULTI_RELAY_HA_DISCOVERY true
```
The following definitions should be a list of values (maximum number of entries is MULTI_RELAY_MAX_RELAYS) that will be applied to the relays in order:
(e.g. assuming MULTI_RELAY_MAX_RELAYS=2)
```cpp
#define MULTI_RELAY_PINS 12,18
#define MULTI_RELAY_DELAYS 0,0
#define MULTI_RELAY_EXTERNALS false,true
#define MULTI_RELAY_INVERTS false,false
```
These can be set via your `platformio_override.ini` file or as `#define` in your `my_config.h` (remember to set `WLED_USE_MY_CONFIG` in your `platformio_override.ini`)
## Configuration
Usermod can be configured via the Usermods settings page.
* `enabled` - enable/disable usermod
* `use-PCF8574` - use PCF8574 port expander instead of GPIO pins
* `first-PCF8574` - I2C address of first expander (WARNING: enter *decimal* value)
* `broadcast`- time in seconds between MQTT relay-state broadcasts
* `HA-discovery`- enable Home Assistant auto discovery
* `pin` - ESP GPIO pin the relay is connected to (can be configured at compile time `-D MULTI_RELAY_PINS=xx,xx,...`)
* `delay-s` - delay in seconds after on/off command is received
* `active-high` - assign high/low activation of relay (can be used to reverse relay states)
* `external` - if enabled, WLED does not control relay, it can only be triggered by an external command (MQTT, HTTP, JSON or button)
* `button` - button (from LED Settings) that controls this relay
If there is no MultiRelay section, just save current configuration and re-open Usermods settings page.
Have fun - @blazoncek
## Change log
2021-04
* First implementation.
2021-11
* Added information about dynamic configuration options
* Added button support.
2023-05
* Added support for PCF8574 I2C port expander (multiple)
2023-11
* @chrisburrows Added support for compile time defaults for setting DELAY, EXTERNAL, INVERTS and HA discovery
---
## File: usermods/mpu6050_imu/readme.md
# MPU-6050 Six-Axis (Gyro + Accelerometer) Driver
v2 of this usermod enables connection of a MPU-6050 IMU sensor to
work with effects controlled by the orientation or motion of the WLED Device.
The MPU6050 has a built in "Digital Motion Processor" which does the "heavy lifting"
integrating the gyro and accelerometer measurements to get potentially more
useful gravity vector and orientation output.
It is fairly straightforward to comment out variables being read from the device if they're not needed. Saves CPU/Memory/Bandwidth.
_Story:_
As a memento to a long trip I was on, I built an icosahedron globe. I put lights inside to indicate cities I travelled to.
I wanted to integrate an IMU to allow either on-board, or off-board effects that would
react to the globes orientation. See the blog post on building it or a video demo .
## Wiring
The connections needed to the MPU6050 are as follows:
```
VCC VU (5V USB) Not available on all boards so use 3.3V if needed.
GND G Ground
SCL D1 (GPIO05) I2C clock
SDA D2 (GPIO04) I2C data
XDA not connected
XCL not connected
AD0 not connected
INT D8 (GPIO15) Interrupt pin
```
You could probably modify the code not to need an interrupt, but I used the
setup directly from the example.
## JSON API
This code adds:
```json
"u":{
"IMU":{
"Quat": [w, x, y, z],
"Euler": [psi, theta, phi],
"Gyro": [x, y, z],
"Accel": [x, y, z],
"RealAccel": [x, y, z],
"WorldAccel": [x, y, z],
"Gravity": [x, y, z],
"Orientation": [yaw, pitch, roll]
}
}
```
to the info object
## Usermod installation
Add `mpu6050_imu` to `custom_usermods` in your platformio_override.ini.
Example **platformio_override.ini**:
```ini
[env:usermod_mpu6050_imu_esp32dev]
extends = env:esp32dev
custom_usermods = ${env:esp32dev.custom_usermods}
mpu6050_imu
```
---
## File: usermods/MAX17048_v2/readme.md
# Adafruit MAX17048 Usermod (LiPo & LiIon Battery Monitor & Fuel Gauge)
This usermod reads information from an Adafruit MAX17048 and outputs the following:
- Battery Voltage
- Battery Level Percentage
## Dependencies
Data is published over MQTT - make sure you've enabled the MQTT sync interface.
## Compilation
Add "MAX17048_v2" to your platformio.ini environment's custom_usermods and build.
To enable, compile with `USERMOD_MAX17048` define in the build_flags (e.g. in `platformio.ini` or `platformio_override.ini`) such as in the example below:
```ini
[env:usermod_max17048_d1_mini]
extends = env:d1_mini
custom_usermods = ${env:d1_mini.custom_usermods} MAX17048_v2
```
### Configuration Options
The following settings can be set at compile-time but are configurable on the usermod menu (except First Monitor time):
- USERMOD_MAX17048_MIN_MONITOR_INTERVAL (the min number of milliseconds between checks, defaults to 10,000 ms)
- USERMOD_MAX17048_MAX_MONITOR_INTERVAL (the max number of milliseconds between checks, defaults to 10,000 ms)
- USERMOD_MAX17048_FIRST_MONITOR_AT
Additionally, the Usermod Menu allows you to:
- Enable or Disable the usermod
- Enable or Disable Home Assistant Discovery (turn on/off to sent MQTT Discovery entries for Home Assistant)
- Configure SCL/SDA GPIO Pins
## API
The following method is available to interact with the usermod from other code modules:
- `getBatteryVoltageV` read the last battery voltage (in Volt) obtained from the sensor
- `getBatteryPercent` reads the last battery percentage obtained from the sensor
## MQTT
MQTT topics are as follows (`` is set in MQTT section of Sync Setup menu):
Measurement type | MQTT topic
--- | ---
Battery Voltage | `/batteryVoltage`
Battery Percent | `/batteryPercent`
## Authors
Carlos Cruz [@ccruz09](https://github.com/ccruz09)
## Revision History
Jan 2024
- Added Home Assistant Discovery
- Implemented PinManager to register pins
- Added API call for other modules to read battery voltage and percentage
- Added info-screen outputs
- Updated `readme.md`
---
## File: usermods/LDR_Dusk_Dawn_v2/README.md
# LDR_Dusk_Dawn_v2
This usermod will obtain readings from a Light Dependent Resistor (LDR) and will turn on/off specific presets based on those readings. This is useful for exterior lighting situations where you want the lights to only be on when it is dark out.
# Installation
Add "LDR_Dusk_Dawn" to your platformio.ini environment's custom_usermods and build.
Example:
```
[env:usermod_LDR_Dusk_Dawn_esp32dev]
extends = env:esp32dev
custom_usermods = ${env:esp32dev.custom_usermods}
LDR_Dusk_Dawn # Enable LDR Dusk Dawn Usermod
```
# Usermod Settings
Setting | Description | Default
--- | --- | ---
Enabled | Enable/Disable the LDR functionality. | Disabled
LDR Pin | The analog capable pin your LDR is connected to. | 34
Threshold Minutes | The number of minutes of consistent readings above/below the on/off threshold before the LED state will change. | 5
Threshold | The analog read value threshold from the LDR. Readings lower than this number will count towards changing the LED state to off. You can see the current LDR reading by going into the info section when LDR functionality is enabled. | 1000
On Preset | The WLED preset to be used for the LED on state. | 1
Off Preset | The WLED preset to be used for the LED off state. | 2
## Author
[@jeffwdh](https://github.com/jeffwdh)
jeffwdh@tarball.ca
## 2. Official Technical Reference & Guides (wled/WLED-docs)
## File: docs/basics/compatible-controllers.md
---
title: Compatible controllers
hide:
# - navigation
# - toc
---
Currently (as of summer 2023) only the microcontrollers from Espressif, types ESP8266 and ESP32 (with dual core) are fully supported, however ESP8266 should not be used for any new installations.
Some of the newer types like ESP32-C3, ESP32-S2 and ESP32-S3 are experimentally supported, but productive use is not recommended yet because some bugs are suspected. In addition, the installation of these newer types is not that easy: there are several hardware variations/boards for which the SW must be specially compiled. It should also be mentioned that some ESP32-C3 boards (so-called C3 mini V1.0.0) are still being sold on the market where WLAN does not work properly.
To try out WLED with 5V addressable strip a simple microcontroller board like ESP32 D1 mini is sufficient. The simplest setup might be like:
However, there are a few other things to keep in mind for a proper setup:
1. A level shifter is required for reliable data transmission from the controller to the LED strip (this is mandatory, especially with 12V or 24V LED strips). Then you have to solder something together or you can buy a ready-made WLED controller right away.
2. For safety reasons, the correct cabling (length, cross-section, contacts) and the fuses to be integrated must be considered. Especially with LED strips, it gets more complicated because you need the so-called intermediate feeds. These must be planned and implemented correctly. [LED power, wiring and fuse calculator](https://wled-calculator.github.io/) can be used as a starting point.
3. LED strips can get quite warm during operation and even overheat in the event of a fault. Again, for safety reasons, you have to protect the area around it: you shouldn't just lay LED strips like that, ideally you should integrate them into aluminum profiles or something similar. In normal operation, these act like a heat sink and thus extend the service life of the LEDs. In the event of a fault, they can protect the surroundings.
4. To save energy while LEDs are off, you might integrate relays that switch the voltage of LEDs off completely.
In the following some third-party controllers are listed. Please use a decent and neutral description when adding things to this list.
**Gold Member** indicates the product owner makes substantial contributions to the WLED community (financial, code, documentation and/or support).
!!! tip
Lists are in alphabetical order. The position of an item in the list does not indicate how good it is or if it will fit your use case.
Please carefully compare all items in the category you are interested in, and you should find the one that suits your needs best in just a few minutes!
## Controllers with WLED pre-installed
!!! check "Info"
Unless otherwise noted, controllers feature everything you need for most WLED setups, except a power supply, wiring and fuses, and of course the LEDs themselves!
!!! info "Transparency Notice"
Warning Products listed below under the name "Athom" are offered by the company ATHOM Technology Co., Ltd., based in China, which is not affiliated in any way with the European company Athom B.V., makers of the Homey smart home platform. There is an ongoing legal process against ATHOM Technology Co., Ltd. for possible trademark infringement.
| Name | Description |
|---|---|
[8 Port LED Distro](https://www.tindie.com/products/bong69/8-port-led-distro/) | This is an 8 port ESP32 based LED distro board running WLED. Distributing both power and data in 1 board. The WT32-ETH01 provides support for Wi-Fi or ethernet connections. It can be used with either 5v or 12v or 24v LED pixels. Also includes a USB-C port for programming, level shifter, 5 amp fuse on every port, multiple voltage inputs with no jumpers to set and phoenix connectors for easy wiring.
[A1-SLWF-03 ESP32 WLED controller](https://smlight.tech/product/slwf-03/) | Built-in digital microphone ICS-43434 for soundReactive WLED, ESP32 + 16M, IR receiver, Sensor button, Type-C plug, DC-plug, Screw-terminal, 5-24V, Pinouts for DIY. Specifically designed Controller that supports 5V-24V addressable strips from Ukrainian developers. Slim design. Screwdriver + adhesive tapes included. [Official store, worldwide](https://smartlight.me/led-strips/adressable-led-strips/a1slwf03controller), [Tindie](https://www.tindie.com/products/smartlightme/a1-slwf-03-wled-esp32-controller-home-assistant/), [Aliexpress](https://www.aliexpress.com/item/1005005947819419.html).
[A1-SLWF-09 Ethernet PoE SoundReactive ESP32 WLED controller](https://smlight.tech/product/slwf-09) | The SMLIGHT A1-SLWF-09 is a high-performance, enterprise-grade LED controller based on the ESP32, designed for demanding addressable lighting applications. Its modular architecture enables optional Ethernet, Power-over-Ethernet (PoE), and microphone addons (so you pay only for features you need). It supports 5–24V LED strips (via Type-C, PoE, DC plug or wire terminal), with an onboard USB-C Power Delivery regulator that uniquely allows direct powering of 5V or 12V strips via Type-C — a feature not available in other controllers. Built-in level shifters, relay output, and DIY GPIOs provide robust flexibility for automation, smart home, or creative projects. Preloaded with WLED and soundreactive mod firmware and engineered for reliability, SLWF-09 is ready for both hobbyist and professional use. [Aliexpress-1:] (https://www.aliexpress.com/item/1005009686374457.html), [Aliexpress-2](https://www.aliexpress.com/item/1005009686142651.html), [Authorized store, worldwide](https://smartlight.me/led-strips/adressable-led-strips/slwf-09-led-controller). [View Full Manual](https://smlight.tech/support/manuals/books/slwf-09), [Youtube showcase](https://www.youtube.com/watch?v=41i7vSHvbuI).
[ABC! WLED Controller V43 / ESP32 based / 5V-24V](https://shop.myhome-control.de/ABC-WLED-Controller-Board-5-24V/HW10015) | Commercial controller board for 5V / 12V / 24V LED strips from creator of [LED power, wiring and fuse calculator](https://wled-calculator.github.io/). Based on ESP32 uC. Preflashed SW. Up to four outputs. Option for digital microphone or [line-in-to-I2S Adapter](https://shop.myhome-control.de/Line-In-zu-I2S-Adapter-fuer-WLED-Controller/HW10013) for sound reactive WLED. Automatic 5V/12V/24V recognition (no jumper/switch etc. required). [Ethernet adapter](https://shop.myhome-control.de/Ethernet-Adapter-fuer-WLED-Controller/HW10016) is available. [RS485 long range/DMX adapter](https://shop.myhome-control.de/WLED-RS-485-Range-Extender-DMX-Adapter/HW10022), [Multi-protection switch board](https://shop.myhome-control.de/ABC-WLED-Switch-Board/HW10021) and [PWM board for analogue LEDs](https://shop.myhome-control.de/WLED-PWM-Board/HW10024) LEDs are available. [Enclosure](https://shop.myhome-control.de/Gehaeuse-fuer-WLED-Boards/ZB10002) is available too. [German shop & shipping only within Germany or to Poland.](https://shop.myhome-control.de/ABC-WLED-Controller-Board-5-24V/HW10015). Worldwide is available at [WLED.SHOP](https://wled.shop/produkt/wladis-wled-controller-v40-esp32/).
[ABC! WLED Controller PRO V57 with iMOSFET and PSRAM](https://shop.myhome-control.de/ABC-WLED-Controller-PRO-V57-mit-iMOSFET/HW10030) | Commercial controller board for 5V / 12V / 24V LED strips from creator of [LED power, wiring and fuse calculator](https://wled-calculator.github.io/). Based on ESP32 uC with 8MB Flash and 2MB PSRAM. Preflashed SW. Up to four outputs. Integrated intelligent MOSFET switch to power off LED strip completely. Option for digital microphone or [line-in-to-I2S Adapter](https://shop.myhome-control.de/Line-In-zu-I2S-Adapter-fuer-WLED-Controller/HW10013) for sound reactive WLED. Automatic 5V/12V/24V recognition (no jumper/switch etc. required). [Ethernet adapter](https://shop.myhome-control.de/Ethernet-Adapter-fuer-WLED-Controller/HW10016) is available. [RS485 long range/DMX adapter](https://shop.myhome-control.de/WLED-RS-485-Range-Extender-DMX-Adapter/HW10022) and [PWM board for analogue LEDs](https://shop.myhome-control.de/WLED-PWM-Board/HW10024) LEDs are available. [Enclosure](https://shop.myhome-control.de/Gehaeuse-fuer-WLED-Boards/ZB10002) is available too. [German shop & shipping only within Germany](https://shop.myhome-control.de/ABC-WLED-Controller-Board-5-24V/HW10015).
[ABC! WLED mini Controller V73 / ESP32 based / 5V-24V](https://shop.myhome-control.de/ABC-WLED-Controller-Board-mini-5-24V-V73-ESP32/HW10019) | Commercial controller board for 5V / 12V / 24V LED strips from creator of [LED power, wiring and fuse calculator](https://wled-calculator.github.io/). Based on ESP32 uC. Preflashed SW. Up to four outputs. Option for digital microphone or [line-in-to-I2S Adapter](https://shop.myhome-control.de/Line-In-zu-I2S-Adapter-fuer-WLED-Controller/HW10013) for sound reactive WLED. Automatic 5V/12V/24V recognition (no jumper/switch etc. required). Enclosure is available. [German shop & shipping only within Germany or to Poland](https://shop.myhome-control.de/ABC-WLED-Controller-Board-mini-5-24V-V73-ESP32/HW10019).
[Athom Light Strip Controller](https://www.aliexpress.com/item/1005008422804802.html) | Simple controller with enclosure for reliably driving 3 pin 5V～24V LEDs. Uses 4MB ESP32C3.
[Athom LS8P ESP32 Music Controller](https://www.athom.tech/blank-1/wled-esp32-music-addressable-led-strip-controller) | ESP32 based controller with dual output, microphone and IR. Comes with WLED preinstalled. Uses 8MB ESP32.
[Athom High Power Addressable LED Strip Controller](https://www.athom.tech/blank-1/wled-high-power-led-strip-controller) | Higher power options than the above system. Supports optional clock output.
[Athom RGBCCT Analog and Digital Light Strip Controller](https://www.athom.tech/blank-1/wled-rgbcct-analog-and-digital-light-strip-controller) | This WLED controller supports both analog and addressable strip. Uses 4MB ESP32C3.
[Athom Ethernet Addressable & DMX LED Strip Controller](https://www.athom.tech/blank-1/ethernet-wled-esp32-addressable-dmx-led-strip-controller) | This WLED controller supports both Addressable and DMX LED Strip. Uses 8MB ESP32.
[Cadsbi Motion Smart](https://www.cadsbi-shop.de/shop/led-beleuchtungscontroller/cadsbi-motion-smart/) | Ready to use solution with 3 output ports, an external antenna, in a high quality metal enclosure
[cod.m WLED Controller](https://shop.codm.de/en/automation/wled/30/wled-controller-wlan/wi-fi) | Compact WLED Controller for 5V/12V/24V strips based in ESP32, complete in case, with plug, including level shifter with 2/4 outputs. Commercially available in Germany throughout Europe with CE, RoHS and WEEE. Made in Germany. See [https://docs.codm.de/en/wled/controller/](https://docs.codm.de/en/wled/controller/) for detailed wiring schemes and documentation.
[cod.m WLED LAN Controller (PoE)](https://shop.codm.de/en/en/automation/wled/wled-lan-controller-poe-din-rail) | DIN-Rail WLED LAN(Ethernet) Controller with PoE and pluggable output modules for direct output or Range Extender Output (up to 500m data line). Currently for up to 4 outputs, more input/output modules are planned. Commercially available in Germany throughout Europe with CE, RoHS and WEEE. Made in Germany. See [https://docs.codm.de/wled/lan-controller/](https://docs.codm.de/wled/lan-controller/) (German) for detailed wiring schemes and documentation.
[Domestic Automation LLC](https://www.domestic-automation.com) | Plug in design makes it the easiest and quickest preinstalled WLED controller to setup! Modular design allows for simple plug-in addition of Motion sensors, Button control, 12V lights and more. Snap track makes for universal mounting. Includes built in fuses and power relay for safety and control. Available on Amazon [here](https://amzn.to/3XFTjpb)
[E8-WiFi Plus](https://computerstyretjulelys.dk/vare/e8-wifi-plus-pixel-controller/) | The E8-WiFi Plus is an advanced 8-port WLED pixel controller built on the robust ESP32 microcontroller, designed for maximum performance and flexibility. It comes fully pre-assembled, supporting a wide voltage range from 5V to 24V DC. With a high output current capacity of up to 30A across all 8 outputs, each is fused by a 5A auto fuse. Features include an external antenna for improved WiFi coverage, dual power input for reliability, spring terminals for easy connections, and a micro-SD card slot for standalone operations. An IR receiver is also included, along with extra connectivity options like access to extra GPIOs and the I2C bus. The controller is also compatible with Xlights, to be used in light shows.
[Esp32-Stick-WLED](https://www.tindie.com/products/allexok/esp32-stick-wled-powering-smart-leds-using-poe/) | PoE-powered ESP32 Ethernet board with 2 smart LEDs and 1 RGB channel, featuring Phoenix connectors. The board includes integrated level shifters and an external antenna connector. A 5V 2.5A output is available, and 3D-printable enclosure files are provided. The boards are shipped with WLED pre-flashed.
[ESP8266 Pixel Controller](https://www.maltepoeggel.de/?site=pixelcontroller) | DIY board for 5V/12V LED strips with TTL or RS485 output using a Wemos D1 mini, integrated fuse, pluggable terminal block, 3D printed module case
[ESPthings.io ET-AL01](https://www.espthings.io/AL01) | DIY board for 5 Analog channels and/or up to 5 Digital LED channels (or a combination of the latter as required), Integrated level shifter, 5v/12/24v compatibility, 4x pull-up/down GPIO, serial interface and power distribution terminals. Can be used with Wemos D1-style ESP8266 or ESP32 boards.
[ESP32 WLED Pico Board](https://www.tindie.com/products/28276/) | ESP32 WLED pico board,super small form factor, ready to buy on [Tindie](https://www.tindie.com/products/28276/) and [Tindie EU](https://www.tindie.com/products/moonmodules/esp32-pico-board-with-digital-microphone/). Integrated level shifter, exposed pins for extending functionality , on board I2S microphone, [Firmware is here](https://github.com/srg74/WLED-wemos-shield/tree/master/resources/Firmware/%40Aircoookie/Latest). Project page is [here](https://github.com/srg74/WLED-ESP32-pico)
[Hikari](https://github.com/goodmicros/hikari) | Pocket-sized, battery powered RGBW light
[HighSet WLED Controller India](https://highset.in/eshop/WLED-India/wled-controller-India) | ESP32 Based Ready to use WLED device for 5V Pixel LEDs with Shift Resistor Pre-Installed & 4 Outputs in Premium Quality Sealed Enclosure, Customized Orders also Welcomed.
[IOT4WLED](https://iot4.eu/product/iot4wled/) | Ready to use hardware for WLED!
[Laterna](https://github.com/Planet-Laterna/Laterna) | Based on an ESP32 for digital LED and RBG/RGBW LED strips with support for 5V, 12V and 24V LED strips. (Up to 4 channels)
[Laterna Mini V3](https://github.com/Planet-Laterna/Laterna-mini-V3) | Small ESP32 based controller with optional digital microphone integrated for digital 5V LED strips.
[Laterna Stick](https://github.com/Planet-Laterna/Laterna_Stick) | USB Stick like ESP32 based controller for digital 5V LED strips.
[LedBox V3](https://stanleyprojects.com/projects/ledbox_v3/) | LedBox V3 by StanleyProjects is the ultimate sound-reactive addressable LED controller powered by ESP32-S3. It is compatible with 5-12V addressable LED strips (WS281x, SK6812, etc.), supporting both 3(data) and 4(data,clock) wire signal protocols. It has a digital MEMS microphone, MOSFET, logic-level converter, button, IR demodulator, variable imedance-matching resistor, USB-C port, and a safety resettable fuse, all in a compact 3D printable case. The board can be purchased [here](https://www.tindie.com/products/stanleyprojects/ledbox-v3/) and comes flashed with [WLED-MM](https://github.com/MoonModules/WLED).
[Luminxa v2.2.2](https://luminxa.com/product/luminxa-2-2-2/) | ESP32 | ESP32 Based board with 12 WS2812 LEDs Onboard (6 on each side) + Gyro Sensor (Business project)
[My Baby's Got LED](https://tindie.com/products/mcqn_ltd/my-babys-got-led/)| [Certified open hardware](https://certification.oshwa.org/uk000030.html). Easy plug-and-play WLED board for those that don't want to figure out the hardware - you won't even need a screwdriver to get started. PC power supply ([ATX](https://en.wikipedia.org/wiki/ATX#:~:text=An%20ATX%20power%20supply%20provides,the%20original%2020-pin%20version.)) powers three 5V injection points on 8A fuses. For sale now on [Tindie](https://tindie.com/products/mcqn_ltd/my-babys-got-led/)! Full details on [the github repo](https://github.com/mcqn/my-babys-got-led) and [maker's website](https://mcqn.com/ibal223/).
[My Bike's Got LED](https://www.tindie.com/products/mcqn_ltd/my-bikes-got-led/)| [Certified open hardware](https://certification.oshwa.org/uk000073.html). Lipo battery version of the above board, designed for portable projects. Based on the ESP C3 mini, with onboard battery charger via USB-C input. Provides 2.5A at 5V for the lights, and has headers available for I2C input for sound reactive projects. For sale now on [Tindie](https://www.tindie.com/products/mcqn_ltd/my-bikes-got-led/)! Full details on [the github repo](https://github.com/mcqn/my-bikes-got-led) and [maker's website](https://mcqn.com/ibal234/).
[QuinLED Dig2go](https://quinled.info/quinled-dig2go/) | Designed to be the quickest and easiest 5v addressable LEDs controller available! Powered simply by using a USB-C input (just like your phone!) for a true plug and play experience. Recommended for small projects up to 15W and very complete with built-in "power cut" circuit when the LEDs are off to minimize idle power consumption, LED data level-shifter, built in protection circuits (including fuses), IR receiver, high quality digital microphone with audio reactive effects and even has some easy to use expansion ports for extra buttons or for instance an I2C screen! All of this is housed in a high-quality custom plastic case (not 3D printed) and small enough to fit in the palm of your hand! Comes ready to go, pre-flashed with WLED and even combined with power supply and/or LED strip in different bundles! [Buy here!](https://dig2go.info/dig2go-buying-page/)
[QuinLED Dig-Octa](https://quinled.info/quinled-dig-octa/) | The Dig-Octa system is for your medium to very large projects! It comes fully pre-assembled and is the ideal board to drive 5v-24v digitally addressable LEDs. The system is composed of brain- and power-boards and is designed to be fully stackable in various configurations of both types of boards, to perfectly adapt to your needs. Some features are: 8 LED data-channels, built-in level-shifters and resistor switchers, Ethernet and external antenna WiFi, auto 5v-24v compatibility, high current handling (up to 50A to 100A!), fully fused inputs and outputs, dedicated relay circuit, I2C temperature sensor, and much more! Comes pre-flashed with WLED and is highly recommended for medium to very large projects. [Buy here!](https://quinled.info/quinled-dig-octa-available-here/)
[QuinLED Dig-Quad](https://quinled.info/quinled-dig-quad/) | **2021 updated version!** DIY/Pre-Assembled board for 4 (5) channel digital LED driving. Integrated level shifters, temperature sensor option, Auto 5v-24v compatibility, pull-up/down GPIO and power distribution terminals with 5x onboard fuses for easy LED power injection. Recommended to use (and comes with) with [custom QuinLED-ESP32](https://quinled.info/quinled-esp32/). Pre-assembled and pre-flashed with WLED [available to buy!](https://quinled.info/pre-assembled-quinled-dig-quad/). Aircoookie's personal recommendation for large-size WLED projects with advanced power and output requirements.
[QuinLED Dig-Uno](https://quinled.info/quinled-dig-uno/) | **2021 updated version!** DIY/Pre-Assembled board for digital LED driving. Integrated level shifters, temperature sensor option, Auto 5v-24v compatibility, pull-up/down GPIO and safety features such as a onboard fuse. Recommended to use (and comes with) with [custom QuinLED-ESP32](https://quinled.info/quinled-esp32/). Pre-assembled and pre-flashed with WLED [available to buy!](https://quinled.info/pre-assembled-quinled-dig-uno/). Aircoookie's personal recommendation for medium-size WLED projects.\
[RGB2Go Duo2Go](https://rgb2go.com/products/duo2go-pixel-controller) | The Duo2Go is a 2-port WiFi pixel controller that comes with WLED pre-installed! Supports a removable ESP8266. Designed specifically with beginners in mind, it is a great way to introduce yourself to this amazing hobby! Two 5A fused outputs are level shifted and uses 33ohm resistors - perfect for use with 3-wire xConnect cables.
[RGB2Go Tetra2Go](https://rgb2go.com/products/tetra2go-4-port-wi-fi-pixel-controller) | The Tetra2Go is a 4-port WiFi pixel controller that comes with WLED pre-installed! Supports a removable ESP32 Mini. Designed specifically with beginners in mind, it is a great way to introduce yourself to this amazing hobby! Four 5A fused outputs are level shifted and uses 33ohm resistors - perfect for use with 3-wire xConnect cables. Also has a built-in expansion header that supports optional modules such as Wired Ethernet, OLED displays, a digital microphone for Audio-Reactive support, a Differential Transmitter with 4 additional outputs, an IR Receiver, and SD Card. Controllers and options available [here](https://rgb2go.com/collections/controllers)
[Simple WLED Board](https://github.com/wladwnt/wled) | Very simple DIY board, minimum of required components, option for 5V/12V LEDs. Easy to solder (no SMT components). Simple to understand connection schematics and pictures. Can be used with ESP8266 or ESP32 in D1 mini Format.
[SJM Electronics rgbw, rgbw2+, rgbw4](https://www.tindie.com/products/sjmelectronics/rgbwx-series-led-controllers/) | Complete, analog and digital controllers for vehicular use. rgbw has one RGBW channel, rgbw2+ has two analog, RGBW channels plus two/four addressable outputs (requires external 5V source for 5V LEDs). rgbw4 has four analog RGBW channels. 2+ and 4 support 12V or PWM/analog inputs and have internal PTC "fuses".
[WiFi Controlled Desk Lamp](https://github.com/stanoba/wifi-desk-lamp) | Open source PCB for WLED
[WLED ESP32 Universal Controller](https://github.com/srg74/WLED-ESP32-universal-controller) | ready to buy on [Tindie](https://www.tindie.com/products/27056/), 100% compatible with WLED project. Integrated level shifter, 2 outputs for LEDs strips, 1 fused out for LED strip, relay for energy-saving, temperature sensor, PWM fan header, USB port for re-programming. Headers for shields to extend functionality. Available [shields for controller is here](https://www.tindie.com/stores/serg74/), [Firmware is here](https://github.com/srg74/WLED-wemos-shield/tree/master/resources/Firmware/%40Aircoookie/Latest/esp32_wled_dev_board).
[WLED Waterproof Controller with external antenna](https://github.com/srg74/Controller-for-WLED-firmware) | DIY board, designed for use outside permanently and for longer range Wi-Fi connection. No SMD components means it is easier to solder for DIYers. 100% compatible with WLED project. Level shifter, fuse for LED strip, resettable fuse for Wi-Fi module, exposed I2C interface for display or sensors, relay for energy-saving and 1-wire temperature sensor. Build around ESP-07S module. [Firmware is here](https://github.com/srg74/WLED-wemos-shield/tree/master/resources/Firmware/WLED_wemos_shield)
[WLED Wemos Mini Shield](https://github.com/srg74/WLED-wemos-shield/tree/master/resources/mini_shield) | shield board, ready to buy on [Tindie](https://www.tindie.com/products/22680/) also [Tindie EU](https://www.tindie.com/products/28777/). Integrated level shifter, 2 outputs for LEDs strips, 1 fused out for LED strip, resettable fuse for the development board, exposed I2C interface for display or sensors. Exposed pins Digital microphones. Works with Wemos D1 mini and D1-style ESP32 boards. [Firmware is here](https://github.com/srg74/WLED-wemos-shield/tree/master/resources/Firmware/WLED_wemos_shield).
[Yet Another WLED Controller](https://github.com/lizardsystems/yawl-controller) | Small and simple device for 5V addressable LED strips with minimum components and fully assembled by PCB manufacturing service in standard case. [Firmware is here](https://github.com/lizardsystems/yawl-controller/tree/main/firmware/WLED)
## Controllers WLED can be installed to
!!! Warning
If the controller does not have a USB port and no firmware supporting wireless updates pre-installed, installing WLED to it requires an FTDI flasher and in some cases, soldering.
| Name | Chip | Description |
|---|---|---|
[ESPixelStick v3](https://forkineye.com/espixelstick-v3/) | ESP8266 | The ESPixelStick V3 is a WiFi Pixel and DMX single output controller built around the ESP8266 platform. It utilizes industry standard E1.31 sACN and DDP protocols for control of up to 680 WS2811 pixels (4 Universes) or 63 GECE Pixels. The output passes through a built-in RS485 transceiver, allowing for driving DMX and differential Renard inputs (or using a differential receiver for long-distance between board and first pixel). The on board switching regulator allows you to power the ESPixelStick with 5V-24V -- Just match the voltage of the pixels you are using, no voltage configuration is required. Note: Does _**not**_ come preconfigured with WLED, you must flash the ESP8266 yourself.
[SP108e v2](https://www.amazon.de/dp/B07KW1W68R) | ESP8285 | Hardware-Modification required and different versions exists! 8285-based 2M Controller that supports addressable RGBWW LED strips, also with CLK line (like ATA102). 5-24v DC input, 85mm x 45mm x 23mm. Vendors list spledapps 'Led Shop' as the supporting mobile application. Board is silk screened with 'SP108e'. No pads are exposed and a second processor is used to control the LEDs. Pin7 of that processor needs to be grounded to hold it in reset state. Then you can connect GPIO0 to GND and TX, RX, VCC, GND for flashing. Connect GPIO2 to R4 for DATA out and GPIO13 to R3 for CLK out. Flashed via PlatformIO, esptool. OTA updates work. Pics of pinout here:
SP501e | ESP8285 | 8285-based 1M Controller that supports both Addressable and PWM-based RGBWW LED strips. _Note that recent versions have 2M._ 5-24v DC input, 55mm x 26mm, sold under BTF lighting, RGBZone, etc. Vendors all list 'Fairynest' as the supporting mobile application. Board is silk screened with 'SP5XXe' but no other markings. Serial pads are exposed on the back-side of the board with GND and GPIO0 right next to each other and thus Flash access fairly straight forward. GPIO 0 must be pulled to GND at boot and throughout the flashing process. I/O configuration: LEDPIN is 'GPIO3' for addressable (note this pin is limited to approx. 250 LEDs), BTNPIN is GPIO 1. PWM pin out for RGBWW: CW: 14, WW: 12, B: 13, R: 15 and G: 4. Flashed via PlatformIO, ESPHome and Tasmotizer. Pics of board here: Flashing Connections:
[SP511e](https://www.aliexpress.com/item/32820185063.html) | ESP8285 | An ESP8285 2MB controller with 3 case buttons, built in mic, IR receiver, 38 key remote, and dual outputs. The dual outputs are connected to the same data pin. There is a step-by-step guide for [Installing WLED on SP511E Controller](https://github.com/scottrbailey/WLED-Utils/blob/gh-pages/sp511e_wled.md).
[SP530e](https://www.aliexpress.com/item/1005006472928868.html) | ESP32-C3 | ESP32-C3 based Controller that supports both Addressable and PWM-based RGBWW LED strips. 5-24v DC input, sold under BTF lighting, RGBZone, etc. Vendors all list 'BanlanX' as the supporting mobile application. Board is silk screened with 'SP530e' but no other markings. Serial pads and GPIO9 are exposed on the back-side of the board. GPIO 9 must be pulled to GND at boot to enter flashing mode. I/O configuration: LEDPIN is 'GPIO19' for addressable LEDs, BTNPIN is GPIO 8, MIC is GPIO3, On-board LEDS are GPIO0 and GPIO1. PWM pin out for RGBWW: WW: 4, CW: 5, R: 10, G: 7 and B: 6. Level shifter used: SN74HCT245 - Warning, the flash is *encrypted* - be sure to specify the `-encrypt` flag when flashing with `esptool.py`. Each device has a unique flash encryption key, but the devs forgot to burn the 'disable UART download' efuse, which means that any non-encrypted firmware can be flashed onto the device, and the device will encrypt the firmware on the first boot. Before flashing, please back up the original firmware of the device with esptool.py `esptool.py read_flash 0 0x400000 sp530e-encrypted.bin`. Pics of board and the flashing connector here: - Sample flashing command: `esptool.py write_flash --encrypt 0x0 C3_bootloader.bin 0x8000 C3_partitions_4M.bin 0x10000 WLED_0.15.0-b3_ESP32C3_4MB.bin`.
[ESP LED Strip WIFI Control Board [ESP Version]](https://www.electrodragon.com/product/esp-led-strip-board) | ESP8266 | Controller for addressable or analog LEDs (RGBW), 6-27VDC input, no level shifter, reset and boot buttons, enclosure. NOTE: Although this uses high-current transistors, they used jumpers on two of the connections so you are limited to their current rating (3A?).
## WLED shields to be use with ESP8266/ESP32 controller boards
| Name | Description |
|---|---|
[ABC! WLED ESP32-P4 Shield, for Waveshare ESP32-P4 nanon board](https://shop.myhome-control.de/ABC-WLED-ESP32-P4-Shield/HW10027) | Commercial WLED Shield. Up to 16 outputs, 4 protected inputs, 4x RS-485 outputs. Integrated line-in-to-I2S Adapter for sound reactive WLED. Enclosure is available too. ATTENTION: WLED software for the ESP32-P4 controller is currently in a very early experimental stage. This [experimental fork on GitHub](https://github.com/troyhacks/WLED/tree/P4_experimental) can be compiled and used. Many features are still far from being fully developed. This shield is therefore only recommended for those who enjoy experimenting and/or want to contribute to the development of WLED on an ESP32-P4 controller. See this [Reddit post](https://www.reddit.com/r/WLED/comments/1nwnsws/announcing_wledmmp4_wled_moonmodules_on_the/) for more information.
[Analog CCT Shield](https://www.tindie.com/products/sjmelectronics/analog-cct-driver-shield/) | Shield for analog single or dual (CCT) LED strips. Compatible with Seeed Studio C3 ESP boards.
[Logic Level Converter Shield](https://www.tindie.com/products/sjmelectronics/logic-level-converter-shield/) | Shield with two, level-shifted, addressable LED outputs that have switchable data-line resistors. Compatible with Mini D1 or Seeed Studio C3 ESP boards.
[WLED Wemos shield](https://github.com/srg74/WLED-wemos-shield) | shield board, ready to buy on [Tindie](https://www.tindie.com/products/22307/) also [Tindie EU](https://www.tindie.com/products/28787/) or DIY 100% compatible with WLED project and WLED [sound reactive fork](https://github.com/atuline/WLED). Integrated level shifter, 4 outputs for LEDs strips, 1 fused out for LED strip, resettable fuse for the development board, exposed I2C interface for display or sensors, relay for energy-saving and 1-wire temperature sensor. Exposed pins for Analog and Digital microphones. Works with Wemos D1 mini and D1-style ESP32 boards. [Firmware is here](https://github.com/srg74/WLED-wemos-shield/tree/master/resources/Firmware/%40Aircoookie/Latest/universal_shield).
## Other products WLED can be installed to
| Name | Chip | Description |
|---|---|---|
[Athom 15W bulb](https://www.athom.tech/blank-1/15w-color-bulb) | ESP8266 (2M flash) | 15W bulb with RGB, warm white, and cold white LEDs. Compatible with all voltages, available form factors E27, B22 and [GU10](https://www.aliexpress.com/item/1005008638498454.html)
[Athom 12W bulb](https://www.athom.tech/blank-1/wled-12w-color-bulb) | ESP32C3 (4MB flash) | 12W bulb with RGB, warm white, and cold white LEDs. Compatible with all voltages.
[Merkury MI-BW210-999W](https://www.walmart.com/ip/Merkury-Innovations-A21-Smart-Light-Bulb-75W-Color-LED-2-Pack/669037420) | ESP8285 | Tuya Style WiFi Led light bulb, Warm White + RGB. There are two versions of this same bulb sold in the same packaging only way to check is to look at the bulb, EBEQPW92 uses PWM led control and is compatible with WLED however EBEQPW06 uses an SM16716 chip and is not currently compatible with WLED. Managed to flash using tuya-convert and a custom WLED build with the following analog pinout: B:4, G:5, R:13, W:14. Extras disabled to allow OTA, OTA only way to flash this, programming headers are not internally available.
[Shelly RGBW2](https://shelly.cloud/wifi-smart-shelly-rgbw-2/) | ESP8266 | For "analog" LED use only! Runs on 12-24VDC. One button and one input. Pins: R=12, G=15, B=14, W=4. _Finished, commercial product that can be flashed._ [More info and flashing docs](https://tasmota.github.io/docs/devices/Shelly-RGBW2/#serial-connection)
## Raw ESP8266/ESP32 boards
!!! tip
While these can work like the controllers above without extra hardware, you might get flickering without adding an external levelshifter. Using them without a controller board/shield is only recommended if you like tinkering with electronic projects.
| Name | Chip | Description |
|---|---|---|
[Adafruit Feather Huzzah](https://learn.adafruit.com/adafruit-feather-huzzah-esp8266) | ESP8266 | General-purpose ESP8266 Board with USB, battery connector, etc.
[D1 mini-style ESP32](https://acrobotic.com/products/acr-00024) | ESP32 | A nice compact ESP32 development board. D1 mini compatible layout.
ESP-01 | ESP8266 | One of the first and cheapest ESP8266 boards available. **_Not recommended for general WLED installs_** (needs external USB/serial chip, voltage converter, only has 1mb of flash, so soon no wireless updates possible)
[ESP32 DevKitC v4](https://www.digikey.com/product-detail/en/espressif-systems/ESP32-DEVKITC-32D/1965-1000-ND/9356990) | ESP32 | The original ESP32 Development Board made by Espressif Systems.
[ESP32-C3 Super Mini](https://www.aliexpress.us/item/3256805781327184.html) | ESP32-C3 | Very compact, easy to flash with the USB-C port, can support 3A over the USB-C connector. Extremely cheap, but only has one core so there's a small stutter during Wifi communication. Be careful purchasing! Some stores sell a version that has [crippling Wifi strength issues](https://github.com/DedeHai/WLED-ESPNow-Remote/blob/main/images/C3_good_bad.jpg).
[ESP32 Mini Dev Board 16mb by SerKo (aka Serg)](https://www.tindie.com/products/28858/)| ESP32 | ESP32 Dev Board with latest WROOM-32E module, USB Type-C, PTC fused, over-voltage protection. D1 Mini32 form factor and compatible [pin out](https://github.com/srg74/WLED-wemos-shield/blob/master/resources/ESP32_mini/Resources/ESP32_mini_board_pinout.pdf)
[H803 WiFi](https://github.com/srg74/WLED/wiki/H803WiFi) | ESP8266 | ESP8266EX based controller with level shifter inside. Data pin GPIO1 Clock pin GPIO14. Tested with WS2813 strip and [Firmware fork is here](https://github.com/srg74/WLED/tree/H803WF).
[Heltec WiFi Kit 8](https://heltec.org/project/wifi-kit-8/) | ESP8266 | Another alternative of ESP8266 board. OLED display 128X32 pixel, battery charger on board. Almost the same functionality and price as the Wemos board. Plus it can be used in projects with external batteries.
[Lolin32 Lite](https://www.aliexpress.us/item/3256806000205489.html) | ESP32 | Low cost ESP32 board optimized for battery usage. Does not have a 5v pin but can be powered with 5v on battery connector.
[NodeMCU](https://github.com/nodemcu/nodemcu-devkit-v1.0) | ESP8266 | Another popular ESP8266 development board. A bit bigger than the D1 and has pins pre-soldered. There are multiple versions with slight differences, not all are tested.
NodeMCU-32s | ESP32 | The most common ESP32 development board. Works well, depending on the board you might have to press the "Boot" button while USB flashing
[Olimex ESP32 POE](https://www.olimex.com/Products/IoT/ESP32/ESP32-POE) | ESP32 | Ethernet (PoE) and WiFi, though usage of the ethernet port requires a custom compile. The PoE should not be used to power LEDs due to a maximum throughput of 4W. For most installations, standard ethernet should be used, supplying power through the 5V pin.
[QuinLED-ESP32](https://quinled.info/quinled-esp32/)| Custom design D1 Mini32 formfactor ESP32 module | Fed up with the bad quality of generic ESP32 modules on the market, designed my own "beefed up" version. Available in multiple versions: QuinLED-ESP32-AB (Antenna Board), QuinLED-ESP32-AE (Antenna External), QuinLED-ESP32-ABE (Antenna Board + Ethernet). Aircoookie's recommendation for running WLED.
[RE5V1C](https://www.itead.cc/sonoff-re5v1c.html) | ESP8285 | 5v DC input - onboard 10A relay
[TwilightLord-ESP32](https://www.tindie.com/products/22968/)| ESP32 | ESP32 Dev Board with latest WROOM-32E module, USB Type-C, 800mA LDO, 8MB flash and PTC fused. D1 Mini32 form factor and compatible pin out.[16MB Flash version also available](https://www.tindie.com/products/23037/)
[Wemos D1 mini](https://docs.wemos.cc/en/latest/d1/d1_mini.html) | ESP8266 | An affordable ESP8266 development board. Aircoookie's recommendation for running WLED if you want an ESP8266 board. Current version: 3.1.0
[Wemos D1 mini Pro](https://docs.wemos.cc/en/latest/d1/d1_mini_pro.html) | ESP8266 | A newer development board with an external antenna connector. Works very well with WLED. Recommended if your signal strength is too low with another board. Current version: 2.0.0. Version 1.0.0 has the same form factor as the D1 mini.
[WT32-ETH01](https://www.aliexpress.com/wholesale?&SearchText=wt32-eth01) | ESP32 | **Under development!** Ethernet (non-PoE) and WiFi enabled alternative to the Olimex boards, for 1/4 the cost. Features no PoE, and requires initial flashing of a custom compiled image using a FTDI or similar USB to serial converter.
---
## File: docs/basics/compatible-hardware.md
---
title: Other Hardware
hide:
# - navigation
# - toc
---
!!! note ""
Still under construction, feel free to add to the list!
This page lists some third-party hardware and/or tools that are working with WLED!
Please use a decent and neutral description when adding things to this list.
!!! tip
Lists are in alphabetical order. The position of an item in the list does not indicate how good it is or if it will fit your use case.
Please carefully compare all items in the category you are interested in, and you should find the one that suits your needs best in just a few minutes!
## Useful boards and addons
| Name | Description |
|---|---|
[ABC! WLED PWM Board](https://shop.myhome-control.de/WLED-PWM-Board/HW10024) | This board integrates MOSFETs with additional protection measures (overcurrent, overtemperature, short circuit and reverse polarity) and can be used in combination with any WLED controller to control analogue LED strips. [German shop & shipping within Germany or to Poland.](https://shop.myhome-control.de/WLED-PWM-Board/HW10024)
[ABC! WLED Switch Board](https://shop.myhome-control.de/en/ABC-WLED-Switch-Board/HW10021) | This board integrates self-protected electronic switches (MOSFET based) as modern alternative to relays and can be used to switch off power provided to LEDs in "OFF" state. It also provides overcurrent, overtemperature, short circuit and reverse polarity protection. [German shop & shipping within Germany or to Poland.](https://shop.myhome-control.de/en/ABC-WLED-Switch-Board/HW10021)
[ESP32 Ethernet Network Shield](https://www.tindie.com/products/30385/)| Ethernet Shield (10/100Mbps) for ESP32 boards. Stackable with D1 Mini32 form factor boards.
[Logic Level Shifter Board](https://www.tindie.com/products/sjmelectronics/logic-level-converter-level-shifter) | A simple level shifter board. Updated version has selectable data-pin resistors.
[Logic Level Shifter Shield](https://www.tindie.com/products/sjmelectronics/logic-level-converter-shield)| Logic level shifter shield for Seeed Studio ESP32-C3 and D1 Mini format dev boards. Updated version has selectable data-pin resistors.
[MagWLED-1](https://magwled.com) | ESP32-C3 based WLED controller with USB-C Power Delivery (up to 36W/12V 3A). Compact 48x32mm form factor with Wago 2060 connector. Features include 3A resettable fuse, ESD protection, and MOSFET relay for power control. Comes pre-flashed with WLED.
[WIZmote remote control](https://www.google.com/search?q=wizmote) | Remote control using radio network. Compatible with WLED (versions 0.14.0-beta3 and above). No additional receiver required.
## Compatible PC RGB Fans and ARGB accessories
| Brand | Model | Comments |
|---|---|---|
Corsair | HD120 Fan | Uses WS2812B, data-in only
PCCOOLER | Moonlight 5-pack Fans | Uses WS2812B, includes Data-out connector to keep each fan uniquely addressable if wired in series like traditional LED strips
Any | 5v 3-pin ARGB for PC | Any PC RGB device that supports the 5v 3-pin ARGB motherboard header should work fine with WLED. All the major motherboard vendors support the Corsair HD120 and PCCOOLER fans listed, so we can safely assume any device that supports motherboard ARGB 5V 3-Pin standard will work with WLED.
## Levelshifters
| Name | Description |
|---|---|
SN74AHCT125 | Aircoookie's recommended levelshifter. Often used in DIY and commercial controllers. [sjm Level Shifter Board](https://www.tindie.com/products/sjmelectronics/logic-level-converter-level-shifter)
SN74AHCT32 | Same pinout as above can be used. This is just an OR gate, but any AHCT gate can be used if inputs are connected appropriately. ;)
SN74HCT125N | Slower, cheaper version. Works just as well for WS2812, but not recommended for APA102.
SN74LVC2T45 | Modern bus transceiver with voltage translation [Yet Another WLED Controller](https://github.com/lizardsystems/yawl-controller)
Amplifier/Splitter | These have been tested and do work. [More info here.](https://discord.com/channels/473448917040758787/719873873071308821/1278797679656439849) - [Example product](https://www.amazon.com/BTF-LIGHTING-WS2812B-Amplifier-Support-addressable/dp/B0B5ZSSFR7)
TXS0102, TXS0108 | Not recommended: these bidirectional levelshifters do work but only for short data lines (less than 50cm).
[F-Amp](https://pixelcontroller.com/store/accessories/54-famp-xconnect.html) | Level shifter/data booster
Adafruit Shifter | https://www.adafruit.com/product/6066
!!! warning
I2C shifters are generally too slow for addressable LEDs, so don't use them.
If you must: there is a [hack to make them work on short data lines](https://wled.discourse.group/t/levelshifter-analysis/11871/12)
Further reading:
[Logic Level Shifters for Driving LED Strips](https://electricfiredesign.com/2021/03/12/logic-level-shifters-for-driving-led-strips/)
How to connect Levelshifters:
## USB/TTL adapters
| Name | Description |
|---|---|
[CH340](https://www.aliexpress.com/item/32761423124.html) | CH340 module instead of CP2102, PL2303 or FTDI/FTDT. The CH340 can deliver more current which is needed while the flash process depending on the board type. The timing is also much more stable. **For boards with a USB/TTL adapter onboard this is NOT needed**
[ESP uploader](https://github.com/srg74/ESP-uploader) | CP2102N module. Same USB to UART converter as many recent Dev boards using. Featuring latest USB-C connector. For use with many ESP32, ESP8266, ESP8255 and Tuya based modules. 3.3V logic and 5V power pass through for custom boards.
## Miscellaneous
Sorting: Sensors, Displays, Actuators
| Name | Description |
|---|---|
[HC-SR501](https://www.aliexpress.com/wholesale?catId=0&SearchText=HC-SR501) | PIR sensor with adjustable sensitivity and on time delay (suitable as a button).
[HC-SR602](https://www.aliexpress.com/wholesale?catId=0&SearchText=HC-SR602) | PIR sensor (not suitable as a button but can be used with _PIR sensor_ usermod).
[TSOP38238](https://www.aliexpress.com/item/32834341300.html) | IR receiver compatible with most IR remotes.
[SSD1305](https://www.aliexpress.com/wholesale?catId=0&SearchText=SSD1305) | I2C display, can be used with [_4 Line Display_ usermod](https://github.com/wled/WLED/tree/master/usermods/usermod_v2_four_line_display).
[SSD1306](https://www.aliexpress.com/wholesale?catId=0&SearchText=SSD1306) | I2C & SPI display, can be used with _4 Line Display_ usermod.
DS18B20 | Recommended temperature sensor for use with WLED. Compatible with the [Temperature usermod](https://github.com/wled/WLED/tree/master/usermods/Temperature)
[Display shield](https://www.tindie.com/products/27112/) | Various configurations. Compatible with the [ESP32 WLED dev board](https://www.tindie.com/products/27056/) also can be used with ESP32 mini dev boards.
[12V Relay & Fuse board](https://shop.myhome-control.de/Relais-Board-fuer-WLED-Controller-12V/HW10011)|Integrates two relays and two 10 A fuses. Suitable for WLED setups with 12 V LED Strips.
[5V relay](https://www.aliexpress.com/wholesale?catId=0&SearchText=5v+relay+module) | Relay module. Some will require 5V to trigger so you will need level-shifted output (similar as for LEDs) for proper functionality or a circuit with transistor or MOSFET.
[5V Relay & Fuse board](https://shop.myhome-control.de/Relais-Board-fuer-WLED-Controller-5V/HW10005)|Integrates two relays and two 10 A fuses. Suitable for WLED setups with 5V LED Strips.
---
## File: docs/basics/compatible-led-strips.md
---
title: Compatible LED strips
hide:
# - navigation
# - toc
---
WLED supports two types of LED strips: the so-called digital addressable LED strips and the so-called analog non-addressable LED strips.
## Addressable LED Strips
Addressable LED Strips allows to control individual LEDs separately. This enables you to use many effects. The supported types are listed below. There are sometimes new types coming onto the market that have a compatible control protocol.
Sorting: 5v data only, 5v Data + Clock, 12v data only
| Type | Voltage | Comments |
|---|---|---|
SK6812 | 5 V / 12 V | RGBW
WS2811 | 5 V / 12 V | usually found in IP68 sealed 12mm pixel strings
WS2812B | 5 V |
WS2813 | 5 V | has a backup data line
APA102 | 5 V | using 2 data pins, Clock and Data
LPD8806 | 5 V | using 2 data pins, Clock and Data
WS2801 | 5 V | using 2 data pins, Clock and Data
SK9822 | 5 V | using 2 data pins, Clock and Data
UCS8903 | 5 V |
GS8208 | 12 V |
TM1814 | 12 V | RGBW
WS2805 | 12 V / 24 V | RGBCCT, 3-LED groups (12V) / 6-LED groups (24V) as one logical LED. Backup data line. Two white channels for Correlated Color Temperature (CCT) (this option is available since WLED 0.15.0-b2)
WS2811 | 12 V | usually 3-LED segments, has data-line resistor
WS2814 | 12 V / 24 V | RGBW, 3-LED groups (12V) / 6-LED groups (24V) as one logical LED. Must be controlled as SK6812 type, color order: BRG, swap W and G (this option is available since WLED 0.14.0-b1)
WS2815 | 12 V | has a backup data line
FW1906 | 24 V | RGBCCT, 6-LED groups as one logical LED. Two white channels for Correlated Color Temperature (CCT) (this option is available since WLED 0.15.0-b2)
LPD6803 | 12 V |
P9813 | 5-24 V |
TM1829 | 5-24 V |
UCS8904 | 5-24 V | RGBW
## Non-Addressable LED Strips
WLED supports non-addressable LED strips as well. Unlike addressable strips, non-addressable strips require a pin for each "color" channel and all LEDs are controlled the same way. To drive these strips, additional circuits (MOSFETs) are required. Basic circuit diagrams for RGB strips are shown here. You need one MOSFET and one GPIO per color. MOSFETs can fail very quickly if overloaded. To reduce the risk of fire and prevent personal injury, additional circuit elements should be implemented to protect MOSFETs from overtemperature and overload. Depending on the type, fuses are too slow for this! You might consider using self-protected MOSFETs too or the entire MOSFET circuit can be packed into a fire-retardant (e.g. metallic) housing.
Recommended MOSFETs are IRLZ44N or STP55NF06L. A much smaller SMD alternative is the AO3400 which can be used up to 24V and 3A. The pulldown resistor from **G**ate to **S**ource prevents the LEDs turning on when the GPIO is disabled or powered down. The resistor between the GPIO and the **G**ate protects the GPIO from overload and reduces voltage ringing. To increase switching speed, add a SN74(A)HCT125 [level shifter](/basics/compatible-hardware#levelshifters) between GPIOs and gate-resistors.
As of v0.13.1, WLED supports single color, CCT, RGB, RGBW and RGBCCT strips. These strips are commonly found at 12 or 24 volts.
The default PWM frequency for dimming is 880 Hz on ESP8266 and 19531 Hz for ESP32.
_See **NOTE** at the end before trying the below amplifiers._
The commercially available so-called RGB(W) LED amplifiers can also be used (also called repeaters/boosters). These typically include optocouplers and MOSFET circuitry (1 to 5 channels) and can be used, for example, as follows:
There is no GND connection between the controller and the amplifier. Unlike most other WLED circuits, the grounds stay separate here because the inputs of the amplifier are galvanically decoupled from the outputs by optocouplers, and the amplifier in this circuit is used slightly differently than in its usual application.
You can connect the GPIOs directly (3.3V signal level) to the input of the amplifier or, if you use a ready-made WLED controller, you can also use the data outputs (of the level shifter, i.e. 5 V signal level). You can also use both at the same time:
The amplifier shown in the picture is a cheap product. Its advantage is a metal case. However, its circuit is very simple:
The simple structure means that the duty cycle of the PWM signal (the ratio between pulse and period duration) at the output is slightly distorted compared to the input. In many cases this is not critical, but it does result in the color composition of an RGB strip being slightly distorted. A significantly better (and slightly more expensive) version is described in [this article (in German, includes schematics)](https://media.elv.com/file/143195_led_rgbw_repeater.pdf). Here the MOSFETs are controlled with push-pull drivers. This and some other measures in the circuit mean that the PWM signal is reproduced very accurately at the output.
**NOTE 1:** Meanwile there is another version of the same amplifier in the same housing on the market that does not have optocouplers and therefore can not be used as describe above (will destroy your WLED controller!).
**NOTE 2:** There are some other types of LED amplifiers on the market (e.g. MiBoxer RGBW amplifiers and similar ones) that DO NOT work as described above because they require higher input voltage.
---
## File: docs/basics/compatible-software.md
---
title: Compatible Software
hide:
# - navigation
# - toc
---
!!! note ""
Still under construction, feel free to add to the list!
This page lists some third-party software that can interface with WLED!
## Controllers
Controllers use the WLED API to change the current light settings.
| Name | Description |
|---|---|
[Home Assistant](https://www.home-assistant.io/integrations/wled/) | Versatile and feature rich home automation system. Out-of-the-box WLED integration with automatic discovery.
[Homey pro with the D.A.L.O.R App](https://homey.app/en-us/app/com.sdn.neopixel-on-rest/D.A.L.O.R/) | Home automation system, WLED integration via the D.A.L.O.R. app with automatic discovery.
[ioBroker adapter](https://github.com/iobroker-community-adapters/ioBroker.wled) | Versatile and feature rich home automation system. Out-of-the-box WLED integration with automatic discovery.
| [Lumia Stream](https://lumiastream.com/) | Allows for control of your lights from streaming software |
| [node-red-contrib-wled](https://flows.nodered.org/node/node-red-contrib-wled) | [Node-RED](https://nodered.org) nodes for WLED |
| [OctoPrint-WLED](https://plugins.octoprint.org/plugins/wled) | Connect your [OctoPrint](https://octoprint.org) install to your WLED install using this plugin to show things like printer status, progress and more! |
[openHAB](https://community.openhab.org/t/wled-a-binding-for-controlling-led-strips-and-strings-from-an-opensource-esp8266-project/87286) | Another more professional feature rich home automation system. WLED integration made easy. [Link 2](https://community.openhab.org/t/solved-wled-please-make-this-work-in-openhab/82783) |
[WLED-GUI](https://github.com/w00000dy/WLED-GUI) | This is a cross-platform desktop app for WLED. You can use it on Windows, Linux and Mac.
[WLED Client](https://github.com/bangboomben/wled-client) | Windows desktop app that puts all your WLED devices in one window: colors, effects with palette previews, segments, presets and playlists. A tray quick access controls power and brightness of every light. English and German, with automatic updates.
[WLED for Android](https://play.google.com/store/apps/details?id=ca.cgagnier.wlednativeandroid) [WLED for iOS](https://apps.apple.com/us/app/wled-official-app/id6446207239) | The official WLED mobile app, with automatic discovery of the devices on your network. Sources: [Android](https://github.com/Moustachauve/WLED-Native-Android), [iOS](https://github.com/Moustachauve/WLED-Native-iOS/).
[wledQuickControl](https://github.com/satrik/wledQuickControl) | macOS 11.0+ Menu Bar app for controlling power and brightness.
[WinLED](https://github.com/clusterzx/WinLED) | Windows App for controlling WLED Instance (Brightness, Power, Presets, Effects...). Also usable from Traybar for quick actions.
## Sources
Source programs generate light data and stream them to WLED in real time.
| Name | Description |
|---|---|
[LedFx](https://github.com/LedFx/LedFx) | A music visualization tool written in Python. Connects to WLED via E1.31 or UDP. [Dr.Zzs tutorial video](https://www.youtube.com/watch?v=ipSfQdfX4fE)
[Prismatik WLED-WiFi](https://github.com/psieg/Lightpack) (native) | Ambilight via WiFi or serial - natively supports UDP (WARLS, DRGB, DNRGB protocols).
[Prismatik WLED-WiFi](https://github.com/Lord-FEAR/Prismatik-WLED-WiFi) (plugin) | Ambilight via WiFi - a Plugin alternative for Prismatik WLED support.
[xLights](http://xlights.org/) | xLights is a Light Sequencer and Show scheduler which works with WLED. Dr.Zzs has made some videos to set it up. [Intro Video](https://www.youtube.com/watch?v=p7wV6A26Gak)
[Hyperion.ng](https://hyperion-project.org/) | Hyperion is an open-source Bias or Ambient Lighting implementation which you might know from TV manufacturers. It supports many LED devices and video grabbers. Support for WLED through UDPraw at port 19446 or E1.31. [Tutorial video](https://www.youtube.com/watch?v=SudT6AjwwOM), [Dr.Zzs video](https://youtu.be/urOEHzbV48A?t=649)
[Hyperion (Classic)](https://hyperion-project.org/) | Hyperion is an open-source Bias or Ambient Lighting implementation which you might know from TV manufacturers. It supports many LED devices and video grabbers. Support for WLED through UDPraw at port 19446 or E1.31.
Enigmalight | Ambilight clone for broadcom based linux receivers. It supports many LED devices. Support for WLED through USB Adalight/Momo. Download to various forums use the WEB search function of your browser.
[Q Light Controller+](https://www.qlcplus.org/) | QLC+ is a free and cross-platform software to control DMX or analog lighting systems like moving heads, dimmers, scanners etc. QLC+ runs on Linux, Windows (XP+), macOS (10.7+) and the Raspberry Pi. WLED can be used with E1.31 (sACN). use major version 4, as 5 is in development.
[RustyLights](https://github.com/appliedapp/rusty_lights) | Resource-efficient audio-reactive LED visualizer written in Rust. Captures audio, processes it through a DSP pipeline, and outputs to LED strips via E1.31/sACN, DDP, or Art-Net. Designed to run on a Raspberry Pi with sub-5% CPU usage.
## Various
| Name | Description |
|---|---|
[Logitech WLED Sync](https://github.com/hkayy/Logitech-WLED-Sync) | Windows tray application to sync Logitech gaming peripherals to WLED.
---
## File: docs/basics/faq.md
---
title: FAQ
hide:
# - navigation
# - toc
---
!!! tip ""
This page will continually get updated with questions often asked.
## Contents
### Installation
- [What binary should I use?](#what-binary-should-i-use)
- [I've flashed a bin, but i get no response at all](#ive-flashed-a-bin-but-i-get-no-response-at-all)
### Connection issues
- [Once I attach LEDs, I can't connect to the ESP anymore!](#once-i-attach-leds-i-cant-connect-to-the-esp-anymore)
- [I have entered my WiFi credentials and rebooted, but I can not connect to the module now!](#i-have-entered-my-wifi-credentials-and-rebooted-but-i-can-not-connect-to-the-module-now)
- [The module once was connected, but I can no longer reach it.](#the-module-once-was-connected-but-i-can-no-longer-reach-it)
- [The wled-xxx.local address (mDNS) does not work.](#the-wled-xxxlocal-address-mdns-does-not-work)
- [Is it safe to expose WLED to the public internet to control the lights from anywhere?](#is-it-safe-to-expose-wled-to-the-public-internet-to-control-the-lights-from-anywhere)
- [My device is unresponsive or animations lag!](#my-device-is-unresponsive-or-animations-lag)
- [I'm having a bootloop! (LEDs turn on every ~5seconds)](#im-having-a-bootloop-leds-turn-on-every-5seconds)
- [I am running realtime (e.g. E1.31) and not all of my LEDs are driven fluently!](#i-am-running-realtime-eg-e131-and-not-all-of-my-leds-are-driven-fluently)
- [Still having connection issues/connection dropping: what more can i check?](#still-having-connection-issuesconnection-dropping-what-more-can-i-check)
### Compilation issues
- [When compiling WLED in VS Code using platformio, I get an error.](#when-compiling-wled-in-vs-code-using-platformio-i-get-an-error)
### LED issues
- [My LEDs don't turn on at all.](#my-leds-dont-turn-on-at-all)
- [My LEDs don't get as bright as they should!](#my-leds-dont-get-as-bright-as-they-should)
- [My LEDs are unable to be set into a consistent solid color.](#my-leds-are-unable-to-be-set-into-a-consistent-solid-color)
- [When I select green, the LEDs turn red!](#when-i-select-green-the-leds-turn-red)
- [My LEDs act funny and flicker randomly.](#my-leds-act-funny-and-flicker-randomly)
- [Not all my LEDs turn on.](#not-all-my-leds-turn-on)
- [How to turn off the bright blue onboard LED?](#how-to-turn-off-the-bright-blue-onboard-led)
- [Why is gpio2/D4 the default LED pin?](#why-is-gpio2d4-the-default-led-pin)
- [Why can I only use 500 LEDs on the ESP8266 GPIO pin 3?](#why-can-i-only-use-500-leds-on-the-esp8266-gpio-pin-3)
- [What LED strip hardware is supported by WLED?](#what-led-strip-hardware-is-supported-by-wled)
### General questions
- [What does the name WLED mean?](#what-does-the-name-wled-mean)
- [What do the WLED version names mean?](#what-do-the-wled-version-names-mean)
- [What is the difference between the brightness sliders in the web UI?](#what-is-the-difference-between-the-brightness-sliders-in-the-web-ui)
- [My Segments are gone after a reboot!](#my-segments-are-gone-after-a-reboot)
### Bundling WLED with custom hardware
- [May I sell a product with WLED pre-installed?](#bundling-wled-with-custom-hardware-license)
- [Does "same license" (copyleft) apply to my hardware design?](#does-same-license-copyleft-apply-to-my-hardware-design-schematics-pcb-layout-enclosure-etc)
- [What if I add a custom usermod or new feature to the WLED firmware?](#what-if-i-add-a-custom-usermod-or-new-feature-to-the-wled-firmware)
### My question or solution is not on this page
- [Check out the WLED forum!](https://wled.discourse.group/)
- [Look through the Issues](#look-through-the-issues)
- [If I report a new Issue, what do i need to share?](#if-i-report-a-new-issue-what-do-i-need-to-share)
## Installation
### What binary should I use?
Please see [this page](/basics/install-binary#what-binary-should-i-use).
### I've flashed a bin, but i get no response at all
Some users report first erasing the flash (yes, even on a new device) sometimes helps .
## Connection issues
### Once I attach LEDs, I can't connect to the ESP anymore!
The gpio2/D4 pin needs to be high (pullup) at powerup time for the controller to boot successfully.
If you accidentally connected the strip the wrong way (if it has arrows printed on, make sure they face away from the pin, otherwise pay attention to the DIN printing). Most strips have the 3-pin male JST connector with 3 holes on the input side. Some users have reported troubles booting even with the direction being correct. In that case, please try adding a 3.3 or 4.7kOhms resistor between the data pin and 3v3 pin!
### I have entered my WiFi credentials and rebooted, but I can not connect to the module now!
If you did not enter a static IP, the module will automatically obtain a dynamic IP from the router.
You can check it in the router configuration or in the settings page, if the Access Point is still enabled.
An easier way is to use the WLED app, for [Android](https://play.google.com/store/apps/details?id=ca.cgagnier.wlednativeandroid) or [iOS](https://apps.apple.com/us/app/wled-official-app/id6446207239), which features automatic discovery!
### The module once was connected, but I can no longer reach it
First, make sure you can reach the connected WiFi yourself (with another device).
See if you can connect to the Access Point, then go to **4.3.2.1/reset**.
Else, power-cycle the module manually.
### The wled-xxx.local address (mDNS) does not work
This only works with Apple devices out of the box. You can install Bonjour to make it work in Windows.
For Android there is no convenient way to achieve it, though you can use apps like "Bonjour search" to find the IP.
It is highly recommended that you install the WLED app, for [Android](https://play.google.com/store/apps/details?id=ca.cgagnier.wlednativeandroid) or [iOS](https://apps.apple.com/us/app/wled-official-app/id6446207239), which makes automatic discovery easy!
### Is it safe to expose WLED to the public internet to control the lights from anywhere?
See [Accessing WLED over Internet](/advanced/access-over-internet) page.
### My device is unresponsive or animations lag!
You are probably using too many sync interfaces. Please only enable one of Hue sync or MQTT at a time.
For optimal performance, use two devices and sync them via the UDP notifier.
Maybe you are also using a very high amount of LEDs. 750 is the recommended maximum. If using E1.31 feature on an ESP32, try "Disabling WiFi Sleep" in the WiFi setup section to reduce lag/stuttering of visual effects.
### I'm having a bootloop! (LEDs turn on every ~5seconds)
Please open an issue or message me on Discord to resolve your issue. Most of the time, wiping the flash (Arduino IDE compile setting: Erase flash -> All flash contents) resolves the issue. Unfortunately it will also reset all your settings and presets. You can also try if using a different ESP resolves the issue. If you compiled with lwip version 2, try version 1.4 Higher Bandwidth instead!
### Still having connection issues/connection dropping: what more can i check?
Try disabling "Emulate Alexa device" in Sync settings before entering your home Wifi credentials.
Check whether mDNS is on or off and toggle it: does it make a difference? Same for 'NTP'. Same for 'Sync Send'. Check your router: is your 2.4Ghz on band 1: if not, try it please. If you have the possibility to try another 8266, please try it.
### I am running realtime (e.g. E1.31) and not all of my LEDs are driven fluently!
Realtime effect streaming uses a rather large bandwidth as data is transmitted uncompressed. For example, to drive 1000 LEDs at 30 fps, you will need a data rate of 720 kBit/s, which is difficult to achieve with most cheap ESP boards over WiFi.
Even if you split the total amount of LEDs across multiple controllers, your WiFi network could become the limiting factor quickly.
The best way to ensure a low-latency, reliable, fluid stream when using large quantities of LEDs is to invest in a wired Ethernet ESP32 board like QuinLED-Dig boards with ethernet or the Olimex ESP32-POE.
There is a 9 DMX universe limit by default in WLED. You can raise it in line 240 of const.h (E131_MAX_UNIVERSE_COUNT 9) and compile your own binary, but the performance of 2000 LEDs over WiFi will likely not be good unless you use an Ethernet enabled board.
If Ethernet is not an option, decrease your LED count as far as possible, lower the frame rate in the sending software and make sure the WiFi signal reception of the board is good. Even without Ethernet, a board with an external antenna is significantly better than a PCB antenna board.
Furthermore I suggest using the DDP protocol if available in your sender software (available in xLights). DDP has a smaller packet header and because of the reduced overhead the fluidity of your animations will be a bit better.
## Compilation issues
### When compiling WLED in VS Code using platformio, I get an error
Try building again. If the error says the `wled00.ino.cpp` or `.sconsign27.db.dblite` file could not be found, this often helps.
You can also try [this](https://github.com/wled/WLED/issues/361#issuecomment-557818554)!
## LED issues
### My LEDs don't turn on at all.
Please make sure you have connected the strip to GPIO2 and it is sufficiently powered.
### My LEDs don't get as bright as they should!
If the brightness slider in the UI is already at maximum, try checking the auto brightness limiter in the LED settings.
Set the milliamp limit to slightly below the rating of your power supply.
If the LEDs are still too dim or change color towards the end of the strip, there may be a significant voltage drop. Try injecting 5v power at the end or middle of the strip with some appropriate cabling.
### My LEDs are unable to be set into a consistent solid color
If the LEDs should be individually addressable, like the SK6812, but instead they only behave as either RED,GREEN OR BlUE pixels (in a row).
You might not have enabled (settings -> led preferences) "LEDs are 4-channel type (RGBW)" for an RGBW/RGBWW/RGBNW strip.
This behaviour is accompanied by WLED being unable to address all LEDs, if you specify the exact amount of LEDs in the strip.
### When I select green, the LEDs turn red!
Depending on the type of LEDs used, Red and Green or other colors might be reversed. You can change the order in LED settings.
WS2812B and most related chips use GRB, WS2811 uses RGB in most cases.
### My LEDs act funny and flicker randomly
#### Reason 1
If you use an external 5V power supply for your LEDs, please connect the GND of power supply, LEDs, and ESP.
Otherwise, the LEDs can't read the data signal from the ESP.
#### Reason 2
The ESP8266 is a 3.3V microcontroller while the WS2812B LED uses 5V.
I have personally got away with this in most cases, but you should technically add a level shifter.
A string of WS2811 did not work in one case (pure static white).
A possible workaround is chaining a single WS2812B pixel in front and checking "Skip first LED" in the settings.
My recommended levelshifter is the SN74AHCT125N, also used in the QuinLED Dig-Uno board.
If you don't have a level shifter, you can use this creative [workaround](https://hackaday.com/2017/01/20/cheating-at-5v-ws2812-control-to-use-a-3-3v-data-line/).
#### Reason 3
Your data line can only be [so long](https://youtu.be/ZFO_QOBG9Bs?t=657). Try out with less or thicker wire between your data pin on your controller and the LED strip, or add (see video) some voltage booster (which can make even 40m data wire length work ;-)).
#### Reason 4
If they don't flicker, but display funny colors, try switching between RGB/RGBW modes in LED settings.
### Not all my LEDs turn on
#### Reason 1
By default the LED count is set to 30.
If you have more and can power them, go to LED settings and increase the LED count!
Please also enter the milliamp rating of your 5v power supply for optimal brightness in the field below it.
Do not increase the mA number if you power LEDs directly from the 5V pin of the ESP!
See [Multi-strip Support](/features/multi-strip) for maximum recommended LED counts.
#### Reason 2
An LED in your chain may be broken. Try another strip or removing the first LED that doesn't light up. Make sure you are in solid effect mode and the LED count is set high enough first!
### How to turn off the bright blue onboard LED?
On ESP8266, this LED can be very distracting. Unfortunately it can't easily be disabled as it shares the gpio2/D4 pin with the LED output.
It is turned off together with your LEDs (unless they require `Off Refresh` to be active)
Currently there are 3 workarounds:
- Cover the LED
- Remove the LED permanently (desolder or apply pressure with e.g. a flathead screwdriver)
- Use a different `LEDPIN`, although the default is recommended for stable operation
### Why is gpio2/D4 the default LED pin?
Although pins D1 and D2 are usually regarded the best GPIO pins to use in an ESP8266 project, D4 is the default in WLED, despite having two major and one minor drawback. The major drawbacks are the permanently lit blue onboard LEDs and the fact that the pin level needs to be high (pullup) at powerup or the controller will not boot. A minor drawback is that the `Serial1` bus can not be used, but this is irrelevant in most cases, as the USB/serial converter is connected to the other `Serial` interface. The reason for using this pin is that it uses UART hardware driving, which increases stability and decreases CPU overhead especially with larger amounts of pixels.
### Why can I only use 500 LEDs on the ESP8266 GPIO pin 3?
The problem is the DMA hardware driving method used on (just) that pin. It works well, but uses **4x (!)** as much RAM memory as the UART hardware driving on pin 2 and the bitbang driver on all other pins.
### What LED strip hardware is supported by WLED?
The compatible chipsets for the color-coding are
- 1 pin:
- WS2812B (5V)
- WS2811 (12V power, with 5V signal)
- WS2813 (WS2812 with redundant data on 2 wires DI and BI, to resist LEDs failure)
- WS2815 (like WS2813 but 12V), send 5V signal on BI.
- BTF2815 (cheaper 12V)
- SK6813 (redundant like WS2813)
- SK6812 (can support up to 4 colors, commonly GRBW)
- SK6805 (3 colors)
- 2 pins (clock CI and data DI) chips:
- APA102
- SK9822
- WS2801 (uses gpio0 and 2)
- LPD8806
Beside the **digital addressable** LED strips the good old **analog** LED strips are supported, too:
- 4 pins: RGB
- 5 pins: RGBW / RGBWW / RGBCW / RGBNW (RGB + one white channel)
- 6 pins: RGBCT (RGB + 2 white channels) _Note: Support is only for Alexa._
## General Questions
### What does the name WLED mean?
WiFi Lighting Effects Driver. Also it has LED in the name and is similar to the official term for WiFi, WLAN!
### What do the WLED version names mean?
WLED version names are Japanese! Here is a nice list of their meanings:
| Version | Name | Kanji | Meaning |
|---|---|---|---|
0.10 | Namigai | 浪貝 | Geoduck (don't google it!)
0.11.0 | Mirai | 未来 | Future
0.11.1 | Fumikiri | 踏切 | Railroad crossing
0.12 | Hikari | 光 | Light
0.13 | Toki | 時 | Time
0.14 | Hoshi | 星 | Star
0.15 | Kōsen | 光線 | Ray of light
16.0 | Niji | 虹 | Rainbow
17.0 | Kagayaki | 輝き | Brilliance
N/A | Kuuhaku | 空白 | Blank
### What is the difference between the brightness sliders in the web UI?
There are three brightness slider types in the web UI. The white one in the **top bar** is the **master brightness** - it scales down every single color and all effects, palettes and segments by the same factor.
In contrast, the slider **underneath the color wheel only** applies to the **currently selected color** and will not affect the brightness of other colors or Palettes. It is recommended to use this slider only if you like a darker version of a color alongside other, brighter colors. It should not be used to control the overall brightness, so it is preferable to leave it on maximum and instead use the master brightness control.
There is a third brightness slider in each Segment panel. This serves the same purpose as master brightness, but limited to that segment. This does not override the master brightness. Instead, it applies additional downscaling. (If you set both Master and Segment brightness sliders to 50%, the resulting brightness is 25%)
### My Segments are gone after a reboot!
Segments are non-persistent by default. If you want to load your preset at every startup, just do the following:
- Set your segments up as desired
- Go into the Presets tab in the web UI, click the save checkbox and save the config to a new preset. Remember the preset slot number.
- In LED settings, set `Boot Preset` to the preset slot number from the previous step.
This will be improved in a future release, so that you will be able to save multiple segment configurations!
## Bundling WLED with custom hardware (License)
!!! warning "Consult a Lawyer"
This FAQ provides a plain-language summary to help you understand the practical intent of the license. It is *not* legal advice.
If you are building a commercial product, consulting a lawyer familiar with open-source licensing is always a good idea.
WLED is licensed under the European Union Public Licence v1.2 (EUPL-1.2), which is a copyleft ("share-alike") software/firmware license.
|Situation|What you must do|
|---|---|
|Use WLED **privately** (change code, flash your own device, never distribute)|Private tinkering - do whatever you like|
|Selling device with unmodified WLED|Keep copyright notice + license text; provide link to source code|
|Selling device with vanilla WLED + closed-source additions as *separate* software|Your separate software is generally not affected, but the WLED parts must remain open|
|Selling device with modified WLED|All of the above plus publish your modifications as open source (EUPL-1.2 or compatible)|
|Using WLED's name/logo in marketing|Be careful — the license does not grant trademark rights|
### What is NOT affected
* **Hardware** — your schematics, PCB layouts, enclosure designs, and BOM are entirely your own. EUPL is a software license; it has no legal reach over hardware. (This is consistent with all mainstream copyleft licenses: GPL, LGPL, MPL, etc.)
* **Independent software on the same device** — code that runs separately and interacts with WLED only via its documented network interfaces/APIs is generally not considered a derivative work.
* **Changes you keep private** — if you write a usermod but *never* distribute the firmware, you have no disclosure obligation. If it works for you, still consider making a PR and share your changes with the community.
### May I sell a product with WLED pre-installed?
Yes, absolutely! The EUPL-1.2 license explicitly allows commercial use, including selling products with WLED pre-installed. Many companies and individuals do exactly this.
#### What you do NOT have to do
* No permission is needed from the WLED authors to sell your device.
* No need to open-source runtime configuration files (e.g., presets.json, cfg.json) — only actual source code modifications to the firmware, including custom build environments to rebuild the firmware for your device (platformio.ini or platformio_override.ini).
* No need to publish your hardware design, schematic, or PCB layout (the license only covers the software/firmware).
#### What you must do
1. **Provide the copyright notice and license text**: You must include the original WLED copyright notice and a copy of the EUPL-1.2 license with every device or product you sell. In practice, this usually means:
- Making it accessible via the device's web interface (WLED already shows this in its *Info* page), or
- Including it in the documentation (printed or digital), or
- Referring customers to a URL where the license and attribution are clearly published.
2. **Provide (or link to) the source code**: You must make the source code of WLED (in the *exact* version you're shipping) available to your customers — either by including it or by providing a clearly visible link to a public repository (e.g., the official WLED GitHub page or your own fork). This link must **remain working** for as long as you distribute the product.
3. **If you modified WLED: share your changes**. You cannot keep your source code modifications private or proprietary.
4. **Do not remove or hide credits**: Do not strip out the "About WLED" or "Info" pages, the copyright notice, or any attribution to the original authors.
5. **No extra restrictions on your customers**: You cannot add license terms that take away the rights the EUPL gives your customers. For example, you cannot tell your customers "you may not modify this firmware" — the EUPL already grants them that right.
### Does "same license" (copyleft) apply to my hardware design — schematics, PCB layout, enclosure, etc.?
No. The EUPL-1.2 is a software license. Its copyleft clause only covers the software (the firmware source code and its derivatives). It has no effect on your hardware.
Your schematics, PCB layout files, bill of materials, enclosure designs, and any other hardware-related work are entirely your own. You can keep them proprietary, patent them, or license them however you like. The EUPL does not require you to share or open-source any of that.
### What if I add a custom usermod or new feature to the WLED firmware?
If you flash a modified version of WLED onto your devices *and* distribute them, you must publish your additions/changes as open source under EUPL-1.2 (or a compatible license such as GPL v2/v3, LGPL, MPL 2.0, etc.). You can publish your own fork on GitHub or any other public platform. You cannot keep it private or sell it as proprietary software.
## My question or solution is not on this page
### Check out the WLED forum!
You can check out and use [the WLED Discourse forum](https://wled.discourse.group).
### Look through the Issues
Maybe someone already reported your issue, so everybody supplying support would be grateful if you take some time to [search through the existing issues](https://github.com/wled/WLED/issues).
### If I report a new Issue, what do i need to share?
When you create a ticket, please share:
- exact controller, maybe a link to the shop you bought it from
- LED-strip type and amount of LEDs
- Specifications of your power supply (max. current/voltage)
- how you wired up all components (a diagram and/or picture often helps)
- the BIN-file you tried to flash (version and file name) or your IDE version if compiling from source
- Have you followed the quick start and compile settings at ?
- Has it worked before?
- Does it works without any LEDs connected? (for instance the controller just connected to your PC over USB)
- Are you using/trying to use DHCP or static IP?
- Did you try to use a mobile hotspot instead of your WLAN AP/home wifi?
---
## File: docs/basics/getting-started.md
---
title: Quick Start
hide:
# - navigation
# - toc
---
## Welcome to the WLED Wiki!
Say hi to Akemi, the WLED mascot. She marks extra information throughout these docs. Click her any time you want to know more. (1)
{ .annotate }
1. For a new project, an ESP32 is the better pick. It's much more capable hardware, and ESP8266 support is coming to an end.
### Quick Start Guide
**1.** Connect your LED strip to your ESP board. A digital strip is three connections at its simplest: power, data, and ground. Analog strips need a channel per color instead. The diagrams below show the extras worth adding.
=== "Digital LED Strips"
Also called addressable strips, for example WS2812B-compatible RGB(W) strips. Each LED can be controlled separately.
For ESP32 use `GPIO16` (or `IO16` or `G16`); GPIOs `4`, `13` and `16-33` can be used, other pins are not recommended.
For ESP8266 use `GPIO2`, on most development boards this pin is labeled `D4`. (1)
{ .annotate }
1. `GPIO1` and `GPIO2` are the recommended LED data pins on ESP8266, and `GPIO3` works for up to 100 LEDs. Other pins need _bit-banging_, which can slow performance and cause problems elsewhere such as with IR decoding. For clock-and-data LEDs, hardware SPI uses `GPIO14` (SCLK) for clock and `GPIO13` (MOSI) for data, and software SPI works on any pins. All pins can be changed in the Hardware section of LED settings.
_If the connecting wire cannot be kept short, use a [level shifter](/basics/wiring-guides#levelshifter)._
=== "Analog LED Strips"
Also called non-addressable strips. Every LED shows the same color, and each color channel needs its own GPIO and MOSFET. The IRLZ44N and STP55NF06L are good choices.
!!! warning
Board pin naming varies depending on the manufacturer. Please use the board pinout from the _specific_ board you purchased and use the GPIO pins to reference this guide. _Make sure to connect ESP and LED-strip grounds together!_
**2.** Flash the software to your ESP board. The web installer flashes it straight from the browser.
[Install WLED](https://install.wled.me){ .md-button .md-button--primary }
Other flashing methods, including for boards with less than 4MB of flash, are on the [Install WLED Binary](/basics/install-binary) page. Advanced users who want to change WLED before flashing it can [compile it from source](/advanced/compiling-wled) instead.
!!! success "How to tell it worked"
The first 30 LEDs will light up in bright orange to stimulate courage, friendliness and success! On an analog strip the whole strip turns orange, since every LED shares the same channels.
**3.** On your phone or computer, connect to the WiFi network `WLED-AP` using the default password `wled1234`.
You can also just scan this QR code:
{ width="220" }
Scan to join WLED-AP
!!! tip "WLED-AP is not showing up!"
If you do not see the `WLED-AP` network, its name may have been changed at [compile time](/advanced/custom-ap).
Open `wled.me` in your browser to control your lights. The IP `4.3.2.1` works too while you're connected to WLED-AP.
### WiFi Setup
To connect your WLED device to your home WiFi:
**1.** Click on the _Config_ (gear) icon to edit your WLED device settings and choose "WiFi Setup".
**2.** Select **Scan** to find nearby networks, or type your network name. Enter your WiFi password, which is case-sensitive.
**3.** Set an **mDNS address**, such as `wled-livingroom`. This becomes the name you use to reach your device from now on. Change the AP password here too, since `wled1234` is the same on every WLED device.
**4.** Click Save & Connect at the bottom of the page.
**5.** Reconnect your phone or computer to your home WiFi network.
**6.** Open your mDNS address in a browser, for example `http://wled-livingroom.local`. If you didn't set one, or the `.local` name doesn't resolve on your device, use the WLED app to find it, or look up its IP in your router's device list.
!!! tip "4.3.2.1 stops working"
Once your device joins your home network, `4.3.2.1` and `wled.me` stop working. Use your mDNS address or the device's IP instead.
Once you're in, take a look at [The Web UI](/basics/web-ui) to find your way around the interface.
### Find Your Device with the WLED App
The WLED app discovers devices on your network for you, so you don't have to dig through your router.
=== "iOS"
Install [WLED from the App Store](https://apps.apple.com/us/app/wled-official-app/id6446207239).
=== "Android"
Install [WLED from Google Play](https://play.google.com/store/apps/details?id=ca.cgagnier.wlednativeandroid).
1. Connect your phone to the same WiFi network as your WLED device.
2. Your device appears in the app automatically. Select it, then open the **Config** tab in the top right.
3. Choose **WiFi Setup**. At the bottom of that screen is a text box with your hostname, ending in `.local`, and the IP address directly below it.
Either one works in a browser, as `http://your-hostname.local` or `http://your-ip-address`.
### Useful Links
- 12V strips, multiple strips, several supplies, level shifters: [Wiring Guides](/basics/wiring-guides)
- Wire and fuse sizing: [LED power, wiring and fuse calculator](https://wled-calculator.github.io/)
- Optional pushbutton for [configurable actions](/features/macros). The default is `GPIO0` (`D3` on NodeMCU/Wemos). On ESP32 use any free pin, such as `IO17`, that you are not already using for LED data
### Software Update Procedure
=== "Reflash"
Download the latest [release binary](https://github.com/wled/WLED/releases) and flash it exactly like the first install. The [Install WLED Binary](/basics/install-binary) page covers every flashing method.
=== "OTA Update"
The software has an integrated _OTA software update_ capability.
1. Type the correct OTA passphrase (default: "wledota") in the settings menu and remove the tick in the checkbox "OTA locked".
2. Save settings and reboot your device.
3. Select "Manual OTA update" in Security settings and upload a [release binary](https://github.com/wled/WLED/releases).
4. When you are done, it is recommended to lock the OTA function again. Tick the checkbox and reboot. You can change the passphrase by typing in a new one first.
If you try to access the update page while OTA is locked, you should see the message "OTA lock active".
ArduinoOTA is also possible, but requires a custom build with `-D WLED_ENABLE_AOTA` added to `build_flags`.
!!! info "If you own multiple devices and want to update them"
The WLED source code includes shell/command prompt scripts that let you update multiple devices with a single command. Please check the `tools` subfolder for the `multi-update` scripts (.cmd or .sh). You will need to modify them to include the IP addresses of your WLED devices and assign a firmware binary file for each device. If you are using Windows, make sure the `curl` utility is somewhere in your `PATH` (curl ships with Windows 10 build 17063 and later, and with Windows 11). This will only work if "OTA Lock" is disabled, so turn it back on and reboot once the batch is finished.
---
## File: docs/basics/install-binary.md
---
title: Install WLED Binary
hide:
# - navigation
# - toc
---
### Flashing method 1: WLED web installer
!!! tip
This is by far the easiest and fastest way to get WLED up and running!
Make sure you are running a desktop version of Chrome, Edge, Opera, or Firefox 151 or newer, and head over to the [WLED installer site](https://install.wled.me)! Safari cannot be used, as it does not support the browser feature the installer needs to talk to your board.
This installer is not yet available for ESPs with flash chips smaller than 4MB (e.g. ESP01)
!!! tip
In case you want to flash WLED with audioreactive usermod:
Several users reported that this alternative, unofficial installer site may work better: [https://wled-install.github.io/](https://wled-install.github.io/).
After using the standard WLED installer, microphone hardware sometimes cannot be initialized properly by WLED.
!!! tip
If your serial port is listed on linux ('ttyUSB0 CP2102' or similar) but you are unable to open it, make sure you give yourself permission to use that device, for example by adding your user to the group that has access to the tty port.
### Flashing method 2: esptool
- First of all, please follow the steps to install esptool.py [here](https://github.com/espressif/esptool).
- Download the latest [release binary](https://github.com/wled/WLED/releases) file!
- Make sure only one ESP device/microcontroller is connected to your computer! Otherwise you could accidentally overwrite the wrong one. If you know the serial port, you can also add the `--port COM3` attribute before `write-flash`
- Execute this command:
#### ESP8266
```bash
esptool.py write-flash 0x0 ./WLED_XXX.bin
```
#### ESP32
Firstly, flash the version 4 bootloader file, which you can find [here](https://github.com/wled/WLED/releases/download/v0.13.1/esp32_bootloader_v4.bin).
This step only has to be done once, to update afterwards the bootloader does not have to be re-installed.
```bash
esptool.py write-flash 0x0 ./esp32_bootloader_v4.bin
```
Now you can flash the actual firmware binary. Keep in mind the bootloader needs to have a flash offset of 0, but the firmware 0x10000.
```bash
esptool.py write-flash 0x10000 ./WLED_XXX.bin
```
When esptool.py says `Connecting...`, some ESP32 boards require you to hold the boot button (to the right of the USB port) for a few seconds
- If you experience issues, run this command before trying `write-flash` again (Note: this will erase all settings stored on the ESP!)
```bash
esptool.py erase-flash
```
If you have a MagicHome controller, here is a [good video tutorial](https://www.youtube.com/watch?v=qgBAU39v07k) on how to flash it.
### ESP8266 Flashing method 3: [ESP Home Flasher](https://github.com/esphome/esphome-flasher/releases) tool
!!! warning
Don't use ESP Home Flasher for ESP32 boards.
On ESP32, ESP Home Flasher will make the filesystem very small (61kB), which leads to issues making presets.
Please consider using [WLED ESP Flasher](/basics/install-wled-flasher), or the web installer or esptool.
This is a GUI-based tool recommended by some users as easier to use than esptool.
For some boards, you might have to press some buttons after uploading:
> Hold both buttons down, plug it in, start flashing, then when it tries to detect, let go of the button to the left of the USB as you look at it, then when it detects the board type, let go of the other button.
If running Windows, you need a driver from here: before your computer will show the COM port in ESPhome Flasher. With a Wemos D1 mini you do not need to hold down the reset button while flashing.
!!! tip
For ESP32 boards, you can use this [WLED ESP Flasher](/basics/install-wled-flasher) instead of ESP Home Flasher.
### Flashing method 4: OTA update
You can alternatively use my [basic HTTP OTA updater](https://github.com/Aircoookie/ESP8266MinimalHTTPUpdater) sketch and upload the binary! This requires the Arduino IDE and ESP8266 core installed.
If your device is already running a firmware with built-in OTA capability, you can probably use that as well.
### What binary should I use?
Use the latest release. Pins can be configured in LED settings — no custom binaries for different LED pins are needed. Use the following binary for your board:
| Binary Name | For devices |
| --- | --- |
| WLED_x.x.x_ESP8266.bin | NodeMCU, Wemos D1 mini, ESP-12, all ESP8266 with 4MB flash. Recommended.|
| WLED_x.x.x_ESP32.bin | classic ESP32 devices - not for ESP32-S3/ESP32-S2/ESP32-C3 (try [this](https://github.com/wled/WLED/issues/517#issuecomment-571333712) if the WLED-AP doesn't appear after flashing) |
| WLED_x.x.x_ESP32_Ethernet.bin | classic ESP32 devices with an Ethernet interface. Also works with WiFi only, but has some restrictions for 2-wire LEDs|
| WLED_x.x.x_ESP01.bin | ESP-01 (black PCB), most Sonoff devices, ESP8265, all ESP8266 with 1MB flash. This binary has the full feature set, but wireless updates will not work. |
| WLED_x.x.x_ESP01_compat.bin | ESP8266 binaries that use 0.14.0 style networking stack for situations where network connectivity is an issue. |
| WLED_x.x.x_ESP02.bin | All ESP8266 with 2MB flash, Athom bulbs. This binary has the full feature set, but wireless updates will not work (for more detail see [this](https://github.com/wled/WLED/issues/3257). For wireless updates use WLED_0.x.x_ESP02.bin.gz firmware instead. |
| WLED_x.x.x_ESP02.bin.gz | All ESP8266 with 2MB flash, Athom bulbs, wireless update are possible with this firmware. |
---
## File: docs/basics/install-gui.md
---
title: Installation using ESP GUI
hide:
# - navigation
# - toc
---
## 1. Downloading the firmware bin file
You can find precompiled .bin files on the [release page](https://bin.wled.me). Be sure to download the latest version. This file looks something like this:
`WLED_[...]_ESP[...].bin`
If you are not sure what binary you should use look at this page:
[What binary should I use?](/basics/install-binary#what-binary-should-i-use)
## 2. Downloading the Flash Download Tools
Espressif has an official GUI tool for Windows.
It has a lot of options and can be used for the ESP8266 and ESP32.
You can find it on Espressif's download page [here](https://www.espressif.com/en/support/download/other-tools)!
(if the link changed, just search for `esp flash download tool` on Google)
After downloading the file, unzip it and start `flash_download_tools_v3.6.8.exe`.
## 3. Flashing the firmware bin files
After starting `flash_download_tools_v[...].exe` there should pop up two small windows. Now just click on the `Developer Mode` and`ESP8266 DownloadTool` button.
Now a new window opens.
- Under the SPIDownload section select the `WLED_[...]_ESP[...].bin` file by clicking on the first `...` button
- In the Textfield next to the "@" char put in this address: `0x0`
- Then make sure that the file is checked (click on the checkbox)
- **Click on the `Default` button**
- Set SPI Speed to `80Mhz`
- Set Flash Size to `32Mbit`
- Select the COM Port of your ESP (usually it's **not** `COM1`)
- BAUD can be set to `921600`
- Verify that everything looks like the two picture below
- _(optionally)_ click on **ERASE** to erase the entire flash chip
- click on `START`
Now the firmware will be flashed to the ESP. When the firmware flashing was successful you see this: . Finally restart your board.
**Next steps:** [Quick start guide](/basics/getting-started)
---
## File: docs/basics/install-wled-flasher.md
---
title: Install using WLED ESP Flasher
hide:
# - navigation
# - toc
---
## 1. Downloading WLED firmware bin file
You can find precompiled .bin files on the [official release page](https://bin.wled.me). Also available [alternative with precompiled usermods](https://github.com/srg74/WLED-wemos-shield/tree/master/resources/Firmware)
If you are not sure what binary you should use look at this page:
[What binary should I use?](/basics/install-binary#what-binary-should-i-use)
## 2. Downloading the WLED ESP Flasher
The flasher is maintained in the [WLED-wemos-shield project](https://github.com/srg74/WLED-wemos-shield). Download it for your operating system:
=== "Windows"
[Download WLED ESP Flasher for Windows](https://github.com/srg74/WLED-wemos-shield/raw/master/resources/Firmware/WLED_%20ESP_Flasher/Windows.zip)
Unzip the file and start the flasher.
=== "macOS"
[Download WLED ESP Flasher for macOS](https://github.com/srg74/WLED-wemos-shield/raw/master/resources/Firmware/WLED_%20ESP_Flasher/macOS.zip)
Unzip the file and start the flasher.
## 3. Flashing firmware bin files
When flasher start, choose `Serial port` (it must be a port your board is connected to).
Next , choose `downloaded BIN file`.
Click on `Flash ESP`.
Now WLED firmware will be flashed to the ESP. Wait until process is finished and you will see `ADA` message.
**Next steps:** [Quick start guide](/basics/getting-started)
---
## File: docs/basics/top5_mistakes.md
---
title: TOP 5 mistakes
hide:
# - navigation
# - toc
---
### Asking for help
Before asking for help on Discord or on other platforms, check the following top 5 most common mistakes while setting up WLED.
If you're still having trouble and want to ask for help, share as much detail as possible: describe your setup, take photos, and add screenshots of your settings. You can also use the [WLED Wiring Designer Tool](https://wled-wiring.github.io/) to create a wiring diagram, validate it with the built-in checker, and simulate current flow.
### TOP 5 mistakes:
1. LED strip is connected from the back side: addressable LED strips have a direction indicated by small arrows on the strip. The data line must be connected from the side where the arrow begins:
2. Incorrect GPIO is set: check in WLED settings whether the correct GPIO number is set as data output. Take care while using ESP8266 D1 mini: the pin labels like "D0", "D1" etc. are not the same numbers as GPIOs. In WLED preferences you have to use GPIO numbers:
The ready-to-use controllers usually have the correct settings printed either on the housing or on the circuit board as in this example:
3. LED strip with many LEDs is connected and configures, but the current limiter is still at the default value (850 mA). This often has the effect that LEDs either remain dark or flash briefly when the color changes and then go out immediately or light up very dimly. Check and, if necessary, correct the settings in WLED:
4. Wrong LED type is set. The correct LED type and the correct color sequence (RGB, BGR, etc.) must be set in WLED LED preferences. Check that these settings are correct. You have to know the LED type, but you can try out the color sequence to see which is the right one. For example, the WS2814 LED strip must be set as SK6812 and not as WS281x in the LED preferences.
5. Wiring is bad. Wiring must be done thoroughly. Loose contacts, cold solder joints etc. must be avoided. You also need to be careful about the correct sizing of the cables: too thin wires can not only cause high voltage drop but also lead to an overheating and fire! For wire sizing you may use this [LED power, wiring and fuse calculator](https://wled-calculator.github.io/). If many power sources are used (for example separate one for ESP and separate one for the LED strip), then all their grounds (GND, V-) must be connected together (but do not connect their V+ together!).
### More to consider
#### Take care of PSU used
Pay close attention to the power supply unit (PSU) you use. Flickering in addressable LED strips is sometimes caused by poor-quality PSUs that generate significant electromagnetic interference (EMI).
When selecting a PSU, don’t rely solely on general customer reviews. Make sure the unit has been successfully used specifically with addressable LED strips (e.g., WS2812, SK6812). Many inexpensive PSUs receive positive reviews but are primarily used with analog LED strips.
Analog LEDs are relatively tolerant of voltage fluctuations and electrical noise. In contrast, addressable LEDs require a stable voltage and low-noise power supply to function correctly, as they rely on precise digital signaling.
Audible artifacts such as humming, buzzing, or high-pitched whining can indicate poor PSU design or low component quality. These issues often correlate with unstable output and increased electrical noise, which can directly affect LED performance.
---
## File: docs/basics/tutorials.md
---
title: Tutorials
hide:
# - navigation
# - toc
---
**Don't know yet how to solder? Unsure how to connect your LEDs safely? How to find the perfect power supply?**
No worries, we have collected a few helpful links for you to learn more about these and more topics:
### WLED specific tutorials
| Resource | Maker | Type | Date | Info
| --- | --- | --- | --- | --- |
[Beginner's guide to freak'n cool Holiday LEDs](https://www.youtube.com/watch?v=tXvtxwK3jRk) | DrZzs | Video (23:22) | 12 Oct 2019 | Excellent guide for getting started with WLED!
[How to Set Colors and Effects, Save Presets, Make Sync Groups, add a Button, & Macros for Scheduling](https://www.youtube.com/watch?v=6eCE2BpLaUQ) | DrZzs | Video (23:39) | 29 Oct 2019 | Learn about some cool additional WLED features!
[Make your LEDs dance to music!](https://www.youtube.com/watch?v=ipSfQdfX4fE) | DrZzs | Video (11:30) | 17 Nov 2019 | How to install LedFx and connect it to WLED for quick sound reactive effects!
[Getting started with WLED](https://tynick.com/blog/11-03-2019/getting-started-with-wled-on-esp8266/) | tynick | Article | 11 Mar 2019 | Complete and excellent guide on how to flash and get WLED up and running!
[How to Compile WLED (from scratch)](https://youtu.be/fRxyp5Yhivc) | Quindor | Video (02:15:00) | 22 Dec 2020 | How to compile WLED yourself from scratch (most info in first 30 minutes)
[WLED with QuinLED-Dig-Uno Install Tutorial](https://youtu.be/2X_0Oe24vkA) | Quindor | Video (11:13) | 21 Sept 2019 | Initial flash and setup of WLED on QuinLED-Dig-Uno board
[Integrating WLED into Home Assistant](https://youtu.be/d8RpFupihWc) | Quindor | Video (8:22) | 25 Nov 2019 | How to use a WLED node in Home Assistant
[Holiday LEDs Step-by-step with WLED & Home Assistant](https://youtu.be/zepNvlN4gEc) | KPeyanski | Video (20:38) | 28 Oct 2020 | Complete and great wiring, installation and HA setup tutorial
[HOW-TO: Holiday LED Strip Lights, Home Assistant and WLED](https://peyanski.com/holiday-led-strip-lights-home-assistant-and-wled/) | KPeyanski | Article | 23 Jul 2022 | Same as the above video, but in text form!
[Smart Ping Pong LED Lamp - Quick&Simple DIY](https://www.youtube.com/watch?v=WlkMbNnIECM) | bitluni | Video (18:19) | 13 Sept 2020 | Construction, wiring and flashing of a cool looking and easy to make lamp
[WLED tutorial series (in Russian/на русском)](https://sprut.ai/article/sistema-wled-upravlenie-umnymi-girlyandami-i-lampami-na-adresnyh-svetodiodah-i-ne-tolko) | Gelmer | Article Series | 11 Jun 2023 | Серия руководств по установке
[Инструкция на русском: Как прошить WLED и LED FX в ESP01](https://youtu.be/sdxyzDjiXn8) [Пример применения WLED: Бесконечный зеркальный туннель внутри столика IKEA Lack](https://youtu.be/zL-aq_SqaW8) | Alchemist | Video (9:16) / Video (13:09) | 19 Aug 2022 | Прошивка, установка необходимых драйверов и демонстрация режимов работы. Пример электронной схемы.
[ESP8266 based LED controller for WS2812b strip. WLED Firmware + OpenHAB (in Russian)](https://www.youtube.com/watch?v=K4ioTt3XvGc) | Room31 | Video (17:04) | 11 Mar 2020 |
[How to use WLED on an ESP32 (German)](https://www.adlerweb.info/blog/2020/11/01/bitbastelei-409-ws2812b-neopixel-mit-wled-einfach-steuern/ ) | Bitbastelei/Adlerweb | Video (11:00) | 1 Nov 2020 |
[DIY Ambilight using WLED and a Relay](https://wiki.faked.org/DIY_Ambilight) | jangrewe | Article | ? | Wiki page with schematics and instructions for Hyperion, etc. |
[Adding Smarts and Color to an IKEA Lamp](https://apop.tech/posts/adding-smarts-and-color-to-an-ikea-lamp/) | apop880 | Article | 21 May 2021 | Tutorial on upgrading a basic IKEA lamp with WLED |
### Digital LED knowledge
| Resource | Maker | Type | Info |
| --- | --- | --- | --- |
[Adafruit NeoPixel Überguide](https://learn.adafruit.com/adafruit-neopixel-uberguide) | Adafruit | Article | Everything that's important at a glance. *Highly recommended for newcomers to digital LEDs*
[Digital LED Power Usage](https://quinled.info/2020/03/12/digital-led-power-usage/) | Quindor | Article/Spreadsheet/Video | Helps you plan the power usage of your installation
[Power calculation and injection live stream](https://quinled.info/2020/09/26/power-injection-livestream/) | Quindor | Video (2:24:52) | Tons of great questions and answers. Live calculations, drawings, 5v vs 12v, strip comparisons, etc.
[Difference between LED strip types](https://www.youtube.com/watch?v=QnvircC22hU) | The Hook Up | Video (14:41) | What is the best LED strip for your project?
[7 Common LED Strip FAILS and How To Avoid Them](https://www.youtube.com/watch?v=Fu4qZW0pQm4) | The Hook Up | Video (12:14) | Make your project look much better!
[Power Injection demystified](http://spikerlights.com/pwrinjection.aspx) | Spiker Lights | Article | What is power injection and how much do I need?
[Common(sharing) Ground / Multiple power supplies](https://majenko.co.uk/blog/importance-sharing-grounds) | | Article | When using more than one power supply.
### Tools & Skills
| Resource | Maker | Type | Info |
| --- | --- | --- | --- |
[How to Solder](https://www.youtube.com/watch?v=ZwU9SqO0udU) | Beauty and the Bolt | Video (9:50) | |
[Soldering new leads to LED strip](https://youtu.be/sU1O80WPqpk) | Quindor | Video (8:24) | |
[Soldering Tutorial Part 2](https://www.youtube.com/watch?v=fYz5nIHH0iY) | EEVblog | Video (34:05) | Detailed tutorial on soldering, see parts 1 and 3 for even more info)
[Voltage Drop Calculator](https://www.rapidtables.com/calc/wire/voltage-drop-calculator.html) | | Tool | |
[Another Voltage Drop Calculator](https://www.calculator.net/voltage-drop-calculator.html) | | Tool | |
[Pixel/Bullet Voltage Drop Calc](http://spikerlights.com/calcpower.aspx) | | Tool |5 and 12V|
[Combined Wire Gauge Calculator](https://www.wirebarn.com/Combined-Wire-Gauge-Calculator_ep_42.html) | | Tool | |
[Wire Size/Ampacity](https://www.powerstream.com/Wire_Size.htm)| | Tool|Use chassis wiring
_Add more categories as needed :)_
---
## File: docs/basics/wiring-guides.md
---
title: Wiring Guides
hide:
# - navigation
# - toc
---
The wiring diagrams in this section are drawn using [Cirkit Designer](https://www.cirkitdesigner.com/), a general-purpose tool. Alternatively, you can use the WLED-specific [WLED Wiring Designer Tool](https://wled-wiring.github.io/) to design your own diagrams, check them with the built-in diagram validator, and simulate current flow.
## Addressable LED Strips
## Non-Addressable LED Strips
More info on analog LEDs can be found [here](/basics/compatible-led-strips/#non-addressable-led-strips)
## Levelshifter
The SN74(A)HCT125(N) can be wired in different ways. The diagrams show the easiest wiring by connecting unused inputs to GND and leaving unused outputs unconnected. In general:
- Inputs 1A to 4A: connect unused inputs to GND
- Connect the output disable pins 1OE to 4OE to GND, enabling all outputs
- Outputs 1Y to 4Y: leave unused outputs unconnected