Home Automation
diff --git a/search/search_index.json b/search/search_index.json
index 9702a895b..e2b44e7fd 100644
--- a/search/search_index.json
+++ b/search/search_index.json
@@ -1 +1 @@
-{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"Welcome to WLED","text":""},{"location":"#welcome-to-my-project-wled","title":"Welcome to my project WLED! \u2728","text":"A fast and feature-rich implementation of an ESP8266/ESP32 webserver to control NeoPixel (WS2812B, WS2811, SK6812) LEDs or also SPI based chipsets like the WS2801 and APA102!
"},{"location":"#features","title":"\u2699\ufe0f Features","text":" - WS2812FX library integrated for over 100 special effects
- FastLED noise effects and 50 palettes
- Modern UI with color, effect and segment controls
- Segments to set different effects and colors to parts of the LEDs
- Settings page - configuration over network
- Access Point and station mode - automatic failsafe AP
- Up to 3 LED outputs per ESP8266 instance and 10 LED outputs per ESP32 instance
- Support for RGBW strips
- Up to 250 user presets to save and load colors/effects easily, supports cycling through them.
- Presets can be used to automatically execute API calls
- Nightlight function (gradually dims down)
- Full OTA software updatability (HTTP + ArduinoOTA), password protectable
- Configurable analog clock + support for the Cronixie kit by Diamex
- Configurable Auto Brightness limit for safer operation
- Filesystem-based config for easier backup of presets and settings
- Native Home-Assistant integration:
"},{"location":"#supported-light-control-interfaces","title":"\ud83d\udca1 Supported light control interfaces","text":" - WLED app for Android and iOS
- JSON and HTTP request APIs
- MQTT
- Blynk IoT
- E1.31, Art-Net, DDP and TPM2.net
- Hyperion
- UDP realtime
- Alexa voice control (including dimming and color)
- Sync to Philips Hue lights
- Adalight (PC ambilight via serial) and TPM2
- Sync color of multiple WLED devices (UDP notifier)
- Infrared remotes (24-key RGB, receiver required)
- Simple timers/schedules (time from NTP, timezones/DST supported)
"},{"location":"#quick-start-guide-and-documentation","title":"\ud83d\udcf2 Quick start guide and documentation","text":"See the getting started page!
On this page you can find excellent tutorials made by the community and helpful tools to help you get your new lamp up and running!
"},{"location":"#user-interface","title":"\ud83d\uddbc\ufe0f User interface","text":""},{"location":"#compatible-hardware","title":"\ud83d\udcbe Compatible hardware","text":"See here!
"},{"location":"#other","title":"\u270c\ufe0f Other","text":"Licensed under the MIT license Credits here!
Join the Discord server to discuss everything about WLED!
Check out the WLED Discourse forum! You can also send me mails to dev.aircoookie@gmail.com, but please only do so if you want to talk to me privately. If WLED really brightens up your every day, you can
Disclaimer
If you are sensitive to photosensitive epilepsy it is not recommended that you use this software. In case you still want to try, don't use strobe, lighting or noise modes or high effect speed settings. As per the MIT license, I assume no liability for any damage to you or any other person or equipment.
"},{"location":"about/contributors/","title":"Contributors and Credits","text":"This page is to honor the work of all the people who helped to make WLED what it is today!
"},{"location":"about/contributors/#direct-contributors-to-wled-code","title":"Direct Contributors to WLED code","text":"Everyone you see on the Contributors page and: 8bitbrett made the WiFi auto connect QR code with the Aircoookie/WLED logo! adamo made the animated Discord server logo! @blazoncek makes countless new features and improvements to many parts of WLED! @debsahu provided the HomeAssistant autodiscovery and a lot of help with PIO! @frenck made an amazing, stable and feature-packed native integration with HomeAssistant! @photocromax is helping bringing the Live visualization feature to life and added GIF previews to the doc! @raymiec is currently working on creating the best clients for Android and iOS! @StormPie, the creator of the awesome mobile UI! @timothybrown added MQTT authentication! @viknet365 ported the Meteor effect! @wiesendaniel added the configuration for the PlatformIO IDE! @YeonV provided the initial HomeAssistant MQTT light config! This list is incomplete.
"},{"location":"about/contributors/#testing-contributors-and-supporters","title":"Testing, Contributors and Supporters","text":"This list has been redacted for privacy reasons. If you've contributed to the project by testing a lot, helping the community, or sending me a gift, feel free to edit this page and add yourself (maintain alphabetical order) \ud83d\ude04 Thank you very much, your help is truly appreciated! Put two spaces behind your name, else the line break will not appear in the final page!
@Def3nder @DutchmanNL DrZzs (Justin A.) Dylan L. Fil Quindor (Andries F.) Tonyno
"},{"location":"about/contributors/#used-libraries-and-dependencies","title":"Used Libraries and Dependencies","text":"ESP8266/ESP32 Arduino Core NeoPixelBus by Makuna FastLED library ESPAsyncTCP by me-no-dev ESPAsyncUDP by me-no-dev (as of 0.9.0) ESPAsyncWebServer by me-no-dev ArduinoJSON by bblanchon async-mqtt-client by marvinroger WS2812FX by kitesurfer1404 (modified) IRremoteESP8266 by markszabo (optional) Timezone by JChristensen Blynk library (compacted) E1.31 library by forkineye (modified) Espalexa by Aircoookie (modified) Many included FastLED effects are modified versions of kriegsman's gists!
WLED implements Art-Net\u2122 Designed by and Copyright Artistic Licence Holdings Ltd
WebServer_tng by bbx10 (ESP32, up to 0.8.3) PubSubClient by knolleary (modified, up to 0.8.3)
iro.js colorpicker by James Daniel! Classic UI icons by Linearicons created by Perxis!
If you would like to appear in this list for a contribution you made or be removed from it, feel free to contact me!
"},{"location":"about/privacy-policy/","title":"Privacy Policy","text":"By using the WLED embedded system code, the WLED iOS mobile application, the WLED Android mobile application, web client, or associated Services, no personally identifiable data is collected, transmitted and/or stored on external servers. No data is processed in any way not absolutely required for the operation of the Service.
This https://kno.wled.ge page is hosted using GitHub Pages. While the author of this page does not collect any personally identifiable data, the service provider GitHub \"may collect User Personal Information from visitors to [the] GitHub Pages website, including logs of visitor IP addresses, to comply with legal obligations, and to maintain the security and integrity of the Website and the Service.\" (https://docs.github.com/en/github/site-policy/github-privacy-statement#github-pages) This is outside the influence of the author.
"},{"location":"about/privacy-policy/#overview-of-collected-data","title":"Overview of collected data","text":"The embedded system internally stores configuration data, including, but not limited to the user's WiFi credentials. This data is deletable by the user. External read access to sensitive data is blocked. No user or configuration data is sent to any system outside the users local network, unless the user modifies the Software or network configuration.
The mobile apps internally store data regarding connected devices, including, but not limited to the device's network-local IP addresses.
Using the provided Support services (including, but not limited to GitHub, Discord and E-mail), only the information you choose to disclose will be processed. Privacy policies and Terms of Service of service providers apply.
In accordance with the Service MIT license, THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
If you have inquiries regarding this Policy please feel free to contact me at: dev.aircoookie@gmail,com
"},{"location":"about/roadmap/","title":"Upcoming Features","text":"These are currently on my list of what COULD be implemented, there is no guarantee if and when they will be available!
- Create named playlists of presets
- Custom color palettes
- Settings pages overhaul
- Rework of WiFi connection logic (reconnect after WiFi or power outage)
"},{"location":"advanced/compile-analog/","title":"Compile Analog WLED","text":"Moved, see How to compile WLED
"},{"location":"advanced/compile-wled/","title":"Compile WLED","text":"Moved, see How to compile WLED
"},{"location":"advanced/compiling-wled/","title":"Compiling WLED","text":"You want to add custom features to WLED, use non-default pins, or add in a usermod? You've found the right place!
WLED has come to rely on so many dependencies in the latest versions that building with the Arduino IDE is no longer recommended. Instead, installing Visual Studio Code and its PlatformIO (PIO) extension is easier, as it will install the ESP Arduino core, all the required libraries and the correct compilation settings for you automatically.
"},{"location":"advanced/compiling-wled/#installation-guide-platformio-recommended","title":"Installation guide (PlatformIO, recommended)","text":" - Make sure Git client is installed on your system. If it isn't, you can get it here.
- Download and install the free Visual Studio Code by Microsoft.
- Open VS Code and go to the Extensions manager (the icon with the stacked blocks in the left bar)
- Search for
platformio ide and install the PlatformIO extension -
Download the WLED source code by executing git clone https://github.com/Aircoookie/WLED.git in some folder. (You can also use GitHub Desktop or download the latest source code from https://github.com/Aircoookie/WLED under the Code dropdown menu as a .zip file.) Alternatively fork the WLED project first and download it from your fork.
-
Go to File -> Open Folder and open that root WLED folder (the one that contains platformio.ini, NOT the wled00 folder)
"},{"location":"advanced/compiling-wled/#compilation-guide-platformio","title":"Compilation guide (PlatformIO)","text":"Tip
Make sure Git Client is installed on your system. You can get it here.
- In VS Code, open the file
platformio.ini. - Add a semicolon in front of the line that says
default_envs = travis_esp8266, travis_esp32 to comment it out. - Select your build environment by un-commenting one of the lines starting with
; default_envs =. Please remove BOTH the ; and the whitespace behind it to correctly uncomment the line. For most ESP8266 boards, the d1_mini environment is best. - In the blue bottom bar, hit the checkmark to compile WLED or the arrow pointing right to compile and upload!
Picture Guide
Success!
If you get one of these two errors, hit the checkmark icon once again to compile and that time the code should build without problems!
error: wled00\\wled00.ino.cpp: No such file or directoryFileNotFoundError: [WinError 2] The system cannot find the file specified: '[...].sconsign37.dblite'
"},{"location":"advanced/compiling-wled/#making-a-custom-environment","title":"Making a custom environment","text":"Once you've confirmed VSCode with Platformio is set up correctly, you can add/define overrides to allow you to use non-default pins, add a usermod, or add other custom features.
- Copy and paste the contents of
platformio_override.ini.sample into a new file called platformio_override.ini. Make sure platformio_override.ini is in the same folder as platformio.ini. - Replace the line
default_envs = WLED_tasmota_1M with the line you uncommented in platformio.ini in the previous steps (from Compilation guide (PlatformIO)). Example: default_envs = d1_mini - In
platformio.ini scroll down until you see #-------------------- # WLED BUILDS #-------------------- - Find the section that matches the build environment you selected in previous steps. Example:
[env:d1_mini] - Select the whole section (including the first line in brackets [ ] ), and copy and paste it into
platformio_override.ini overwriting the build environment section that was already there. - Add a new line under the the line that starts with
build_flags = - Put your
-D overrides on this new line, giving each -D it's own new line. - Compile your freshly customized WLED image!
"},{"location":"advanced/compiling-wled/#flashing-the-compiled-binary","title":"Flashing the compiled binary","text":"Tip
This step is optional and only recommended if you want to install the same binary to multiple boards. For testing, it is easiest to upload directly from PlatformIO
The .bin file is located in the subfolder /build_output/firmware in your WLED folder. The binary will have the same name as your environment.
All that's left to do is flash this .bin file onto your ESP board and then connect it to WiFi.
"},{"location":"advanced/compiling-wled/#compilation-guide-arduino-ide-not-recommended","title":"Compilation guide (Arduino IDE, not recommended)","text":"Warning
This method is outdated. The source is no longer officially checked to be buildable with the Arduino IDE. Using PlatformIO is strongly advised.
-
Follow a guide to setup your Arduino IDE (I am using version 1.8.9) with the ESP8266 libraries. For current compiles I recommend the latest Arduino core version 2.7.4. If you do not wish to install all libraries manually it is recommended to download the PlatformIO extension for VS Code (see above).
-
You will need to install a few libraries:
Library Name Platform NeoPixelBus (2.6.0) All FastLED All ESPAsyncWebServer Aircoookie fork (2.0.0) All IRRemoteESP8266 All ESPAsyncTCP ESP8266 only ESPAsyncUDP ESP8266 only AsyncTCP for ESP32 ESP32 only LITTLEFS_esp32* ESP32 only * Please see the installation guide. You might need to enable a define in the library code.
All other dependencies are included with WLED for convenience.
- Now compile and flash the software! Make sure you erase everything when you flash! (If your board config does not provide this option, you can
Sketch -> Export compiled Binary and upload with any ESP flashing tool.)
"},{"location":"advanced/compiling-wled/#compilation-settings-arduino-ide","title":"Compilation settings (Arduino IDE)","text":"ESP8266:
- Arduino Core v2.7.4
- Board: NodeMCU 1.0 (ESP-12E module) (or select your ESP board)
- CPU frequency: 80 MHz
- Flash size : 4MB (1MB SPIFFS)
- LwIP variant: v1.4 Higher Bandwidth (try 2 if you experience issues)
- Upload speed: Any, 921600 recommended
ESP8266-07 (External Antenna):
- Variants have 512kB or 1MB flash
- Be sure to use DOUT mode when flashing
- Flash Size 1MB (128k SPIFFS)
- 512kB variant no longer compatible
ESP-07s (External Antenna):
- Variant has 4MB flash
- Settings as for NodeMCU or Wemos
ESP32:
"},{"location":"advanced/custom-ap/","title":"Custom Access Point SSID and Password","text":"Warning
Note: These options change the documented access point name and password. The WLED community does not recommend changing these settings unless you are familiar with the risks.
Three compile time defines are available to modify the access point name. These are WLED_AP_SSID, WLED_AP_PASS, and WLED_AP_SSID_UNIQUE. Defining WLED_AP_SSID will set the SSID to the value of the define. Defining WLED_AP_PASS will set the password to the value of the define. Defining WLED_AP_SSID_UNIQUE will append the last 6 digits of the MAC address to the SSID.
WLED_AP_SSID and WLED_AP_PASS are string values, and as such need to be defined with \" surrounding them. For example, #define WLED_AP_SSID \"MyWLED\" or -D WLED_AP_SSID='\"MyWLED\"' in the build_flags of platformio.ini.
"},{"location":"advanced/custom-ap/#modifying-the-access-point-ssid","title":"Modifying the Access Point SSID","text":"Defining WLED_AP_SSID will set the SSID to the value of the define. This is useful to set a device specific access point name. For example, if you have multiple WLED devices, you can set the SSID to the device name.
WLED_AP_SSID is a string value, and as such needs to be defined with \" surrounding it. For example, #define WLED_AP_SSID \"MyWLED\" or -D WLED_AP_SSID='\"MyWLED\"' in the build_flags of platformio.ini.
"},{"location":"advanced/custom-ap/#modifying-the-access-point-password","title":"Modifying the Access Point Password","text":"Defining WLED_AP_PASS will set the password to the value of the define. This is useful to set a device specific access point password. For example, if you have multiple WLED devices, you can set the password to the device name.
Tip
If WLED_AP_PASS is defined, but WLED_AP_SSID is not, the compilation will fail. Ensure you define both WLED_AP_SSID and WLED_AP_PASS if you wish to change the access point password. Please also change the SSID if you wish to set a custom password.
WLED_AP_PASS is a string value, and as such needs to be defined with \" surrounding it. For example, #define WLED_AP_PASS \"MyWLEDPass\" or -D WLED_AP_PASS='\"MyWLEDPass\"' in the build_flags of platformio.ini.
"},{"location":"advanced/custom-ap/#modifying-the-access-point-ssid-to-be-unique","title":"Modifying the Access Point SSID to be Unique","text":"Defining WLED_AP_SSID_UNIQUE will append the last 6 digits of the MAC address to the SSID. This is useful to set a device specific access point name with a common prefix. For example, if you have multiple WLED devices, you can set the SSID to ChristmasTree- followed by the last 6 digits of the MAC address.
WLED_AP_SSID_UNIQUE is a boolean value, and as such only needs to be defined or not. For example, #define WLED_AP_SSID_UNIQUE or -D WLED_AP_SSID_UNIQUE in the build_flags of platformio.ini.
"},{"location":"advanced/custom-ap/#example","title":"Example","text":"For custom devices in platformio_override.ini:
[env:mywled]\nboard = esp32dev\nplatform = ${esp32.platform}\nplatform_packages = ${esp32.platform_packages}\nbuild_unflags = ${common.build_unflags}\nbuild_flags =\n${common.build_flags_esp32}\n-D WLED_AP_SSID_UNIQUE\n-D WLED_AP_SSID='\"MyWLED\"'\n-D WLED_AP_PASS='\"MyWLEDPass\"'\nlib_deps = ${esp32.lib_deps}\nmonitor_filters = esp32_exception_decoder\nboard_build.partitions = ${esp32.default_partitions}\n
In my_config.h:
#define WLED_AP_SSID_UNIQUE\n#define WLED_AP_SSID \"MyWLED\"\n#define WLED_AP_PASS \"MyWLEDPass\"\n
"},{"location":"advanced/custom-features/","title":"Custom Features","text":"Warning
Note: this page is now out of date, see updated functionality in the code (WLED/usermods/EXAMPLE_v2)
This page is intended for those wishing to modify the WLED code to add their own functionality.
"},{"location":"advanced/custom-features/#basics","title":"Basics","text":"Programming is done in the Arduino IDE. There is a special file, usermod.cpp, to write your own code. (however, if you think your code may be relevant to many users, feel free to code it in directly and open a pull request)
This file has three empty methods: - userSetup() is called after loading settings but before connecting to WiFi. Use it to start own interfaces if it does not depend on WiFi (IR, Sensors, GPIOs,...). Also you can use it to load custom settings or to specify own server pages with the server.on() method. - userConnected() is called once WiFi is connected. Use it to connect to external servers or init interfaces using wiFi. - userLoop() is called by the main loop() function.
"},{"location":"advanced/custom-features/#modify-wled-values","title":"Modify WLED values","text":"If you know what you're doing, you may choose to change the value of any global variable declared in wled.h. However, for basic color and brightness changes, these are the most important:
Variable Name Type Purpose bri byte (0-255) Master Brightness (0 is off, 255 is maximum) col[0] byte (0-255) Red color value col[1] byte (0-255) Green color value col[2] byte (0-255) Blue color value col[3] byte (0-255) White color value After updating the color, you must call the colorUpdated(int) method. If you want to send a notification with the new color to other ESPs, use colorUpdated(NOTIFIER_CALL_MODE_DIRECT_CHANGE), otherwise colorUpdated(NOTIFIER_CALL_MODE_NO_NOTIFY).
"},{"location":"advanced/custom-features/#timing","title":"Timing","text":"If you'd just like a simple modification that requires timing (like sending a request every 2 seconds), please never use the delay() function in your userLoop()! It will block everything else and WLED will become unresponsive and effects won't work! Instead, try this instead:
long lastTime = 0;\nint delayMs = 2000; //we want to do something every 2 seconds\n\nvoid userLoop()\n{\nif (millis()-lastTime > delayMs)\n{\nlastTime = millis();\n//do something you want to do every 2 seconds\n}\n}\n
"},{"location":"advanced/custom-features/#internal-segments-api","title":"Internal Segments API","text":"You can use Segments from your code to set different parts of the strip to different colors or effects. This can be very useful for highly customized installations, clocks, ...
To set a segment, use strip.setSegment(id, start, stop);, where id is the segment ID, start is the first LED of the segment and stop is the LED after the last one in the segment.
To edit the configuration of a segment, use:
WS2812FX::Segment& seg = strip.getSegment(id);\n//set color (i=0 is primary, i=1 secondary i=2 tertiary)\nseg.colors[i] = ((myWhite << 24) | ((myRed&0xFF) << 16) | ((myGreen&0xFF) << 8) | ((myBlue&0xFF)));\n//set effect config\nseg.mode = myFxI;\nseg.speed = mySpeed;\nseg.intensity = myIntensity;\nseg.palette = myPaletteId;\n
Keep in mind that this will not cause interface updates as of 0.8.6. For that, you still need to use colorUpdated(NOTIFIER_CALL_MODE_DIRECT_CHANGE)"},{"location":"advanced/custom-features/#create-custom-effects","title":"Create custom effects","text":"It is possible to create your own effects and add them to the FX library. The relevant files for that are FX.cpp and FX.h.
Here is a step-by-step guide on how to make your effect:
-
Take a look at some of the effects in FX.cpp to see how they are implemented!
-
Add your own routine in FX.cpp starting with: uint16_t WS2812FX::mode_custom
-
Add to total number of effects in FX.h line 110: #define MODE_COUNT
-
Add your mode number (ie#define FX_MODE_CUSTOM 110) in FX.h around line 200.
-
Add your mode around line 400 of FX.h, like so: _mode[FX_MODE_CUSTOM] = &WS2812FX::mode_custom;
-
Add it to the functions in FX.h around line 600:mode_custom(void),
-
Give it a name at the bottom (10 modes per line) in JSON_mode_names[]. Wrap your name in quotes just like the others.
-
Compile, upload and enjoy! Your new effect will automatically be added to the list in the web ui.
If you programmed a nice effect you want to share, submit a pull request!
"},{"location":"advanced/custom-features/#changing-web-ui","title":"Changing Web UI","text":"In order to conserve space, the Web UI interface is represented as a series of wled00/html_ui.h, wled00/html_settings.h and wled00/html_other.h files which contain C/C++ strings with specific parts of the Web UI.
These files are automatically created from source files available in wled00/data folder. To generate files, install NodeJS 11.0+ globally. After that, recreate html_*.h files by running in the repo directory:
> npm install\n> npm run build\n
If you want to test changes to the UI, it is easiest to work with the local wled00/data/index.htm file. You just need to enter the IP address of a WLED 0.10.0 or newer instance into the popup. If you accidentally input an incorrect IP or want to test with a different instance, clear the local storage (in Chrome: Developer Tools -> Application -> Local Storage)
If you continuously modify files in the wled00/data directory, you want to monitor these changes to make local html_*.h files being updated automatically. To do this, run this in repo directory:
> npm run dev\n
This will start monitoring wled00/data folder for changes. WARNING!! Be careful with changing the javascript in HTML files! For example function GetV() {} must be the last javascript function in the <script> element as it will be replaced by automatically generated code to fetch relevant settings from EEPROM. See tools/cdata.js for the replacement rules which run for every *.htm file in wled00/data.
Recompile and flash WLED!
"},{"location":"advanced/ddp/","title":"Virtual LEDs via DDP/ArtNet","text":""},{"location":"advanced/ddp/#overview","title":"Overview","text":"Virtual LEDs allow you to \"attach\" LEDs from multiple ESPs to a main, controlling ESP. These LEDs can be added to an ESP just like physical pins.
On the controlling ESP, go to Config, LED Preferences.
Select DDP RGB (Network) as the LED type and enter the Length (number of LEDs on that remote ESP), then enter the ESPs IP address.
Multiple remote ESP's can be setup this way.
Note: The controlling ESP must be running at least 0.13 firmware while the remotes can be older. As usual, best perfomance is obtained by using an ESP32 for the controlling device. You can use an ESP8266, but only with a small number of LEDs (<300).
Also, support was recently added for ArtNet virtual LEDs.
"},{"location":"advanced/esp32-recovery/","title":"ESP32 Recovery","text":"In Platformio IDE open a new terminal and type: pio run -v -t upload When you see the \"Connecting........\" abort the upload.
Below you can see Esptool commands, that was used by Platformio. Now you able to find all files that we need to build the binary (screenshot for visualization):
"},{"location":"advanced/home-automation/","title":"Home Automation Integration","text":"It is possible to interface WLED with home automation systems and other 3rd party software. You can use any API WLED provides (JSON, HTTP, UDP, MQTT), JSON is preferred. This page is intended for sample code and configs others use to control WLED from various 3rd party software:
HomeAssistant and NodeRED flows
"},{"location":"advanced/home-automation/#domoticz","title":"Domoticz:","text":"Please see here!
"},{"location":"advanced/home-automation/#home-assistant","title":"Home Assistant","text":""},{"location":"advanced/home-automation/#using-the-native-integration","title":"Using the native integration","text":"Compatibility notice
WLED devices are not supported by Home Assistant 2022.2 or later if a CCT bus is configured or White Balance Correction is enabled.
We hope to resolve this issue as soon as possible. As a temporary workaround you can enable the option Calculate CCT from RGB in LED settings.
WLED can be configured using the integrations in the Home Assistant frontend.
Menu: Configuration -> Integrations.
In most cases, the WLED devices will be automatically discovered by Home Assistant. Those automatically discovered WLED devices are listed on the integrations page.
If for some reason (e.g., due to lack of mDNS support on your network), the WLED device isn't discovered, it can be added manually.
Click on the + sign to add an integration and click on WLED. After completing the configuration flow, the WLED integration will be available.
WLED integration documentation
"},{"location":"advanced/home-automation/#using-mqtt","title":"Using MQTT","text":"Alternatively, MQTT can be used (not recommended). Auto discovery is no longer supported since version 0.9 of WLED. In case you want to configure the device manually:
Expand to show MQTT configuration light:\n - platform: mqtt\n name: \"Kitchen Floor Lights\"\n command_topic: \"wled/all\"\n brightness_command_topic: \"wled/all\"\n rgb_command_topic: \"wled/all/col\"\n rgb_command_template: \"{{ '#%02x%02x%02x' | format(red, green, blue)}}\"\n effect_command_topic : \"wled/all/api\"\n effect_list:\n - \"FX=0\"\n - \"FX=1\"\n - \"FX=2\"\n - \"FX=3\"\n - \"FX=4\"\n - \"FX=5\"\n - \"FX=6\"\n - \"FX=7\"\n - \"FX=8\"\n - \"FX=9\"\n - \"FX=10\"\n - \"FX=11\"\n - \"FX=12\"\n - \"FX=13\"\n - \"FX=14\"\n - \"FX=15\"\n - \"FX=16\"\n - \"FX=17\"\n - \"FX=18\"\n - \"FX=19\"\n - \"FX=20\"\n - \"FX=21\"\n - \"FX=22\"\n - \"FX=23\"\n - \"FX=24\"\n - \"FX=25\"\n - \"FX=26\"\n - \"FX=27\"\n - \"FX=28\"\n - \"FX=29\"\n - \"FX=30\"\n - \"FX=31\"\n - \"FX=32\"\n - \"FX=33\"\n - \"FX=34\"\n - \"FX=35\"\n - \"FX=36\"\n - \"FX=37\"\n - \"FX=38\"\n - \"FX=39\"\n - \"FX=40\"\n
by @acid2000 Config json which is sent via autodiscovery:
{\n\"name\": \"WLED Light\",\n\"stat_t\": \"wled/840d8e989815/c\",\n\"cmd_t\": \"wled/840d8e989815\",\n\"rgb_stat_t\": \"wled/840d8e989815/c\",\n\"rgb_cmd_t\": \"wled/840d8e989815/col\",\n\"bri_cmd_t\": \"wled/840d8e989815\",\n\"bri_stat_t\": \"wled/840d8e989815/g\",\n\"fx_cmd_t\": \"wled/840d8e989815/api\",\n\"fx_stat_t\": \"wled/840d8e989815/api\",\n\"bri_val_tpl\": \"{{value}}\",\n\"rgb_cmd_tpl\": \"{{'#%02x%02x%02x' | format(red, green, blue)}}\",\n\"rgb_val_tpl\": \"{{value[1:3]|int(base=16)}},{{value[3:5]|int(base=16)}},{{value[5:7]|int(base=16)}}\",\n\"qos\": 0,\n\"opt\": true,\n\"pl_on\": \"ON\",\n\"pl_off\": \"OFF\",\n\"fx_val_tpl\": \"{{value}}\",\n\"fx_list\": [\n\"[FX=00] Solid\", \"[FX=01] Blink\", \"[FX=02] Breathe\", \"[FX=03] Wipe\", \"[FX=04] Wipe Random\", \"[FX=05] Random Colors\", \"[FX=06] Sweep\", \"[FX=07] Dynamic\", \"[FX=08] Colorloop\", \"[FX=09] Rainbow\", \"[FX=10] Scan\", \"[FX=11] Dual Scan\", \"[FX=12] Fade\", \"[FX=13] Chase\", \"[FX=14] Chase Rainbow\", \"[FX=15] Running\", \"[FX=16] Saw\", \"[FX=17] Twinkle\", \"[FX=18] Dissolve\",\n\"[FX=19] Dissolve Rnd\", \"[FX=20] Sparkle\", \"[FX=21] Dark Sparkle\", \"[FX=22] Sparkle+\", \"[FX=23] Strobe\", \"[FX=24] Strobe Rainbow\", \"[FX=25] Mega Strobe\", \"[FX=26] Blink Rainbow\", \"[FX=27] Android\", \"[FX=28] Chase\", \"[FX=29] Chase Random\", \"[FX=30] Chase Rainbow\", \"[FX=31] Chase Flash\", \"[FX=32] Chase Flash Rnd\", \"[FX=33] Rainbow Runner\", \"[FX=34] Colorful\", \"[FX=35] Traffic Light\", \"[FX=36] Sweep Random\", \"[FX=37] Running 2\", \"[FX=38] Red & Blue\", \"[FX=39] Stream\", \"[FX=40] Scanner\", \"[FX=41] Lighthouse\", \"[FX=42] Fireworks\", \"[FX=43] Rain\", \"[FX=44] Merry Christmas\", \"[FX=45] Fire Flicker\", \"[FX=46] Gradient\", \"[FX=47] Loading\", \"[FX=48] In Out\", \"[FX=49] In In\", \"[FX=50] Out Out\", \"[FX=51] Out In\", \"[FX=52] Circus\", \"[FX=53] Halloween\", \"[FX=54] Tri Chase\", \"[FX=55] Tri Wipe\", \"[FX=56] Tri Fade\", \"[FX=57] Lightning\", \"[FX=58] ICU\", \"[FX=59] Multi Comet\", \"[FX=60] Dual Scanner\", \"[FX=61] Stream 2\", \"[FX=62] Oscillate\", \"[FX=63] Pride 2015\", \"[FX=64] Juggle\", \"[FX=65] Palette\", \"[FX=66] Fire 2012\", \"[FX=67] Colorwaves\", \"[FX=68] BPM\", \"[FX=69] Fill Noise\", \"[FX=70] Noise 1\", \"[FX=71] Noise 2\", \"[FX=72] Noise 3\", \"[FX=73] Noise 4\",\n\"[FX=74] Colortwinkle\", \"[FX=75] Lake\", \"[FX=76] Meteor\", \"[FX=77] Smooth Meteor\", \"[FX=78] Railway\", \"[FX=79] Ripple\"\n]\n}\n
"},{"location":"advanced/home-automation/#indigo-domotics","title":"Indigo Domotics:","text":"Please see here!
"},{"location":"advanced/home-automation/#openhab","title":"openHAB:","text":"In openHAB 3 based environments you are able to use the native openHAB WLED Binding, which also supports discovery of your WLED devices.
For older openHAB (2.5.x) environmantes the connection can be configured via MQTT broker & Openhab MQTT Binding (2.5x) with configuration files Please find the details here
"},{"location":"advanced/longdata/","title":"Long Data Line configurations","text":"Addressable LEDs are controlled over a data line(s) based on 5V TTL (Transistor-Transistor-Logic) signals. Over long distances (> 5m) keeping those signals \"clean\" and well defined for the LED they're meant to drive can be difficult. While there are many methods used to get good results over 10m and longer runs (in-line resistors, voltage boosters, sacrificial pixels, etc.) they are often problematic and unreliable. There is a method specifically designed to send high speed (~1Mhz) TTL data over long (10's to 100's of meter) distances: using a differential pair.
Commonly known as RS485, differential pair transmission for LED's takes the single data line from your MCU (ESP32, ESP8266, etc) and translates that into a differential signal that is sent across two wires instead of one. A transmitter unit (Tx) at the MCU takes in the single data signal and outputs 2 lines usually called A+ and B-. At the LED strip a matching receiver unit (Rx) takes the A+, B- signals as inputs and outputs clean and accurate 5V LED data that can directly feed the strip. The only thing that needs to connect the TxRx pair is a pair of wires and a common ground. The wires don't carry much current at all (~50mA) and can often be a light wire pair from a length of Cat5e or 22/4 alarm wire.
The distance between the Tx and Rx devices can easily be 30m. With Cat5e UTP wire you can reliably reach 150m or more.
Note, there is no need for a level shifter with the Tx module. Typical transmitters are spec'd for a minimum 2.4V High level input which is well within the output range of a 3.3V MCU. The only other thing to note about the TxRx pair is that they usually require 5V to operate and often have a 120 ohm termination resistor across the A+,B- connections. Those resistors are important to maintain the integrity of the transmitted data.
A TxRx pair can also be used in the middle of a run of LED's when the distance to the next strip is long. Just put a Tx unit at the end of the first strip and the Rx unit at the start of the next strip.
The individual Tx and Rx units are fairly inexpensive and can found on Amazon or via Aliexpress usually for less than $2 USD each (try \"RS485 TTL interface\").
"},{"location":"advanced/mapping/","title":"Mapping","text":"WLED now has the ability to remap your LED strip programmatically.
"},{"location":"advanced/mapping/#what-is-it","title":"What is it?","text":"This allows us to treat the WLED strip as if it is wired in any way - we can then use the mapping feature to address the strip in any order. This allows for matrix support, serpentine runs and such.
"},{"location":"advanced/mapping/#how-do-we-do-it","title":"How do we do it?","text":"Navigate to the edit page for your WLED device by adding /edit to its' address - for example, https://my-led-device.local/edit Use this edit page to create a file called ledmap.json.
ledmap.json file needs to be a JSON formatted file with the the key being \"map\" and the value being an array of numbers representing the new order of pixels. The position of values in the array is the \"natural\" order of LEDs and the value entered is the new position.
The ArduinoJSON library is *extremely*** white-space sensitive. If your ledmap.json file is not working, check for white-spaces where they should not be. The LED positions are zero-indexed.
Multiple maps are supported in the latest versions by using ledmapx.json where x is a number. Maps can be selected in a preset using {\"ledmap\":x,....
Use -1 in the map for gaps/blank/nul LEDs.
"},{"location":"advanced/mapping/#examples","title":"Examples","text":"In the below example (formatted multiple ways), we remap a strip of four LEDs from a physical order of 0 1 2 3 into a new order of 0 2 1 3.
{\"map\":[0,2,1,3]}\n\n{\"map\":[\n0,2,1,3\n]}\n\n{\"map\":[\n0,2,\n1,3\n]}\n
This is another example that switches direction every 5 LEDs. It could be formatted any of the three ways demonstrated above.
{\"map\":[0, 1, 2, 3, 4, 9, 8, 7, 6, 5, 10, 11, 12, 13, 14,\n19, 18, 17, 16, 15, 20, 21, 22, 23, 24, 29, 28, 27, 26, 25]}\n
"},{"location":"advanced/remote-access-ifttt/","title":"Remote Access / IFTTT","text":"WLED is open-source, DIY software. This means all services are hosted locally on your ESP8266/32. Therefore you can only control your lights from within your local (home) network.
If you need to control WLED from anywhere (the public internet) you can do so in multiple ways, some requiring additional hardware:
"},{"location":"advanced/remote-access-ifttt/#1-home-automation-systems","title":"1. Home Automation systems","text":"If you add your WLED device to your Home Automation system (e.g. Home Assistant or ioBroker), you can control WLED remotely if you have set up remote access for your Home Automation system, for example via Nabu Casa.
"},{"location":"advanced/remote-access-ifttt/#2-amazon-echo-device","title":"2. Amazon Echo device","text":"If you have set up your Alexa device to control WLED, you can just use the Alexa App or another Echo device linked to your account to control your lights (on/off and brightness only)
"},{"location":"advanced/remote-access-ifttt/#3-port-forwarding","title":"3. Port Forwarding","text":"Warning: An insecure HTTP connection is used, please do NOT edit sensitive info like the WiFi settings when connected via port forwarding! This method offers more flexibility, but is also more involved. Keep in mind this causes anyone with your IP address to have access to your ESP8266! Setting up an OTA lock password is a must to prevent attackers from acquiring your WiFi credentials!
To expose WLED to the internet, create a port forwarding rule for your ESP's IP local ip and port (80) in your router configuration. It is not recommended to use port 80 on your public IP address since 80 is scanned constantly by bots good and bad. Use a 5 digit port for better securuty. If your public IP changes a lot, make sure to also use a dynamic DNS service so your lights are always accessible. Unsure what any of this means or how to do it? Google for \"[your router model] port forwarding\"!
Additionally, this opens up many new possibilities for automation! You can use a service like IFTTT Webhooks to send automated WLED API calls that can do anything from turning on the lights at a set time to changing their color if you get a new email!
"},{"location":"advanced/remote-access-ifttt/#4-hue-sync","title":"4. Hue sync","text":"If you have a Philips hue setup and sync WLED to it, you can control your WLED lights in any way it's possible to control your hue lights (hue App, Alexa (including colors), any other service that uses Philips hue API)
"},{"location":"advanced/security/","title":"Security","text":"WLED was designed in a way that you should be safe to have a router port forwarding to control the system from the public internet. This page will tell you what you can expect by WLEDs security.
"},{"location":"advanced/security/#tldr-what-to-do","title":"TLDR - what to do?","text":"A: If you just operate WLED within a local network and/or with a secured Access Point (change the default password \"wled1234\"!!) you are fine.
If you have configured a port forwarding to control WLED from outside your local subnet, please make sure the setting \"OTA Lock\" is enabled and you have changed the default OTA password \"wledota\"! Also, NEVER edit sensitive data (like WiFi credentials) while connected via the port forwarding!
"},{"location":"advanced/security/#1-is-the-connection-itself-safe","title":"1: Is the connection itself safe?","text":"A: Technically not. The ESP8266 uses unencrypted HTTP traffic. Implementing HTTPS would take too much processing power and memory on this little device. This means an attacker could read your passwords during transmit. Therefore, to be safe, please do NOT change the AP/Client WiFi/OTA password from outside of your LAN via a forwarded port. If you are at home, you should be safe if your WiFi is secured. You can change any other setting while you're away, though. WLED doesn't send your actual password to the settings page, just its length.
"},{"location":"advanced/security/#2-what-do-you-mean-by-secure-then","title":"2: What do you mean by secure then?","text":"A: WLED comes with the ability to carry out a software update via WiFi (OTA). However, no one must be able to flash a malicious new binary firmware to steal your WiFi credentials or make your ESP part of a botnet. Therefore, you should enable the \"OTA Lock\" setting and change its default passphrase \"wledota\".
"},{"location":"advanced/security/#3-can-i-protect-the-light-configuration-or-the-settings-page","title":"3: Can I protect the light configuration or the settings page?","text":"A: Currently not. This is not sensitive information like your WiFi password. Anyone with your IP and port can control the lights. Open an issue if it should ever happen that somebody plays with your lights. I might consider adding an optional password lock then. For now, it is way too cumbersome for what it does.
"},{"location":"advanced/security/#4-i-want-to-do-a-software-update-but-it-says-ota-lock-active","title":"4: I want to do a software update, but it says \"OTA lock active\"?","text":"A: You need to go to the settings page. Untick the \"OTA Lock\" setting and input your passphrase in the field below it. Now apply the settings and reboot. After that you can carry out the software update. Don't forget to re-enable OTA Lock afterwards! To enable, you don't have to enter the passphrase, unless you want to change it. For the lock to work you need to apply and reboot again.
"},{"location":"advanced/security/#5-why-is-this-ota-lock-stuff-that-important","title":"5: Why is this OTA lock stuff that important?","text":"A: Your unencrypted WiFi password is stored in the module's EEPROM. It would be easy to \"update\" the software to a malicious version which sends your password to the attacker. OTA Lock makes sure only those with the passphrase may carry out a software update. And yes, while you can disable OTA lock by doing a factory reset, this would also kill the WiFi connection to the attacker.
"},{"location":"advanced/security/#6-anything-else","title":"6: Anything else?","text":"A: A personal tip from me is not to give anyone your IP to control the software who you do not wish to do so on a regular basis. It is not critical from a security standpoint, but it can be very annoying if someone plays with your lights, or even worse, change your AP credentials to the point where you can no longer access the module except via USB.
"},{"location":"advanced/wiring/","title":"Overview","text":"RGB LEDs can draw a lot of current (amps). While most people usually worry about the dangers from high voltage, low voltage + high amperage can be dangerous too, as it can easily become a fire hazard in certain circumstances. Depending on your setup size (the number of LEDs you want to drive), use these tips to help guide your wiring.
There are plenty of guides out there to help with power supply selection, which is out of scope of this page. Size your power supply to your installation both up and down, so you both provide them with enough current and don't introduce unnecessary risk. It's better to power 30 LEDs from a 10W (2A @5V) power supply than a 100W power supply, as you don't need to worry about the potential for as much energy flowing through small wires.
As you increase the number of LEDs, you increase the amps your power supply will need to be able to provide. The more amps you're working with, the more you need to be cautious about your wiring and fusing.
For example, if you want to power your LEDs off a sealed lead acid battery (e.g. a car battery), you need to be very careful about current. These kinds of batteries can supply hundreds of amps, so you need to ensure that you use fuses along the way to protect against shorts. If you're using USB pocket chargers on the other hand, they tend to be current limited (most provide only 1-2A max) so you can worry less about fusing there.
Make sure to also check out this great list of resources to help you learn!
"},{"location":"advanced/wiring/#small-setups-30-rgb-leds","title":"Small Setups (< 30 RGB LEDs)","text":"WLED has a great built-in automatic current-limiting feature, set to 850mA by default. If you have a very small setup (< 30 LEDs), you can use this feature to help simplify your wiring and keep things safe.
In most circumstances, it's best to power your LED strip directly from the power supply and wire power to your WLED control board in parallel.
{insert diagram here}
With the current limiting feature turned on and for very small setups (on the smaller side of 1-30 LEDs), you can power the LED strip directly through the USB port of D1 mini or similar board. That is, power comes in to the control board through the USB port and out to a 5V pin. Each board will be a little different, so it would be wise to verify that you can do this for your specific board. You want to ensure that there are no voltage regulators, diodes, or other components between the 5V pin and the USB port input that are going to be damaged by the high-current draw of the LEDs. You also want to ensure that any PCB traces are big enough that they don't heat up with increased current. Never try to draw more than 1A through a board's USB port like this; the boards really aren't designed for large amounts of current to flow through them.
When using this technique, make sure to add strain relief to your wires so that they don't flex and break. The easiest way to do this is to use hot glue. While you want to use plenty of hot glue, just be careful to not cover any components that are going to get hot with hot glue.
"},{"location":"advanced/wiring/#medium-setups-30-300-rgb-leds","title":"Medium Setups (30-300 RGB LEDs)","text":"For a medium-sized setup of 30-300 LEDs, you should find a power supply that can provide enough current (see the link above) and make sure to power the strip directly. For setups with more than 150 LEDs, you should consider power injection.
"},{"location":"advanced/wiring/#power-injection","title":"Power injection","text":"Power injection is where you connect multiple wires from your power supply to the strip in multiple places, usually once at the beginning and once at the end. This is needed because the LED strips can only pass a small amount of current through them and you need to ensure that all your power-hungry LEDs get fed enough power. If your LEDs are dim or discolored at one end of the strip, you should add power injection.
When doing power injection, make sure your wires are rated for the amperage you wish to send over them. You should also check the voltage drop if you're doing a particularly long run. As a rough guide, you should never use anything thinner than 22AWG wire for power injection.
For medium-sized setups, you should add fuses if your power supply is over 100W. Considering an inline fuse on each power injection line.
"},{"location":"advanced/wiring/#inline-fuses","title":"Inline Fuses","text":"You should place the fuse as close to the power supply as possible, on the positive lead, so that as much of the current flows through it as possible. That will cause the fuse to blow if the power injection line shorts or if the strip shorts, instead of causing your power injection wire or strip to heat up. Buy a fuse that's rated just over what you expect your LED strip to draw. For example, if you calculate that your LEDs will draw at most 4.5A, buy a 5A fuse.
First match your power injection wire size with the inline fuse's wire. If the inline fuse comes with 16AWG wire (it's usually printed on the wire itself in small type), you should use 16AWG or thicker wire for your power injection wire. If you use thinner wire, you weaken the utility of the inline fuse and risk your power injection wire heating up in the case of a failure.
To wire in an inline fuse, trim back the positive wire (not ground) of your power injection line enough to allow the inline fuse to be spliced in. Place a cut of heat-shrink tubing over the wire so that the cable can be insulated once your solder joint is complete. Strip and bend both wires of your splice so that they create hooks to mechanically reinforce the joint, then solder. Cover with the heat-shrink tubing and you're done! Now you have a beautiful, professional-looking fused power injection line.
"},{"location":"advanced/wiring/#larger-setups-300-rgb-leds","title":"Larger Setups (300+ RGB LEDs)","text":"The more power you're working with, the more you need to be careful about your wiring. If you're using a 150W or higher power supply or multiple power supplies, check out these tips:
"},{"location":"advanced/wiring/#wire-ferrules","title":"Wire ferrules","text":"If you're using stranded wire and lever-lock or screw terminals, all your wire \u2192 terminal connections should be terminated with a wire ferrule of the appropriate wire gauge.
This is because stranded wires can splay and lose tension over time, creating a weaker connection that could lead to sparking. Loose strands can also cause shorts or break off. The same is true for tinned stranded wires: the solder can deform (especially if it's heated), loosening the screw terminal, and cause a weaker electrical connection or complete failure. That said, untinned stranded wire in a screw terminal actually creates a better connection than tinned stranded wire, so for high current applications where they could possibly heat up, don't tin them if you don't have ferrules.
Shrouded wire ferrules also act as strain relief, minimizing mechanical damage if the wire moves at all. This is especially important for any installations that are mobile, could experience vibrations, or are installed/removed seasonally.
"},{"location":"advanced/wiring/#multiple-power-supplies","title":"Multiple power supplies","text":"When doing power injection with multiple power supplies never mix two power supplies on the same LED strip. You can connect grounds together, just never the positive rails. This means you need to segment your LEDs based on power supplies, including your power injection. For the same reasons listed below, never connect multiple power supplies to the same strip for power injection purposes, always fork one power supply and route it to the start/mid/end of the same strip.
Because multiple power supplies could have subtle variations in their positive voltages (e.g. 12.1V and 12.3V), this could lead to power flowing in ways that aren't expected or which could be damaging to your equipment. In general, wired power supplies don't like to be directly connected to other power supplies unless they are explicitly designed for that purpose. This is not true for cell batteries, which are usually fine with being connected in parallel provided all the battery voltage + chemistry are the same.
"},{"location":"advanced/wiring/#even-more-tips","title":"Even more tips","text":" - Always check wire gauge + amp ratings and make sure to overcompensate by 2-3\u00d7
- more, lower-current wires are better than fewer, higher-current wires
- Ensure that all strips are fused just above their max current. Fuses should be located as close to the power supply as possible.
- Make sure all distribution wires are neat, tidy, and mounted to a structure. If it needs to be loose to bridge an air gap, minimize the amount of dangling wire as much as possible. This ensures that if you were to have a wire become disconnected, it'll be easy to see where it is.
- Did you add fuses? Add fuses. Seriously.
"},{"location":"basics/compatible-controllers/","title":"Compatible controllers","text":"Currently (as of summer 2023) only the microcontrollers from Espressif, types ESP8266 and ESP32 (with dual core) are fully supported. 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 ESP8266 D1 mini or 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 can be used as an 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 integarte 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.
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!
"},{"location":"basics/compatible-controllers/#controllers-with-wled-pre-installed","title":"Controllers with WLED pre-installed","text":"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!
Name Description 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-02 WLED controller WLED dedicatedly designed Controller that supports 5V-12V addressable strips from Ukrainian developers. Based on ESP8266. Slim design, sensor button, powered either by type-C or screw-terminal. Screwdriver included. Worldwide delivery. ABC! WLED Controller / ESP8266 Commercial controller for 5V LED strips. Based on ESP8266 uC. Two outputs. Ready to use. Additional Relay&Fuse board available. (German shop & shipping only within Germany.). A similar one is available at WLED.SHOP ABC! WLED Controller / ESP32 Commercial controller for 5V LED strips. Based on ESP32 uC. Two outputs. Option for digital microphone or line-in-to-I2S Adapter for sound reactive WLED. Ready to use. Additional Relay&Fuse board available. (German shop & shipping only within Germany.). A similar one is available at WLED.SHOP. ABC! WLED Controller V43 / ESP32 based / 5V-24V Commercial controller board for 5V / 12V / 24V LED strips from creator of LED power, wiring and fuse calculator. Based on ESP32 uC. Preflashed SW. Up to four outputs. Option for digital microphone or line-in-to-I2S Adapter for sound reactive WLED. Automatic 5V/12V/24V recognition (no jumper/switch etc. required). Ethernet adapter is available . Enclosure is available too. German shop & shipping only within Germany. Worldwide shipping available soon at WLED.SHOP. ABC! WLED mini Controller V70 / ESP32 based / 5V-12V Commercial controller board for 5V / 12V LED strips from creator of LED power, wiring and fuse calculator. Based on ESP32 uC. Preflashed SW. Up to four outputs. Option for digital microphone or line-in-to-I2S Adapter for sound reactive WLED. Automatic 5V/12V recognition (no jumper/switch etc. required). Enclosure is available. German shop & shipping only within Germany.. Athom Light Strip Controller Simple controller with enclosure for reliably driving 3 pin 5V LEDs. Uses 2M ESP8266. Athom High Power Addressable LED Strip Controller Higher power options than the above system. Supports optional clock output. Athom LS8P ESP32 Music Controller ESP32 based controller with dual output, microphone and IR. Comes with WLED preinstalled Athom RGBW Light Strip Controller Has outputs for individual color channels. Cadsbi Motion Smart Ready to use solution with 3 output ports, an external antenna, in a high quality metal enclosure cod.m Wi-Fi Pixel Controller Fully completed control PCB with level shifter, terminals and case - pre-flashed with WLED! ESP8266 Pixel Controller 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 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 ESP32 WLED pico board,super small form factor, ready to buy on Tindie and Tindie EU. Integrated level shifter, exposed pins for extending functionality , on board I2S microphone, Firmware is here. Project page is here IOT4WLED Ready to use hardware for WLED! 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 Small ESP32 based controller with optional digital microphone integrated for digital 5V LED strips. Laterna Stick USB Stick like ESP32 based controller for digital 5V LED strips. LedBox V2 LedBox V2 by StanleyProjects is a fully contained, sound reactive, ESP32 based module for controlling 5-12V addressable LED strips (WS2812, SK6812, etc.), supporting both 3-(VDD,DAT,GND) and 4-(VDD,DAT,CLK,GND) pin configuration. It includes a digital MEMS microphone, button and IR control, and a safety resettable fuse, all in a compact 3D printable case. The board comes all setup, flashed with sound reactive WLED fork, and can be purchased here. Luminxa v2.2.2 ESP32 My Baby's Got LED Certified open hardware. 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) powers three 5V injection points on 8A fuses. For sale now on Tindie! Full details on the github repo and maker's website. 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! 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. Pre-assembled and pre-flashed with WLED available to buy!. Aircoookie's personal recommendation for medium-size WLED projects. 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. Pre-assembled and pre-flashed with WLED available to buy!. Aircoookie's personal recommendation for large-size WLED projects with advanced power and output requirements. 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! Simple WLED Board 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 autoprod rgbw, rgbw2+, rgbw4 Complete, fully-sealed, 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 Open source PCB for WLED WLED ESP32 universal controller ready to buy on Tindie, 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-programing. Headers for shields to extend functionality. Available shields for controller is here, Firmware is here. WLED Wemos mini shield shield board, ready to buy on Tindie also Tindie EU. 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. WLED waterproof controller with external antenna 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 Yet Another WLED 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 HighSet 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."},{"location":"basics/compatible-controllers/#controllers-wled-can-be-installed-to","title":"Controllers WLED can be installed to","text":"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 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 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: https://github.com/psxde/sp108e-led-controller/raw/main/sp108ev2_inside.png 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: https://github.com/Operation760/SP501e-RGB-LED-Controller-/blob/master/SP501e_top_bottom_traced.jpg Flashing Connections: https://github.com/tonyn0/sp501e-flashing/blob/main/sp501e%20flash.png SP511e 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. ESP LED Strip WIFI Control Board [ESP Version] 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?)."},{"location":"basics/compatible-controllers/#wled-shields-to-be-use-with-esp8266esp32-controllr-boards","title":"WLED shields to be use with ESP8266/ESP32 controllr boards","text":"Name Description ABC! WLED Shield, all-purpose, for ESP8266/ESP32 Commercial WLED Shield for 5V/12V LED strips. To be used with ESP8266 or ESP32 in D1 mini format. Two outputs. Option for digital microphone or line-in-to-I2S Adapter for sound reactive WLED (with ESP32 only!). Automatic 5V/12V recognition (no jumper/switch etc. required). Enclosure is available too. German shop & shipping currently only within Germany. ESP-01 WLED shield shield board for ESP-01 board, ready to buy on Tindie. Integrated level shifter, 3 outputs for various configurations, mosfet for 1 analog channel, Firmware is here. WLED Wemos shield shield board, ready to buy on Tindie also Tindie EU or DIY 100% compatible with WLED project and WLED sound reactive fork. 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."},{"location":"basics/compatible-controllers/#other-products-wled-can-be-installed-to","title":"Other products WLED can be installed to","text":"Name Chip Description Merkury MI-BW210-999W 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 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 Athom 15W 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"},{"location":"basics/compatible-controllers/#raw-esp8266esp32-boards","title":"Raw ESP8266/ESP32 boards","text":"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 ESP8266 General-purpose ESP8266 Board with USB, battery connector, etc. D1 mini-style ESP32 ESP32 A nice compact ESP32 development board. D1 mini compatible layout. ESP32 DevKitC v4 ESP32 The original ESP32 Development Board made by Espressif Systems. H803 WiFi ESP8266 ESP8266EX based controller with level shifter inside. Data pin GPIO1 Clock pin GPIO14. Tested with WS2813 strip and Firmware fork is here. 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 Heltec 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. NodeMCU 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. 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) Olimex 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 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 ESP8285 5v DC input - onboard 10A relay TwilightLord-ESP32 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 ESP32 mini dev board 16mb by SerKo (aka Serg) 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 Wemos D1 mini 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 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 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."},{"location":"basics/compatible-hardware/","title":"Other Hardware","text":"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!
"},{"location":"basics/compatible-hardware/#useful-boards-and-addons","title":"Useful boards and addons","text":"Name Description TwilightLord-ESP32 Ethernet Shield Ethernet Shield (10/100Mbps) for ESP32 boards. Stackable with D1 Mini32 form factor boards. Wemos D1 mini Level Shifter Shield A level shifter shield (74HCT125) - by Evil Genius Labs LLC. WIZmote remote control Remote control using radio network. Compatible with WLED (vesions 0.14.0-beta3 and above). No additional receiver required."},{"location":"basics/compatible-hardware/#compatible-pc-rgb-fans-and-argb-accessories","title":"Compatible PC RGB Fans and ARGB accessories","text":"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."},{"location":"basics/compatible-hardware/#levelshifters","title":"Levelshifters","text":"Name Description SN74AHCT125 Aircoookie's recommended levelshifter. Often used in DIY and commercial controllers. 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 TXS0102, TXS0108 Bidirectional levelshifters that may work fine with WLED (if possible, 74AHCT gates should be preferred as they support both longer data lines and faster protocols) F-Amp Level shifter/data booster Warning
I2C shifters are generally too slow for addressable LEDs, so don't use them.
Further reading: Logic Level Shifters for Driving LED Strips
How to connect Levelshifters:
"},{"location":"basics/compatible-hardware/#usbttl-adapters","title":"USB/TTL adapters","text":"Name Description CH340 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 an USB/TTL adapter onboard this is NOT needed 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."},{"location":"basics/compatible-hardware/#miscellaneous","title":"Miscellaneous","text":"Sorting: Sensors, Displays, Actuators
Name Description HC-SR501 \u00a0PIR sensor with adjustable sensitivity and on time delay (suitable as a button). HC-SR602 \u00a0PIR sensor (not suitable as a button but can be used with PIR sensor usermod). TSOP38238 IR receiver compatible with most IR remotes. SSD1305 I2C display, can be used with 4 Line Display usermod. 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 Display shield Various configurations. Compatible with the ESP32 WLED dev board also can be used with ESP32 mini dev boards. 12V Relay & Fuse board Integrates two relays and two 10 A fuses. Suitable for WLED setups with 12 V LED Strips. 5V relay 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 Integrates two relays and two 10 A fuses. Suitable for WLED setups with 5V LED Strips."},{"location":"basics/compatible-led-strips/","title":"Compatible LED strips","text":"WLED supports two types of LED strips: the so-called digital addressable LED strips and the so-called analog non-addressable LED strips.
"},{"location":"basics/compatible-led-strips/#addressable-led-strips","title":"Addressable LED Strips","text":"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 5v/12v RGBW WS2811 5v usually found in IP68 sealed 12mm pixel strings WS2812B 5v WS2813 5v has a backup data line APA102 5v using 2 data pins, Clock and Data LPD8806 5v using 2 data pins, Clock and Data WS2801 5v using 2 data pins, Clock and Data SK9822 5v using 2 data pins, Clock and Data UCS8903 5v GS8208 12v TM1814 12v RGBW WS2811 12v usually 3-LED segments, has data-line resistor WS2814 12v/24v 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 12v has a backup data line LPD6803 12v P9813 5-24 v TM1829 5-24 v UCS8904 5-24 v RGBW"},{"location":"basics/compatible-led-strips/#non-addressable-led-strips","title":"Non-Addressable LED Strips","text":"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. A basic circuit diagram is shown here. You need one MOSFET and one GPIO per color. It should be noted that the MOSFETs are destroyed very quickly in the event of an overload. 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. 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.
"},{"location":"basics/compatible-software/","title":"Compatible Software","text":"Still under construction, feel free to add to the list!
This page lists some third-party software that can interface with WLED!
"},{"location":"basics/compatible-software/#controllers","title":"Controllers","text":"Controllers use the WLED API to change the current light settings.
Name Description Home Assistant 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 Home automation system, WLED integration via the D.A.L.O.R. app with automatic discovery. ioBroker adapter Versatile and feature rich home automation system. Out-of-the-box WLED integration with automatic discovery. Lumia Stream Allows for control of your lights from streaming software node-red-contrib-wled Node-RED nodes for WLED OctoPrint-WLED Connect your OctoPrint install to your WLED install using this plugin to show things like printer status, progress and more! openHAB Another more professional feature rich home automation system. WLED integration made easy. Link 2 WLED-GUI This is a cross-platform desktop app for WLED. You can use it on Windows, Linux and Mac. wledQuickControl macOS 11.0+ Menu Bar app for controlling power and brightness."},{"location":"basics/compatible-software/#sources","title":"Sources","text":"Source programs generate light data and stream them to WLED in real time.
Name Description LedFx A music visualization tool written in Python. Connects to WLED via E1.31 or UDP. Dr.Zzs tutorial video Prismatik WLED-WiFi (native) Ambilight via WiFi or serial - natively supports UDP (WARLS, DRGB, DNRGB protocols). Prismatik WLED-WiFi (plugin) Ambilight via WiFi - a Plugin alternative for Prismatik WLED support. xLights xLights is a Light Sequencer and Show scheduler which works with WLED. Dr.Zzs has made some videos to set it up. Intro Video Hyperion.ng 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, Dr.Zzs video Hyperion (Classic) 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+ 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."},{"location":"basics/compatible-software/#various","title":"Various","text":"Name Description Logitech WLED Sync Windows tray application to sync Logitech gaming peripherals to WLED."},{"location":"basics/compiling-wled/","title":"Compiling WLED","text":"Moved, see How to compile WLED
"},{"location":"basics/faq/","title":"FAQ","text":"This page will continually get updated with questions often asked.
"},{"location":"basics/faq/#contents","title":"Contents","text":""},{"location":"basics/faq/#installation","title":"Installation","text":" - What binary should I use?
- I've flashed a bin, but i get no response at all
"},{"location":"basics/faq/#connection-issues","title":"Connection issues","text":" - Once I attach LEDs, I can't connect to the ESP anymore!
- 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 wled-xxx.local address (mDNS) does not work.
- Is it safe to do a port forwarding to the public internet to control the lights from anywhere?
- My device is unresponsive or animations lag!
- I'm 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!
- Still having connection issues/connection dropping: what more can i check?
"},{"location":"basics/faq/#compilation-issues","title":"Compilation issues","text":" - When compiling WLED in VS Code using platformio, I get an error.
"},{"location":"basics/faq/#led-issues","title":"LED issues","text":" - My LEDs don't turn on at all.
- My LEDs don't get as bright as they should!
- My LEDs are unable to be set into an consistent solid color.
- When I select green, the LEDs turn red!
- My LEDs act funny and flicker randomly.
- Not all my LEDs turn on.
- How to turn off the bright blue onboard LED?
- Why is gpio2/D4 the default LED pin?
- Why can I only use 500 LEDs on the ESP8266 GPIO pin 3?
- What LED strip hardware is supported by WLED?
"},{"location":"basics/faq/#general-questions","title":"General questions","text":" - What does the name WLED mean?
- What do the WLED version names mean?
- What is the difference between the brightness sliders in the web UI?
- My Segments are gone after a reboot!
- May I sell a product running WLED?
"},{"location":"basics/faq/#my-question-or-solution-is-not-on-this-page","title":"My question or solution is not on this page","text":" - Check out the WLED forum!
- Look through the Issues
- If I report a new Issue, what do i need to share?
"},{"location":"basics/faq/#installation_1","title":"Installation","text":""},{"location":"basics/faq/#what-binary-should-i-use","title":"What binary should I use?","text":"Please see this page.
"},{"location":"basics/faq/#ive-flashed-a-bin-but-i-get-no-response-at-all","title":"I've flashed a bin, but i get no response at all","text":"Some users report first erasing the flash (yes, even on a new device) sometimes helps .
"},{"location":"basics/faq/#connection-issues_1","title":"Connection issues","text":""},{"location":"basics/faq/#once-i-attach-leds-i-cant-connect-to-the-esp-anymore","title":"Once I attach LEDs, I can't connect to the ESP anymore!","text":"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!
"},{"location":"basics/faq/#i-have-entered-my-wifi-credentials-and-rebooted-but-i-can-not-connect-to-the-module-now","title":"I have entered my WiFi credentials and rebooted, but I can not connect to the module now!","text":"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 Android app which features automatic discovery!
"},{"location":"basics/faq/#the-module-once-was-connected-but-i-can-no-longer-reach-it","title":"The module once was connected, but I can no longer reach it","text":"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.
"},{"location":"basics/faq/#the-wled-xxxlocal-address-mdns-does-not-work","title":"The wled-xxx.local address (mDNS) does not work","text":"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. I highly recommend you install the WLED app, which makes automatic discovery easy!
"},{"location":"basics/faq/#is-it-safe-to-do-a-port-forwarding-to-the-public-internet-to-control-the-lights-from-anywhere","title":"Is it safe to do a port forwarding to the public internet to control the lights from anywhere?","text":"See this page.
"},{"location":"basics/faq/#my-device-is-unresponsive-or-animations-lag","title":"My device is unresponsive or animations lag!","text":"You are probably using too many sync interfaces. Please only enable one of Hue sync, MQTT, or Blynk 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.
"},{"location":"basics/faq/#im-having-a-bootloop-leds-turn-on-every-5seconds","title":"I'm having a bootloop! (LEDs turn on every ~5seconds)","text":"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!
"},{"location":"basics/faq/#still-having-connection-issuesconnection-dropping-what-more-can-i-check","title":"Still having connection issues/connection dropping: what more can i check?","text":"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.
"},{"location":"basics/faq/#i-am-running-realtime-eg-e131-and-not-all-of-my-leds-are-driven-fluently","title":"I am running realtime (e.g. E1.31) and not all of my LEDs are driven fluently!","text":"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.
"},{"location":"basics/faq/#compilation-issues_1","title":"Compilation issues","text":""},{"location":"basics/faq/#when-compiling-wled-in-vs-code-using-platformio-i-get-an-error","title":"When compiling WLED in VS Code using platformio, I get an error","text":"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!
"},{"location":"basics/faq/#led-issues_1","title":"LED issues","text":""},{"location":"basics/faq/#my-leds-dont-turn-on-at-all","title":"My LEDs don't turn on at all.","text":"Please make sure you have connected the strip to GPIO2 and it is sufficiently powered.
"},{"location":"basics/faq/#my-leds-dont-get-as-bright-as-they-should","title":"My LEDs don't get as bright as they should!","text":"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.
"},{"location":"basics/faq/#my-leds-are-unable-to-be-set-into-an-consistent-solid-color","title":"My LEDs are unable to be set into an consistent solid color","text":"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.
"},{"location":"basics/faq/#when-i-select-green-the-leds-turn-red","title":"When I select green, the LEDs turn red!","text":"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.
"},{"location":"basics/faq/#my-leds-act-funny-and-flicker-randomly","title":"My LEDs act funny and flicker randomly","text":""},{"location":"basics/faq/#reason-1","title":"Reason 1","text":"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.
"},{"location":"basics/faq/#reason-2","title":"Reason 2","text":"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.
"},{"location":"basics/faq/#reason-3","title":"Reason 3","text":"Your data line can only be so long. 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 ;-)).
"},{"location":"basics/faq/#reason-4","title":"Reason 4","text":"If they don't flicker, but display funny colors, try switching between RGB/RGBW modes in LED settings.
"},{"location":"basics/faq/#not-all-my-leds-turn-on","title":"Not all my LEDs turn on","text":""},{"location":"basics/faq/#reason-1_1","title":"Reason 1","text":"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 here for maximum recommended LED counts.
"},{"location":"basics/faq/#reason-2_1","title":"Reason 2","text":"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!
"},{"location":"basics/faq/#how-to-turn-off-the-bright-blue-onboard-led","title":"How to turn off the bright blue onboard LED?","text":"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
"},{"location":"basics/faq/#why-is-gpio2d4-the-default-led-pin","title":"Why is gpio2/D4 the default LED pin?","text":"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.
"},{"location":"basics/faq/#why-can-i-only-use-500-leds-on-the-esp8266-gpio-pin-3","title":"Why can I only use 500 LEDs on the ESP8266 GPIO pin 3?","text":"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.
"},{"location":"basics/faq/#what-led-strip-hardware-is-supported-by-wled","title":"What LED strip hardware is supported by WLED?","text":"The compatible chipsets for the color-coding are
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.
"},{"location":"basics/faq/#general-questions_1","title":"General Questions","text":""},{"location":"basics/faq/#what-does-the-name-wled-mean","title":"What does the name WLED mean?","text":"WiFi Lighting Effects Driver. Also it has LED in the name and is similar to the official term for WiFi, WLAN!
"},{"location":"basics/faq/#what-do-the-wled-version-names-mean","title":"What do the WLED version names mean?","text":"WLED version names are Japanese! Here is a nice list of their meanings:
Version Name Kanji Meaning 0.10 Namigai \u6d6a\u8c9d Geoduck (don't google it!) 0.11.0 Mirai \u672a\u6765 Future 0.11.1 Fumikiri \u8e0f\u5207 Railroad crossing 0.12 Hikari \u5149 Light 0.13 Toki \u6642 Time N/A Kuuhaku \u7a7a\u767d Blank"},{"location":"basics/faq/#what-is-the-difference-between-the-brightness-sliders-in-the-web-ui","title":"What is the difference between the brightness sliders in the web UI?","text":"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. Please note that this does not override the master brightness, but instead is an additional downscaling. (If you set both Master and Segment brightness sliders to 50%, the resulting brightness is 25%)
"},{"location":"basics/faq/#my-segments-are-gone-after-a-reboot","title":"My Segments are gone after a reboot!","text":"Segments are non-persistant 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 Favorites tab in the web UI, click the save checkbox and save the config to preset slot number
16 - In LED settings, set
Boot Preset to 16
This will be improved in a future release, so that you will be able to save multiple segment configurations!
"},{"location":"basics/faq/#may-i-sell-a-product-running-wled","title":"May I sell a product running WLED?","text":"WLED is licensed under the MIT license, thus you are free to use it in any way you wish as long as you retain the copyright notice and accept that I am not to be held liable for anything regarding your use of the software. For product pages, a link to the WLED GitHub repository would be hugely appreciated !
"},{"location":"basics/faq/#my-question-or-solution-is-not-on-this-page_1","title":"My question or solution is not on this page","text":""},{"location":"basics/faq/#check-out-the-wled-forum","title":"Check out the WLED forum!","text":"You can check out and use the WLED Discourse forum.
"},{"location":"basics/faq/#look-through-the-issues","title":"Look through the Issues","text":"Maybe someone already reported your issue, so everybody supplying support would be grateful if you take some time to search through the existing issues.
"},{"location":"basics/faq/#if-i-report-a-new-issue-what-do-i-need-to-share","title":"If I report a new Issue, what do i need to share?","text":"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 https://docs.wled.me?
- 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?
"},{"location":"basics/getting-started/","title":"Getting Started","text":""},{"location":"basics/getting-started/#welcome-to-the-wled-wiki","title":"Welcome to the WLED wiki!","text":"Version Info
Unless noted otherwise, all information applies to the latest release (v0.13.3).
"},{"location":"basics/getting-started/#quick-start-guide","title":"Quick start guide","text":"1. Connect a WS2812B-compatible RGB(W) led strip to GPIO2. On most ESP8266 based development boards this pin is labeled D4, on ESP32 based boards use IO16 or G16 or 16. If the connecting wire cannot be kept short, use a level shifter/translator. Optionally connect a normally open pushbutton to GPIO0 (NodeMCU/Wemos pin D3, on ESP32 use IO17) and ground for configurable actions. Note: 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!
While using an ESP8266 and LEDs that have clock and data, you can either use hardware SPI (mostly faster) or software SPI. - hardware SPI: use GPIO14 (SCLK) for clock and GPIO13 (MOSI) for data. - software SPI: since all pins can be changed in the Hardware section of LED settings, you can use any pins. Recommend is to use GPIO1 (TxD) for clock and GPIO2 (D4) for data.
For safe operation it is recommended to size your power wires correctly and to integrate fuses. For reference, you may use this LED power, wiring and fuse calculator.
For analog LEDs, the MOSFETs IRLZ44N or STP55NF06L are good candidates. Partial, example circuit...
2. Flash the software to your ESP module! There are two options for this step:
I just want to use WLED! (install release binary)
I want to modify WLED (compile from source code)
If everything worked the first thirty LEDs will light up in bright orange to stimulate courage, friendliness and success!
3. Use a WiFi device to connect to the access point WLED-AP using the default password wled1234. You can also just scan this QR code:
WLED-AP is not showing up!
If you do not see the WLED-AP SSID, the default SSID may have been changed at compile time.
Go to the IP 4.3.2.1 in your browser to control your lights! You should also be able to connect to wled.me if in access point mode (embedded DNS server).
"},{"location":"basics/getting-started/#wifi-setup","title":"Wifi Setup","text":"To connect your WLED module to your home Wifi:
1. Click on the Config (gear) icon to edit your WLED module settings and choose 'Wifi Setup'.
2. For most home networks, simply enter your Wifi network's name and network password. You can also change the mDNS address for your WLED module here.
3. Click Save & Connect at the bottom of the page.
4. Reconnect your device to your home's Wifi network.
5. Check the device list in your router's user interface for the IP of the WLED device within your local network. For easy automatic discovery, use the WLED app! Have fun with the WLED software!
"},{"location":"basics/getting-started/#default-gpio-usage","title":"Default GPIO Usage","text":"These are only defaults
All pins can be changed in the Hardware section of LED settings. Please note that these are GPIO numbers, please consult a pinout for your board to find the labeled pin (e.g D4 = GPIO2 on most ESP8266 boards). When using an ESP8266 board, it's recommended to use pins GPIO1, GPIO2, or GPIO3 for LED Data; using other pins will require bit-banging and may cause slow performance and/or issues elsewhere (such as with IR decoding).
Function GPIO Suggested pin LED Data 2 ESP8266: 1, 2 (3 if <= 100 LEDs), ESP32: 1, 2, 3, 4, 16 Button 0 IR Remote None 4 Relay None 12"},{"location":"basics/getting-started/#software-update-procedure","title":"Software update procedure","text":"Method 1: Reflashing the new update like a new install (see above).
Method 2: The software has an integrated OTA software update capability. First you have to enable it by typing in the correct OTA passphrase (default: \"wledota\") in the settings menu. Remove the tick in the checkbox \"OTA locked\". Then save settings and reboot the ESP. Then you can select \"Manual OTA update\" in Security settings and upload a release binary. After you are done, it is recommended to lock the OTA function again. To do so, tick the checkbox again (you can change the passphrase by typing in a new one now). Reboot. If you try to access the update page now, you should see the message \"OTA lock active\".
Method 3: ArduinoOTA is also supported.
If you own multiple devices and want to update them
Since v0.13 of WLED source code includes shell/command prompt scripts which is allow you to update multiple devices with a single command. Please check tools subfolder for multi-update scripts (.cmd or .sh). You will need to modify them to include IP addresses of your WLED devices and assign firmware binary file for each device. If you are using Windows, make sure you install curl utility somewhere in your PATH (curl is included with Windows 10 since build 17063). This will only work if \"OTA Lock\" is disabled.
"},{"location":"basics/install-binary/","title":"Install WLED Binary","text":""},{"location":"basics/install-binary/#flashing-method-1-wled-web-installer","title":"Flashing method 1: WLED web installer","text":"Tip
This is by far the easiest and fastest way to get WLED up and running!
Make sure you are running a recent desktop Chrome or Edge browser and head over to the WLED installer site! If you are updating an existing version of WLED, make sure to uncheck \"Clean install\" so that your settings are kept. 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/. After using the standard WLED installer, microphone hardware sometimes cannot be initialized properly by WLED.
"},{"location":"basics/install-binary/#flashing-method-2-esptool","title":"Flashing method 2: esptool","text":" - First of all, please follow the steps to install esptool.py here.
- Download the latest release binary 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 after write_flash - Execute this command:
"},{"location":"basics/install-binary/#esp8266","title":"ESP8266","text":"esptool.py write_flash 0x0 ./WLED_XXX.bin\n
"},{"location":"basics/install-binary/#esp32","title":"ESP32","text":"Firstly, flash the version 4 bootloader file, which you can find here. This step only has to be done once, to update afterwards the bootloader does not have to be re-installed.
esptool.py write_flash 0x0 ./esp32_bootloader_v4.bin\n
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.
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!)
esptool.py erase_flash\n
If you have a MagicHome controller, here is a good video tutorial on how to flash it.
"},{"location":"basics/install-binary/#esp8266-flashing-method-3-esp-home-flasher-tool","title":"ESP8266 Flashing method 3: ESP Home Flasher tool","text":"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, 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: https://www.wemos.cc/en/latest/ch340_driver.html 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 instead of ESP Home Flasher.
"},{"location":"basics/install-binary/#flashing-method-4-ota-update","title":"Flashing method 4: OTA update","text":"You can alternatively use my basic HTTP OTA updater 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.
"},{"location":"basics/install-binary/#what-binary-should-i-use","title":"What binary should I use?","text":"I always recommend to use the latest release. Starting from WLED 0.12.0, pins can be configured in LED settings and specific binaries for different LED pins or types are no longer needed. Please use the following binary for these boards respectively:
Binary Name For devices WLED_0.x.x_ESP8266.bin NodeMCU, Wemos D1 mini, ESP-12, all ESP8266 with 4MB flash. Recommended. WLED_0.x.x_ESP32.bin All ESP32 devices (try this if the WLED-AP doesn't appear after flashing) WLED_0.x.x_ESP32_Ethernet.bin ESP32 devices with an Ethernet interface. Also works with WiFi only. WLED_0.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_0.x.x_ESP02.bin All ESP8266 with 2MB flash, Athom bulbs esp32_bootloader.bin Not a WLED release. To be flashed to a brand new ESP32 before flashing the WLED binary itself. Legacy binary format (up to 0.11.1)
Binary Name For devices WLED_0.x.x_ESP8266_1M_ota.bin ESP-01 (black PCB), most Sonoff devices, ESP8265, all ESP8266 with 1MB flash. This binary has some interfaces disabled (Alexa, Blynk, Hue sync, Infrared) in order for wireless updates to continue working. WLED_0.x.x_ESP8266_1M_full.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_0.x.x_ESP8266_512k.bin ESP-01 (blue PCB), older Sonoff devices, all ESP8266 with 512kB flash. Interfaces (Alexa, Blynk, Hue sync, Infrared) disabled, no OTA. Support will not be possible in future versions. WLED_0.x.x_ESP8266_ledpinY.bin Custom build for 4MB flash ESP8266 and WS2812B. LED pin is changed (default is GPIO2). (This is GPIOY and not DY for the D to GPIO mapping, check your boards spec!) WLED_0.x.x_ESP8266_apa102.bin Custom build for 4MB flash ESP8266 and APA102 LEDs (clock pin GPIO0, data GPIO2). WLED_0.x.x_ESP8266_ws2801.bin Custom build for 4MB flash ESP8266 and WS2801 LEDs (clock pin GPIO0, data GPIO2). WLED_0.x.x_ESP32_ledpinY.bin Custom build for ESP32 and WS2812b. LED pin is changed (default is GPIO2). LED pin 16 is useful for the QuinLed-Dig-Uno board with ESP32."},{"location":"basics/install-gui/","title":"Installation using ESP GUI","text":""},{"location":"basics/install-gui/#1-downloading-the-firmware-bin-file","title":"1. Downloading the firmware bin file","text":"You can find precompiled .bin files on the release page. 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?
"},{"location":"basics/install-gui/#2-downloading-the-flash-download-tools","title":"2. Downloading the Flash Download Tools","text":"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! (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.
"},{"location":"basics/install-gui/#3-flashing-the-firmware-bin-files","title":"3. Flashing the firmware bin files","text":"After starting flash_download_tools_v[...].exe there should pop up two small windows. Now just click on the Developer Mode andESP8266 DownloadTool button. Now a new window opens.
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
"},{"location":"basics/install-wled-flasher/","title":"Installation using ESP GUI","text":""},{"location":"basics/install-wled-flasher/#1-downloading-wled-firmware-bin-file","title":"1. Downloading WLED firmware bin file","text":"You can find precompiled .bin files on the official release page. Also available alternative with precompiled usermods
If you are not sure what binary you should use look at this page: What binary should I use?
"},{"location":"basics/install-wled-flasher/#2-downloading-the-esp-wled-flasher","title":"2. Downloading the ESP WLED Flasher","text":"You can find and download flasher here!
After downloading a file, unzip it and start
"},{"location":"basics/install-wled-flasher/#3-flashing-firmware-bin-files","title":"3. Flashing firmware bin files","text":"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
"},{"location":"basics/tutorials/","title":"Tutorials","text":"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:
"},{"location":"basics/tutorials/#wled-specific-tutorials","title":"WLED specific tutorials","text":"Resource Maker Type Date Info Beginner's guide to freak'n cool Holiday LEDs 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 DrZzs Video (23:39) 29 Oct 2019 Learn about some cool additional WLED features! Make your LEDs dance to music! 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 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) 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 Quindor Video (11:13) 21 Sept 2019 Initial flash and setup of WLED on QuinLED-Dig-Uno board Integrating WLED into Home Assistant 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 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 KPeyanski Article 23 Jul 2022 Same as the above video, but in text form! Smart Ping Pong LED Lamp - Quick&Simple DIY 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/\u043d\u0430 \u0440\u0443\u0441\u0441\u043a\u043e\u043c) Gelmer Article Series 11 Jun 2023 \u0421\u0435\u0440\u0438\u044f \u0440\u0443\u043a\u043e\u0432\u043e\u0434\u0441\u0442\u0432 \u043f\u043e \u0443\u0441\u0442\u0430\u043d\u043e\u0432\u043a\u0435 \u0418\u043d\u0441\u0442\u0440\u0443\u043a\u0446\u0438\u044f \u043d\u0430 \u0440\u0443\u0441\u0441\u043a\u043e\u043c: \u041a\u0430\u043a \u043f\u0440\u043e\u0448\u0438\u0442\u044c WLED \u0438 LED FX \u0432 ESP01 \u041f\u0440\u0438\u043c\u0435\u0440 \u043f\u0440\u0438\u043c\u0435\u043d\u0435\u043d\u0438\u044f WLED: \u0411\u0435\u0441\u043a\u043e\u043d\u0435\u0447\u043d\u044b\u0439 \u0437\u0435\u0440\u043a\u0430\u043b\u044c\u043d\u044b\u0439 \u0442\u0443\u043d\u043d\u0435\u043b\u044c \u0432\u043d\u0443\u0442\u0440\u0438 \u0441\u0442\u043e\u043b\u0438\u043a\u0430 IKEA Lack Alchemist Video (9:16) / Video (13:09) 19 Aug 2022 \u041f\u0440\u043e\u0448\u0438\u0432\u043a\u0430, \u0443\u0441\u0442\u0430\u043d\u043e\u0432\u043a\u0430 \u043d\u0435\u043e\u0431\u0445\u043e\u0434\u0438\u043c\u044b\u0445 \u0434\u0440\u0430\u0439\u0432\u0435\u0440\u043e\u0432 \u0438 \u0434\u0435\u043c\u043e\u043d\u0441\u0442\u0440\u0430\u0446\u0438\u044f \u0440\u0435\u0436\u0438\u043c\u043e\u0432 \u0440\u0430\u0431\u043e\u0442\u044b. \u041f\u0440\u0438\u043c\u0435\u0440 \u044d\u043b\u0435\u043a\u0442\u0440\u043e\u043d\u043d\u043e\u0439 \u0441\u0445\u0435\u043c\u044b. ESP8266 based LED controller for WS2812b strip. WLED Firmware + OpenHAB (in Russian) Room31 Video (17:04) 11 Mar 2020 How to use WLED on an ESP32 (German) Bitbastelei/Adlerweb Video (11:00) 1 Nov 2020 DIY Ambilight using WLED and a Relay jangrewe Article ? Wiki page with schematics and instructions for Hyperion, etc. Adding Smarts and Color to an IKEA Lamp apop880 Article 21 May 2021 Tutorial on upgrading a basic IKEA lamp with WLED"},{"location":"basics/tutorials/#digital-led-knowledge","title":"Digital LED knowledge","text":"Resource Maker Type Info Adafruit NeoPixel \u00dcberguide Adafruit Article Everything that's important at a glance. Highly recommended for newcomers to digital LEDs Digital LED Power Usage Quindor Article/Spreadsheet/Video Helps you plan the power usage of your installation Power calculation and injection live stream 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 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 The Hook Up Video (12:14) Make your project look much better! Power Injection demystified Spiker Lights Article What is power injection and how much do I need? Common(sharing) Ground / Multiple power supplies Article When using more than one power supply."},{"location":"basics/tutorials/#tools-skills","title":"Tools & Skills","text":"Resource Maker Type Info How to Solder Beauty and the Bolt Video (9:50) Soldering new leads to LED strip Quindor Video (8:24) Soldering Tutorial Part 2 EEVblog Video (34:05) Detailed tutorial on soldering, see parts 1 and 3 for even more info) Voltage Drop Calculator Tool Another Voltage Drop Calculator Tool Pixel/Bullet Voltage Drop Calc Tool 5 and 12V Combined Wire Gauge Calculator Tool Wire Size/Ampacity Tool Use chassis wiring Add more categories as needed :)
"},{"location":"features/cct/","title":"White handling","text":""},{"location":"features/cct/#white-channels-handling","title":"White channel(s) handling","text":"Besides addressable RGB and RGBW bus types, WLED 0.13.0 also supports PWM CCT (correlated color temperature) lights.
"},{"location":"features/cct/#auto-white-handling","title":"Auto white handling","text":"Many effects and realtime sources are based on an RGB color model, which necessitates a method to calculate a white channel value from the RGB value for lights that support more than RGB.
WLED offers four auto white modes, one of which can be selected in LED settings using the option Auto-calculate white channel from RGB. This option is only shown if at least one bus with White channel support is present.
Auto White mode Description Accurate This mode subtracts the calculated white value from the RGB channels. This gets rid of the \"RGB-white\" but means that the light is less bright with only the white channel and not the RGB channels being utilized for pure white. Brighter This does the exact opposite and not touch the RGB channels at all, just mix in the dedicated white. None No auto white calculation is performed. The white channel of colors can be manually set using the White channel slider in the user interface, RGB-only effects and most realtime sources will leave the white channel off. Dual The White channel slider is present in the UI and works the same as in None mode, however if the slider value is 0 (far left), the Brighter mode is used for auto white calculation. This is the default auto white mode. Accurate and Brighter methods are applied on a per-pixel basis, so they also work in color palettes and realtime effects!
"},{"location":"features/cct/#white-balance-correction","title":"White Balance correction","text":"If enabled in LED settings, WB correction allows either making all pixels colder or warmer on a per-segment basis using a slider in the main user interface. This is applied to the RGB color only, after the auto white channel calculation.
"},{"location":"features/cct/#cct-handling","title":"CCT handling","text":"WLED starting with version 0.13.0 also supports bus types with two white channels, one with a warm color temperature (e.g. 2700 Kelvin, reddish white) and one with a cold white color temperature (e.g. 8000 Kelvin, bluish white).
Since as of the release of version 0.13.0 no adjustable CCT addressable LEDs are supported*, this only applies to PWM analog LED outputs.
*SK6812 WWA (with 3 channels, warm white, cold white and amber) are supported, but treated as if RGB using the WS281x bus type. White spectrum support for this LED type will be added at a later point.
The overall brightness of the white channels is determined from the auto-white calculation outlined above, and as such is identical in behavior to that of single white channel busses.
The color temperature is set either on a per-segment basis via a dedicated slider in the UI, or if Calculate CCT from RGB is enabled in LED settings, is estimated on a per-pixel basis from the set RGB color (e.g. setting Red results in the warmest, setting Blue results in the coldest possible white). The former has the advantage of granular white spectrum control independent of the set RGB color, while the latter enables control of the color temperature from all effects and realtime sources.
"},{"location":"features/cct/#cct-additive-blending","title":"CCT additive blending","text":"Setting this to 0% results in a more even brightness output across the supported temperature range, as the fading between the warm and cold white channels is linear.
Setting this to 100% results in the highest peak brightness output at the neutral white point (CCT value 127), as both white channels are active at 100%.
Warning
Make sure your setup can handle driving both white channels at maximum output simultaneously. This results in a higher heat output and might reduce the lifetime of your LEDs. For example, bulbs by Athom are designed for linear blending (0%) and may be damaged by attempting to use additive blending.
You can limit the maximum allowed additive blending at build time using the WLED_MAX_CCT_BLEND macro. For example, add -D WLED_MAX_CCT_BLEND=0 to your build flags to force linear blending only.
"},{"location":"features/cct/#ic-cct","title":"IC CCT","text":"By default, PWM CCT bus types set the value of the warm and cold white channels. If your hardware uses an IC that controls the color temperature based on one PWM signal and the overall brightness on the other, please use the build flag -D WLED_USE_IC_CCT in a custom compilation. (the 15W bulb by Athom uses this method)
"},{"location":"features/cct/#cct-in-the-json-api","title":"CCT in the JSON API","text":"Please see here for more info on how to handle WLED CCT from integrations.
"},{"location":"features/effects/","title":"Effects","text":"Version Info
Effects above 117 are only available 0.14+ or Sound Reactive forks. Retired Effects - Can't find an old favorite? Look here.
"},{"location":"features/effects/#effect-overlay","title":"Effect Overlay","text":"Some effects can be overlaid on the background of another effect. To use overlay, set up segments with overlapping pixels. The overlay effect must be playing on the segment with the higher id. If the Overlay option is checked, the background will not be painted and the effect from the lower segment will be displayed.
To aid in showing where colors vs palettes are used, all effects are rendered with the Party palette and the colors: Primary (Fx) (or black) Secondary (Bg) Tertiary (Cs).
ID Effect Description Flags Colors Parms 0 Solid Solid primary color on all LEDs \u22ee 1 Blink Blinks between primary and secondary color \u22ee \ud83c\udfa8 Fx, Bg Speed, Duty cycle 2 Breathe Fades between primary and secondary color \u22ee \ud83c\udfa8 Fx, Bg Speed 3 Wipe Switches between primary and secondary, switching LEDs one by one, start to end \u22ee \ud83c\udfa8 Fx, Bg Speed, Intensity 4 Wipe Random Same as Wipe, but uses random colors \u22ee \ud83c\udfa8 Speed 5 Random Colors Applies a new random color to all LEDs \u22ee \ud83c\udfa8 Speed, Fade time 6 Sweep Switches between primary and secondary, switching LEDs one by one, start to end to start \u22ee \ud83c\udfa8 Fx, Bg Speed, Intensity 7 Dynamic Sets each LED to a random color \u22ee \ud83c\udfa8 Speed, Intensity, Smooth 8 Colorloop Cycle all LEDs through the rainbow colors \u22ee \ud83c\udfa8 Speed, Saturation 9 Rainbow Displays rainbow colors along the whole strip \u22ee \ud83c\udfa8 Speed, Size 10 Scan A single primary colored light wanders between start and end \u22ee \ud83c\udfa8 Fx, Bg, Cs Speed, # of dots, Overlay 11 Scan Dual Same as Scan but uses two lights starting at both ends \u22ee \ud83c\udfa8 Fx, Bg, Cs Speed, # of dots, Overlay 12 Fade Fades smoothly between primary and secondary color \u22ee \ud83c\udfa8 Fx, Bg Speed 13 Theater Pattern of one lit and two unlit LEDs running \u22ee \ud83c\udfa8 Fx, Bg Speed, Gap size 14 Theater Rainbow Same as Theater but uses colors of the rainbow \u22ee \ud83c\udfa8 Bg Speed, Gap size 15 Running Sine Waves scrolling \u22ee \ud83c\udfa8 Fx, Bg Speed, Wave width 16 Saw Sawtooth Waves scrolling \u22ee \ud83c\udfa8 Fx, Bg Speed, Width 17 Twinkle Random LEDs light up in the primary color with secondary as background \u22ee \ud83c\udfa8 Fx, Bg Speed, Intensity 18 Dissolve Fills LEDs with primary in random order, then off again \u22ee \ud83c\udfa8 Fx, Bg Repeat speed, Dissolve speed, Random 19 Dissolve Rnd Fills LEDs with random colors in random order, then off again \u22ee \ud83c\udfa8 Bg Repeat speed, Dissolve speed 20 Sparkle Single random LEDs light up in the primary color for a short time, secondary is background \u22ee \ud83c\udfa8 Fx, Bg Speed, Overlay 21 Sparkle Dark All LEDs are lit in the primary color, single random LEDs turn off for a short time \u22ee \ud83c\udfa8 Bg, Fx Speed, Intensity, Overlay 22 Sparkle+ All LEDs are lit in the primary color, multiple random LEDs turn off for a short time \u22ee \ud83c\udfa8 Bg, Fx Speed, Intensity, Overlay 23 Strobe All LEDs are lit in the secondary color, all LEDs flash in a single short burst in primary color \u22ee \ud83c\udfa8 Fx, Bg Speed 24 Strobe Rainbow Same as strobe, cycles through the rainbow \u22ee \ud83c\udfa8 Bg Speed 25 Strobe Mega All LEDs are lit in the secondary color, all LEDs flash in several short bursts in primary color \u22ee \ud83c\udfa8 Fx, Bg Speed, Intensity 26 Blink Rainbow Same as blink, cycles through the rainbow \u22ee \ud83c\udfa8 Fx, Bg Frequency, Blink duration 27 Android Section of varying length running \u22ee \ud83c\udfa8 Fx, Bg Speed, Width 28 Chase 2 LEDs in primary color running on secondary \u22ee \ud83c\udfa8 Fx, Bg, Cs Speed, Width 29 Chase Random Like Chase but leaves trail of random color \u22ee \ud83c\udfa8 Fx, Cs Speed, Width 30 Chase Rainbow Like 28 but leaves trail of rainbow \u22ee \ud83c\udfa8 Fx, Bg Speed, Width 31 Chase Flash 2 LEDs flash in secondary color while the rest is lit in primary. The flashing LEDs wander from start to end \u22ee \ud83c\udfa8 Bg, Fx Speed 32 Chase Flash Rnd Like Chase Flash, but the 2 LEDs flash in random colors and leaves a random color behind \u22ee \ud83c\udfa8 Fx, Bg Speed 33 Rainbow Runner Like Chase, but the 2 LEDs light up in rainbow colors and leave a primary color trail \u22ee \ud83c\udfa8 Bg Speed, Size 34 Colorful Shifting Red-Amber-Green-Blue pattern \u22ee \ud83c\udfa8 1, 2, 3 Speed, Saturation 35 Traffic Light Emulates a traffic light \u22ee \ud83c\udfa8 Bg Speed, US style 36 Sweep Random Like Sweep, but uses random colors \u22ee \ud83c\udfa8 Speed 37 Chase 2 Pattern of n LEDs primary and n LEDs secondary moves along the strip \u22ee \ud83c\udfa8 Fx, Bg Speed, Width 38 Aurora Simulation of the Aurora Borealis \u22ee \ud83c\udfa8 1, 2, 3 Speed, Intensity 39 Stream Flush bands random hues along the string \u22ee \ud83c\udfa8 Speed, Zone size 40 Scanner Dot moves between ends, leaving behind a fading trail \u22ee \ud83c\udfa8 Fx, Bg Speed, Fade rate 41 Lighthouse Dot moves from start to end, leaving behind a fading trail \u22ee \ud83c\udfa8 Fx, Bg Speed, Fade rate 42 Fireworks Random color blobs light up, then fade again \u22ee \u25a6 \ud83c\udfa8 Fx, Bg Frequency 43 Rain Like Fireworks, but the blobs move \u22ee \u25a6 \ud83c\udfa8 Fx, Bg Speed, Spawning rate 44 Tetrix Falling blocks stack \u22ee \ud83c\udfa8 Fx, Bg Speed, Width, One color 45 Fire Flicker LEDs randomly flickering \u22ee \ud83c\udfa8 Fx Speed, Intensity 46 Gradient Moves a saturation gradient of the primary color along the strip \u22ee \ud83c\udfa8 Fx, Bg Speed, Spread 47 Loading Moves a sawtooth pattern along the strip \u22ee \ud83c\udfa8 Fx, Bg Speed, Fade 49 Fairy Inspired by twinkle style Christmas lights. \u22ee \ud83c\udfa8 Fx, Bg Speed, # of flashers 50 Two Dots Two areas sweeping \u22ee \ud83c\udfa8 1, 2, Bg Speed, Dot size, Overlay 51 Fairytwinkle Like Colortwinkle, but starting from all lit \u22ee \ud83c\udfa8 Fx, Bg Speed, Intensity 52 Running Dual Sine waves in both directions \u22ee \ud83c\udfa8 L, Bg, R Speed, Wave width 54 Chase 3 Like Chase, but with 3 colors \u22ee \ud83c\udfa8 1, 2, 3 Speed, Size 55 Tri Wipe Like Wipe but turns LEDs off as \"third color\" \u22ee \ud83c\udfa8 1, 2, 3 Speed 56 Tri Fade Fades the whole strip from primary color to secondary color to off \u22ee \ud83c\udfa8 1, 2, 3 Speed 57 Lightning Short random white strobe similar to a lightning bolt \u22ee \ud83c\udfa8 Fx, Bg Speed, Intensity, Overlay 58 ICU Two \"eyes\" running on opposite sides of the strip \u22ee \ud83c\udfa8 Fx, Bg Speed, Intensity, Overlay 59 Multi Comet Like Scanner, but creates multiple trails \u22ee 60 Scanner Dual Like Scanner, but with two dots running on opposite sides \u22ee \ud83c\udfa8 Fx, Bg, Cs Speed, Fade rate 61 Stream 2 Flush random hues along the string \u22ee Speed 62 Oscillate Areas of primary and secondary colors move between opposite ends, combining colors where they touch \u22ee 63 Pride 2015 Rainbow cycling with brightness variation \u22ee Speed 64 Juggle Eight colored dots running, leaving trails \u22ee \ud83c\udfa8 Speed, Trail 65 Palette Running color palette \u22ee \ud83c\udfa8 Cycle speed 66 Fire 2012 Simulates flickering fire in red and yellow \u22ee \ud83c\udfa8 Cooling, Spark rate, Boost 67 Colorwaves Like Pride 2015, but uses palettes \u22ee \ud83c\udfa8 Fx Speed, Hue 68 Bpm Pulses moving back and forth on palette \u22ee \ud83c\udfa8 Fx Speed 69 Fill Noise Noise pattern \u22ee \ud83c\udfa8 Fx Speed 70 Noise 1 Fast Noise shift pattern \u22ee \ud83c\udfa8 Fx Speed 71 Noise 2 Fast Noise shift pattern \u22ee \ud83c\udfa8 Fx Speed 72 Noise 3 Noise shift pattern \u22ee \ud83c\udfa8 Fx Speed 73 Noise 4 Noise sparkle pattern \u22ee \ud83c\udfa8 Fx Speed 74 Colortwinkles LEDs light up randomly in random colors and fade off again \u22ee \ud83c\udfa8 Fade speed, Spawn speed 75 Lake Calm palette waving \u22ee \ud83c\udfa8 Fx Speed 76 Meteor The primary color creates a trail of randomly decaying color \u22ee \ud83c\udfa8 Fx Speed, Trail length 77 Meteor Smooth Smoothly animated meteor \u22ee \ud83c\udfa8 Fx Speed, Trail length 78 Railway Shows primary and secondary color on alternating LEDs. All LEDs fade to their opposite color and back again \u22ee \ud83c\udfa8 1, 2 Speed, Smoothness 79 Ripple Effect resembling random water ripples \u22ee \u25a6 \ud83c\udfa8 Bg Speed, Wave #, Overlay 80 Twinklefox FastLED gentle twinkling with slow fade in/out \u22ee \ud83c\udfa8 Speed, Twinkle rate 81 Twinklecat Twinkling with fast in / slow out \u22ee \ud83c\udfa8 Speed, Twinkle rate 82 Halloween Eyes One Pair of blinking eyes at random intervals along strip \u22ee \u25a6 \ud83c\udfa8 Fx, Bg Duration, Eye fade time, Overlay 83 Solid Pattern Speed sets number of LEDs on, intensity sets off \u22ee \ud83c\udfa8 Fg, Bg Fg size, Bg size 84 Solid Pattern Tri Solid Pattern with three colors \u22ee 1, 2, 3 Size 85 Spots Solid lights with even distance \u22ee \ud83c\udfa8 Fx, Bg Width, Overlay 86 Spots Fade Spots, getting bigger and smaller \u22ee \ud83c\udfa8 Fx, Bg Spread, Width, Overlay 87 Glitter Rainbow with white sparkles \u22ee \ud83c\udfa8 1, 2, Glitter color Speed, Intensity, Overlay 88 Candle Flicker resembling a candle flame \u22ee \ud83c\udfa8 Fx, Bg Speed, Intensity 89 Fireworks Starburst Exploding multicolor fireworks \u22ee \ud83c\udfa8 Bg Chance, Fragments, Overlay 90 Fireworks 1D one dimension fireworks with flare \u22ee \u25a6 \ud83c\udfa8 Fx, Bg Gravity, Firing side 91 Bouncing Balls Bouncing ball effect \u22ee \ud83c\udfa8 Fx, Bg, Cs Gravity, # of balls, Overlay 92 Sinelon Fastled sinusoidal moving eye \u22ee \ud83c\udfa8 Fx, Bg, Cs Speed, Trail 93 Sinelon Dual Sinelon from both directions \u22ee \ud83c\udfa8 Fx, Bg, Cs Speed, Trail 94 Sinelon Rainbow Sinelon in rainbow colours \u22ee \ud83c\udfa8 Cs Speed, Trail 95 Popcorn popping kernels \u22ee \ud83c\udfa8 Fx, Bg, Cs Speed, Intensity, Overlay 96 Drip Water dripping effect \u22ee \ud83c\udfa8 Fx, Bg Gravity, # of drips, Overlay 97 Plasma Plasma lamp \u22ee \ud83c\udfa8 Fx Phase, Intensity 98 Percent Lights up a percentage of segment \u22ee \ud83c\udfa8 Fx, Bg % of fill, One color 99 Ripple Rainbow Like ripple, but with a dimly lit changing background \u22ee \u25a6 \ud83c\udfa8 Speed, Wave # 100 Heartbeat led strip pulsing rhythm similar to a heart beat \u22ee \ud83c\udfa8 Fx, Bg Speed, Intensity 101 Pacifica Gentle ocean waves \u22ee \ud83c\udfa8 Speed, Angle 102 Candle Multi Like candle effect, but each LED has it's own flicker pattern \u22ee \ud83c\udfa8 Fx, Bg Speed, Intensity 103 Solid Glitter Like Glitter, but with solid color background \u22ee Bg, Glitter color Intensity 104 Sunrise Simulates a gradual sunrise or sunset. Speed sets: 0 - static sun, 1 - 60: sunrise time in minutes,60 - 120: sunset time in minutes - 60, above: \"breathing\" rise and set \u22ee \ud83c\udfa8 Time [min], Width 105 Phased Sine waves (in sourcecode) \u22ee \ud83c\udfa8 Fx, Bg Speed, Intensity 106 Twinkleup Twinkle effect with fade-in \u22ee \ud83c\udfa8 Fx, Bg Speed, Intensity 107 Noise Pal Peaceful noise that's slow and with gradually changing palettes \u22ee \ud83c\udfa8 Speed, Scale 108 Sine Controllable sine waves \u22ee 109 Phased Noise Noisy sine waves \u22ee \ud83c\udfa8 Fx, Bg Speed, Intensity 110 Flow Blend of palette and spot effects \u22ee \ud83c\udfa8 Speed, Zones 111 Chunchun Birds flying in a circle formation \u22ee \ud83c\udfa8 Fx, Bg Speed, Gap size 112 Dancing Shadows Moving spotlights \u22ee \ud83c\udfa8 Fx Speed, # of shadows 113 Washing Machine Spins, slows, reverses directions \u22ee \ud83c\udfa8 Speed, Intensity 115 Blends Blends random colors across palette \u22ee \ud83c\udfa8 Shift speed, Blend speed 116 TV Simulator TV light spill simulation \u22ee Speed, Intensity 117 Dynamic Smooth Like Dynamic, but with smooth palette blends \u22ee \ud83c\udfa8 Speed, Intensity 118 Spaceships Circling ships with fading trails. Homage to 80s spaceship shooter games. \u25a6 \ud83c\udfa8 Speed, Blur 119 Crazy Bees Bees darting from flower to flower. \u25a6 Speed, Blur 120 Ghost Rider Color changing ghost riding a kite... in a tornado. \u25a6 \ud83c\udfa8 Fade rate, Blur 121 Blobs No really, they are blobs. \u25a6 \ud83c\udfa8 Fx Speed, # blobs, Blur 122 Scrolling Text Edit segment name to set text (#DATE and #TIME to include those) \u25a6 \ud83c\udfa8 Fx, Bg, Gradient Speed, Y Offset, Trail, Font size, Gradient, Overlay 123 Drift Rose Spinning arms that adds and removes nodes as it winds and unwinds. \u25a6 Fade, Blur 124 Distortion Waves Distorted sine waves with a psychedelic flair. \u25a6 Speed, Scale 125 Soap Like soap bubbles, but lasts longer. \u25a6 \ud83c\udfa8 Speed, Smoothness 126 Octopus A cephalopod stuck in a whirlpool. \u25a6 \ud83c\udfa8 Speed, Offset X, Offset Y, Legs 127 Waving Cell If a bunch of eucaryotes went to a sports stadium and did the wave, it would look exactly like this. \u25a6 \ud83c\udfa8 Speed, Amplitude 1, Amplitude 2, Amplitude 3 128 Pixels Random pixels \u22ee \u266a \ud83c\udfa8 Fx, Bg Fade rate, # of pixels 129 Pixelwave Pixels emanating from center \u22ee \u266a \ud83c\udfa8 Fx, Bg Speed, Sensitivity 130 Juggles Juggling balls. \u22ee \u266a \ud83c\udfa8 Fx, Bg Speed, # of balls 131 Matripix Similar to Matrix. \u22ee \u266a \ud83c\udfa8 Fx, Bg Speed, Brightness 132 Gravimeter Volume reactive vu-meter with gravity and perlin noise. \u22ee \u266a \ud83c\udfa8 Fx, Bg Rate of fall, Sensitivity 133 Plasmoid Sine wave based plasma. \u22ee \u266a \ud83c\udfa8 Fx, Bg Phase, # of pixels 134 Puddles Blast coloured puddles based on volume. \u22ee \u266a \ud83c\udfa8 Fx, Bg Fade rate, Puddle size 135 Midnoise Perlin noise emanating from center. \u22ee \u266a \ud83c\udfa8 Fx, Bg Fade rate, Max. length 136 Noisemeter Volume reactive vu-meter. \u22ee \u266a \ud83c\udfa8 Fx, Bg Fade rate, Width 137 Freqwave Maps the major frequencies from the incoming signal to colors in the HSV color space. \u22ee \u266b Time delay, Sound effect, Low bin, High bin, Pre-amp 138 Freqmatrix The temporal tail for this animation starts at the beginning of the Segment rather than in the center of the segment. \u22ee \u266b Time delay, Sound effect, Low bin, High bin, Sensivity 139 GEQ A 16x16 graphic equalizer. \u25a6 \u266b \ud83c\udfa8 Fx, Peaks Fade speed, Ripple decay, # of bands, Color bars 140 Waterfall A volume AND FFT version of a Waterfall that has 'beat' support. \u22ee \u266b \ud83c\udfa8 Fx, Bg Speed, Adjust color, Select bin, Volume (min) 141 Freqpixels Random pixels coloured by frequency. \u22ee \u266b Fade rate, Starting color and # of pixels 143 Noisefire A perlin noise based volume reactive fire routine. \u22ee \u266a Speed, Intensity 144 Puddlepeak Blast coloured puddles randomly up and down the strand with the 'beat'. \u22ee \u266a \ud83c\udfa8 Fx, Bg Fade rate, Puddle size, Select bin, Volume (min) 145 Noisemove Using perlin noise as movement for different frequency bins. \u22ee \u266b \ud83c\udfa8 Fx, Bg Speed of perlin movement, Fade rate 146 Noise2D \u25a6 \ud83c\udfa8 Speed, Scale 147 Perlin Move Using Perlin Noise for movement. \u22ee \ud83c\udfa8 Fx, Bg Speed, # of pixels, Fade rate 148 Ripple Peak Peak detection triggers ripples. \u22ee \u266a \ud83c\udfa8 Fx, Bg Fade rate, Max # of ripples, Select bin, Volume (min) 149 Firenoise Using Perlin Noise for fire. \u25a6 \ud83c\udfa8 X scale, Y scale 150 Squared Swirl Boxes moving around \u25a6 \ud83c\udfa8 Blur 152 DNA A very cool DNA like pattern. \u25a6 \ud83c\udfa8 Scroll speed, Blur 153 Matrix The Matrix, on a 2D matrix. \u25a6 Spawn, Trail Speed, Spawning rate, Trail, Custom color 154 Metaballs A cool plasma type effect. \u25a6 \ud83c\udfa8 Speed 155 Freqmap Map the loudest frequency throughout the length of the LED's. \u22ee \u266b \ud83c\udfa8 Fx, Bg Fade rate, Starting color 156 Gravcenter Volume reactive vu-meter from center with gravity and perlin noise. \u22ee \u266a \ud83c\udfa8 Fx, Bg Rate of fall, Sensitivity 157 Gravcentric Volume reactive vu-meter from center with gravity. Volume provides index to (time rotating) palette colour. \u22ee \u266a \ud83c\udfa8 Fx, Bg Rate of fall, Sensitivity 158 Gravfreq VU Meter from center. Log of frequency is index to center colour. \u22ee \u266b \ud83c\udfa8 Fx, Bg Rate of fall, Sensivity 159 DJ Light An effect emanating from the center to the edges. \u22ee \u266b Speed 160 Funky Plank A 2D wall of reactivity running from bottom to top \u25a6 \u266b Scroll speed, # of bands 162 Pulser Travelling waves. \u25a6 \ud83c\udfa8 Speed, Blur 163 Blurz Flash an fftResult bin per frame and then blur/fade. \u22ee \u266b \ud83c\udfa8 Fx, Color mix Fade rate, Blur 164 Drift A rotating kaleidoscope. \u25a6 \ud83c\udfa8 Rotation speed, Blur amount 165 Waverly Noise waves with some sound. \u25a6 \u266a \ud83c\udfa8 Amplification, Sensitivity 166 Sun Radiation The sun! Doesn't support segments. \u25a6 Variance, Brightness 167 Colored Bursts Rotating rays of color. \u25a6 \ud83c\udfa8 Speed, # of lines, Blur, Gradient, Dots 168 Julia Animated Julia set fractal named after mathematician Gaston Julia. \u25a6 \ud83c\udfa8 Fx Max iterations per pixel, X center, Y center, Area size 172 Game Of Life Scrolling game of life. \u25a6 \ud83c\udfa8 Fx, Bg Speed 173 Tartan Plaid pattern of horizontal and vertical bands. Makes a great kilt. \u25a6 \ud83c\udfa8 X scale, Y scale 174 Polar Lights The northern lights. \u25a6 Speed, Scale 175 Swirl Several blurred circles. Looks good with pink plasma palette. Supports AGC. \u25a6 \u266a \ud83c\udfa8 Bg Swirl Speed, Sensitivity, Blur 176 Lissajous A frequency based Lissajous pattern. \u25a6 \ud83c\udfa8 Fx X frequency, Fade rate 177 Frizzles Moving patterns. \u25a6 \ud83c\udfa8 X frequency, Y frequency, Blur 178 Plasma Ball A ball of plasma. \u25a6 \ud83c\udfa8 Speed, Fade, Blur 179 Flow Stripe Strip with rotating colours. \u22ee Hue speed, Effect speed 180 Hiphotic A moving plasma. \u25a6 \ud83c\udfa8 Fx X scale, Y scale, Speed 181 Sindots Dots revolving in a circle while the 'camera' \u25a6 \ud83c\udfa8 Speed, Dot distance, Fade rate, Blur 182 DNA Spiral Spiraling DNA pattern \u25a6 \ud83c\udfa8 Scroll speed, Y frequency 183 Black Hole Colorful dots orbiting a white black hole. \u25a6 Fade rate, Outer Y freq., Outer X freq., Inner X freq., Inner Y freq. 184 Wavesins Beat waves and phase shifting. Looks OK in 2D'ish as well. \u22ee \ud83c\udfa8 Fx Speed, Brightness variation, Starting color, Range of colors, Color variation 185 Rocktaves Colours the same for each note between octaves, with sine wave going back and forth. \u22ee \u266b \ud83c\udfa8 Fx, Bg 186 Akemi The WLED mascot rocking to your tunes. \u25a6 \u266b Head palette, Arms & Legs, Eyes & Mouth Color speed, Dance"},{"location":"features/effects/#retired-effects","title":"Retired Effects","text":"Some effects get retired when they can be recreated with newer, more general effects.
Removed Effect Replacement Retired After Candy Cane Chase 2 0.14.0 Dissolve Rnd Dissolve 0.14.0 Dynamic Smooth Dynamic 0.14.0 Halloween Chase 2 0.14.0 Merry Christmas Chase 2 - red/green 0.12.0 Police Two Dot 0.14.0 Police All Two Dots - red/blue w/ full intensity 0.13.0 Two Areas Two Dots - full intensity 0.13.0"},{"location":"features/macros/","title":"Macros","text":"Info
Also see Presets for 0.11.0+.
You are able to set custom actions (\"Macros\") in Time & Macro settings for the following events:
- Specific time of day
- Button short/long/double press
- HTTP API call executing a macro with
&M= - Alexa On/Off
- Countdown over
- Timed light duration over
- Device (re)boot (up to 0.10.2, use LED settings
Boot preset in 0.11)
Each macro has the format of a standard HTTP API call without the IP. Optionally, the \"win&\" may be omitted. For example, the macro \"A=255\" sets the brightness to maximum. \"R=255&G=160&B=0\" sets the color to orange. You can specify up to 16 macros. (up to 250 in WLED 0.11 since the Macro functionality has been merged into the Presets feature)
Examples of how to use API-calls and define macros can be found in this issue and in this one.
The simplest macro example is getting a button to do your bidding. The default pin to which a button can be connected is GPIO 0 (D3 on NodeMCU, D1 Mini and others). Even though WLED uses the internal pull up resistors on input pins, this pin is ideally externally pulled high to 3.3V with a 10k resistor. The configured macro executes when the pin is pulled low (grounded). The desired macro is entered on the Time/Macros configuration page and then assigned to a short, long or double press. Like this:
The \"T=2\" macro toggles power to the LEDs (in this case long press). The \"FX=~\" macro steps through the effects (in this case short press).
You can set a preset to P1=1&P2=3&PL=~, enter the preset number for your button, and this will step through presets 1 and 3. Change the \"3\" to whatever your highest preset is that you want to include.
The default (built-in) actions for button 0 are short-press: toggle on/off and long-press: select random color. Long-pressing for more than 6 seconds will open the WLED-AP with the default password (wled1234). For further buttons, the default action for short press is cycling effects, long press ramp brightness, and double press cycle palettes.
"},{"location":"features/macros/#buttons","title":"Buttons","text":"Multiple buttons are implemented since 0.13 and allow a few different types of buttons to be connected to the ESP:
- momentary push-buttons that are normally open and short GPIO pin to ground (active low)
- momentary push-buttons that are normally closed and release the connection from GPIO pin to GND (inverted, active high)
- switches (be careful with selection of GPIO for switch since some GPIOs will prevent successful boot of ESP if held LOW or HIGH at boot)
- PIR switch AKA motion detection sensor (they set GPIO HIGH when motion is detected, this type of buttons will also trigger MQTT message with /motion topic if \"Publish on button press\" is set on MQTT config)
- some GPIO pins on ESP32 can act as momentary touch buttons with no additional hardware
- analog \"buttons\" (also with inverted logic) those can be used as potentiometers or analog input buttons
Button GPIO pin and type can be selected in the LED Settings page.
Each momentary button can have 3 different Presets assigned, for short press, long press or double press. Momentary push-buttons by default trigger shortly after the release of a button, to be able to detect if it has been pressed short, long or twice. When configuring the same preset number for short, long and double press, it will trigger directly when being pressed as of WLED 0.14.0-b2-2306020.
For switch type buttons you can assign only 2 presets, one for transition of switch from LOW to HIGH and second for the opposite transition from HIGH to LOW.
Selecting 0 for preset will use the default action. If you find that the default action is inverted for switch, please create presets for On and Off actions and assign them appropriately.
For assigning Presets to buttons use Time & Macros settings page.
Note: Button 0 has two, built-in functions. 1. Hold it down for >6 seconds and the Wi-Fi settings will be reset to default. 2. Hold it down for >12 seconds and flash memory is erased.
"},{"location":"features/macros/#analog-button","title":"Analog button","text":"Starting in WLED 0.13, analog \"buttons\" (e.g. a potentiometer) are supported. With the Short and Long columns set to 0, set the Double column in Button Actions to one of these values to configure:
Property Value Global brightness 250 Effect speed 249 Effect intensity 248 Palette 247 Primary color hue 200 Segment N opacity 0-32 This potentiometer should be supplied 3.3V and GND, with it's output supplied to A0 (or any other ADC pin you specify), recommended 10K\u03a9 or greater.
Do not use ESP32 ADC2 GPIO pins for analog buttons
On ESP8266, you can only have a single analog button on pin A0, the pin set in the settings UI is ignored. On ESP32, only ADC1 pins will work for analog input while WiFi is active (pins 32-39). ADC2 pins will not work.
"},{"location":"features/macros/#global-brightness","title":"Global brightness","text":"Users planning to use a potentiometer for global brightness should be aware that wled is configured to turn off when the potentiometer is adjusted to either extreme - both maximum and minimum adjustments. Users who desire to disable this functionality may do so on the hardware side by adding resistors between the potentiometer and the rails.
Adding a resistor between the potentiometer and 3.3V prevents A0 from fully reaching 3.3V and allows the potentiometer to be adjusted to the maximum adjustment without powering off wled. A value of 7.5%-10% of the potentiometer value should be sufficient for this (~750\u03a9 for a 10K\u03a9 potentiometer). Similarly, added resistance between the potentiometer and GND prevents A0 from reaching 0V, and allows the potentiometer to be adjusted to the minimum adjustment without powering off wled. A value of 3-5% of the potentiometer value should be sufficient (~500\u03a9 for a 10K\u03a9 potentiomenter).
In both instances, the added resistances will slightly reduce the overall adjustment range, with a larger reduction for larger resistor choices. As such, A user who desires the maximum possible adjustment range should determine their needed resistance values experimentally by installing the potentiometer, adjusting for stable behavior at the desired extrema, measuring the voltage on A0, using the voltage divider equation to determine the optimal resistance, then retesting for confirmation.
"},{"location":"features/multi-strip/","title":"Multi-strip Support","text":""},{"location":"features/multi-strip/#multi-strip-support","title":"Multi strip support","text":"Starting in WLED 0.12.0, you are able to use multiple LED outputs from one ESP board! Pins and LED numbers can be easily configured in LED settings, you don't need to re-compile code for your specific setup. Custom binaries for multiple pins are now also a thing of the past!
There are a few tips and recomendations to keep in mind when designing your setup:
"},{"location":"features/multi-strip/#general","title":"General","text":" - It is highly recommended to use an ESP32 when using more than 1 output
- You may freely choose the LEDs type, pin numbers, length and color order of your LED strips at runtime in the LED settings page
- Highly recommeded to size power supply correctly according to your setup and disable the WLED brightness limiter setting to increase framerate with very large LED counts
- Most strip types have yet to be tested. Add confirmed working below:
- Confirmed working: WS281x, SK6812 RGBW, PWM white
"},{"location":"features/multi-strip/#esp8266","title":"ESP8266","text":" - There is a maximum of 3 strips supported.
- It is highly recommended to use two specific LED pins, GPIO1 (TX) and GPIO2 (D4), since they allow for hardware driving.
- It is recommended to use 512 LEDs/pin for good performance for a total of 1024 LEDs.
- 800 LEDs/pin for a total of 1600 has been confirmed working, but is not recommended for good performance and reliability.
- Using GPIO1 will disable serial debugging. If you need it, you can't use a strip on this pin.
- GPIO3 (RX) is the third pin that allows hardware driving on ESP8266. However, it uses 5 times as much memory per LED as GPIO 1 and 2, so use it only for low LED counts (recommended <50)
- You can use any other pin, but it will use the bitbang method, which is not recommended for reliability. It is best to stick to GPIO 1, 2, and if need be, 3.
- Using pin GPIO16 for WS2812b LEDs did not work in my testing.
- ESP8266 can calculate about 15k LEDs per second (that means 250LEDs @~60fps, 500 LEDs @~30fps, 1000 LEDs @~15fps)
- The LED settings will give you a bar that shows how much memory you can allocate.
"},{"location":"features/multi-strip/#esp32","title":"ESP32","text":" - There is a maximum of 10 strips supported
- Contrary to the ESP8266, the pin usage does not matter on ESP32, feel free to use any available pin
- For perfect performance, it is recommeded to use 512 LEDs/pin with 4 outputs for a total of 2048 LEDs.
- For very good performance, it is recommended to use 800 LEDs/pin with 4 outputs for a total of 3200 LEDs.
- For good performance, you can use 1000 LEDs/pin with 4 outputs for a total of 4000 LEDs.
- For okay performance, you can use 1000 LEDs/pin with 5 outputs for a total of 5000 LEDs.
- For okay performance, you can use 800 LEDs/pin with 6 outputs for a total of 4800 LEDs.
- ESP32 can calculate about 65k-85k LEDs per second (that means 1000 LEDs @~70fps, 2000 LEDs @~35fps, 4000 LEDs @~18fps)
- 4 outputs seem to be the sweet spot.
"},{"location":"features/multi-strip/#virtual-leds-ddp","title":"Virtual LEDs (DDP)","text":"See Virtual Leds
"},{"location":"features/palettes/","title":"Palettes","text":"Version Info
Beginning in 0.14 up to 10 Custom Palletes can be uploaded.
PaletteID Name Description 0 Default The palette is automatically selected depending on the effect. For most effects, this is the primary color 1 Random Cycle The palette changes to a random one every few seconds. Subject to change 2 Color 1 A palette consisting only of the primary color 3 Colors 1 & 2 Consists of the primary and secondary color 4 Color Gradient A palette which is a mixture of all segment colors 5 Colors Only Contains primary, secondary and tertiary colors 6 Party Rainbow without green hues 7 Cloud Gray-blueish colors 8 Lava Dark red, yellow and bright white 9 Ocean Blue, teal and white colors 10 Forest Yellow and green hues 11 Rainbow Every hue 12 Rainbow bands Rainbow colors with black spots in-between 13 Sunset Dark blue with purple, red and yellow hues 14 Rivendell Desaturated greens 15 Breeze Teal colors with varying brightness 16 Red & Blue Red running on blue 17 Yellowout Yellow, fading out 18 Analoguous Red running on blue 19 Splash Vibrant pink and magenta 20 Pastel Different hues with very little saturation 21 Sunset 2 Yellow and white running on dim blue 22 Beech Different shades of light blue 23 Vintage Warm white running on very dim red 24 Departure Greens and white fading out 25 Landscape Blue, white and green gradient 26 Beach Teal and yellow gradient fading out 27 Sherbet Bright white, pink and mint colors 28 Hult White, magenta and teal 29 Hult 64 Teal and yellow hues 30 Drywet Blue and yellow gradient 31 Jul Pastel green and red 32 Grintage Yellow fading out 33 Rewhi Bright orange on desaturated purple 34 Tertiary Red, green and blue gradient 35 Fire White, yellow and fading red gradient 36 Icefire Same as Fire, but with blue colors 37 Cyane Desaturated pastel colors 38 Light Pink Desaturated purple hues 39 Autumn Three white fields surrounded by yellow and dim red 40 Magenta White with magenta and blue 41 Magred Magenta and red hues 42 Yelmag Magenta and red hues with a yellow 43 Yelblu Blue with a little yellow 44 Orange & Teal An Orange - Gray - Teal gradient 45 Tiamat A bright meteor with blue, teal and magenta hues 46 April Night Dark blue background with colorful snowflakes 47 Orangery Orange and yellow tones 48 C9 Christmas lights palette. Red - amber - green - blue 49 Sakura Pink and rose tones 50 Aurora Greens on dark blue 51 Atlantica Greens & Blues of the ocean 52 C9 2 C9 plus yellow 53 C9 New C9, but brighter and with a less purple blue 54 Temperature Temperature mapping 55 Aurora 2 Aurora with some pinks & blue 56 Retro Clown Yellow to purple gradient 57 Candy Vivid yellows, magenta, salmon and blues 58 Toxy Reaf Vivid aqua to purple gradient 59 Fairy Reaf Bright aqua to purple gradient 60 Semi Blue Dark blues with a bright blue burst 61 Pink Candy White, pinks and purple 62 Red Reaf Blue, aqua and red gradient 63 Aqua Flash Aqua gradient with a flash of yellow and white 64 Yelblu Hot Yellow, red, blue spectrum 65 Lite Light Faint white and purple 66 Red Flash Red gradient with burst of white in the center 67 Blink Red Dark blue to dark red gradient with burst of purple 68 Red Shift Vibrant yellow to blue gradient with magenta, purple and red 69 Red Tide Waves of yellow, orange and red 70 Candy2 Faded gradient of yellow, salmon and blue"},{"location":"features/palettes/#custom-palettes","title":"Custom Palettes","text":"As of 0.14, up to 10 custom palettes can be uploaded by the user in JSON files named palette0.json through palette9.json The format closely resembles that of the palettes defined in palettes.h with a position (0-255), red, green, blue for each color. An example of the content would be:
{\"palette\":[ \n 0, 255, 33, 4, \n 43, 255, 68, 25,\n 86, 255, 7, 25,\n 127, 255, 82, 103,\n 170, 255, 255, 242,\n 209, 42, 255, 22,\n 255, 87, 255, 65]}\n
Once a palette[0-9].json file has been created, it can be uploaded to the controller using the /edit page (http://[controller-ip]/edit). The controller must be rebooted (/win&RB) before the newly uploaded palettes will be available. After reboot, the custom palette(s) will be named ~ Custom [0-9] ~ in the Palettes section of the user interface.
"},{"location":"features/pixel-art-converter/","title":"Pixel Art Converter","text":"The Pixel Art Converter tool aims to make it easier to show pixel art on a LED matrix panel, by converting any image to 2D pixel art and sending it to the WLED device. The file types PNG, JPG, WEBP and GIF have been tested to work with the tool.
"},{"location":"features/pixel-art-converter/#installation-approaches","title":"Installation Approaches","text":"There are three ways to install the pixel art converter:
- Local web browser. Will a web page run on the local machine connecting to the WLED device but will require fetching an extra file. Supported from WLED release v0.14.0-b1 or later
- Include the pixel art converter in the binary and compile it from the source code. Allows access to the pixel art converter on any device that has a connection to the WLED device. Supported from WLED release v0.14.0-b2 (PR #3042)
- WLED editor mode. Upload the web page to your WLED device while it is running
"},{"location":"features/pixel-art-converter/#approach-1-local-browser","title":"Approach 1: Local Browser","text":" - Download the
pixartmin.htm from the WLED-PixelArtConverter repository - Open
pixartmin.htm in a browser - Head over to the Setup 2D Matrix point
"},{"location":"features/pixel-art-converter/#approach-2-include-pixart-converter-in-build-files","title":"Approach 2: Include Pixart Converter In Build Files","text":"Compilation required
Compiling WLED from the source code is required. Follow the instructions on compiling WLED to do this.
- Follow the instructions under Making a custom environment and set the flag
-D WLED_ENABLE_PIXART under the line that starts with build_flags = in platformio_override.ini - Compile and flash the binary to the ESP board
- Power on board and connect via WiFi using the default login
- It is now time to Setup the 2D Matrix
"},{"location":"features/pixel-art-converter/#approach-3-wled-editor-mode","title":"Approach 3: WLED Editor Mode","text":"Network connection
A network connection is required to connect to the CDN, hosting the JS library Ace, an embedded code editor.
- Download the
pixartmin.html file from the WLED-PixelArtConverter repository - Go to the URL
http://[device_ip_address]/edit - Upload the
pixartmin.html file using the UI - Go to
http://[device_ip_address]/pixartmin.html - Now head to the Setup 2D Matrix point
"},{"location":"features/pixel-art-converter/#setup-2d-matrix","title":"Setup 2D Matrix","text":"2D LED panels are natively supported by WLED but need some configuration for the software to show the 2D grid correctly.
- Head into the
2D Configuration settings menu in WLED - Set the option \"Strip or panel\" to
2D Matrix - Setup rest of the LED panel layout according to the specifics of your LED panel
Serpentine option
Setting the serpentine LED panel option incorrectly can lead to very confusing results that look almost correct but not quite. Enabling or Disabling the option depends on the characteristics of the 2D matrix
"},{"location":"features/pixel-art-converter/#usage","title":"Usage","text":"The Pixel Art Generator does not yet have a link in the WLED front-end, therefore head over to the web page: http://[device_ip_address]/pixart.htm (default DHCP IP-address link).
On the web page:
- Set the option \"LED setup\" to 2D matrix or serpentine accordingly.
-
Select an image that should be shown on the matrix display
This example uses a 16x16 pixel, happy version of the WLED mascot Akemi by Aircoookie.
-
A preview is displayed further down the web page.
Scaling option
It can help to use the Scale image option, depending on the image size used.
-
Click on \"Send to device\" to push the generated image to the WLED device.
"},{"location":"features/presets/","title":"Presets","text":"Presets can be used to save your favorite light configurations to apply later! You can compare them to the \"scenes\" feature present in some other smart devices.
"},{"location":"features/presets/#new-version-011","title":"New version (0.11+)","text":""},{"location":"features/presets/#overview","title":"Overview","text":"WLED 0.11.0 contains a major overhaul of presets, storing them in a /presets.json file in an internal filesystem. This enables many new features, you can now have up to 250 presets and each of them can save all segments which are set up! Speaking of segments, the maximum number has been increased to 12 on ESP8266 and 16 on ESP32! Presets can now also contain both HTTP and JSON API commands, replacing the previous Macro functionality. Each preset can be named, so you'll be able to access it more easily!
"},{"location":"features/presets/#how-to-use","title":"How to use","text":"The new preset system is quite a bit more advanced than the previous one, thus it is likely not as self-explanatory to use. Here you can find what each setting does and how to make best use of it!
\"Create Preset\" button Use this to save the current state as a permanent preset, or to add a new API macro.
Preset name Enter a nice name for your preset here. I would recommend putting something short, but to the point here, like Epic fireworks or Slow fade. All special characters and emoji are permitted (however, there must not be more than 6 consecutive whitespaces) If you leave this empty, you'll get a name based on the preset ID number, like Preset 16.
Quick load label You can optionally add a short label up to 2 characters or 1 emoji long. It will show up in a small circle on top of the preset list for extra quick access without scrolling! I recommend using this for the presets you truly love.
Use current state/Overwrite with state This is enabled by default when adding a new preset and disabled when editing an existing preset. When enabled, it will write the current segment config, including all colors and effect, to the preset. When disabled, it will instead give you a textfield to enter a custom API command or show you the command currently saved.
Include brightness If disabled, the brightness value is not included in the preset. This can be useful e.g. when you want to control the brightness manually and want the preset to only set the effect.
Save segment bounds This is an important one. Make sure it is enabled for your boot preset, so that your segment config is properly restored on boot! When disabled, the segment start and stop LEDs are not included in the preset. This can be useful if you plan to make changes to your segment setup and don't want your presets to always reset it to the point it was when the preset was saved.
API command This accepts any HTTP or JSON API command! (only visible if the current state checkbox is unchecked) It replaces the previous macro functionality. If you know your JSON, you can even create playlists of other presets!
Save to ID This is the ID the preset will be saved to. When creating a new preset, you likely won't have to change it as the lowest unused ID will be chosen automatically. If you change the ID on an existing preset and save, you can copy it to the new ID - change the name though.
Save and Delete buttons Now these are self-explanatory, but I said I'd cover each point :)
ID This is the number you'll want to use to apply this preset from a timed macro or automation!
"},{"location":"features/presets/#a-note-on-performance","title":"A note on performance","text":"This new preset system is quite fast where it matters, reading the presets. Applying a preset will typically take less than a tenth of a second.
However, due to a design choice of the LittleFS filesystem used by WLED, random writes to the preset file are very resource intensive. This means that while updating your presets, you might notice your light freezing and becoming unresponsive for up to a few seconds. Adding new presets is usually very fast, those performance issues will occur once you delete/edit/overwrite older presets and your preset file becomes very large, or when adding presets after deleting older ones.
I'm looking into ways to mitigate this situation as soon as possible! Meanwhile, to keep things snappy, I would recommend not having more than 50-ish single segment or a dozen of multi-segment presets.
"},{"location":"features/presets/#what-about-my-cool-presets-from-earlier-versions","title":"What about my cool presets from earlier versions?","text":"Don't worry, they (as well as your settings) will be automatically imported to the new system! And if you ever need to downgrade to v0.10 for some reason, they will still be there (although any changes made in v0.11 won't be applied)
"},{"location":"features/presets/#obtaining-preset-list","title":"Obtaining preset list","text":"Obtaining the preset list is possible with the /presets.json file Seeing the name of the current preset with the API only is not possible, you can only obtain its ID. Then you'd need some code to match it with the entries from presets.json (this is also what the UI does). See section \"Backing up/restoring presets\".
"},{"location":"features/presets/#saving-named-presets","title":"Saving named presets","text":"Save a named preset with {\"psave\":<preset number here>;\"n\":\"Preset name\",\"ib\":true,\"sb\":true}
"},{"location":"features/presets/#backing-uprestoring-presets","title":"Backing up/restoring presets","text":"To backup all presets, go to [WLED-IP]/edit (OTA lock must be off), right click the presets.json file and download! To restore, use the Choose file and Upload buttons.
"},{"location":"features/presets/#applying-presets-at-a-certain-time-of-day","title":"Applying presets at a certain time of day","text":"Tip
If you want to create a preset that turns on the light to the last effect displayed, uncheck Use current state and enter T=1 into the API Command field.
WLED supports schedules - that is, applying presets at a certain time automatically. Here is a simple guide to get it set up quickly!
- Creates the preset(s) you want to load at specific time(s)
- Note the preset ID - the small gray number to the left of the preset name (or, in the bottom of the preset menu)
- Go to the
Time & Macros section in the WLED settings. - Make sure the time displayed is correct and accurate. It is highly recommended to enable NTP for a reliable schedule. Do not forget to set the correct timezone. If applicable, daylight saving time is handled automatically.
- Scroll down to
Time-controlled presets. There are 8 different timer slots available. - Enter the hour, minute, and weekdays you want the preset to activate. In the
Preset column, enter the preset ID you noted earlier. - Save the settings page! You have successfully set up a schedule :)
Note
This only applies the preset at the start of the specified minute. If you set up two presets, one to turn on the light at 7 and another to turn it off at 8, if WLED is booted at 7:30, the light will not turn on. This should not be an issue in most applications.
"},{"location":"features/presets/#applying-presets-at-sunrise-and-sunset","title":"Applying presets at sunrise and sunset","text":"Applying a preset at sunrise and/or sunset is also supported, the last two timed preset slots are used for this. To calculate the times, WLED needs your location. This is possible with the \"Get Location\" button in Time & Macro settings if accessed via a browser. If you are using the WLED app, you will need to open locate.wled.me in your browser and copy the coordinates over to the settings page manually. With the Minutes input field, you may specify an offset of up to 59 minutes before or 59 minutes after the actual sunrise/set time.
Location
Sunrise and sunset calculation do not work if you live in the polar circles (latitude >66.6N or >66.6S).
"},{"location":"features/presets/#earlier-versions-up-to-010","title":"Earlier versions (up to 0.10)","text":"There are 16 preset slots in total. In 0.9.0, the last preset (16) is capable of saving the entire segment configuration. All other presets only save a single segment (main segment, the first one by default) and restore that preset to all selected segments.
In the Favorites tab, the number buttons from 1-16 are the different save slots. Find a config you like, then toggle Saving mode on and click on a number to save the preset to that slot. If Saving mode is toggled off, you can restore presets with a single click.
"},{"location":"features/presets/#preset-cycle-up-to-0121","title":"Preset cycle (up to 0.12.1)","text":"With this feature, you can create an animation by automatically swapping between presets within a specified range. Keep in mind that any changes you make to effects/colors will be overridden once the system applies the next preset.
If you want to start the preset cycle on boot, go to LED settings and tick \"Save current preset cycle configuration as boot default
To modify the duration of the preset cycle, ensure the preset cycle box is unchecked before entering a new time value. Once updated, the preset cycle can be enabled again\"
Playlists supersede Preset cycle in 0.13.
"},{"location":"features/relay-control/","title":"Control a Relay","text":"Digital LED strips still use power when seemingly switched off, about 1W per 200 LEDs. In case you want to prevent that, you can completely cut power to the LEDs by adding a relay to your circuit. It is toggled by WLED when WLED is turned on/off (in the UI, or through other interfaces). No pin is allocated for a relay by default, but can be easily set in the LED preferences page. Previously, GPIO12 (Pin D6 on many devices) was set as the default and is confirmed to work well on most boards except the ESP32-C3.
When you decide that you want WLED to control a relay, make sure you buy a suitable relay board. Check what voltage you can supply from your controller to relay (available 3.3V or 5V pin or different voltage from external power source), and make sure the relay can be controlled by voltage level your board is providing (3.3V CMOS, 5V TTL). Note, some relays come with a jumper that lets you configure whether the relay switches at high or low level of signal, giving you maximum flexibility.
This page gives a clear description using a light bulb instead of a LED strip. And instead of the D1 mentioned there, with WLED, you use the pin you set.
The default WLED behavior is to turn the relay pin on (high) when the LEDs are on and off (low) when the LEDs are off. This can be changed in the LED Preferences page. Many relays are powered when the signal is LOW. See this thread.
Sometimes people ask whether they can control more than one relay through WLED, including controlling this all via Alexa. Controlling an extra relay separately from the RGB lights is not something WLED is designed to do, however you can modify the code to add that functionality. For that, make sure you can compile WLED from source unmodified first. Then, change #define ESPALEXA_MAXDEVICES 1 in line 71 of the wled.h file to 2. After that, just follow the API documentation on https://github.com/Aircoookie/Espalexa to add a new EspalexaDevice to the alexa.cpp file
Second option for controlling multiple relays is using a Multi Relay usermod. As with Alexa you will need to compile WLED from source an include Multi Relay usermod either by including -D USERMOD_MULTI_RELAY in PlatformIO.ini or adding #define USERMOD_MULTI_RELAY in wled.h or my_config.h. You can also override default number of relays by defining MULTI_RELAY_MAX_RELAYS. Configuring usermod is done using Usermod settings page where you can define GPIO pins used, wether relay activates on HIGH or LOW logic, if the activation has any delay and if the relay can be controlled from the outside using MQTT message (external). MQTT topic for controlling relays is wled/[device]/relay/[relay_id]/command and accepts on, off and toggle messages. When the relay changes state a message with on or off is sent with the topic wled/[device]/relay/[relay_id].
How To: Use WLED to switch external relay with PIR sensor without affecting WLED state
If you do not want PIR (motion) sensor attached to WLED controller to trigger change of WLED state, but still want to control a legacy light, fan, etc. use the Multi Relay usermod and another relay attached to WLED controller. Create two presets for relay control (shown for switching relay off) and set up PIR and multi relay usermods as shown.
If you do not want button relay control just leave relay button at -1, the same goes for PIR sensor parameters (leave nighttime-only and/or off-only unchecked). Adjust preset numbers and GPIO pins to your liking. Multi relay usermod can also switch relay using MQTT messages or HTTP requests (check source code for available commands). Of course if you configured MQTT on your WLED device PIR sensor usermod will publish /motion topic to MQTT broker for your HA integration.
"},{"location":"features/segments/","title":"Segments","text":"Info
Starting in WLED 0.9.0, Segments are supported.
This feature allows you to set different zones on the LED strip, each running a different effect or color.
A segment is selected if the checkmark next to the segment number is checked. Changes you make to color or effects will apply to all selected segments. The color/effect that is shown in the web UI is that of the first selected segment.
There is one main segment, Segment 0 by default. This segment has a few important differences to the rest of the segments. - Color transitions only work on the main segment - The main segment's color is the one that will be reported to HTTP and MQTT APIs
Tip: If you divide your strip into two segments, reverse the second one and select both, you can achieve very nice symmetrical effects!
Segment 0 has a Start LED of 0 and a Stop LED equal to the LED Count you defined in Configuration, LED Preferences. The Stop LED is not included in the Segment. Currently you can create a maximum of 10 segments. Presets 1-15 use only Segment 0 by default. Preset 16 is the only Preset that saves settings for Segments 1-10.
To display segment information select the down arrow in the Segment box. To add a Segment select \u201c+ Add Segment\u201d. Enter the Start and Stop LED as appropriate. Grouping and Spacing control the organization of the LEDs within the selected effect. To reverse the direction of an effect select Reverse Direction. To delete a Segment select the trash can. To save your Segment settings select the checkmark to the right of the Start and Stop LED numbers.
"},{"location":"features/segments/#grouping-and-spacing","title":"Grouping and Spacing","text":"When an effect changes the color of one LED, it is really changing the color of one LED group. Since the default group size is one, the effect normally only changes a single LED. When Grouping is set to two, the effect will light two LEDs using the same color. The two LEDs are treated as a single virtual LED.
To illustrate this, we can create a segment with 12 LEDS (physically referred to as LED 0 to LED 11) and select an effect that repeats three colors. When Grouping is set to one we see a repeating pattern of one red LED, one blue LED, and one green LED. When Grouping is set to two the segment of 12 physical LEDs becomes a segment of 6 virtual LEDs (virtualLED 0 to virtualLED 5). The same effect will now set the color of each virtual LED (which consists of two physical LEDs). The pattern becomes two red LEDs followed by two blue LEDs then two green LEDs.
Setting LED Output Grouping 1 Spacing 0 Grouping 2 Spacing 0 As the pattern cycles, the group of LEDs will move together.
Setting LED Output Grouping 1 Spacing 0 Grouping 2 Spacing 0 Spacing controls the space or gap between LEDs. The default spacing is zero, so normally there is no space between LEDs. When Spacing is set to one, every other LED will be lit. The number of virtual LEDs in the strip will be half the number of physical LEDs.
Again, we can create a segment with 12 LEDS (physically referred to as LED 0 to LED 11) and select an effect that repeats three colors. When Spacing is set to zero we see a repeating pattern of one red LED, one blue LED, and one green LED. When Spacing is set to one the segment of 12 physical LEDs becomes a segment of 6 virtual LEDs (virtualLED 0 to virtualLED 5). The same effect will now set the color of each virtual LED (which consists of the even numbered physical LEDs). The pattern becomes one red LED followed by a blank LED, one blue LED followed by a blank LED, then one green LED followed by a blank LED.
Setting LED Output Grouping 1 Spacing 0 Grouping 1 Spacing 1 As the pattern cycles, only the virtual LEDs will be lit - the blank LEDs in between the virtual LEDs will always be off.
Setting LED Output Grouping 1 Spacing 0 Grouping 1 Spacing 1 Grouping and Spacing can be combined to create many different custom LED layouts. In the example below, the strip of 12 physical LEDs has been configured to function as four virtual LEDs with a small gap between them.
Setting LED Output Grouping 2 Spacing 1 Grouping 2 Spacing 1"},{"location":"features/segments/#interleaving","title":"Interleaving","text":"This is an easy way to get a repeating pattern of colors using one segment per color.
"},{"location":"features/segments/#offset-in-a-segment","title":"Offset in a segment","text":"By default effects start in the first LED in the segment and finish in the last one. If the offset parameter in a segment is used, the effect start will be moved by the number of positions entered. It will continue to the last LED and then finish with the initial positions that were skipped.
For instance, let's assume assume a strip of 12 LEDs with the positions numbered as follows (like the examples above):
An offset value of 5 will make the effect start in the physical position 5, continue to position 11 and then finish with positions 0 through 4, like this:
A negative offset value is allowed and represents an offset starting from the last position in the segment. In our previous example, an offset of -2 will start the effect in position 10, like this:
The offset values is prioritized over grouping and/or spacing. For example, if the offset is 2, grouping 4 and spacing 1, the first group of 4 LEDs will start at the physical position number 2.
"},{"location":"features/segments/#effect-overlay","title":"Effect Overlay","text":"Some effects can be overlaid on the background of another effect. To use overlay, set up segments with overlapping pixels. The overlay effect must be playing on the segment with the higher id. If the Overlay option is checked, the background will not be painted and the effect from the lower segment will be displayed.
"},{"location":"features/settings/","title":"Settings","text":"All web configurable settings are split in 5 sub-pages. This page is meant to clarify the purpose of each setting. This documentation applies to WLED 0.8.5.
"},{"location":"features/settings/#settings-overview","title":"Settings overview","text":""},{"location":"features/settings/#wifi-settings","title":"WiFi Settings","text":"This sub-page offers options to connect the ESP to different WiFi/WLAN devices.
Setting name Value Range Description Network Name String 0..32 The name (SSID) of your home WiFi. Spaces and some other characters are not supported. Network password String 0..64 The password of your home WiFi Static IP 4x 0..256 An optional static IPv4 address Static gateway 4x 0..255 In a static config, your gateway's IPv4 address Static subnet 4x 0..255 In a static config, this normally is 255.255.255.0 mDNS address String 0..32 Name of your device for the Bonjour/Zeroconf protocol Client IP - The current IP of the ESP in the home network AP SSID String 0..32 The name of the ESPs internal WiFi hotspot (Access Point) Hide AP name Y/N The ESPs Access Point won't appear in WiFi lists of other devices AP password String 0..64 The password of the ESPs WiFi Access Point AP WiFi channel 1..13 The 2.4G WiFi band of the AP. For advanced users AP opens select Condition on when to open the AP AP IP - The Access Point IPv4 address of the ESP (is 192.168.4.1 in most cases) WiFi sleep Y/N Disabling WiFi sleep can increase reliability, but increases power consumption"},{"location":"features/settings/#led-settings","title":"LED settings","text":"This sub-page configures the state of your lights.
Setting name Value Range Description LED count 1..1500 How many LEDs are in your WS2812B strip Automatic brightness limiter Y/N Limit brightness to stay in a given current range Maximum current 300..65000 Current limit im milliamps LED voltage select Voltage/type of LEDs Custom max. current 1..255 Custom current per LED on full white 4-channel LEDs (RGBW) Y/N Support for SK6812 LEDs with white channel Color order select If your LEDs display incorrect colors (red and green swapped), try changing it Auto-calculate white select Get white channel from RGB automatically (only applicable for RGBW) Details Turn on after power up Y/N Whether the lights should turn on after a reset Apply preset 0..16 Preset to load at boot (0 = none) Set current preset cycle... Y/N The current preset cycle configuration will be used as boot default Use Gamma for brightness Y/N Will correct brightness changes to make it appear more linear. Advised to leave off Use Gamma for color Y/N Will correct colors to match those on a monitor. Strongly advised to keep on Brightness factor 1..255 Factor to change master brightness if it is to dim/bright for a certain configuration Crossfade Y/N Whether to have a smooth fading transitional effect when changing colors/brightness Transition time 0..65535 How many milliseconds the transition lasts Enable transition for secondary color Y/N Enable Palette transitions Y/N Enable transitions for palettes (not affected by transition time) Timed light duration 1..255 How long the nightlight should stay on Target brightness 0..255 What brightness the light should have after time is over. 0=off. Fade down Y/N Gradually fades down the light over the duration instead of turning it off at the end Palette blending select Choose how the palette wraps at the end (seam) Reverse LED order Y/N Mirrors the LEDs (last LED is first) Skip first LED Y/N Will turn off the first LED and shift the remaining by 1 (1st LED used as a signal repeater)"},{"location":"features/settings/#user-interface-settings","title":"User Interface settings","text":"This sub-page changes the look of the web interface.
Setting name Value Range Description Server description String 1..32 The name of the device as shown on the top of the UI. Differs from Alexa device name Sync button toggles... Y/N If enabled, both send and receive are toggled by the button in UI. If disabled, only sending is toggled and receiving is kept as configured in Sync settings."},{"location":"features/settings/#sync-settings","title":"Sync settings","text":"This sub-page configures external software synchronization interfaces.
Setting name Value Range Description On/Off button enabled Y/N Check if there is a physical pushbutton connected to GPIO0 Infrared receiver type select Type of infrared receiver Broadcast UDP port 1..65535 All WLED lights you want to group together must have the same port Receive Brightness Y/N If there is a sync notification, whether its brightness should be applied Color Y/N Whether the color of the synced device should be applied Effects Y/N Whether the effect settings should be applied Send on direct change Y/N Whether to send a sync notification when state changed via web UI or API Send on button press Y/N Whether to send sync when toggled by button or IR Send Alexa notifications Y/N Whether to send sync after changed by Alexa (you may use Alexa groups instead) Send Hue notifications Y/N Whether to send sync after a connected Philips light changed Send Macro notifications Y/N Whether to send sync after a macro was triggered Send notifications twice Y/N Sends notifications twice (if you have issues with UDP packet loss) Receive UDP realtime Y/N Receive live UDP stream data (DRGB, WARLS, ...) Use E1.31 multicast Y/N Listen on multicast IP instead of unicast E1.31 start universe 1..63000 Only applies for multicast. If you want to set different content, set ESPs at least 8 universes apart Timeout 100..65000 Time after which to resume normal mode once stream has stopped. 65000 will keep the data indefinitely Force max brightness Y/N Realtime stream with max. brightness (unless limited by power brightness limiter) Disable realtime gamma correction Y/N Check if your host software does gamma correction already Realtime LED offset -255..255 Shift the realtime input by how many LEDs Emulate Alexa device Y/N Allows you to control the light via the Amazon Echo voice assistant. Requires reboot Alexa Invocation name String 1..32 The name you want the device to have for control via Alexa. Choose something easy she can understand Device Auth token String 40 You will get this in an e-mail during Blynk setup MQTT Broker IP or String 0..32 Connect to this host MQTT broker Device topic String 0..32 MQTT topic unique to this light Group topic String 0..32 MQTT topic for all lights in a group (room, floor, ...) Hue Bridge IP 4x 0..255 Your Hue bridge IPv4 address. Should be static to avoid reassigning Poll Hue light 0..99 The ID of the hue lamp you want to sync WLED to every x ms 100..65000 How often to poll. Smaller numbers decrease lag but might hurt bridge responsiveness ... Y/N Turn polling on/off Receive On/Off Y/N Turn on/off like the hue light Brightness Y/N Set brightness to that of the hue light Color Y/N Set color to that of the hue light Hue status - Shows the current connection status to a hue bridge Baud rate Various Set the default Serial connection Baud Rate"},{"location":"features/settings/#time-settings","title":"Time settings","text":"This sub-page configures automation tasks.
Setting name Value Range Description Get time from NTP Y/N Whether to get the current time from the internet Use 24h format Y/N Use 24h clock format instead of AM/PM Time zone - Your time zone. Open an issue if yours is unsupported. DST is applied automatically UTC offset -65000..65000 Seconds to offset. If you want e.g. 1h offset, use 3600 Current local time - The local time the ESP has acquired. If set up correctly, should equal actual time Clock overlay - The special overlay to use. Allows to display a clock on the strip Countdown mode Y/N Allows to have a visual countdown towards a specific date API macro fields 16x String 0..64 Allows you to define custom API calls which can be triggered by events Boot Macro 0..16 Which macro to trigger after WiFi connected (0 is default action) Alexa On/Off Macros 2x 0..16 Which macros to trigger when turning on/off via Alexa Button Macro 0..16 Macro to trigger if button is short pressed. Default action is on/off toggle. Long Press 0..16 Macro to trigger if button is long pressed (>0.7s). Default action is random color. Double press 0..16 Macro for double click on button. Countdown-Over Macro 0..16 Macro to trigger when the countdown is over Timed-Light-Over Macro 0..16 Macro to trigger when timed light is done"},{"location":"features/settings/#security-settings","title":"Security settings","text":"This sub-page manages permissions and updates.
Setting name Value Range Description Enable OTA lock Y/N If enabled, no firmware updates may be done via WiFi and some settings can't be changed. Passphrase String 0..32 To disable OTA lock, you need a password. The default is \"wledota\". Change it! Deny access to WiFi settings Y/N Disables changes to WiFi settings while locked Disable recovery AP Y/N If enabled, the module will not open an Access Point if connection to home WiFi failed. Factory reset Y/N Deletes all custom settings data (passwords, configuration, macros, presets) Manual OTA - If OTA is enabled, you can upload new binary firmware Enable ArduinoOTA Y/N Useful for developers. Be careful, can even be left on when OTA locked!"},{"location":"features/subpages/","title":"Web GUI Sitemap","text":"This is the sitemap of the module server. Access with \\<ESP-IP>/path (Example: 192.168.8.4/settings)
Path Description OTA rights required Since version / Default UI, index page No 0.2 /update Upload new firmware Yes 0.3 /win HTTP Request API (since 0.3) No 0.3 /json JSON API No 0.8.4 /json/state JSON state object No 0.8.4 /json/info JSON information No 0.8.4 /json/eff Effect name list No 0.8.4 /json/pal Palette name list No 0.8.4 /json/live Current colors of LEDs No 0.9.0 /liveview Live preview of current LEDs No 0.9.0 /settings Settings index page No 0.2 /settings/wifi WiFi Settings page Cnfg 0.5.0 /settings/led LED Settings page No 0.5.0 /settings/ui UI Settings page No 0.5.0 /settings/sync Sync Settings page No 0.5.0 /settings/time Time Settings page No 0.5.0 /settings/sec Security Settings page Yes 0.5.0 /welcome New User Welcome page No 0.5.0 /sliders UI, index page No 0.5.0 /reset Reboot module No 0.3 /version Returns build version No 0.3 /uptime Returns runtime in ms No 0.4 /freeheap Returns free memory No 0.4 /favicon.ico Page icon No 0.2 /teapot :) No 0.5.0 /edit Filesystem editor Yes 0.2 /u Custom usermod page 0.8.4 (?) /cpal.htm Custom palette editor 0.14.0-b3 /pixart.htm 2D Pixel Art converter (not compiled by default) 0.14.0-b3 /pxmagic.htm 2D Image converter 0.14.0-b4"},{"location":"features/subpages/#removed-sites","title":"Removed sites","text":"Path Description OTA rights required Versions /list Lists SPIFFS contents (if USEFS) Yes 0.2-0.8.3 /easter Joke page No 0.6.2 only /power Returns an estimate of used LED current No 0.5.0-0.8.3 /build Returns details about the build No 0.5.0-0.8.3 /cleareeprom Resets to factory defaults Yes 0.3-0.6.4 /down Kills software. Hard reset required. Yes 0.3-0.6.4 /url Returns current light setup API url No 0.9.1-0.14.0-b3"},{"location":"interfaces/blynk/","title":"Blynk","text":"Warning
The official Blynk v1 server is shut down as of January 2023. WLED v0.14.0-b1 binaries no longer have Blynk support enabled by default. This only works with the legacy Blynk app, for which new signups have been closed by the Blynk developer. WLED will either move to Blynk 2.0 or a different solution soon.
You can use the free (if you only use it for 1 WLED light) IoT cloud Blynk to control your WLED Lights with the beautiful Blynk app for Android and iOS!
With Blynk, you can also even control your lights when you are not connected to your home network!
"},{"location":"interfaces/blynk/#installation","title":"Installation","text":" - Download the Blynk (legacy) app from the Play Store or the App Store
- Scan this QR code with the app:
- Paste the device auth token Blynk sends to your e-mail into the WLED sync settings (only one ESP!)
You can use the sync button in Blynk to sync other WLED ESPs, just like with the web UIs!
If you have doubts about the security of using a 3rd party IoT cloud, don't worry. WLED will only attempt to connect to Blynk if you put the device token string into Sync settings! Keep in mind that your ESP needs to connect to an external server, which may cause lag.
"},{"location":"interfaces/dmx-output/","title":"DMX","text":""},{"location":"interfaces/dmx-output/#dmx-output","title":"DMX output","text":"Version Info
As of version 0.9.2 WLED supports DMX output via MAX485. This is great for controlling DMX LED PAR lamps with WLED patterns.
"},{"location":"interfaces/dmx-output/#features-and-limitations","title":"features and limitations","text":" - up to 15 DMX channels per fixture
- channels can be set to dimmer (brightness), red, green, blue, white, 0, 255
- supports channel spacing between fixtures
- outputs a DMX channel map
- one universe (512 channels)
- type of fixture
"},{"location":"interfaces/dmx-output/#software-setup","title":"software setup","text":"For the DMX feature to work, you'll need to compile WLED from source. It's not a big deal, you can do it! Here is the Quick Start guide. There you'll find the section \"i want to modify WLED\".
-
make sure, you can compile the latest version of WLED without any issues. Then continue.
-
Once that works, in wled00/wled.h you need to change the line //#define WLED_ENABLE_DMX to #define WLED_ENABLE_DMX Yes, you just remove the //, which enables the line and therefore DMX support.
-
Once you successfully uploaded the sketch to your board, you'll find a new entry \"DMX Output\" in your settings menu.
-
Grab the manual for your lamp and maybe some snacks, look up the dmx channels and set everything up accordingly.
"},{"location":"interfaces/dmx-output/#hardware-setup","title":"hardware setup","text":"The DMX output required the use of a MAX485 transceiver connected to the TX-pin of the ESP in order to produce DMX output.
I am currently working on an open source PCB design to go along with this feature.
For information about the use of DMX with ESP8266, you might like to read this tutorial by Robert Oostenveld. Note this is just background information about the hardware and you do not need any of the code listed here when using WLED output.
If you need to use another pin for output than the TX-pin, you'll need to change this in the ESP-Dmx library itself. This setting is located in src/dependencies/dmx/ESPDMX.cpp on line 31.
"},{"location":"interfaces/dmx-output/#questions","title":"questions","text":"If you have further questions about this feature, you can reach me via github (@jwingefeld), ICQ (30914656) or via WLED Discord (JvPeek).
"},{"location":"interfaces/e1.31-dmx/","title":"E1.31 (DMX) / Art-Net","text":""},{"location":"interfaces/e1.31-dmx/#e131","title":"E1.31","text":"WLED supports the E1.31 (sACN) realtime light protocol.
Version Info
As of WLED v0.10.0, Art-Net is alternatively supported. All information on this page applies for Art-Net as well. You will need to switch to Art-Net mode in Sync settings and reboot once.
Version Info
As of WLED v0.11.0, DDP is alternatively supported. Using DDP, the Multi RGB DMX mode is always used regardless of the DMX mode setting (as it is no DMX) You will need to switch to DDP mode in Sync settings and reboot once.
Version Info
As > WLED 0.14.0-b1, DMX Effect mode channel mapping changed. This is a breaking change in E131 sync behavior. Existing DMX setups using WLED Effect mode are likely to break. Solution: Adopt external DMX channel mappings according to the new Effect mode channel layout.
"},{"location":"interfaces/e1.31-dmx/#features","title":"Features","text":" - 170 LEDs (510 DMX channels) are supported per universe.
- You can use up to 9 adjacent universes which is a total of more than the maximum 1500 LEDs WLED can drive.
- E1.31 priority handling. HTP for multiple senders with same priority is not implemented!
Note: WLED > 0.14.0-b1 implements a basic priority handling. To enable it set E1.31 port priority UI config > 0. Packages < config priority will always be skipped. Higher priority senders will overrule lower priority package senders (timeout 3 seconds). Non-zero start code and E1.31 preview data is ignored.
Note: If you see issued with lag, you may see better performance if you disable Wi-Fi Multimedia (WMM) Mode QoS on your router
"},{"location":"interfaces/e1.31-dmx/#general-recommendations","title":"General Recommendations","text":" - For a fluent 25ms (40fps) or more framerate, it is recommended to use no more than 3 universes (510 LEDs).
- Using multiple E1.31 sources to control a single WLED controller will impact performance. If possible it's recommended to avoid this.
- Configure WLED to connect to a WiFi Network. It was observed that sending E1.31 from a computer to WLED when accessed as access point (WLED-AP) may not work, see forum post.
- When using an ESP32, disabling WiFi sleep in the WiFi settings of WLED can reduce/eliminate visual stuttering/lag of effects, and significantly reduce ping times. Note: disabling WiFi sleep will increase power consumption.
"},{"location":"interfaces/e1.31-dmx/#using-ledfx","title":"Using LedFX","text":"We highly recommend the LedFx project in combination with WLED! Configure WLED first, ensure devices are powered on and connected to your WiFi. To add WLED devices, in the 'Device Management', click on the Find WLED devices button. If you want to manually add devices, use more than 170 LEDs with LedFx, you need to go to additional settings and set \"Universe Size\" to 510 when adding the WLED device!
"},{"location":"interfaces/e1.31-dmx/#settings","title":"Settings","text":""},{"location":"interfaces/e1.31-dmx/#dmx-types","title":"DMX types","text":"Select the mode you want to use in Sync settings.
"},{"location":"interfaces/e1.31-dmx/#disabled","title":"Disabled","text":"Incoming E1.31 packets will be ignored.
"},{"location":"interfaces/e1.31-dmx/#single-rgb","title":"Single RGB","text":"All LEDs are set to the same color. 3 Channels: Red, Green, Blue
"},{"location":"interfaces/e1.31-dmx/#single-drgb","title":"Single DRGB","text":"All LEDs are set to the same color. 4 Channels: Master Dimmer, Red, Green, Blue
"},{"location":"interfaces/e1.31-dmx/#effect","title":"Effect","text":"Not a realtime mode & only support 1 universe. Allows setting WLED effect properties over E1.31 with 15 channels.
Channel Property 1 Master Dimmer 2 Effect mode ID 3 Effect speed 4 Effect intensity 5 Effect palette ID 6 Effect option 7 Red Primary 8 Green Primary 9 Blue Primary 10 Red Secondary 11 Green Secondary 12 Blue Secondary 13 Red Tertiary 14 Green Tertiary 15 Blue Tertiary The effect option channel is divided into 4 macro parts to control mirror and reverse states:
value mirror reverse 0..63 false false none 64..127 false true reverse 128..191 true false mirror 192..255 true true mirror & reverse"},{"location":"interfaces/e1.31-dmx/#effect-white","title":"Effect + White","text":"Same as Effect with additional whites = 18 channels.
Channel Property .. .. 16 White Primary 17 White Secondary 18 White Tertiary"},{"location":"interfaces/e1.31-dmx/#effect-segment","title":"Effect Segment","text":"Same as Effect with 15 channels per segment; expect channel 1 = \"Segment Dimmer\".
All effect segment modes introduce an additional DMX segment spacing. If spacing s = 0 subsequent DMX addresses for all segments are created. When s > 0 a gap of s DMX addresses between segments is used. To calculate segment DMX fixture addresses:
Segment DMX Address (i) = DMXAddress + i * (dmxEffectChannels + s)\n
Where DMXAddress = start address as configured in UI, dmxEffectChannels = 15|18 depending on selected effect segment mode, s = address gap as configured in UI and i is the index id of each segment as existing.
Note: 1 DMX universe = max 512 DMX addresses. So max number of segments depends on start address, selected segment mode and configured DMX segment spacing. To calculate how many segments can be controlled:
Max segments = floor[ (512 - DMXAddress) / (dmxEffectChannels + s) ]\n
"},{"location":"interfaces/e1.31-dmx/#effect-segment-white","title":"Effect Segment + White","text":"Same as Effect Segment including whites, so it uses 18 DMX channels per segment.
"},{"location":"interfaces/e1.31-dmx/#multiple-rgb","title":"Multiple RGB","text":"3 Channels per LED in sequence. LED 0 Red, LED 0 Green, LED 0 Blue, LED 1 Red, ... Default mode, equivalent to pre-0.9.1 E1.31. This is the mode you want to use for xLights and LedFx.
"},{"location":"interfaces/e1.31-dmx/#multiple-rgbw","title":"Multiple RGBW","text":"Like Multiple RGB + additional white channels.
"},{"location":"interfaces/e1.31-dmx/#dimmer-multi-rgb","title":"Dimmer + Multi RGB","text":"Like Multiple RGB, but the first channel is a brightness control. Master Dimmer, LED 0 Red, LED 0 Green, ...
"},{"location":"interfaces/e1.31-dmx/#preset","title":"Preset","text":"Trigger presets and control brightness. 2 Channels: Brightness, Preset ID
"},{"location":"interfaces/http-api/","title":"HTTP Request API","text":"Hint
While this API is not deprecated, it is highly recommended to use the JSON API instead of the HTTP API for new integrations, as it is structured in a better way and allows efficient use of newer features like segments, presets, and playlists.
WLED's HTTP API allows you to set many properties of your lights, even more than the index page UI supports, via a simple GET web request.
Help
Unsure how all this API stuff works? Check out this amazing guide by tynick!
The basic URL scheme is: [ipadress]/win. This will return an XML file with some current values (see bottom of page). Parameters can be added to control some of the variables.
- Example (AP):
192.168.4.1/win&A=255 sets the brightness to maximum - Example (mdns):
led.local/win&A=128&FX=0 sets the brightness to half and the effect to Solid
In conjunction with a router port forwarding this can be used to automate WLED, for example via IFTTT.
Add one or multiple of the following parameters after the base URL/IP to change values: (if the parameter is unknown or the value illegal nothing will happen)
"},{"location":"interfaces/http-api/#led-control","title":"LED control","text":"Parameter Value Range Description Since Version &A= 0 to 255 Master brightness 0.2 &T= 0, 1, or 2 Master Off/On/Toggle 0.3 &R= 0 to 255 Primary Red value 0.2 &G= 0 to 255 Primary Green value 0.2 &B= 0 to 255 Primary Blue value 0.2 &W= 0 to 255 Primary White value 0.4 &FX= 0 to 101 LED Effect Index 0.3 &SX= 0 to 255 Effect Speed 0.3 &IX= 0 to 255 Effect Intensity 0.5.0 &FP= 0 to 46 FastLED Palette 0.8.0 &NL= 0 to 255 Nightlight active and duration in minutes 0.3 &ND none Toggles nightlight on but uses default duration 0.6.3 &NT= 0 to 255 Nightlight target brightness 0.5.0 &NF= 0 to 2 Fade Nightlight, 1 = fade brightness only, 2 = additionaly fade color from primary to secondary color 0.5.0"},{"location":"interfaces/http-api/#advanced","title":"Advanced","text":"Parameter Value Range Description Since Version &CL= HEX/DEC Primary color 0.8.0 &C2= HEX/DEC Secondary color 0.8.0 &C3= HEX/DEC Third color 0.8.0 &R2= 0 to 255 Secondary Red value 0.4 &G2= 0 to 255 Secondary Green value 0.4 &B2= 0 to 255 Secondary Blue value 0.4 &W2= 0 to 255 Secondary White value 0.4 &HU= 0 to 65535 Hue 0.5.1 &SA= 0 to 255 Saturation (only in conjunction with Hue) 0.5.1 &H2 none Hue + Saturation will set secondary color 0.5.1 &SR= 0 or 1 Set Primary/Secondary color to random hue 0.4 &SC none Swap primary and secondary color 0.4"},{"location":"interfaces/http-api/#use-of-hex-values","title":"Use of hex values","text":"Hex values need to be prefaced with the character h or H. The normal format is RRGGBB. If the led strip is RGBW, the hex format is WWRRGGBB. Note: In the UI the format is RRGGBBWW, so the values cannot be copied without a transformation.
"},{"location":"interfaces/http-api/#loxone-commands","title":"Loxone commands","text":"Loxone offers two commands. One for RGB values and one for brightness and color temperature.
Parameter Syntax Range Description Since Version &LX= BBBGGGRRR 0 - 100100100 Loxone RGB value for primary color. Each color (RRR,GGG,BBB) is specified in the range from 0 to 100%. 0.11 &LX= 20bbbtttt 200002700 - 201006500 Loxone brightness and color temperature values for primary color. Brightness bbb is specified in the range 0 to 100%. tttt defines the color temperature in the range from 2700 to 6500 Kelvin. 0.11 &LY= BBBGGGRRR 0 - 100100100 Loxone RGB value for secondary color. Each color (RRR,GGG,BBB) is specified in the range from 0 to 100%. 0.11 &LY= 20bbbtttt 200002700 - 201006500 Loxone brightness and color temperature values for secondary color. Brightness bbb is specified in the range 0 to 100%. tttt defines the color temperature in the range from 2700 to 6500 Kelvin. 0.11"},{"location":"interfaces/http-api/#notifications","title":"Notifications","text":"Parameter Value Range Description Since Version &RN= 0 or 1 Receive UDP Notifications 0.3 &SN= 0 or 1 Send UDP Notifications 0.3 &NN none No notification for this request 0.3 &HP= 0 to 99 Sets Hue polling light ID (0 is off) 0.5.1"},{"location":"interfaces/http-api/#presets","title":"Presets","text":"Parameter Value Range Description Since Version &PS= 1 to 16 Saves current setup to preset. Preset 255 can be used and is temporary/not persistent. 0.4 &PL= 1 to 250 Applies entire preset 0.4 &P1= 1 to 249 First cycle preset 0.6.3 &P2= 2 to 250 Last cycle preset 0.6.3 &TT= 0 to 65000 Set transition time (ms) 0.6.3"},{"location":"interfaces/http-api/#macros","title":"Macros","text":"Parameter Value Range Description Since Version &M= 1 to 16 Apply macro (deprecated, added for compatibility with pre-0.11 automations) 0.5.0"},{"location":"interfaces/http-api/#segments","title":"Segments","text":"It is highly recommended to use the JSON API when dealing with Segments.
Parameter Value Range Description Since Version &SM= 0 to 9 Set the main segment (values are reported to XML) 0.9.0 &SS= 0 to 9 Select segment to apply THIS api call to 0.9.0 &SV= 0, 1, or 2 Set segment selected (2 unselects others) 0.9.0 &S= 0 to ledcount-1 Set segment start 0.9.0 &S2= 0 to ledcount Set segment stop 0.9.0 &GP= 1 to 255 Set segment grouping 0.9.1 &SP= 0 to 255 Set segment spacing 0.9.1 &RV= 0 or 1 Reverse/Flip Segment direction 0.9.1 &SB= 0 to 255 Segment brightness 0.10.0"},{"location":"interfaces/http-api/#general-and-experimental","title":"General and Experimental","text":"Parameter Value Range Description Since Version &RB none Reboot WLED 0.10.0 (?) &ST= 32bit Current UTC time in Unix epoch 0.4 &CT= 32bit UTC time for countdown end 0.4 &MD= 0 or 1 Set slider mode to RGB/HSB 0.3 &AX= 0 to 255 Debug feature, can be configured for general IO 0.3 &IN none Server will not respond to this request (internal) 0.3 &OL= 0 to 255 Experimental overlays 0.3 &L= 0 to 255 Lock pixel 0.4 &L2= 0 to 255 Lock pixel range L to L2 0.4 &UL none Unlock instead (used in conjunction with L and L2) 0.4 &NX= String 1..6 Cronixie clockface 0.4 &NM= 0 or 1 Cronixie Time or Countdown mode 0.4 &NB= 0 or 1 Cronixie Backlight 0.4 &IT none Include UI color theme in API response 0.8.2 &RD= 0 or 1 Toggle realtime UDP 0.8.4 &LO= 0-2 Live data override. 0 is off, 1 is override until live data ends, 2 is override until ESP reboot 0.10.2"},{"location":"interfaces/http-api/#xml-response","title":"XML response","text":"This is the XML file sent as response to every API call.
Parameter Value Range Description ac 0 to 255 Master Brightness cl 3x 0..255 Primary Color RGB cs 3x 0..255 Secondary RGB ns 0 or 1 Notification Sending on nr 0 or 1 Notification Receive on nl 0 or 1 Nightlight active nf 0 or 2 Nightlight Fade type nd 0 to 255 Nightlight delay nt 0 to 255 Nightlight target brightness fx 0 to 73 Effect index sx 0 to 255 Effect speed ix 0 to 255 Effect intensity fp 0 to 43 FastLED palette wv -1 to 255 Primary White value ws 0 to 255 Secondary White ps 0 to 255 Current Preset cy 0 or 1 Preset Cycling enabled md 0 or 1 RGB or HSB UI mode ds String 0..32 Server description ss 0 to 12 Segment ID"},{"location":"interfaces/http-api/#in-decrementing-values","title":"In-/decrementing values","text":"You can use the ~ character to easily set values relative to their current value. This is currently supported for the following parameters: A, R, G, B, W, R2, G2, B2, W2, FX, SX, IX, FP, PL
For example, use PL=~ to go to the next preset. Using just ~ without a number will increase the value by 1, ~- will decrease it by 1. The value will then wrap around, so using A=~- when A is 0 will set A to 255.
You can also specify by how much to change the value. For example, using A=~10 will increase the brightness by 10. In case of using a number behind ~, the value will clip (so it will not wrap around, if the maximum brightness is set, A=~10 will not have any effect)
To setup a Macro for a Button to advance to the next Preset, use win&P1=1&P2=30&PL=~ P1 will equal the first Preset of the rotation while P2 will be the last Preset.
"},{"location":"interfaces/infrared/","title":"Infrared","text":"Version Info
Since v0.8.2, infrared control from various IR remotes is supported for ESP8266 and since v0.9.0 for ESP32, too.
A dedicated infrared receiver module is required and must be connected to the WLED Controller. For example, KY-022 or TSOP38238 are confirmed to work and inexpensive. These receivers each have three pins: 3.3V, GND and IR data. IR data pin must be connected to a free GPIO pin. This GPIO must then be set as IR GPIO under \"Config->LED Preferences\" (The default sensor pin is GPIO4).
Warning
IR receiving will not work on ESP8266 if you use any LED pin other than GPIO 1, 2, or 3 for digital LED strips.
"},{"location":"interfaces/infrared/#supported-ir-remotes","title":"Supported IR remotes","text":"To use IR remote go to Settings, Sync Interfaces and change the value for Infrared receiver type according to the IR remote type of the following list:
- white 24-key IR remote with R,G,B + 12 color-tones
- white 24-key IR remote with CT+ / CT- buttons
- blue 40-key IR remote with keys for 25%, 50%, 75% and 100%
- white 44-key IR remote with up/down arrows for the colors R,G and B
- white 21-key IR remote with R,G,B + 9 color-tones
- black 6-key IR remote with CH up/down + Vol up/down
- JSON IR remote - Easily configure and use any IR remote.
"},{"location":"interfaces/infrared/#esp-now-based-remote-control","title":"ESP-NOW based remote control","text":"Since version WLED 14.0-beta3: An ESP-NOW compatible remote control is supported. An example of this is the \u201eWIZmote\u201c remote control. This is based on an ESP microcontroller. ESP-NOW can be activated in WLED settings. You have to enter the Hardware MAC address of the remote control. This is determined by clicking on any button on the remote control and copying the last received MAC address from the \"Last Seen\" field to the \"Hardware MAC\" field in WLED ESP-NOW settings (\u201cConfig->WiFi Setup\u201d) and saving it with \"Save\". Advantages: no special receiver needs to be attached to the WLED controller and the signals are transmitted via radio network. Therefore there is no line of sight between the remote control and the WLED controller required, as is the case with an IR remote control. The 4 buttons \"1\"-\"4\" of the WIZmote remote control are linked to presets 1 to 4. The meaning of other keys is self-explanatory. Attention: WIZmote needs two good quality AAA batteries to work properly. If the batteries are too weak, the correct signal will not be sent, even if the blue LED on the remote control lights up briefly, actually indicating signal transmission.
"},{"location":"interfaces/json-api/","title":"JSON API","text":"WLED versions since 0.8.4 implement a powerful JSON API over HTTP. It is accessible using the /json subpage.
"},{"location":"interfaces/json-api/#obtaining-light-information","title":"Obtaining light information","text":"Sending a GET request will return an object similar to the sample below The response consists of four objects:
state contains the current state of the light. All values may be modified by the client (see below)info contains general information about the device. No value can be modified using this APIeffects contains an array of the effect mode namespalettes contains an array of the palette names
You may also obtain those objects individually using the URLs /json/state /json/info /json/eff, and /json/pal.
Reserved effect IDs
In WLED versions 0.14+, some effects are unsupported in certain builds (e.g. some audio reactive effects may only work on ESP32). In order for each effect to have an unique ID on all devices, having unsupported ones in between supported ones is possible. If called, these will fallback to the Solid effect, in the effects list they have the name RSVD or -. To improve user experience, it is recommended to remove effects with the names RSVD or - form the UI effect selection.
"},{"location":"interfaces/json-api/#setting-new-values","title":"Setting new values","text":"Sending a POST request to /json or /json/state with (parts of) the state object will update the respective values. Example: {\"on\":true,\"bri\":255} sets the brightness to maximum. {\"seg\":[{\"col\":[[0,255,200]]}]} sets the color of the first segment to teal. {\"seg\":[{\"id\":X,\"on\":\"t\"}]} and replacing X with the desired segment ID will toggle on or off that segment.
CURL example
This will toggle on and off and return the new state (v0.13+): curl -X POST \"http://[WLED-IP]/json/state\" -d '{\"on\":\"t\",\"v\":true}' -H \"Content-Type: application/json\"
Sample JSON API response (v0.8.4):
{\n\"state\": {\n\"on\": true,\n\"bri\": 127,\n\"transition\": 7,\n\"ps\": -1,\n\"pl\": -1,\n\"nl\": {\n\"on\": false,\n\"dur\": 60,\n\"fade\": true,\n\"tbri\": 0\n},\n\"udpn\": {\n\"send\": false,\n\"recv\": true\n},\n\"seg\": [{\n\"start\": 0,\n\"stop\": 20,\n\"len\": 20,\n\"col\": [\n[255, 160, 0, 0],\n[0, 0, 0, 0],\n[0, 0, 0, 0]\n],\n\"fx\": 0,\n\"sx\": 127,\n\"ix\": 127,\n\"pal\": 0,\n\"sel\": true,\n\"rev\": false,\n\"cln\": -1\n}]\n},\n\"info\": {\n\"ver\": \"0.8.4\",\n\"vid\": 1903252,\n\"leds\": {\n\"count\": 20,\n\"rgbw\": true,\n\"pin\": [2],\n\"pwr\": 0,\n\"maxpwr\": 65000,\n\"maxseg\": 1\n},\n\"name\": \"WLED Light\",\n\"udpport\": 21324,\n\"live\": false,\n\"fxcount\": 80,\n\"palcount\": 47,\n\"arch\": \"esp8266\",\n\"core\": \"2_4_2\",\n\"freeheap\": 13264,\n\"uptime\": 17985,\n\"opt\": 127,\n\"brand\": \"WLED\",\n\"product\": \"DIY light\",\n\"btype\": \"src\",\n\"mac\": \"60019423b441\"\n},\n\"effects\": [\n\"Solid\", \"Blink\", \"Breathe\", \"Wipe\", \"Wipe Random\", \"Random Colors\", \"Sweep\", \"Dynamic\", \"Colorloop\", \"Rainbow\",\n\"Scan\", \"Dual Scan\", \"Fade\", \"Chase\", \"Chase Rainbow\", \"Running\", \"Saw\", \"Twinkle\", \"Dissolve\", \"Dissolve Rnd\",\n\"Sparkle\", \"Dark Sparkle\", \"Sparkle+\", \"Strobe\", \"Strobe Rainbow\", \"Mega Strobe\", \"Blink Rainbow\", \"Android\", \"Chase\", \"Chase Random\",\n\"Chase Rainbow\", \"Chase Flash\", \"Chase Flash Rnd\", \"Rainbow Runner\", \"Colorful\", \"Traffic Light\", \"Sweep Random\", \"Running 2\", \"Red & Blue\",\"Stream\",\n\"Scanner\", \"Lighthouse\", \"Fireworks\", \"Rain\", \"Merry Christmas\", \"Fire Flicker\", \"Gradient\", \"Loading\", \"In Out\", \"In In\",\n\"Out Out\", \"Out In\", \"Circus\", \"Halloween\", \"Tri Chase\", \"Tri Wipe\", \"Tri Fade\", \"Lightning\", \"ICU\", \"Multi Comet\",\n\"Dual Scanner\", \"Stream 2\", \"Oscillate\", \"Pride 2015\", \"Juggle\", \"Palette\", \"Fire 2012\", \"Colorwaves\", \"BPM\", \"Fill Noise\", \"Noise 1\",\n\"Noise 2\", \"Noise 3\", \"Noise 4\", \"Colortwinkle\", \"Lake\", \"Meteor\", \"Smooth Meteor\", \"Railway\", \"Ripple\"\n],\n\"palettes\": [\n\"Default\", \"Random Cycle\", \"Primary Color\", \"Based on Primary\", \"Set Colors\", \"Based on Set\", \"Party\", \"Cloud\", \"Lava\", \"Ocean\",\n\"Forest\", \"Rainbow\", \"Rainbow Bands\", \"Sunset\", \"Rivendell\", \"Breeze\", \"Red & Blue\", \"Yellowout\", \"Analogous\", \"Splash\",\n\"Pastel\", \"Sunset 2\", \"Beech\", \"Vintage\", \"Departure\", \"Landscape\", \"Beach\", \"Sherbet\", \"Hult\", \"Hult 64\",\n\"Drywet\", \"Jul\", \"Grintage\", \"Rewhi\", \"Tertiary\", \"Fire\", \"Icefire\", \"Cyane\", \"Light Pink\", \"Autumn\",\n\"Magenta\", \"Magred\", \"Yelmag\", \"Yelblu\", \"Orange & Teal\", \"Tiamat\", \"April Night\"\n]\n}\n
"},{"location":"interfaces/json-api/#overview-of-values","title":"Overview of values","text":""},{"location":"interfaces/json-api/#state-object","title":"State object","text":"JSON key Value range Description on bool On/Off state of the light bri 0 to 255 Brightness of the light. If on is false, contains last brightness when light was on (aka brightness when on is set to true. Setting bri to 0 is supported but it is recommended to use the range 1-255 and use on: false to turn off. The state response will never havethe value 0 for bri. transition 0 to 255 Duration of the crossfade between different colors/brightness levels. One unit is 100ms, so a value of 4 results in atransition of 400ms. tt 0 to 255 Similar to transition, but applies to just the current API call. Not included in state response. ps -1 to 65535 ID of currently set preset. 1~17~ can be used to iterate through presets 1-17. pss 0 to 65535 Bitwise indication of preset slots (0 - vacant, 1 - written). Always 0 in 0.11. Not changable. Removed as of v0.11.1 psave 1 to 16 (250 in 0.11) Save current light config to specified preset slot. Not included in state response. pl -1 to 0 ID of currently set playlist. For now, this sets the preset cycle feature, -1 is off and 0 is on. nl.on bool Nightlight currently active nl.dur 1 to 255 Duration of nightlight in minutes nl.fade bool If true, the light will gradually dim over the course of the nightlight duration. If false, it will instantly turn to the target brightness once the duration has elapsed. Removed in 0.13.0 (use mode instead) nl.mode 0 to 3 Nightlight mode (0: instant, 1: fade, 2: color fade, 3: sunrise) (available since 0.10.2) nl.tbri 0 to 255 Target brightness of nightlight feature nl.rem -1 to 15300 Remaining nightlight duration in seconds, -1 if not active. Only in state response, can not be set. udpn.send bool Send WLED broadcast (UDP sync) packet on state change udpn.recv bool Receive broadcast packets udpn.nn bool Don't send a broadcast packet (applies to just the current API call). Not included in state response. v bool If set to true in a JSON POST command, the response will contain the full JSON state object. Not included in state response rb bool If set to true, device will reboot immediately. Not included in state response. live bool If set to true, enters realtime mode and blanks the LEDs. The realtime timeout option does not have an effect when this command is used, WLED will stay in realtime mode until the state (color/effect/segments, excluding brightness) is changed. It is expected that {\"live\":false} is sent once live data sending is terminated. Not included in state response. lor 0, 1, or 2 Live data override. 0 is off, 1 is override until live data ends, 2 is override until ESP reboot (available since 0.10.0) time uint32 Set module time to unix timestamp. Not included in state response. mainseg 0 to info.leds.maxseg-1 Main Segment seg Array of segment objects Segments are individual parts of the LED strip. In 0.9.0 this will enables running different effects on differentparts of the strip. playlist object Custom preset playlists. Not included in state response (available since 0.11.0) tb uint32 Sets timebase for effects. Not reported."},{"location":"interfaces/json-api/#contents-of-the-segment-object","title":"Contents of the segment object","text":"Notice: start, stop, and len are not changeable in 0.8.4. Any segment with id > 0 is ignored. Unless stated otherwise, every value may be changed via an HTTP POST request. The tertiary color is not gamma-corrected in 0.8.4, but is in subsequent releases.
JSON key Value range Description id 0 to info.maxseg -1 Zero-indexed ID of the segment. May be omitted, in that case the ID will be inferred from the order of the segment objects in the seg array. start 0 to info.leds.count -1 LED the segment starts at. stop 0 to info.leds.count LED the segment stops at, not included in range. If stop is set to a lower or equal value than start (setting to 0 is recommended), the segment is invalidated and deleted. len 0 to info.leds.count Length of the segment (stop - start). stop has preference, so if it is included, len is ignored. grp 0 to 255 Grouping (how many consecutive LEDs of the same segment will be grouped to the same color) spc 0 to 255 Spacing (how many LEDs are turned off and skipped between each group) of -len+1 to len Offset (how many LEDs to rotate the virtual start of the segments, available since 0.13.0) col array of colors Array that has up to 3 color arrays as elements, the primary, secondary (background) and tertiary colors of the segment. Each color is an array of 3 or 4 bytes, which represent an RGB(W) color. fx 0 to info.fxcount -1 ID of the effect or ~ to increment, ~- to decrement, or r for random. sx 0 to 255 Relative effect speed. ~ to increment, ~- to decrement. ~10 to increment by 10, ~-10 to decrement by 10. ix 0 to 255 Effect intensity. ~ to increment, ~- to decrement. ~10 to increment by 10, ~-10 to decrement by 10. c1 0 to 255 Effect custom slider 1. Custom sliders are hidden or displayed and labeled based on effect metadata. c2 0 to 255 Effect custom slider 2. c3 0 to 31 Effect custom slider 3. o1 bool Effect option 1. Custom options are hidden or displayed and labeled based on effect metadata. o2 bool Effect option 2. o3 bool Effect option 3. pal 0 to info.palcount -1 ID of the color palette or ~ to increment, ~- to decrement, or r for random. sel bool true if the segment is selected. Selected segments will have their state (color/FX) updated by APIs that don't support segments (e.g. UDP sync, HTTP API). If no segment is selected, the first segment (id:0) will behave as if selected. WLED will report the state of the first (lowest id) segment that is selected to APIs (HTTP, MQTT, Blynk...), or mainseg in case no segment is selected and for the UDP API. Live data is always applied to all LEDs regardless of segment configuration. rev bool Flips the segment, causing animations to change direction. on bool Turns on and off the individual segment. (available since 0.10.0) bri 0 to 255 Sets the individual segment brightness (available since 0.10.0) mi bool Mirrors the segment (available since 0.10.2) cct 0 to 255 or 1900 to 10091 White spectrum color temperature (available since 0.13.0) lx BBBGGGRRR: 0 - 100100100 Loxone RGB value for primary color. Each color (RRR,GGG,BBB) is specified in the range from 0 to 100%. lx 20bbbtttt: 200002700 - 201006500 Loxone brightness and color temperature values for primary color. Brightness bbb is specified in the range 0 to 100%. tttt defines the color temperature in the range from 2700 to 6500 Kelvin. (available since 0.11.0, not included in state response) ly BBBGGGRRR: 0 - 100100100 Loxone RGB value for secondary color. Each color (RRR,GGG,BBB) is specified in the range from 0 to 100%. ly 20bbbtttt: 200002700 - 201006500 Loxone brightness and color temperature values for secondary color. Brightness bbb is specified in the range 0 to 100%. tttt defines the color temperature in the range from 2700 to 6500 Kelvin. (available since 0.11.0, not included in state response) i array Individual LED control. Not included in state response (available since 0.10.2) frz bool freezes/unfreezes the current effect m12 0 to 4 [map1D2D.count] Setting of segment field 'Expand 1D FX'. (0: Pixels, 1: Bar, 2: Arc, 3: Corner) si 0 to 3 Setting of the sound simulation type for audio enhanced effects. (0: 'BeatSin', 1: 'WeWillRockYou', 2: '10_3', 3: '14_3') (as of 0.14.0-b1, there are these 4 types defined)"},{"location":"interfaces/json-api/#info-object","title":"Info object","text":"No value may be changed by means of this API.
JSON key Value range Description ver string Version name. vid uint32 Build ID (YYMMDDB, B = daily build index). leds object Contains info about the LED setup. leds.cct bool true if the light supports color temperature control (available since 0.13.0, deprecated, use info.leds.lc) leds.count 1 to 1200 Total LED count. leds.fps 0 to 255 Current frames per second. (available since 0.12.0) leds.rgbw bool true if LEDs are 4-channel (RGB + White). (deprecated, use info.leds.lc) leds.wv bool true if a white channel slider should be displayed. (available since 0.10.0, deprecated, use info.leds.lc) leds.pin byte array LED strip pin(s). Always one element. Removed as of v0.13 leds.pwr 0 to 65000 Current LED power usage in milliamps as determined by the ABL. 0 if ABL is disabled. leds.maxpwr 0 to 65000 Maximum power budget in milliamps for the ABL. 0 if ABL is disabled. leds.maxseg byte Maximum number of segments supported by this version. leds.lc byte Logical AND of all active segment's virtual light capabilities leds.seglc byte array Per-segment virtual light capabilities str bool If true, an UI with only a single button for toggling sync should toggle receive+send, otherwise send only name string Friendly name of the light. Intended for display in lists and titles. udpport uint16 The UDP port for realtime packets and WLED broadcast. live bool If true, the software is currently receiving realtime data via UDP or E1.31. lm string Info about the realtime data source lip string Realtime data source IP address ws -1 to 8 Number of currently connected WebSockets clients. -1 indicates that WS is unsupported in this build. fxcount byte Number of effects included. palcount uint16 Number of palettes configured. wifi object Info about current signal strength wifi.bssid string The BSSID of the currently connected network. wifi.signal 0 to 100 Relative signal quality of the current connection. wifi.channel 1 to 14 The current WiFi channel. fs object Info about the embedded LittleFS filesystem (since 0.11.0) fs.u uint32 Estimate of used filesystem space in kilobytes fs.t uint32 Total filesystem size in kilobytes fs.pmt uint32 Unix timestamp for the last modification to the presets.json file. Not accurate after boot or after using /edit ndc -1 to 255 Number of other WLED devices discovered on the network. -1 if Node discovery disabled. (since 0.12.0) arch string Name of the platform. core string Version of the underlying (Arduino core) SDK. lwip 0, 1, or 2 Version of LwIP. 1 or 2 on ESP8266, 0 (does not apply) on ESP32. Deprecated, removal in 0.14.0 freeheap uint32 Bytes of heap memory (RAM) currently available. Problematic if <10k. uptime uint32 Time since the last boot/reset in seconds. opt uint16 Used for debugging purposes only. brand string The producer/vendor of the light. Always WLED for standard installations. product string The product name. Always FOSS for standard installations. btype string The origin of the build. src if a release version is compiled from source, bin for an official release image, dev for a development build (regardless of src/bin origin) and exp for experimental versions. ogn if the image is flashed to hardware by the vendor. Removed as of v0.10 mac string The hexadecimal hardware MAC address of the light, lowercase and without colons. ip string The IP address of this instance. Empty string if not connected. (since 0.13.0)"},{"location":"interfaces/json-api/#per-segment-individual-led-control","title":"Per-segment individual LED control","text":"Using the i property of the segment object, you can set the LED colors in the segment using the JSON API. Keep in mind that this is non-persistent, if the light is turned off the segment will return to effect mode. The segment is frozen when using individual control, the set effect will not run. To unfreeze the segment, click the \"eye\" icon, change any property of the segment or turn off the light.
To set individual LEDs starting from the beginning, use an array of Color arrays [255, 0, 0] or hex values \"FF0000\". Hex values are more efficient than Color arrays and should be preferred when setting a large number of colors. {\"seg\":{\"i\":[\"FF0000\", \"00FF00\", \"0000FF\"]}} or {\"seg\":{\"i\":[[255,0,0], [0,255,0], [0,0,255]]}} will set the first LED red, the second green and the third blue.
To set individual LEDs, use the LED index followed by its color value. {\"seg\":{\"i\":[0,\"FF0000\", 2,\"00FF00\", 4,\"0000FF\"]}} is the same as above, but leaves blank spaces between the lit LEDs.
To set ranges of LEDs, use the LED start and stop index followed by its color value. {\"seg\":{\"i\":[0,8,\"FF0000\", 10,18,\"0000FF\"]}} sets the first eight LEDs to red, leaves out two, and sets another 8 to blue.
To set a large number of colors, send multiple api calls of 256 colors at a time. {\"seg\": {\"i\":[0,\"CC0000\", \"00CC00\", \"0000CC\", \"CC0000\"...]}} {\"seg\": {\"i\":[256, \"CC0000\", \"00CC00\", \"0000CC\", \"CC0000\"...]}} {\"seg\": {\"i\":[512, \"CC0000\", \"00CC00\", \"0000CC\", \"CC0000\"...]}}
Do not make several calls in parallel, that is not optimal for the device. Instead make your call in sequence, where each call waits for the previous to complete before making a new one. How this is done depends on your choice of tool, but with CURL you que your commands by separating then with && i.e. CURL [command 1] && CURL [command 2] && CURL [command 3].
Command buffer size
If you are trying to set many LEDs and it fails to work, you can check your request here for length. Select ESP32 and Deserialize. If the required buffer size is above 10K for ESP8266 and 24K for ESP32, please split it into multiple sequential requests and consider using the Hex string syntax.
Keep in mind that the LED indices are segment-based, so LED 0 is the first LED of the segment, not of the entire strip. Segment features, including Grouping, Spacing, Mirroring and Reverse are functional.
Matrices are handled as a non-serpentine layout.
Brightness interaction
For your colors to apply correctly, make sure the desired brightness is set beforehand. Turning on the LEDs from an off state and setting individual LEDs in the same JSON request will not work!
"},{"location":"interfaces/json-api/#playlists","title":"Playlists","text":"(Available since 0.11.0)
Sample playlist API call:
{\n\"playlist\": {\n\"ps\": [26, 20, 18, 20],\n\"dur\": [30, 20, 10, 50],\n\"transition\": 0,\n\"repeat\": 10,\n\"end\": 21\n}\n}\n
This example applies preset ID 26 for 3 seconds, then preset 20 for 2 seconds, then preset 18 for 1 second, lastly preset 20 again for 5 seconds.This repeats 10 times, then preset 21 is applied.
Playlist object:
JSON key Description ps Array of preset ID integers to be applied in this order. dur Array of time each preset should be kept, in tenths of seconds. If only one integer is supplied, all presets will be kept for that time.Defaults to 10 seconds if not provided. transition Array of time each preset should transition to the next one, in tenths of seconds. If only one integer is supplied, all presets will transition for that time. Defaults to the current transition time if not provided. repeat How many times the entire playlist should cycle before finishing. Set to 0 for an indefinite cycle. Default to indefinite if not provided. end Single preset ID to apply after the playlist finished. Has no effect when an indefinite cycle is set. If not provided, the light will stay on the last preset of the playlist."},{"location":"interfaces/json-api/#light-capabilities","title":"Light capabilities","text":"In order to e.g. only show color controls relevant to a given setup, it is necessary to obtain the color capabilities of the light. The info.leds.seglc array can be used to do so on a per-segment level. It contains n+1 8-bit integers, where n is the id of the last active segment, each index corresponds to the segment with that ID. This integer indicates whether a given segment supports (24 bit) RGB colors, an extra (8 bit) white channel and/or adjustable color temperature (CCT):
Bit Capability 0 Segment supports RGB color 1 Segment supports white channel 2 Segment supports color temperature 3-7 Reserved (expect any value) Therefore:
lc value Capabilities 0 None. Indicates a segment that does not have a bus within its range, e.g. because it is not active. 1 Supports RGB 2 Supports white channel only 3 Supports RGBW 4 Supports CCT only, no white channel (unused) 5 Supports CCT + RGB, no white channel (unused) 6 Supports CCT (including white channel) 7 Supports CCT (including white channel) + RGB Note that CCT is controllable per-segment, while RGB color and white channel have 3 color slots each per segment.
info.leds.lc contains this info on a global level, and is a bitwise AND of the per-segment light capability values.
"},{"location":"interfaces/json-api/#cct-control","title":"CCT control","text":"Please also see the general info about CCT.
"},{"location":"interfaces/json-api/#supported-value-ranges","title":"Supported value ranges","text":"Given that the white spectrum handling is agnostic to the true color temperature of the LEDs used, a relative range is preferred for the time being, where a value of 0 indicates the warmest possible color temperature, while a value of 255 indicates the coldest temperature.
It is also possible to pass a value in the range of 1900 to 10091, in which case it is treated as a Kelvin color temperature, where 1900 is mapped to a relative value of 0 and 10091 to a relative value of 255.
As such, it is unlikely to match the actual color temperature output by the light, therefore the relative values 0-255 are preferred for the time being.
In the future, an option to specify the Kelvin temperatures of the utilized hardware may be added, once this is done, a color temperature can be set to more accurately match other lights.
Therefore, for forward compatibility, your integration should expect both either a 0-255 value for seg.cct, in which case it is a relative value, or an absolute Kelvin value in the range 1000-16000 K. In case a Kelvin value is provided, you can consider the color temperature as accurate, which is not possible with relative 0-255 values as the Kelvin points of the white channels are unknown. It is preferred that you set a new CCT value in the same range as received from WLED, that is, use 0-255 if the original value was within this range, and 1000-20000 K otherwise.
If your code relies on absolute Kelvin values, a reasonable estimate for the warm white point (relative 0) could be 2700K, while cold white (relative 255) could commonly be 6500K.
"},{"location":"interfaces/json-api/#effect-of-the-segcct-value","title":"Effect of the seg.cct value","text":"seg.cct can always be set, but only has an effect on the physical state of the light if one or both of the following conditions is met:
- White Balance correction is enabled
- A bus supporting CCT is configured and
Calculate CCT from RGB is not enabled
CCT support is indicated by info.leds.cct being true, in which case you can regard the instance as a CCT light and e.g. display a color temperature control.
"},{"location":"interfaces/json-api/#effect-metadata","title":"Effect metadata","text":"Why effect metadata?
Prior to 0.14, user interfaces showed Speed and Intensity slider, palette controls, and all three color slots regardless of the effect selected. This may cause confusion to the user because controls are displayed that have no immediate effect in the current configuration. Effect metadata allows you to dynamically hide certain controls, so that the user only sees controls actually utilized by the selected effect mode.
Starting with WLED 0.14, effect metadata is available under the /json/fxdata URL. This returns an array of strings with info.fxcount entries. The string at a given index corresponds to the metadata of the effect with the same ID as that index. Metadata is stored in a memory-optimized string format, for example the Aurora effect has the metadata !,!;;!;1;sx=24,pal=50.
The metadata string consists of up to five sections, separated by semicolons: <Effect parameters>;<Colors>;<Palette>;<Flags>;<Defaults>
"},{"location":"interfaces/json-api/#effect-parameters","title":"Effect parameters","text":"The first section specifies the number and labels of effect parameters (e.g. speed, intensity). Up to 5 sliders and 3 checkboxes are supported (sx,ix,c1,c2,c3,o1,o2,o3 parameters in the seg object). Slider/checkbox labels are comma separated. An empty or missing label disables this control. ! specifies the default label is used:
Parameter Default tooltip label sx Effect speed ix Effect intensity c1 Custom 1 c2 Custom 2 c3 Custom 3 o1 Option 1 o2 Option 2 o3 Option 3 The fallback value if this section is missing is two sliders, Effect speed and Effect intensity.
Examples:
Parameter string Displayed controls <empty> No effect parameters ! 1 slider: Effect speed !,! 2 sliders: Effect speed + Effect intensity !,Phase 2 sliders: Effect speed + Phase ,Saturation,,,,Invert 1 slider (sets ix parameter) and 1 checkbox: Saturation + Invert ,,,,,Random colors 1 checkbox: Random colors"},{"location":"interfaces/json-api/#colors","title":"Colors","text":"Up to 3 colors can be used. Please note that only the first two characters of the label are visible in the WLED UI. ! specifies the default label is used. The default labels for the color slots are Fx, Bg, and Cs.
The fallback value if this section is missing is 3 colors: Fx + Bg + Cs.
Examples:
Colors string Displayed controls <empty> No color controls ! 1 color: Fx ,! 1 color: Bg !,! 2 colors: Fx + Bg 1,2,3 3 colors: 1 + 2 + 3"},{"location":"interfaces/json-api/#palette","title":"Palette","text":"If empty, the effect does not use palettes. If !, palette selection is enabled.
The fallback value if this section is missing is palette selection enabled.
"},{"location":"interfaces/json-api/#flags","title":"Flags","text":"Flags allow filtering for effects with certain characteristics. They are a single character each and not comma-separated. Currently, the following flags are specified:
Flag Effect characteristic 0 Effect works well on a single LED. If flag 0 is present, flags 1/2/3 are omitted. (unused) 1 Effect is optimized for use on 1D LED strips. 2 Effect requires a 2D matrix setup (unless flag 1 is also present) 3 Effect requires a 3D cube (unless flags 1 and/or 2 are also present) (unused) v Effect is audio reactive, reacts to amplitude/volume. f Effect is audio reactive, reacts to audio frequency distribution. For example, a Flag string of 2v denotes a volume reactive effect that is to be used on 2D matrices.
The fallback value if this section is missing is 1, i.e. a 1D optimized effect.
"},{"location":"interfaces/json-api/#defaults","title":"Defaults","text":"Defaults are values for effect parameters that work particularly well on that effect. They are set automatically when the effect is loaded. To specify defaults, use the standard segment parameter name (e.g. ix) followed by an = and the default value. For example, sx=24,pal=50 sets the effect speed to 24 (slow) and the palette to ID 50 (Aurora).
If no default is specified for a given parameter, it retains the current value.
"},{"location":"interfaces/json-api/#sensors","title":"Sensors","text":"Warning
This section about the Sensor API is a DRAFT specification. It is not yet implemented and subject to change.
Various types of sensors (e.g. for Temperature, light intensity, PIR) may be added to WLED via usermods. To allow read access to sensor data via the JSON API in a standardized way, the info.sensor array is used.
If the info.sensor array is missing or empty, no sensor values are exposed.
"},{"location":"interfaces/json-api/#sensor-object","title":"Sensor object","text":"Each sensor/measurement is represented by an object within the info.sensor array.
For example,
{\"type\":\"T\",\"n\":\"Outside\",\"val\":12}\n
refers to a 12 \u00b0C temperature measurement in Celsius with the sensor name \"Outside\".
The object may contain the following properties, of which all are optional, except type.
JSON key Value range Description type string The type of the sensor. n string The name of the sensor. If omitted, the client may generate a suitable name (e.g. \"Temperature sensor 1\") val any The most current sensor reading. May be of any JSON type depending on the type of the sensor, this is a number for all sensor types pre-defined below except for the \"b\" and \"CL\" types and custom type sensors. null if the reading is invalid, either due to an error or because the first reading has not yet completed. unit string An explicit human-readable unit string for the measurement. If omitted, the default for the sensor type is used. error int or string If present and not null,false,0 or an empty string, a sensor error is indicated. May either be an integer error code or an error string. tc number Seconds of WLED uptime when the value last changed substantially. The threshold for a \"substantial\" change is up to the implementation. This can for example be used to find when a PIR sensor was last activated. tm number Seconds of WLED uptime when the last reading given by val was obtained. ts number Seconds of WLED uptime at the first measurement / start of measurement period. (required for Energy sensor type) min number Lower bound of possible value range max number Upper bound of possible value range u number Absolute uncertainty of the measurement model string Identification of the sensor hardware used"},{"location":"interfaces/json-api/#sensor-types","title":"Sensor types","text":"These are the standardized sensor types that may be implemented by usermods:
Type ID string Measurement type Default unit \"\" (empty string) Invalid sensor (reserved) - b Button/Boolean true/false c Custom user-defined sensor - q Electric charge As t Time s BL Battery Level % CL 24-bit RGB color hex string E Energy (ts property required) J I Electric current A J Illuminance lx L Distance m Lp Sound pressure level dB M Mass kg N Number/count - P Power W Pe General purpose percentage % PL Power Level (signal strength) dBm Pr Pressure Pa R Electric Resistance Ohms RH Relative Humidity % T Temperature \u00b0C U Voltage V (other strings) Reserved, let us know if you need a new type added - If a client is only interested in certain sensor types (e.g. Temperature), it may disregard all other sensor objects.
"},{"location":"interfaces/mqtt/","title":"MQTT","text":"Important
Notice: The MQTT implementation is currently being restructured to provide a better experience for users of Home Assistant and other automation software. This will be a breaking change. For details regarding the rework, please see #207!
WLED versions from 0.8.0 up are able to connect to an MQTT broker for smart home control. Connection to both domains and IP servers is supported on port 1883.
Warning
Secure connections are not currently supported. I recommend only connecting to local MQTT brokers. In v0.8.4-0.8.6 only, WLED supports MQTT autodiscovery by the HomeAssistant software. This has been removed because of bootloop issues and in favor of the native HomeAssistant integration.
WLED will subscribe to up to six topics to change the state of the lights.
The topic paths [mqttDeviceTopic] and [mqttGroupTopic] are customizable in Sync settings. If [mqttGroupTopic] is left empty, it will not subscribe to anything. An empty [mqttDeviceTopic] will instead be replaced with the default \"wled/macaddr\". [mqttDeviceTopic] is intended to be unique to one WLED device and just control that device. [mqttGroupTopic] is intended to control a group of or all WLED devices.
UDP notifications will be sent just as if the change was done via the UI or HTTP API.
Additionally, on light change, WLED will publish to 3 topics for MQTT clients to query the state of the light.
-
[mqttDeviceTopic]/g -> Contains current brightness as ASCII number 0-255
-
[mqttDeviceTopic]/c -> Contains current color as HEX (#RRGGBB if white is 0, else #WWRRGGBB)
-
[mqttDeviceTopic]/v -> Contains XML API response (same as HTTP API)
There is support for client ID and authentication, but this is presently transmitted over an unencrypted connection, so please do not use the same password for other services.
Attention
The maximum length of an MQTT message for WLED is only limited by free RAM.
"},{"location":"interfaces/philips-hue/","title":"Philips Hue","text":"WLED can sync to your Philips hue lights.
Info
This feature allows your WLED light to set it color to that of one of your Hue lights. It does NOT enable individual control of your WLED light from the hue app.
To activate it, please go to Sync settings, fill in the IP of your hue bridge. Also you need to fill in the numeric ID of the hue light you want to sync to. Newer versions of the Hue app do not display light IDs in the \"About\" section of the app anymore, to find it, the app Hue Config Viewer is highly recommended. It is available on the Play Store as well as the App Store. After pairing the app to your Hue bridge, you can see the numeric IDs of all your Hue lights in the Lights menu.
The poll interval specifies how often WLED asks the hue bridge for a light change. Lower values will mean a quicker response of WLED to hue light changes, but also decrease responsiveness and stability of WLED and potentially the hue bridge. It is recommended to set it to 1000-2000ms.
Due to the nature of the hue protocol, WLED can only sync itself to a native hue bulb. At this time, there is no way to add WLED to the hue bridge and control it individually as if it was a native light.
Please don't expect the same level of stability with this feature active, the ESP may reset itself because of the increased traffic it needs to handle.
With DiyHue you can emulate a hue bridge that will show all WLED strips as Hue Strip Plus which will work with Hue Sync in realtime.
"},{"location":"interfaces/serial/","title":"Serial","text":"WLED 0.13.0 supports multiple protocols over Serial. Serial is available via USB, and on most boards, GPIO1 for TX and GPIO3 for RX.
Pin usage limitation
If GPIO3 is allocated (e.g. for LED output), all Serial functionality except debug output is unavailable. If GPIO1 is allocated, all Serial output is disabled, including the JSON API response, Improv, and tpm2 output.
"},{"location":"interfaces/serial/#adalight-and-tpm2","title":"Adalight and tpm2","text":"Both these protocols are supported and can be used to stream realtime LED data to WLED for direct display, e.g. from an bias lighting program. For tpm2, only data packets are supported and data in 24-bit RGB format is expected. If you want to drive a large amount of LEDs, you may need to increase the Baud rate in WLED Sync settings, as the default baud rate of 115200 is only sufficient for about 50-100 LEDs depending on the refresh rate. Adalight is supported since WLED 0.6.3, tpm2 since version 0.10.2.
"},{"location":"interfaces/serial/#json-over-serial","title":"JSON over Serial","text":"You can send commands to the WLED instance via Serial using the JSON API. To request a JSON response containing the state and info objects, send {\"v\":true}.
"},{"location":"interfaces/serial/#improv","title":"Improv","text":"Improv Serial is supported and can be used to check the installed software version as well as connect your device to WiFi without needing to connect to the WLED access point. Improv is used by the WLED web installer for an easy installation and setup process. Note that the baud rate must remain at the default 115200 setting for the device to be detected as Improv-capable.
"},{"location":"interfaces/serial/#other","title":"Other","text":""},{"location":"interfaces/serial/#version-query","title":"Version query","text":"Send a lowercase 'v' character (byte 0x76) to obtain the ID of the installed WLED version.
"},{"location":"interfaces/serial/#led-data-query","title":"LED data query","text":"To get the colors currently displayed by LEDs:
-
Send an uppercase 'L' (byte 0x4C) to request the current LED data as a tpm2 data packet in 24-bit RGB format.
-
Send a lowercase 'l' (byte 0x6C) to request the current LED data in JSON format. This returns the LED colors as 32-bit integers, of which the lowest byte is the Blue value, then Green, then Red, and the highest byte is the White channel value.
For both of these methods, you may need to increase the baud rate if you have a large amount of LEDs. However, tpm2 requires on average 2-4x less bandwidth than JSON, and should therefore be preferred if your application can parse binary data.
"},{"location":"interfaces/serial/#changing-baud-rate","title":"Changing Baud Rate","text":"There are 2 main method for changing Baud Rate for the serial connection - Persistant: Configure in App under Sync Interfaces. This setting will persist, and WLED will use specified Baud Rate from this point forward. - Temporary: Utilizing the serial connection at the existing Baud Rate, send the specific command byte to have WLED temporarily change to new Baud Rate. This Baud Rate is temporary and will be reset to default or peristant setting on reboot.
Byte Baud Rate 0xB0 115200 0xB1 230400 0xB2 460800 0xB3 500000 0xB4 576000 0xB5 921600 0xB6 1000000 0xB7 1500000 - Note: Keep at 115200 to use Improv. Some boards may not support high rates."},{"location":"interfaces/serial/#debugging","title":"Debugging","text":"Compile with the -D WLED_DEBUG build flag to enable serial debugging using DEBUG_PRINTLN(x) macros. This will reserve pin GPIO1, therefore it cannot be used for other purposes when debugging.
"},{"location":"interfaces/udp-notifier/","title":"WLED UDP Sync","text":""},{"location":"interfaces/udp-notifier/#usage","title":"Usage","text":"The UDP notifier function of WLED makes it easy to sync multiple lights to the same color/effect, enabled by default. You can set the specific behavior of it in Sync settings, also you can choose if all aspects or only brightness/color/effects are applied.
Additionally, there is a \"Sync\" quick toggle for it in the main control UI! In UI settings, you can set whether this button only turns on/off sending (default) or also receiving, with the option Sync button toggles both send and receive.
If your sync settings are not the way you like on boot, check the WLED Broadcast section in Sync settings, where you can specify what is sent and received by default:
"},{"location":"interfaces/udp-notifier/#receiving-settings","title":"Receiving settings","text":"Setting Description Receive Brightness If there is a sync notification, whether its brightness should be applied Color Whether the color of the synced device should be applied Effects Whether the effect settings should be applied If all checkboxes are disabled, nothing is received by default after each boot. If the sync is toggled on in the main UI and the corresponding checkbox in UI settings is checked, everything is received.
A sync receiver will not assume the state of the last sender directly after booting, a new packet must be send for it to react.
"},{"location":"interfaces/udp-notifier/#sending-settings","title":"Sending settings","text":"Setting Description Send on direct change Whether to send a sync notification when state changed via the web UI or API Send on button press Whether to send sync when toggled by the physical hardware button Send Alexa notifications Whether to send sync after changed by Alexa (you may use Alexa groups instead) Send Hue notifications Whether to send sync after a connected Philips light changed Send Macro notifications Whether to send sync after a macro was triggered Send notifications twice Sends notifications twice (if you have issues with UDP packet loss) The quick toggle in the main UI will only apply to direct changes (UI + API), all other sync type sending behavior remains unaffected.
You can easily group WLED devices (for example all in one room) by changing the UDP port of all devices you want in that group.
"},{"location":"interfaces/udp-notifier/#sync-groups","title":"Sync groups","text":"From v0.13.0, 8 Sync groups are available. This allows syncing select instances only without changing the UDP port. For example, you might use one sync group per room you use WLED devices in. Make sure the sender and receiver you want to sync both have the same sync group ticked (a sender can send to multiple groups and a receiver can listen to multiple groups).
Sync packets received from pre-0.13.0 instances are treated as if sent in sync group 1 only.
"},{"location":"interfaces/udp-notifier/#protocol-description","title":"Protocol description","text":"Warning
Note: this info is partly out of date, see updated functionality in the code (udp.cpp)
When enabled, the module where a value was changed will send an UDP broadcast to a port (default 21324). Other modules that listen on this port will set themselves to the same color.
For interoperability, the protocol was designed so that even modules with different WLED versions can sync. Therefore, if a WLED 0.4 system receives a WLED 0.3 UDP notification it will apply the primary color but keep its current secondary color.
The UDP packet is currently 24 bytes long. It is laid out in the following:
Byte Index Var Name Description Notifier Version 0 - Packet Purpose Byte* 0 1 callMode Packet Reason** 0 2 bri Master Brightness 0 3 col[0] Primary Red Value 0 4 col[1] Primary Green Value 0 5 col[2] Primary Blue Value 0 6 nightlightActive Nightlight running? 0 7 nightlightDelayMins Nightlight Time 0 8 effectCurrent Effect Index 0 9 effectSpeed Effect Speed 0 10 white Primary White Value 1 11 - Version Byte*** 1 12 colSec[0] Secondary Red Value 2 13 colSec[1] Secondary Green Value 2 14 colSec[2] Secondary Blue Value 2 15 whiteSec Secondary White Value 2 16 effectIntensity Effect Intensity 3 17 transitionDelay Transition Duration Upper 4 18 transitionDelay Transition Duration Lower 4 19 effectPalette FastLED palette 5 20-23 - Zeros - *The notifier protocol is only used if this byte is 0. Otherwise, one of the UDP Realtime protocols will be used.
**The callMode variable specifies the reason for the notification. Every color update has the potential to trigger a notification.
callMode Description Behavior 0 Initial Boot Do not notify 1 Direct Change via UI or API notifyDirect? 2 Button was pressed notifyButton? 3 Update by other notification Do not notify 4 Nightlight activated notifyDirect? 5 Other (Req. with &NN) Do not notify 6 Effect changed notifyDirect? 7 Hue light changed notifyHue? 8 Preset Cycle active notifyDirect? 9 Updated via Blynk notifyDirect? ***This is the version of the UDP protocol.
UDP Version Description WLED Version 0 Basic Support 0.3 1 White Value supported 0.4p 2 Secondary Color supported 0.4 3 Effect Intensity supported 0.5.0 4 Transition Time supported 0.6.0 5 Palettes supported 0.8.0"},{"location":"interfaces/udp-realtime/","title":"UDP Realtime / tpm2.net","text":""},{"location":"interfaces/udp-realtime/#hyperion","title":"Hyperion","text":"You can now use WLED with the popular Ambilight software Hyperion. Just configure Hyperion to use an UDP device with protocol 0 on port 19446! The maximum number of LEDs supported in this mode is 490. (WLED 0.8.0 and lower: 341)
"},{"location":"interfaces/udp-realtime/#prismatik","title":"Prismatik","text":"Prismatik is another Ambilight option. Select one of the UDP options in the device configuration wizard.
"},{"location":"interfaces/udp-realtime/#tpm2net","title":"TPM2.NET","text":"Supported in latest master and will be available in WLED 0.10.1. Please set the WLED broadcast UDP port to 65506 in Sync settings to enable receiving TPM2.NET data.
"},{"location":"interfaces/udp-realtime/#udp-realtime","title":"UDP Realtime","text":"Additionally, WLED offers a way to directly drive the connected LEDs via UDP. The protocol is referred to as WLED Audio-Reactive-Led-Strip (WARLS), since the support of that project was its primary goal. However, it can also be used for other realtime applications like an ambilight.
WARLS uses the same UDP port the notifier uses (default 21324, can be changed in settings). At the moment, the web UI will be disabled while active, the HTTP API, Alexa and button control remains functional. It uses the current brightness and gamma correction settings.
Byte 0 of the UDP packet tells the server which realtime protocol to use.
Value Description Max. LEDs 1 WARLS 255 2 DRGB 490 3 DRGBW 367 4 DNRGB 489/packet 0 WLED Notifier - In every protocol, Byte 1 tells the server how many seconds to wait after the last received packet before returning to normal mode, in practice you should use 1-2 (seconds) here in most cases so that the module returns to normal mode quickly after the end of transmission. Use 255 to stay on the UDP data without a timeout until a request is requested via another method.
After this the LED color information is transmitted like this:
WARLS
Byte Description 2 + n*4 LED Index 3 + n*4 Red Value 4 + n*4 Green Value 5 + n*4 Blue Value DRGB: This mode has the difference that the LED indices are not part of the packet, instead every LED is updated. This leads to a higher speed when all LEDs are changed, but a drastically lower speed if only one LED is updated per packet.
Byte Description 2 + n*3 Red Value 3 + n*3 Green Value 4 + n*3 Blue Value DRGBW: Like DRGB, but supports the White value for RGBW strips.
Byte Description 2 + n*4 Red Value 3 + n*4 Green Value 4 + n*4 Blue Value 5 + n*4 White Value DNRGB: DRGB, but with 2 additional bytes that signify the starting LED index. This allows for more than 490 LEDs in realtime mode by sending multiple packets.
Byte Description 2 Start index high byte 3 Start index low byte 4 + n*3 Red Value 5 + n*3 Green Value 6 + n*3 Blue Value When realtime mode starts, all LEDs will be black. However, you don't have to change all LEDs using one packet. Changing a single LED therefore only requires a packet of 2+4 bytes. All LEDs maintain their color until it is changed or the module exits WARLS mode because of a timeout.
"},{"location":"interfaces/udp-realtime/#setup-with-arls","title":"Setup with ARLS","text":"The software now supports audio-reactive-led-strip!
- Download audio-reactive-led-strip and follow its installation instruction. You can also use my (untested) fork. In that case, you can skip step 2.
- Insert the following code in led.py after line 66: m.append(1); m.append(2); These are the first two bytes of the protocol.
- In config.py set your led amount, ESP IP and WLED UDP notifier port. For FPS, a setting between 15-30 is recommended.
- Run visualization.py! If you have a low amount of LEDS (e.g. 10) try lowering the sigma values in line 129-131.
- If you have multiple WLED devices, you can sync them all with music. Use the led count of your largest device and set the IP to X.X.X.255 (UDP broadcast). You can adjust the position of the amplitude with the WARLS offset setting. Note that web control currently does not work while it is active.
"},{"location":"interfaces/websocket/","title":"WebSocket","text":"Version Info
Since WLED 0.10.2, a WebSocket server is enabled by default and can be used to access a subset of the JSON API.
The server is available at the /ws endpoint, you can access it like ws://[WLED-IP]/ws.
You may send any JSON state update to the socket. On change of the lighting state, the server will send a JSON object containing the state and info objects (this is equivalent to HTTP GET /json/si) to all connected clients. This object will also be sent to a client upon connecting.
You can also request a live stream of the LED values (e.g. the \"Peek\" feature of WLED-UI) by sending {\"lv\":true} to the websocket. The returned format is the same as for /json/live. Only one client can receive this at a time, if a new client requests it the stream will stop for the previous client (but the websocket will stay connected).
There can be a maximum of 4 clients connected at a time. If a fifth client connects, a different client will be disconnected. On ESP8266, it is recommended to have no more than 2 clients connected simultaneously.
"},{"location":"interfaces/json-ir/json_infrared/","title":"Infrared","text":"Version Info
Since v0.13.0, infrared control for any IR remote compatible with your IR receiver with JSON remote.
A dedicated infrared receiver module is required. (KY-022 or TSOP38238 are confirmed to work and inexpensive)
The default sensor pin is GPIO4. It can be changed in the WLED settings.
"},{"location":"interfaces/json-ir/json_infrared/#json-ir-remote","title":"JSON IR Remote","text":"The JSON IR remote allows users to customize IR remote behavior without writing custom C code or compiling. Using the JSON IR remote, you can map buttons from any compatible remote to any HTTP request API or JSON API command.
The map of IR codes to API commands is stored on your ESP's file system in ir.json. From the \"LED Preferences\" page, set the IR pin and remote type to \"JSON remote\". Once \"JSON remote\" is selected, a file upload control will appear. You can also upload and edit ir.json from the /edit page, which can be reached by going to http://[controller-ip]/edit. If you use the edit page to upload your config file, be sure to name it ir.json.
"},{"location":"interfaces/json-ir/json_infrared/#preconfigured-remotes","title":"Preconfigured Remotes","text":"LED remotes typically are not sold separately. But you can purchase with an RGB controller for $2-4 on AliExpress and $5-10 on Amazon. When purchasing a remote, be sure that it is an infrared (IR) remote and not a radio (RF) remote as they are not supported at this time.
44-key white ir.json
40-key blue ir.json
40-key black ir.json
38-key ir.json (Sold with WLED compatible SP511E controllers)
32-key ir.json (commonly sold with fairy string lights)
24-key (very common, but buttons need repurposed to be very useful with WLED) ir.json v1 gray buttons load presets 1-4 ir.json v2 gray buttons cycle effects, palettes and change speed
24-key grey ir.json
24-key music ir.json v3
21-key ir.json
18-Key Silver ir.json
6-key ir.json
"},{"location":"interfaces/json-ir/json_infrared/#editing-irjson","title":"Editing ir.json","text":"First see if a JSON file already exists for your remote. If not, see if there is a JSON file for a remote with the same number of buttons. Often remotes with the same number of buttons have different labels but emit the same codes. The JSON keys are the hex encoded IR codes emitted by each button. The keys are strings and case is important, be sure to use the same format as the sample below. It is also the same format used when codes are echoed on the serial console.
In the JSON document, each button object should have a cmd attribute containing the HTTP request or JSON API command. In addition to HTTP and JSON API commands, several C functions are supported (!incBrightness, !decBrightness, !presetFallback). The !incBrightness and !decBrightness functions, take smaller steps at the dim end of the range with progressively larger steps at the bright end. The !presetFallback function applies a preset (attribute PL) and falls back to the specified effect and palette (attributes FX and FP) if preset does not exist. (see sample below)
If an IR remote button is pressed rapidly or held down, subsequent presses have a different code (0xFFFFFFFF). If your command is repeatable but does not contain the \"~\" character and is not calling incBrightness or decBrightness, then add a \"rpt\" attribute with a value of true. Label and position attributes are ignored by WLED but useful when making edits.
If an ir.json file does not already exist for your remote, you will need to determine what code each button emits. To do this, connect your ESP8266 or ESP32 to a computer and open Arduino or VSCode serial monitor. Then press each button and record the code printed on the serial monitor. You should see something like this:
IR recv\n0xFFDE10\n
You should get a 24-bit hex encoded integer. If you get 0xFFFFFFFF, that means the button has been pressed repeatedly or held down. Try tapping quickly.
"},{"location":"interfaces/json-ir/json_infrared/#tips","title":"Tips","text":" - Map
play or auto buttons to a playlist. They currently just turn on preset cycling CY=1 or load a playlist of presets 1-5. You can define the playlist in ir.json as in the sample below, or save a playlist as a preset and load that. - Save your 'every day' presets in one range of ids, maybe 1-30; your 'holiday' presets in another range, maybe 31-40. Then you can devote two buttons to cycle through presets. In our example, the command on the 'holiday cycle' button would be
P1=31&P2=40&PL=~ - You can also group your presets by color; for instance reddish animations in 1-10, greenish in 11-20, bluish in 21-30. The 44-key remote has up and down arrows for red, green and blue. So the command on the 'blue down' button would be
P1=21&P2=30&PL=~- - Most of the 24-key and fewer remotes are designed with analog LEDs in mind and do not have very useful labels for WLED. With JSON IR and a fine-tip Sharpie, you can repurpose buttons to make them more useful.
"},{"location":"interfaces/json-ir/json_infrared/#irjson-sample","title":"ir.json sample","text":"{\n\"0xF740BF\": {\n\"label\": \"On/Off\",\n\"cmd\": \"T=2\",\n\"rpt\": true\n},\n\"0xF700FF\": {\n\"label\": \"Speed +\",\n\"cmd\": \"SX=~16\"\n},\n\"0xF720DF\": {\n\"label\": \"Red\",\n\"cmnt\": \"Lava palette + primary, secondary and tertiary colors\",\n\"cmd\": \"FP=8&CL=hFF7F00&C2=hFF0000&C3=hCC3D60\"\n}, \"0xF710EF\": {\n\"label\": \"Timer1\",\n\"cmnt\": \"Timer 60 min\",\n\"cmd\": \"NL=60&NT=0\"\n},\n\"0xF730CF\": {\n\"label\": \"Play\",\n\"cmnt\": \"prime example of a playlist that cycles every 180 seconds and continues to repeat\",\n\"cmd\": {\"playlist\":{\"ps\":[1,3,5,7,11,13,17],\"dur\": 1800,\"transition\":7,\"repeat\":0,\"end\":0}}\n}, \"0xFF9867\": {\n\"label\": \"Bright+\",\n\"cmnt\": \"smaller steps at beginning, larger steps at the end\",\n\"cmd\": \"!incBrightness\"\n},\n\"0xF78877\": {\n\"label\": \"DIY1\",\n\"cmnt\": \"Preset 1, fallback to Saw(16) - Party(6) if it doesn't exist\",\n\"cmd\": \"!presetFallback\",\n\"PL\": 1,\n\"FX\": 16,\n\"FP\": 6\n},\n}\n
"}]}
\ No newline at end of file
+{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"Welcome to WLED","text":""},{"location":"#welcome-to-my-project-wled","title":"Welcome to my project WLED! \u2728","text":"A fast and feature-rich implementation of an ESP8266/ESP32 webserver to control NeoPixel (WS2812B, WS2811, SK6812) LEDs or also SPI based chipsets like the WS2801 and APA102!
"},{"location":"#features","title":"\u2699\ufe0f Features","text":" - WS2812FX library integrated for over 100 special effects
- FastLED noise effects and 50 palettes
- Modern UI with color, effect and segment controls
- Segments to set different effects and colors to parts of the LEDs
- Settings page - configuration over network
- Access Point and station mode - automatic failsafe AP
- Up to 3 LED outputs per ESP8266 instance and 10 LED outputs per ESP32 instance
- Support for RGBW strips
- Up to 250 user presets to save and load colors/effects easily, supports cycling through them.
- Presets can be used to automatically execute API calls
- Nightlight function (gradually dims down)
- Full OTA software updatability (HTTP + ArduinoOTA), password protectable
- Configurable analog clock + support for the Cronixie kit by Diamex
- Configurable Auto Brightness limit for safer operation
- Filesystem-based config for easier backup of presets and settings
- Native Home-Assistant integration:
"},{"location":"#supported-light-control-interfaces","title":"\ud83d\udca1 Supported light control interfaces","text":" - WLED app for Android and iOS
- JSON and HTTP request APIs
- MQTT
- Blynk IoT
- E1.31, Art-Net, DDP and TPM2.net
- Hyperion
- UDP realtime
- Alexa voice control (including dimming and color)
- Sync to Philips Hue lights
- Adalight (PC ambilight via serial) and TPM2
- Sync color of multiple WLED devices (UDP notifier)
- Infrared remotes (24-key RGB, receiver required)
- Simple timers/schedules (time from NTP, timezones/DST supported)
"},{"location":"#quick-start-guide-and-documentation","title":"\ud83d\udcf2 Quick start guide and documentation","text":"See the getting started page!
On this page you can find excellent tutorials made by the community and helpful tools to help you get your new lamp up and running!
"},{"location":"#user-interface","title":"\ud83d\uddbc\ufe0f User interface","text":""},{"location":"#compatible-hardware","title":"\ud83d\udcbe Compatible hardware","text":"See here!
"},{"location":"#other","title":"\u270c\ufe0f Other","text":"Licensed under the MIT license Credits here!
Join the Discord server to discuss everything about WLED!
Check out the WLED Discourse forum! You can also send me mails to dev.aircoookie@gmail.com, but please only do so if you want to talk to me privately. If WLED really brightens up your every day, you can
Disclaimer
If you are sensitive to photosensitive epilepsy it is not recommended that you use this software. In case you still want to try, don't use strobe, lighting or noise modes or high effect speed settings. As per the MIT license, I assume no liability for any damage to you or any other person or equipment.
"},{"location":"about/contributors/","title":"Contributors and Credits","text":"This page is to honor the work of all the people who helped to make WLED what it is today!
"},{"location":"about/contributors/#direct-contributors-to-wled-code","title":"Direct Contributors to WLED code","text":"Everyone you see on the Contributors page and: 8bitbrett made the WiFi auto connect QR code with the Aircoookie/WLED logo! adamo made the animated Discord server logo! @blazoncek makes countless new features and improvements to many parts of WLED! @debsahu provided the HomeAssistant autodiscovery and a lot of help with PIO! @frenck made an amazing, stable and feature-packed native integration with HomeAssistant! @photocromax is helping bringing the Live visualization feature to life and added GIF previews to the doc! @raymiec is currently working on creating the best clients for Android and iOS! @StormPie, the creator of the awesome mobile UI! @timothybrown added MQTT authentication! @viknet365 ported the Meteor effect! @wiesendaniel added the configuration for the PlatformIO IDE! @YeonV provided the initial HomeAssistant MQTT light config! This list is incomplete.
"},{"location":"about/contributors/#testing-contributors-and-supporters","title":"Testing, Contributors and Supporters","text":"This list has been redacted for privacy reasons. If you've contributed to the project by testing a lot, helping the community, or sending me a gift, feel free to edit this page and add yourself (maintain alphabetical order) \ud83d\ude04 Thank you very much, your help is truly appreciated! Put two spaces behind your name, else the line break will not appear in the final page!
@Def3nder @DutchmanNL DrZzs (Justin A.) Dylan L. Fil Quindor (Andries F.) Tonyno
"},{"location":"about/contributors/#used-libraries-and-dependencies","title":"Used Libraries and Dependencies","text":"ESP8266/ESP32 Arduino Core NeoPixelBus by Makuna FastLED library ESPAsyncTCP by me-no-dev ESPAsyncUDP by me-no-dev (as of 0.9.0) ESPAsyncWebServer by me-no-dev ArduinoJSON by bblanchon async-mqtt-client by marvinroger WS2812FX by kitesurfer1404 (modified) IRremoteESP8266 by markszabo (optional) Timezone by JChristensen Blynk library (compacted) E1.31 library by forkineye (modified) Espalexa by Aircoookie (modified) Many included FastLED effects are modified versions of kriegsman's gists!
WLED implements Art-Net\u2122 Designed by and Copyright Artistic Licence Holdings Ltd
WebServer_tng by bbx10 (ESP32, up to 0.8.3) PubSubClient by knolleary (modified, up to 0.8.3)
iro.js colorpicker by James Daniel! Classic UI icons by Linearicons created by Perxis!
If you would like to appear in this list for a contribution you made or be removed from it, feel free to contact me!
"},{"location":"about/privacy-policy/","title":"Privacy Policy","text":"By using the WLED embedded system code, the WLED iOS mobile application, the WLED Android mobile application, web client, or associated Services, no personally identifiable data is collected, transmitted and/or stored on external servers. No data is processed in any way not absolutely required for the operation of the Service.
This https://kno.wled.ge page is hosted using GitHub Pages. While the author of this page does not collect any personally identifiable data, the service provider GitHub \"may collect User Personal Information from visitors to [the] GitHub Pages website, including logs of visitor IP addresses, to comply with legal obligations, and to maintain the security and integrity of the Website and the Service.\" (https://docs.github.com/en/github/site-policy/github-privacy-statement#github-pages) This is outside the influence of the author.
"},{"location":"about/privacy-policy/#overview-of-collected-data","title":"Overview of collected data","text":"The embedded system internally stores configuration data, including, but not limited to the user's WiFi credentials. This data is deletable by the user. External read access to sensitive data is blocked. No user or configuration data is sent to any system outside the users local network, unless the user modifies the Software or network configuration.
The mobile apps internally store data regarding connected devices, including, but not limited to the device's network-local IP addresses.
Using the provided Support services (including, but not limited to GitHub, Discord and E-mail), only the information you choose to disclose will be processed. Privacy policies and Terms of Service of service providers apply.
In accordance with the Service MIT license, THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
If you have inquiries regarding this Policy please feel free to contact me at: dev.aircoookie@gmail,com
"},{"location":"about/roadmap/","title":"Upcoming Features","text":"These are currently on my list of what COULD be implemented, there is no guarantee if and when they will be available!
- Create named playlists of presets
- Custom color palettes
- Settings pages overhaul
- Rework of WiFi connection logic (reconnect after WiFi or power outage)
"},{"location":"advanced/audio-reactive/","title":"Audio Reactive WLED","text":""},{"location":"advanced/audio-reactive/#what-is-audio-reactive-wled","title":"What is Audio Reactive WLED?","text":"Audio Reactive WLED is a possibility of using WLED controllers in such a way that the LEDs react to music and light up in time. First time this was implemented by a Sound Reactive Fork. As of WLED version 0.14.0-beta1 an usermod is available for original WLED too. Currently only ESP32 microcontrollers are supported.
"},{"location":"advanced/audio-reactive/#hardware-required","title":"Hardware required","text":"The audio must be \"feed\" into the microcontroller. There are basically two options: using microphones or line-in adapters.
"},{"location":"advanced/audio-reactive/#microphones-supported","title":"Microphones supported","text":"Three microphone types are supported:
"},{"location":"advanced/audio-reactive/#1-analog-microphones","title":"1. Analog microphones","text":"Examples are MAX4466 (not really good) and MAX9814 (slightly better). These microphones are easy to use: you just have to connect 3.3V, GND and the analog output from the microphone to an ADC input (Analog-to-Digital Converter) of ESP32. However, the big disadvantage is the quality: both from the microphones themselves and from the ADCs integrated into microcontrollers, which are actually not well suited for audio processing and highly influenced by the power supply noise.
"},{"location":"advanced/audio-reactive/#2-i2s-digital-microphones","title":"2. I2S digital microphones","text":"Examples are INMP4411 and ICS-43434/ICS-43432. These have an integrated ADC and already output a digital signal. The advantage is the best possible quality. The disadvantage is higher complexity (you need several PINs for a digital signal). For proper trouble-free operation keep wires between the microphone and ESP32 as short as possible and solder them properly.
There are also some commercial controllers with integrated digital microphone or plug-in capability available. Be sure to setup correct GPIOs according to the information you typically will find printed on the board or in user manual.
"},{"location":"advanced/audio-reactive/#3-pdm-microphones","title":"3. PDM microphones","text":"An example is SPM1423. In principle, these are also digital microphones with an integrated Sigma-Delta ADC. They are slightly cheaper than I2S microphones, require one PIN less and the quality is quite good.
"},{"location":"advanced/audio-reactive/#line-in-options","title":"Line-In options","text":"Similar to microphones there ara options for analog or digital line-in adapters. In both cases you use line-out (AUX) or headphone-out signal of your sound system/TV/Smartphone/etc.
"},{"location":"advanced/audio-reactive/#1-analog-line-in-option","title":"1. Analog line-in option","text":"At least a simple analog circuit as shown below is required to prepare the analog line-out signal and to feed it to the ADC converter of ESP32 microcontroller. In this case, the whole thing works like with an analog microphone. The quality is not the best here either because the ESP32 ADC is not particularly good at converting audio signals and the signal conditioning circuitry is very simple, but not very good. In addition, the sensitivity can be quite poor, so that the whole thing only works at a higher volume of the signal.
In some cases, you can do it without this circuit and connect the GND of the audio source and an audio channel (left or right) directly to ESP32 ADC Pin (GND and analog input, e.g. GPIO36 pin on the ESP32). This solution is rather quite dirty workaround and might work well or not at all.
"},{"location":"advanced/audio-reactive/#2-line-in-to-i2s-adapter","title":"2. Line-in to I2S adapter","text":"Line-in to I2S adapter converts the analog line-out or headphone signal into a digital I2S signal that can be proceed by ESP32. There are some general or for WLED specially developed analog-to-I2S adapters based on for example CirrusLogic CS5343, TI PCM1808 or es7243 chips on the market. In this case, the whole thing works like with a digital I2S microphone. The only difference to I2S microphone is that you at least need an extra PIN for MCLK (Master Clock) signal, which can only be generated by the ESP32 on GPIOs 0, 1 or 3. The other complication is that MCLK is a high frequency signal and must be wired extremely accurate and have short wires. Some adapter types also require more additional signals. For stability it is better to use ready-to-use controller with special Line-In to I2S adapter or DIY PCB design where you can integrate general analog-to-I2S adapter directly without long wires.
For some more details please refer to Sound Reactive WLED WIKI
"},{"location":"advanced/audio-reactive/#software-required","title":"Software required","text":"Because audio reactive capability is currently implemented as a usermod, you need WLED compiled with this usermod included or use Sound Reactive WLED fork. The official WEB-based WLED installer does not include original WLED with audio reactive usermod, but offers Sound Reactive WLED as an option. The unofficial WEB-based WLED installer offers more options including original WLED with audio reactive usermod.
"},{"location":"advanced/compile-analog/","title":"Compile Analog WLED","text":"Moved, see How to compile WLED
"},{"location":"advanced/compile-wled/","title":"Compile WLED","text":"Moved, see How to compile WLED
"},{"location":"advanced/compiling-wled/","title":"Compiling WLED","text":"You want to add custom features to WLED, use non-default pins, or add in a usermod? You've found the right place!
WLED has come to rely on so many dependencies in the latest versions that building with the Arduino IDE is no longer recommended. Instead, installing Visual Studio Code and its PlatformIO (PIO) extension is easier, as it will install the ESP Arduino core, all the required libraries and the correct compilation settings for you automatically.
"},{"location":"advanced/compiling-wled/#installation-guide-platformio-recommended","title":"Installation guide (PlatformIO, recommended)","text":" - Make sure Git client is installed on your system. If it isn't, you can get it here.
- Download and install the free Visual Studio Code by Microsoft.
- Open VS Code and go to the Extensions manager (the icon with the stacked blocks in the left bar)
- Search for
platformio ide and install the PlatformIO extension -
Download the WLED source code by executing git clone https://github.com/Aircoookie/WLED.git in some folder. (You can also use GitHub Desktop or download the latest source code from https://github.com/Aircoookie/WLED under the Code dropdown menu as a .zip file.) Alternatively fork the WLED project first and download it from your fork.
-
Go to File -> Open Folder and open that root WLED folder (the one that contains platformio.ini, NOT the wled00 folder)
"},{"location":"advanced/compiling-wled/#compilation-guide-platformio","title":"Compilation guide (PlatformIO)","text":"Tip
Make sure Git Client is installed on your system. You can get it here.
- In VS Code, open the file
platformio.ini. - Add a semicolon in front of the line that says
default_envs = travis_esp8266, travis_esp32 to comment it out. - Select your build environment by un-commenting one of the lines starting with
; default_envs =. Please remove BOTH the ; and the whitespace behind it to correctly uncomment the line. For most ESP8266 boards, the d1_mini environment is best. - In the blue bottom bar, hit the checkmark to compile WLED or the arrow pointing right to compile and upload!
Picture Guide
Success!
If you get one of these two errors, hit the checkmark icon once again to compile and that time the code should build without problems!
error: wled00\\wled00.ino.cpp: No such file or directoryFileNotFoundError: [WinError 2] The system cannot find the file specified: '[...].sconsign37.dblite'
"},{"location":"advanced/compiling-wled/#making-a-custom-environment","title":"Making a custom environment","text":"Once you've confirmed VSCode with Platformio is set up correctly, you can add/define overrides to allow you to use non-default pins, add a usermod, or add other custom features.
- Copy and paste the contents of
platformio_override.ini.sample into a new file called platformio_override.ini. Make sure platformio_override.ini is in the same folder as platformio.ini. - Replace the line
default_envs = WLED_tasmota_1M with the line you uncommented in platformio.ini in the previous steps (from Compilation guide (PlatformIO)). Example: default_envs = d1_mini - In
platformio.ini scroll down until you see #-------------------- # WLED BUILDS #-------------------- - Find the section that matches the build environment you selected in previous steps. Example:
[env:d1_mini] - Select the whole section (including the first line in brackets [ ] ), and copy and paste it into
platformio_override.ini overwriting the build environment section that was already there. - Add a new line under the the line that starts with
build_flags = - Put your
-D overrides on this new line, giving each -D it's own new line. - Compile your freshly customized WLED image!
"},{"location":"advanced/compiling-wled/#flashing-the-compiled-binary","title":"Flashing the compiled binary","text":"Tip
This step is optional and only recommended if you want to install the same binary to multiple boards. For testing, it is easiest to upload directly from PlatformIO
The .bin file is located in the subfolder /build_output/firmware in your WLED folder. The binary will have the same name as your environment.
All that's left to do is flash this .bin file onto your ESP board and then connect it to WiFi.
"},{"location":"advanced/compiling-wled/#compilation-guide-arduino-ide-not-recommended","title":"Compilation guide (Arduino IDE, not recommended)","text":"Warning
This method is outdated. The source is no longer officially checked to be buildable with the Arduino IDE. Using PlatformIO is strongly advised.
-
Follow a guide to setup your Arduino IDE (I am using version 1.8.9) with the ESP8266 libraries. For current compiles I recommend the latest Arduino core version 2.7.4. If you do not wish to install all libraries manually it is recommended to download the PlatformIO extension for VS Code (see above).
-
You will need to install a few libraries:
Library Name Platform NeoPixelBus (2.6.0) All FastLED All ESPAsyncWebServer Aircoookie fork (2.0.0) All IRRemoteESP8266 All ESPAsyncTCP ESP8266 only ESPAsyncUDP ESP8266 only AsyncTCP for ESP32 ESP32 only LITTLEFS_esp32* ESP32 only * Please see the installation guide. You might need to enable a define in the library code.
All other dependencies are included with WLED for convenience.
- Now compile and flash the software! Make sure you erase everything when you flash! (If your board config does not provide this option, you can
Sketch -> Export compiled Binary and upload with any ESP flashing tool.)
"},{"location":"advanced/compiling-wled/#compilation-settings-arduino-ide","title":"Compilation settings (Arduino IDE)","text":"ESP8266:
- Arduino Core v2.7.4
- Board: NodeMCU 1.0 (ESP-12E module) (or select your ESP board)
- CPU frequency: 80 MHz
- Flash size : 4MB (1MB SPIFFS)
- LwIP variant: v1.4 Higher Bandwidth (try 2 if you experience issues)
- Upload speed: Any, 921600 recommended
ESP8266-07 (External Antenna):
- Variants have 512kB or 1MB flash
- Be sure to use DOUT mode when flashing
- Flash Size 1MB (128k SPIFFS)
- 512kB variant no longer compatible
ESP-07s (External Antenna):
- Variant has 4MB flash
- Settings as for NodeMCU or Wemos
ESP32:
"},{"location":"advanced/custom-ap/","title":"Custom Access Point SSID and Password","text":"Warning
Note: These options change the documented access point name and password. The WLED community does not recommend changing these settings unless you are familiar with the risks.
Three compile time defines are available to modify the access point name. These are WLED_AP_SSID, WLED_AP_PASS, and WLED_AP_SSID_UNIQUE. Defining WLED_AP_SSID will set the SSID to the value of the define. Defining WLED_AP_PASS will set the password to the value of the define. Defining WLED_AP_SSID_UNIQUE will append the last 6 digits of the MAC address to the SSID.
WLED_AP_SSID and WLED_AP_PASS are string values, and as such need to be defined with \" surrounding them. For example, #define WLED_AP_SSID \"MyWLED\" or -D WLED_AP_SSID='\"MyWLED\"' in the build_flags of platformio.ini.
"},{"location":"advanced/custom-ap/#modifying-the-access-point-ssid","title":"Modifying the Access Point SSID","text":"Defining WLED_AP_SSID will set the SSID to the value of the define. This is useful to set a device specific access point name. For example, if you have multiple WLED devices, you can set the SSID to the device name.
WLED_AP_SSID is a string value, and as such needs to be defined with \" surrounding it. For example, #define WLED_AP_SSID \"MyWLED\" or -D WLED_AP_SSID='\"MyWLED\"' in the build_flags of platformio.ini.
"},{"location":"advanced/custom-ap/#modifying-the-access-point-password","title":"Modifying the Access Point Password","text":"Defining WLED_AP_PASS will set the password to the value of the define. This is useful to set a device specific access point password. For example, if you have multiple WLED devices, you can set the password to the device name.
Tip
If WLED_AP_PASS is defined, but WLED_AP_SSID is not, the compilation will fail. Ensure you define both WLED_AP_SSID and WLED_AP_PASS if you wish to change the access point password. Please also change the SSID if you wish to set a custom password.
WLED_AP_PASS is a string value, and as such needs to be defined with \" surrounding it. For example, #define WLED_AP_PASS \"MyWLEDPass\" or -D WLED_AP_PASS='\"MyWLEDPass\"' in the build_flags of platformio.ini.
"},{"location":"advanced/custom-ap/#modifying-the-access-point-ssid-to-be-unique","title":"Modifying the Access Point SSID to be Unique","text":"Defining WLED_AP_SSID_UNIQUE will append the last 6 digits of the MAC address to the SSID. This is useful to set a device specific access point name with a common prefix. For example, if you have multiple WLED devices, you can set the SSID to ChristmasTree- followed by the last 6 digits of the MAC address.
WLED_AP_SSID_UNIQUE is a boolean value, and as such only needs to be defined or not. For example, #define WLED_AP_SSID_UNIQUE or -D WLED_AP_SSID_UNIQUE in the build_flags of platformio.ini.
"},{"location":"advanced/custom-ap/#example","title":"Example","text":"For custom devices in platformio_override.ini:
[env:mywled]\nboard = esp32dev\nplatform = ${esp32.platform}\nplatform_packages = ${esp32.platform_packages}\nbuild_unflags = ${common.build_unflags}\nbuild_flags =\n${common.build_flags_esp32}\n-D WLED_AP_SSID_UNIQUE\n-D WLED_AP_SSID='\"MyWLED\"'\n-D WLED_AP_PASS='\"MyWLEDPass\"'\nlib_deps = ${esp32.lib_deps}\nmonitor_filters = esp32_exception_decoder\nboard_build.partitions = ${esp32.default_partitions}\n
In my_config.h:
#define WLED_AP_SSID_UNIQUE\n#define WLED_AP_SSID \"MyWLED\"\n#define WLED_AP_PASS \"MyWLEDPass\"\n
"},{"location":"advanced/custom-features/","title":"Custom Features","text":"Warning
Note: this page is now out of date, see updated functionality in the code (WLED/usermods/EXAMPLE_v2)
This page is intended for those wishing to modify the WLED code to add their own functionality.
"},{"location":"advanced/custom-features/#basics","title":"Basics","text":"Programming is done in the Arduino IDE. There is a special file, usermod.cpp, to write your own code. (however, if you think your code may be relevant to many users, feel free to code it in directly and open a pull request)
This file has three empty methods: - userSetup() is called after loading settings but before connecting to WiFi. Use it to start own interfaces if it does not depend on WiFi (IR, Sensors, GPIOs,...). Also you can use it to load custom settings or to specify own server pages with the server.on() method. - userConnected() is called once WiFi is connected. Use it to connect to external servers or init interfaces using wiFi. - userLoop() is called by the main loop() function.
"},{"location":"advanced/custom-features/#modify-wled-values","title":"Modify WLED values","text":"If you know what you're doing, you may choose to change the value of any global variable declared in wled.h. However, for basic color and brightness changes, these are the most important:
Variable Name Type Purpose bri byte (0-255) Master Brightness (0 is off, 255 is maximum) col[0] byte (0-255) Red color value col[1] byte (0-255) Green color value col[2] byte (0-255) Blue color value col[3] byte (0-255) White color value After updating the color, you must call the colorUpdated(int) method. If you want to send a notification with the new color to other ESPs, use colorUpdated(NOTIFIER_CALL_MODE_DIRECT_CHANGE), otherwise colorUpdated(NOTIFIER_CALL_MODE_NO_NOTIFY).
"},{"location":"advanced/custom-features/#timing","title":"Timing","text":"If you'd just like a simple modification that requires timing (like sending a request every 2 seconds), please never use the delay() function in your userLoop()! It will block everything else and WLED will become unresponsive and effects won't work! Instead, try this instead:
long lastTime = 0;\nint delayMs = 2000; //we want to do something every 2 seconds\n\nvoid userLoop()\n{\nif (millis()-lastTime > delayMs)\n{\nlastTime = millis();\n//do something you want to do every 2 seconds\n}\n}\n
"},{"location":"advanced/custom-features/#internal-segments-api","title":"Internal Segments API","text":"You can use Segments from your code to set different parts of the strip to different colors or effects. This can be very useful for highly customized installations, clocks, ...
To set a segment, use strip.setSegment(id, start, stop);, where id is the segment ID, start is the first LED of the segment and stop is the LED after the last one in the segment.
To edit the configuration of a segment, use:
WS2812FX::Segment& seg = strip.getSegment(id);\n//set color (i=0 is primary, i=1 secondary i=2 tertiary)\nseg.colors[i] = ((myWhite << 24) | ((myRed&0xFF) << 16) | ((myGreen&0xFF) << 8) | ((myBlue&0xFF)));\n//set effect config\nseg.mode = myFxI;\nseg.speed = mySpeed;\nseg.intensity = myIntensity;\nseg.palette = myPaletteId;\n
Keep in mind that this will not cause interface updates as of 0.8.6. For that, you still need to use colorUpdated(NOTIFIER_CALL_MODE_DIRECT_CHANGE)"},{"location":"advanced/custom-features/#create-custom-effects","title":"Create custom effects","text":"It is possible to create your own effects and add them to the FX library. The relevant files for that are FX.cpp and FX.h.
Here is a step-by-step guide on how to make your effect:
-
Take a look at some of the effects in FX.cpp to see how they are implemented!
-
Add your own routine in FX.cpp starting with: uint16_t WS2812FX::mode_custom
-
Add to total number of effects in FX.h line 110: #define MODE_COUNT
-
Add your mode number (ie#define FX_MODE_CUSTOM 110) in FX.h around line 200.
-
Add your mode around line 400 of FX.h, like so: _mode[FX_MODE_CUSTOM] = &WS2812FX::mode_custom;
-
Add it to the functions in FX.h around line 600:mode_custom(void),
-
Give it a name at the bottom (10 modes per line) in JSON_mode_names[]. Wrap your name in quotes just like the others.
-
Compile, upload and enjoy! Your new effect will automatically be added to the list in the web ui.
If you programmed a nice effect you want to share, submit a pull request!
"},{"location":"advanced/custom-features/#changing-web-ui","title":"Changing Web UI","text":"In order to conserve space, the Web UI interface is represented as a series of wled00/html_ui.h, wled00/html_settings.h and wled00/html_other.h files which contain C/C++ strings with specific parts of the Web UI.
These files are automatically created from source files available in wled00/data folder. To generate files, install NodeJS 11.0+ globally. After that, recreate html_*.h files by running in the repo directory:
> npm install\n> npm run build\n
If you want to test changes to the UI, it is easiest to work with the local wled00/data/index.htm file. You just need to enter the IP address of a WLED 0.10.0 or newer instance into the popup. If you accidentally input an incorrect IP or want to test with a different instance, clear the local storage (in Chrome: Developer Tools -> Application -> Local Storage)
If you continuously modify files in the wled00/data directory, you want to monitor these changes to make local html_*.h files being updated automatically. To do this, run this in repo directory:
> npm run dev\n
This will start monitoring wled00/data folder for changes. WARNING!! Be careful with changing the javascript in HTML files! For example function GetV() {} must be the last javascript function in the <script> element as it will be replaced by automatically generated code to fetch relevant settings from EEPROM. See tools/cdata.js for the replacement rules which run for every *.htm file in wled00/data.
Recompile and flash WLED!
"},{"location":"advanced/ddp/","title":"Virtual LEDs via DDP/ArtNet","text":""},{"location":"advanced/ddp/#overview","title":"Overview","text":"Virtual LEDs allow you to \"attach\" LEDs from multiple ESPs to a main, controlling ESP. These LEDs can be added to an ESP just like physical pins.
On the controlling ESP, go to Config, LED Preferences.
Select DDP RGB (Network) as the LED type and enter the Length (number of LEDs on that remote ESP), then enter the ESPs IP address.
Multiple remote ESP's can be setup this way.
Note: The controlling ESP must be running at least 0.13 firmware while the remotes can be older. As usual, best perfomance is obtained by using an ESP32 for the controlling device. You can use an ESP8266, but only with a small number of LEDs (<300).
Also, support was recently added for ArtNet virtual LEDs.
"},{"location":"advanced/esp32-recovery/","title":"ESP32 Recovery","text":"In Platformio IDE open a new terminal and type: pio run -v -t upload When you see the \"Connecting........\" abort the upload.
Below you can see Esptool commands, that was used by Platformio. Now you able to find all files that we need to build the binary (screenshot for visualization):
"},{"location":"advanced/home-automation/","title":"Home Automation Integration","text":"It is possible to interface WLED with home automation systems and other 3rd party software. You can use any API WLED provides (JSON, HTTP, UDP, MQTT), JSON is preferred. This page is intended for sample code and configs others use to control WLED from various 3rd party software:
HomeAssistant and NodeRED flows
"},{"location":"advanced/home-automation/#domoticz","title":"Domoticz:","text":"Please see here!
"},{"location":"advanced/home-automation/#home-assistant","title":"Home Assistant","text":""},{"location":"advanced/home-automation/#using-the-native-integration","title":"Using the native integration","text":"Compatibility notice
WLED devices are not supported by Home Assistant 2022.2 or later if a CCT bus is configured or White Balance Correction is enabled.
We hope to resolve this issue as soon as possible. As a temporary workaround you can enable the option Calculate CCT from RGB in LED settings.
WLED can be configured using the integrations in the Home Assistant frontend.
Menu: Configuration -> Integrations.
In most cases, the WLED devices will be automatically discovered by Home Assistant. Those automatically discovered WLED devices are listed on the integrations page.
If for some reason (e.g., due to lack of mDNS support on your network), the WLED device isn't discovered, it can be added manually.
Click on the + sign to add an integration and click on WLED. After completing the configuration flow, the WLED integration will be available.
WLED integration documentation
"},{"location":"advanced/home-automation/#using-mqtt","title":"Using MQTT","text":"Alternatively, MQTT can be used (not recommended). Auto discovery is no longer supported since version 0.9 of WLED. In case you want to configure the device manually:
Expand to show MQTT configuration light:\n - platform: mqtt\n name: \"Kitchen Floor Lights\"\n command_topic: \"wled/all\"\n brightness_command_topic: \"wled/all\"\n rgb_command_topic: \"wled/all/col\"\n rgb_command_template: \"{{ '#%02x%02x%02x' | format(red, green, blue)}}\"\n effect_command_topic : \"wled/all/api\"\n effect_list:\n - \"FX=0\"\n - \"FX=1\"\n - \"FX=2\"\n - \"FX=3\"\n - \"FX=4\"\n - \"FX=5\"\n - \"FX=6\"\n - \"FX=7\"\n - \"FX=8\"\n - \"FX=9\"\n - \"FX=10\"\n - \"FX=11\"\n - \"FX=12\"\n - \"FX=13\"\n - \"FX=14\"\n - \"FX=15\"\n - \"FX=16\"\n - \"FX=17\"\n - \"FX=18\"\n - \"FX=19\"\n - \"FX=20\"\n - \"FX=21\"\n - \"FX=22\"\n - \"FX=23\"\n - \"FX=24\"\n - \"FX=25\"\n - \"FX=26\"\n - \"FX=27\"\n - \"FX=28\"\n - \"FX=29\"\n - \"FX=30\"\n - \"FX=31\"\n - \"FX=32\"\n - \"FX=33\"\n - \"FX=34\"\n - \"FX=35\"\n - \"FX=36\"\n - \"FX=37\"\n - \"FX=38\"\n - \"FX=39\"\n - \"FX=40\"\n
by @acid2000 Config json which is sent via autodiscovery:
{\n\"name\": \"WLED Light\",\n\"stat_t\": \"wled/840d8e989815/c\",\n\"cmd_t\": \"wled/840d8e989815\",\n\"rgb_stat_t\": \"wled/840d8e989815/c\",\n\"rgb_cmd_t\": \"wled/840d8e989815/col\",\n\"bri_cmd_t\": \"wled/840d8e989815\",\n\"bri_stat_t\": \"wled/840d8e989815/g\",\n\"fx_cmd_t\": \"wled/840d8e989815/api\",\n\"fx_stat_t\": \"wled/840d8e989815/api\",\n\"bri_val_tpl\": \"{{value}}\",\n\"rgb_cmd_tpl\": \"{{'#%02x%02x%02x' | format(red, green, blue)}}\",\n\"rgb_val_tpl\": \"{{value[1:3]|int(base=16)}},{{value[3:5]|int(base=16)}},{{value[5:7]|int(base=16)}}\",\n\"qos\": 0,\n\"opt\": true,\n\"pl_on\": \"ON\",\n\"pl_off\": \"OFF\",\n\"fx_val_tpl\": \"{{value}}\",\n\"fx_list\": [\n\"[FX=00] Solid\", \"[FX=01] Blink\", \"[FX=02] Breathe\", \"[FX=03] Wipe\", \"[FX=04] Wipe Random\", \"[FX=05] Random Colors\", \"[FX=06] Sweep\", \"[FX=07] Dynamic\", \"[FX=08] Colorloop\", \"[FX=09] Rainbow\", \"[FX=10] Scan\", \"[FX=11] Dual Scan\", \"[FX=12] Fade\", \"[FX=13] Chase\", \"[FX=14] Chase Rainbow\", \"[FX=15] Running\", \"[FX=16] Saw\", \"[FX=17] Twinkle\", \"[FX=18] Dissolve\",\n\"[FX=19] Dissolve Rnd\", \"[FX=20] Sparkle\", \"[FX=21] Dark Sparkle\", \"[FX=22] Sparkle+\", \"[FX=23] Strobe\", \"[FX=24] Strobe Rainbow\", \"[FX=25] Mega Strobe\", \"[FX=26] Blink Rainbow\", \"[FX=27] Android\", \"[FX=28] Chase\", \"[FX=29] Chase Random\", \"[FX=30] Chase Rainbow\", \"[FX=31] Chase Flash\", \"[FX=32] Chase Flash Rnd\", \"[FX=33] Rainbow Runner\", \"[FX=34] Colorful\", \"[FX=35] Traffic Light\", \"[FX=36] Sweep Random\", \"[FX=37] Running 2\", \"[FX=38] Red & Blue\", \"[FX=39] Stream\", \"[FX=40] Scanner\", \"[FX=41] Lighthouse\", \"[FX=42] Fireworks\", \"[FX=43] Rain\", \"[FX=44] Merry Christmas\", \"[FX=45] Fire Flicker\", \"[FX=46] Gradient\", \"[FX=47] Loading\", \"[FX=48] In Out\", \"[FX=49] In In\", \"[FX=50] Out Out\", \"[FX=51] Out In\", \"[FX=52] Circus\", \"[FX=53] Halloween\", \"[FX=54] Tri Chase\", \"[FX=55] Tri Wipe\", \"[FX=56] Tri Fade\", \"[FX=57] Lightning\", \"[FX=58] ICU\", \"[FX=59] Multi Comet\", \"[FX=60] Dual Scanner\", \"[FX=61] Stream 2\", \"[FX=62] Oscillate\", \"[FX=63] Pride 2015\", \"[FX=64] Juggle\", \"[FX=65] Palette\", \"[FX=66] Fire 2012\", \"[FX=67] Colorwaves\", \"[FX=68] BPM\", \"[FX=69] Fill Noise\", \"[FX=70] Noise 1\", \"[FX=71] Noise 2\", \"[FX=72] Noise 3\", \"[FX=73] Noise 4\",\n\"[FX=74] Colortwinkle\", \"[FX=75] Lake\", \"[FX=76] Meteor\", \"[FX=77] Smooth Meteor\", \"[FX=78] Railway\", \"[FX=79] Ripple\"\n]\n}\n
"},{"location":"advanced/home-automation/#indigo-domotics","title":"Indigo Domotics:","text":"Please see here!
"},{"location":"advanced/home-automation/#openhab","title":"openHAB:","text":"In openHAB 3 based environments you are able to use the native openHAB WLED Binding, which also supports discovery of your WLED devices.
For older openHAB (2.5.x) environmantes the connection can be configured via MQTT broker & Openhab MQTT Binding (2.5x) with configuration files Please find the details here
"},{"location":"advanced/longdata/","title":"Long Data Line configurations","text":"Addressable LEDs are controlled over a data line(s) based on 5V TTL (Transistor-Transistor-Logic) signals. Over long distances (> 5m) keeping those signals \"clean\" and well defined for the LED they're meant to drive can be difficult. While there are many methods used to get good results over 10m and longer runs (in-line resistors, voltage boosters, sacrificial pixels, etc.) they are often problematic and unreliable. There is a method specifically designed to send high speed (~1Mhz) TTL data over long (10's to 100's of meter) distances: using a differential pair.
Commonly known as RS485, differential pair transmission for LED's takes the single data line from your MCU (ESP32, ESP8266, etc) and translates that into a differential signal that is sent across two wires instead of one. A transmitter unit (Tx) at the MCU takes in the single data signal and outputs 2 lines usually called A+ and B-. At the LED strip a matching receiver unit (Rx) takes the A+, B- signals as inputs and outputs clean and accurate 5V LED data that can directly feed the strip. The only thing that needs to connect the TxRx pair is a pair of wires and a common ground. The wires don't carry much current at all (~50mA) and can often be a light wire pair from a length of Cat5e or 22/4 alarm wire.
The distance between the Tx and Rx devices can easily be 30m. With Cat5e UTP wire you can reliably reach 150m or more.
Note, there is no need for a level shifter with the Tx module. Typical transmitters are spec'd for a minimum 2.4V High level input which is well within the output range of a 3.3V MCU. The only other thing to note about the TxRx pair is that they usually require 5V to operate and often have a 120 ohm termination resistor across the A+,B- connections. Those resistors are important to maintain the integrity of the transmitted data.
A TxRx pair can also be used in the middle of a run of LED's when the distance to the next strip is long. Just put a Tx unit at the end of the first strip and the Rx unit at the start of the next strip.
The individual Tx and Rx units are fairly inexpensive and can found on Amazon or via Aliexpress usually for less than $2 USD each (try \"RS485 TTL interface\").
"},{"location":"advanced/mapping/","title":"Mapping","text":"WLED now has the ability to remap your LED strip programmatically.
"},{"location":"advanced/mapping/#what-is-it","title":"What is it?","text":"This allows us to treat the WLED strip as if it is wired in any way - we can then use the mapping feature to address the strip in any order. This allows for matrix support, serpentine runs and such.
"},{"location":"advanced/mapping/#how-do-we-do-it","title":"How do we do it?","text":"Navigate to the edit page for your WLED device by adding /edit to its' address - for example, https://my-led-device.local/edit Use this edit page to create a file called ledmap.json.
ledmap.json file needs to be a JSON formatted file with the the key being \"map\" and the value being an array of numbers representing the new order of pixels. The position of values in the array is the \"natural\" order of LEDs and the value entered is the new position.
The ArduinoJSON library is *extremely*** white-space sensitive. If your ledmap.json file is not working, check for white-spaces where they should not be. The LED positions are zero-indexed.
Multiple maps are supported in the latest versions by using ledmapx.json where x is a number. Maps can be selected in a preset using {\"ledmap\":x,....
Use -1 in the map for gaps/blank/nul LEDs.
"},{"location":"advanced/mapping/#examples","title":"Examples","text":"In the below example (formatted multiple ways), we remap a strip of four LEDs from a physical order of 0 1 2 3 into a new order of 0 2 1 3.
{\"map\":[0,2,1,3]}\n\n{\"map\":[\n0,2,1,3\n]}\n\n{\"map\":[\n0,2,\n1,3\n]}\n
This is another example that switches direction every 5 LEDs. It could be formatted any of the three ways demonstrated above.
{\"map\":[0, 1, 2, 3, 4, 9, 8, 7, 6, 5, 10, 11, 12, 13, 14,\n19, 18, 17, 16, 15, 20, 21, 22, 23, 24, 29, 28, 27, 26, 25]}\n
"},{"location":"advanced/remote-access-ifttt/","title":"Remote Access / IFTTT","text":"WLED is open-source, DIY software. This means all services are hosted locally on your ESP8266/32. Therefore you can only control your lights from within your local (home) network.
If you need to control WLED from anywhere (the public internet) you can do so in multiple ways, some requiring additional hardware:
"},{"location":"advanced/remote-access-ifttt/#1-home-automation-systems","title":"1. Home Automation systems","text":"If you add your WLED device to your Home Automation system (e.g. Home Assistant or ioBroker), you can control WLED remotely if you have set up remote access for your Home Automation system, for example via Nabu Casa.
"},{"location":"advanced/remote-access-ifttt/#2-amazon-echo-device","title":"2. Amazon Echo device","text":"If you have set up your Alexa device to control WLED, you can just use the Alexa App or another Echo device linked to your account to control your lights (on/off and brightness only)
"},{"location":"advanced/remote-access-ifttt/#3-port-forwarding","title":"3. Port Forwarding","text":"Warning: An insecure HTTP connection is used, please do NOT edit sensitive info like the WiFi settings when connected via port forwarding! This method offers more flexibility, but is also more involved. Keep in mind this causes anyone with your IP address to have access to your ESP8266! Setting up an OTA lock password is a must to prevent attackers from acquiring your WiFi credentials!
To expose WLED to the internet, create a port forwarding rule for your ESP's IP local ip and port (80) in your router configuration. It is not recommended to use port 80 on your public IP address since 80 is scanned constantly by bots good and bad. Use a 5 digit port for better securuty. If your public IP changes a lot, make sure to also use a dynamic DNS service so your lights are always accessible. Unsure what any of this means or how to do it? Google for \"[your router model] port forwarding\"!
Additionally, this opens up many new possibilities for automation! You can use a service like IFTTT Webhooks to send automated WLED API calls that can do anything from turning on the lights at a set time to changing their color if you get a new email!
"},{"location":"advanced/remote-access-ifttt/#4-hue-sync","title":"4. Hue sync","text":"If you have a Philips hue setup and sync WLED to it, you can control your WLED lights in any way it's possible to control your hue lights (hue App, Alexa (including colors), any other service that uses Philips hue API)
"},{"location":"advanced/security/","title":"Security","text":"WLED was designed in a way that you should be safe to have a router port forwarding to control the system from the public internet. This page will tell you what you can expect by WLEDs security.
"},{"location":"advanced/security/#tldr-what-to-do","title":"TLDR - what to do?","text":"A: If you just operate WLED within a local network and/or with a secured Access Point (change the default password \"wled1234\"!!) you are fine.
If you have configured a port forwarding to control WLED from outside your local subnet, please make sure the setting \"OTA Lock\" is enabled and you have changed the default OTA password \"wledota\"! Also, NEVER edit sensitive data (like WiFi credentials) while connected via the port forwarding!
"},{"location":"advanced/security/#1-is-the-connection-itself-safe","title":"1: Is the connection itself safe?","text":"A: Technically not. The ESP8266 uses unencrypted HTTP traffic. Implementing HTTPS would take too much processing power and memory on this little device. This means an attacker could read your passwords during transmit. Therefore, to be safe, please do NOT change the AP/Client WiFi/OTA password from outside of your LAN via a forwarded port. If you are at home, you should be safe if your WiFi is secured. You can change any other setting while you're away, though. WLED doesn't send your actual password to the settings page, just its length.
"},{"location":"advanced/security/#2-what-do-you-mean-by-secure-then","title":"2: What do you mean by secure then?","text":"A: WLED comes with the ability to carry out a software update via WiFi (OTA). However, no one must be able to flash a malicious new binary firmware to steal your WiFi credentials or make your ESP part of a botnet. Therefore, you should enable the \"OTA Lock\" setting and change its default passphrase \"wledota\".
"},{"location":"advanced/security/#3-can-i-protect-the-light-configuration-or-the-settings-page","title":"3: Can I protect the light configuration or the settings page?","text":"A: Currently not. This is not sensitive information like your WiFi password. Anyone with your IP and port can control the lights. Open an issue if it should ever happen that somebody plays with your lights. I might consider adding an optional password lock then. For now, it is way too cumbersome for what it does.
"},{"location":"advanced/security/#4-i-want-to-do-a-software-update-but-it-says-ota-lock-active","title":"4: I want to do a software update, but it says \"OTA lock active\"?","text":"A: You need to go to the settings page. Untick the \"OTA Lock\" setting and input your passphrase in the field below it. Now apply the settings and reboot. After that you can carry out the software update. Don't forget to re-enable OTA Lock afterwards! To enable, you don't have to enter the passphrase, unless you want to change it. For the lock to work you need to apply and reboot again.
"},{"location":"advanced/security/#5-why-is-this-ota-lock-stuff-that-important","title":"5: Why is this OTA lock stuff that important?","text":"A: Your unencrypted WiFi password is stored in the module's EEPROM. It would be easy to \"update\" the software to a malicious version which sends your password to the attacker. OTA Lock makes sure only those with the passphrase may carry out a software update. And yes, while you can disable OTA lock by doing a factory reset, this would also kill the WiFi connection to the attacker.
"},{"location":"advanced/security/#6-anything-else","title":"6: Anything else?","text":"A: A personal tip from me is not to give anyone your IP to control the software who you do not wish to do so on a regular basis. It is not critical from a security standpoint, but it can be very annoying if someone plays with your lights, or even worse, change your AP credentials to the point where you can no longer access the module except via USB.
"},{"location":"advanced/wiring/","title":"Overview","text":"RGB LEDs can draw a lot of current (amps). While most people usually worry about the dangers from high voltage, low voltage + high amperage can be dangerous too, as it can easily become a fire hazard in certain circumstances. Depending on your setup size (the number of LEDs you want to drive), use these tips to help guide your wiring.
There are plenty of guides out there to help with power supply selection, which is out of scope of this page. Size your power supply to your installation both up and down, so you both provide them with enough current and don't introduce unnecessary risk. It's better to power 30 LEDs from a 10W (2A @5V) power supply than a 100W power supply, as you don't need to worry about the potential for as much energy flowing through small wires.
As you increase the number of LEDs, you increase the amps your power supply will need to be able to provide. The more amps you're working with, the more you need to be cautious about your wiring and fusing.
For example, if you want to power your LEDs off a sealed lead acid battery (e.g. a car battery), you need to be very careful about current. These kinds of batteries can supply hundreds of amps, so you need to ensure that you use fuses along the way to protect against shorts. If you're using USB pocket chargers on the other hand, they tend to be current limited (most provide only 1-2A max) so you can worry less about fusing there.
Make sure to also check out this great list of resources to help you learn!
"},{"location":"advanced/wiring/#small-setups-30-rgb-leds","title":"Small Setups (< 30 RGB LEDs)","text":"WLED has a great built-in automatic current-limiting feature, set to 850mA by default. If you have a very small setup (< 30 LEDs), you can use this feature to help simplify your wiring and keep things safe.
In most circumstances, it's best to power your LED strip directly from the power supply and wire power to your WLED control board in parallel.
{insert diagram here}
With the current limiting feature turned on and for very small setups (on the smaller side of 1-30 LEDs), you can power the LED strip directly through the USB port of D1 mini or similar board. That is, power comes in to the control board through the USB port and out to a 5V pin. Each board will be a little different, so it would be wise to verify that you can do this for your specific board. You want to ensure that there are no voltage regulators, diodes, or other components between the 5V pin and the USB port input that are going to be damaged by the high-current draw of the LEDs. You also want to ensure that any PCB traces are big enough that they don't heat up with increased current. Never try to draw more than 1A through a board's USB port like this; the boards really aren't designed for large amounts of current to flow through them.
When using this technique, make sure to add strain relief to your wires so that they don't flex and break. The easiest way to do this is to use hot glue. While you want to use plenty of hot glue, just be careful to not cover any components that are going to get hot with hot glue.
"},{"location":"advanced/wiring/#medium-setups-30-300-rgb-leds","title":"Medium Setups (30-300 RGB LEDs)","text":"For a medium-sized setup of 30-300 LEDs, you should find a power supply that can provide enough current (see the link above) and make sure to power the strip directly. For setups with more than 150 LEDs, you should consider power injection.
"},{"location":"advanced/wiring/#power-injection","title":"Power injection","text":"Power injection is where you connect multiple wires from your power supply to the strip in multiple places, usually once at the beginning and once at the end. This is needed because the LED strips can only pass a small amount of current through them and you need to ensure that all your power-hungry LEDs get fed enough power. If your LEDs are dim or discolored at one end of the strip, you should add power injection.
When doing power injection, make sure your wires are rated for the amperage you wish to send over them. You should also check the voltage drop if you're doing a particularly long run. As a rough guide, you should never use anything thinner than 22AWG wire for power injection.
For medium-sized setups, you should add fuses if your power supply is over 100W. Considering an inline fuse on each power injection line.
"},{"location":"advanced/wiring/#inline-fuses","title":"Inline Fuses","text":"You should place the fuse as close to the power supply as possible, on the positive lead, so that as much of the current flows through it as possible. That will cause the fuse to blow if the power injection line shorts or if the strip shorts, instead of causing your power injection wire or strip to heat up. Buy a fuse that's rated just over what you expect your LED strip to draw. For example, if you calculate that your LEDs will draw at most 4.5A, buy a 5A fuse.
First match your power injection wire size with the inline fuse's wire. If the inline fuse comes with 16AWG wire (it's usually printed on the wire itself in small type), you should use 16AWG or thicker wire for your power injection wire. If you use thinner wire, you weaken the utility of the inline fuse and risk your power injection wire heating up in the case of a failure.
To wire in an inline fuse, trim back the positive wire (not ground) of your power injection line enough to allow the inline fuse to be spliced in. Place a cut of heat-shrink tubing over the wire so that the cable can be insulated once your solder joint is complete. Strip and bend both wires of your splice so that they create hooks to mechanically reinforce the joint, then solder. Cover with the heat-shrink tubing and you're done! Now you have a beautiful, professional-looking fused power injection line.
"},{"location":"advanced/wiring/#larger-setups-300-rgb-leds","title":"Larger Setups (300+ RGB LEDs)","text":"The more power you're working with, the more you need to be careful about your wiring. If you're using a 150W or higher power supply or multiple power supplies, check out these tips:
"},{"location":"advanced/wiring/#wire-ferrules","title":"Wire ferrules","text":"If you're using stranded wire and lever-lock or screw terminals, all your wire \u2192 terminal connections should be terminated with a wire ferrule of the appropriate wire gauge.
This is because stranded wires can splay and lose tension over time, creating a weaker connection that could lead to sparking. Loose strands can also cause shorts or break off. The same is true for tinned stranded wires: the solder can deform (especially if it's heated), loosening the screw terminal, and cause a weaker electrical connection or complete failure. That said, untinned stranded wire in a screw terminal actually creates a better connection than tinned stranded wire, so for high current applications where they could possibly heat up, don't tin them if you don't have ferrules.
Shrouded wire ferrules also act as strain relief, minimizing mechanical damage if the wire moves at all. This is especially important for any installations that are mobile, could experience vibrations, or are installed/removed seasonally.
"},{"location":"advanced/wiring/#multiple-power-supplies","title":"Multiple power supplies","text":"When doing power injection with multiple power supplies never mix two power supplies on the same LED strip. You can connect grounds together, just never the positive rails. This means you need to segment your LEDs based on power supplies, including your power injection. For the same reasons listed below, never connect multiple power supplies to the same strip for power injection purposes, always fork one power supply and route it to the start/mid/end of the same strip.
Because multiple power supplies could have subtle variations in their positive voltages (e.g. 12.1V and 12.3V), this could lead to power flowing in ways that aren't expected or which could be damaging to your equipment. In general, wired power supplies don't like to be directly connected to other power supplies unless they are explicitly designed for that purpose. This is not true for cell batteries, which are usually fine with being connected in parallel provided all the battery voltage + chemistry are the same.
"},{"location":"advanced/wiring/#even-more-tips","title":"Even more tips","text":" - Always check wire gauge + amp ratings and make sure to overcompensate by 2-3\u00d7
- more, lower-current wires are better than fewer, higher-current wires
- Ensure that all strips are fused just above their max current. Fuses should be located as close to the power supply as possible.
- Make sure all distribution wires are neat, tidy, and mounted to a structure. If it needs to be loose to bridge an air gap, minimize the amount of dangling wire as much as possible. This ensures that if you were to have a wire become disconnected, it'll be easy to see where it is.
- Did you add fuses? Add fuses. Seriously.
"},{"location":"basics/compatible-controllers/","title":"Compatible controllers","text":"Currently (as of summer 2023) only the microcontrollers from Espressif, types ESP8266 and ESP32 (with dual core) are fully supported. 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 ESP8266 D1 mini or 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 can be used as an 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 integarte 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.
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!
"},{"location":"basics/compatible-controllers/#controllers-with-wled-pre-installed","title":"Controllers with WLED pre-installed","text":"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!
Name Description 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-02 WLED controller WLED dedicatedly designed Controller that supports 5V-12V addressable strips from Ukrainian developers. Based on ESP8266. Slim design, sensor button, powered either by type-C or screw-terminal. Screwdriver included. Worldwide delivery. ABC! WLED Controller / ESP8266 Commercial controller for 5V LED strips. Based on ESP8266 uC. Two outputs. Ready to use. Additional Relay&Fuse board available. (German shop & shipping only within Germany.). A similar one is available at WLED.SHOP ABC! WLED Controller / ESP32 Commercial controller for 5V LED strips. Based on ESP32 uC. Two outputs. Option for digital microphone or line-in-to-I2S Adapter for sound reactive WLED. Ready to use. Additional Relay&Fuse board available. (German shop & shipping only within Germany.). A similar one is available at WLED.SHOP. ABC! WLED Controller V43 / ESP32 based / 5V-24V Commercial controller board for 5V / 12V / 24V LED strips from creator of LED power, wiring and fuse calculator. Based on ESP32 uC. Preflashed SW. Up to four outputs. Option for digital microphone or line-in-to-I2S Adapter for sound reactive WLED. Automatic 5V/12V/24V recognition (no jumper/switch etc. required). Ethernet adapter is available . Enclosure is available too. German shop & shipping only within Germany. Worldwide shipping available soon at WLED.SHOP. ABC! WLED mini Controller V70 / ESP32 based / 5V-12V Commercial controller board for 5V / 12V LED strips from creator of LED power, wiring and fuse calculator. Based on ESP32 uC. Preflashed SW. Up to four outputs. Option for digital microphone or line-in-to-I2S Adapter for sound reactive WLED. Automatic 5V/12V recognition (no jumper/switch etc. required). Enclosure is available. German shop & shipping only within Germany.. Athom Light Strip Controller Simple controller with enclosure for reliably driving 3 pin 5V LEDs. Uses 2M ESP8266. Athom High Power Addressable LED Strip Controller Higher power options than the above system. Supports optional clock output. Athom LS8P ESP32 Music Controller ESP32 based controller with dual output, microphone and IR. Comes with WLED preinstalled Athom RGBW Light Strip Controller Has outputs for individual color channels. Cadsbi Motion Smart Ready to use solution with 3 output ports, an external antenna, in a high quality metal enclosure cod.m Wi-Fi Pixel Controller Fully completed control PCB with level shifter, terminals and case - pre-flashed with WLED! ESP8266 Pixel Controller 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 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 ESP32 WLED pico board,super small form factor, ready to buy on Tindie and Tindie EU. Integrated level shifter, exposed pins for extending functionality , on board I2S microphone, Firmware is here. Project page is here IOT4WLED Ready to use hardware for WLED! 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 Small ESP32 based controller with optional digital microphone integrated for digital 5V LED strips. Laterna Stick USB Stick like ESP32 based controller for digital 5V LED strips. LedBox V2 LedBox V2 by StanleyProjects is a fully contained, sound reactive, ESP32 based module for controlling 5-12V addressable LED strips (WS2812, SK6812, etc.), supporting both 3-(VDD,DAT,GND) and 4-(VDD,DAT,CLK,GND) pin configuration. It includes a digital MEMS microphone, button and IR control, and a safety resettable fuse, all in a compact 3D printable case. The board comes all setup, flashed with sound reactive WLED fork, and can be purchased here. Luminxa v2.2.2 ESP32 My Baby's Got LED Certified open hardware. 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) powers three 5V injection points on 8A fuses. For sale now on Tindie! Full details on the github repo and maker's website. 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! 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. Pre-assembled and pre-flashed with WLED available to buy!. Aircoookie's personal recommendation for medium-size WLED projects. 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. Pre-assembled and pre-flashed with WLED available to buy!. Aircoookie's personal recommendation for large-size WLED projects with advanced power and output requirements. 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! Simple WLED Board 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 autoprod rgbw, rgbw2+, rgbw4 Complete, fully-sealed, 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 Open source PCB for WLED WLED ESP32 universal controller ready to buy on Tindie, 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-programing. Headers for shields to extend functionality. Available shields for controller is here, Firmware is here. WLED Wemos mini shield shield board, ready to buy on Tindie also Tindie EU. 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. WLED waterproof controller with external antenna 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 Yet Another WLED 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 HighSet 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."},{"location":"basics/compatible-controllers/#controllers-wled-can-be-installed-to","title":"Controllers WLED can be installed to","text":"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 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 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: https://github.com/psxde/sp108e-led-controller/raw/main/sp108ev2_inside.png 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: https://github.com/Operation760/SP501e-RGB-LED-Controller-/blob/master/SP501e_top_bottom_traced.jpg Flashing Connections: https://github.com/tonyn0/sp501e-flashing/blob/main/sp501e%20flash.png SP511e 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. ESP LED Strip WIFI Control Board [ESP Version] 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?)."},{"location":"basics/compatible-controllers/#wled-shields-to-be-use-with-esp8266esp32-controllr-boards","title":"WLED shields to be use with ESP8266/ESP32 controllr boards","text":"Name Description ABC! WLED Shield, all-purpose, for ESP8266/ESP32 Commercial WLED Shield for 5V/12V LED strips. To be used with ESP8266 or ESP32 in D1 mini format. Two outputs. Option for digital microphone or line-in-to-I2S Adapter for sound reactive WLED (with ESP32 only!). Automatic 5V/12V recognition (no jumper/switch etc. required). Enclosure is available too. German shop & shipping currently only within Germany. ESP-01 WLED shield shield board for ESP-01 board, ready to buy on Tindie. Integrated level shifter, 3 outputs for various configurations, mosfet for 1 analog channel, Firmware is here. WLED Wemos shield shield board, ready to buy on Tindie also Tindie EU or DIY 100% compatible with WLED project and WLED sound reactive fork. 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."},{"location":"basics/compatible-controllers/#other-products-wled-can-be-installed-to","title":"Other products WLED can be installed to","text":"Name Chip Description Merkury MI-BW210-999W 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 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 Athom 15W 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"},{"location":"basics/compatible-controllers/#raw-esp8266esp32-boards","title":"Raw ESP8266/ESP32 boards","text":"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 ESP8266 General-purpose ESP8266 Board with USB, battery connector, etc. D1 mini-style ESP32 ESP32 A nice compact ESP32 development board. D1 mini compatible layout. ESP32 DevKitC v4 ESP32 The original ESP32 Development Board made by Espressif Systems. H803 WiFi ESP8266 ESP8266EX based controller with level shifter inside. Data pin GPIO1 Clock pin GPIO14. Tested with WS2813 strip and Firmware fork is here. 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 Heltec 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. NodeMCU 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. 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) Olimex 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 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 ESP8285 5v DC input - onboard 10A relay TwilightLord-ESP32 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 ESP32 mini dev board 16mb by SerKo (aka Serg) 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 Wemos D1 mini 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 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 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."},{"location":"basics/compatible-hardware/","title":"Other Hardware","text":"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!
"},{"location":"basics/compatible-hardware/#useful-boards-and-addons","title":"Useful boards and addons","text":"Name Description TwilightLord-ESP32 Ethernet Shield Ethernet Shield (10/100Mbps) for ESP32 boards. Stackable with D1 Mini32 form factor boards. Wemos D1 mini Level Shifter Shield A level shifter shield (74HCT125) - by Evil Genius Labs LLC. WIZmote remote control Remote control using radio network. Compatible with WLED (vesions 0.14.0-beta3 and above). No additional receiver required."},{"location":"basics/compatible-hardware/#compatible-pc-rgb-fans-and-argb-accessories","title":"Compatible PC RGB Fans and ARGB accessories","text":"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."},{"location":"basics/compatible-hardware/#levelshifters","title":"Levelshifters","text":"Name Description SN74AHCT125 Aircoookie's recommended levelshifter. Often used in DIY and commercial controllers. 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 TXS0102, TXS0108 Bidirectional levelshifters that may work fine with WLED (if possible, 74AHCT gates should be preferred as they support both longer data lines and faster protocols) F-Amp Level shifter/data booster Warning
I2C shifters are generally too slow for addressable LEDs, so don't use them.
Further reading: Logic Level Shifters for Driving LED Strips
How to connect Levelshifters:
"},{"location":"basics/compatible-hardware/#usbttl-adapters","title":"USB/TTL adapters","text":"Name Description CH340 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 an USB/TTL adapter onboard this is NOT needed 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."},{"location":"basics/compatible-hardware/#miscellaneous","title":"Miscellaneous","text":"Sorting: Sensors, Displays, Actuators
Name Description HC-SR501 \u00a0PIR sensor with adjustable sensitivity and on time delay (suitable as a button). HC-SR602 \u00a0PIR sensor (not suitable as a button but can be used with PIR sensor usermod). TSOP38238 IR receiver compatible with most IR remotes. SSD1305 I2C display, can be used with 4 Line Display usermod. 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 Display shield Various configurations. Compatible with the ESP32 WLED dev board also can be used with ESP32 mini dev boards. 12V Relay & Fuse board Integrates two relays and two 10 A fuses. Suitable for WLED setups with 12 V LED Strips. 5V relay 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 Integrates two relays and two 10 A fuses. Suitable for WLED setups with 5V LED Strips."},{"location":"basics/compatible-led-strips/","title":"Compatible LED strips","text":"WLED supports two types of LED strips: the so-called digital addressable LED strips and the so-called analog non-addressable LED strips.
"},{"location":"basics/compatible-led-strips/#addressable-led-strips","title":"Addressable LED Strips","text":"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 5v/12v RGBW WS2811 5v usually found in IP68 sealed 12mm pixel strings WS2812B 5v WS2813 5v has a backup data line APA102 5v using 2 data pins, Clock and Data LPD8806 5v using 2 data pins, Clock and Data WS2801 5v using 2 data pins, Clock and Data SK9822 5v using 2 data pins, Clock and Data UCS8903 5v GS8208 12v TM1814 12v RGBW WS2811 12v usually 3-LED segments, has data-line resistor WS2814 12v/24v 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 12v has a backup data line LPD6803 12v P9813 5-24 v TM1829 5-24 v UCS8904 5-24 v RGBW"},{"location":"basics/compatible-led-strips/#non-addressable-led-strips","title":"Non-Addressable LED Strips","text":"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. A basic circuit diagram is shown here. You need one MOSFET and one GPIO per color. It should be noted that the MOSFETs are destroyed very quickly in the event of an overload. 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. 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.
"},{"location":"basics/compatible-software/","title":"Compatible Software","text":"Still under construction, feel free to add to the list!
This page lists some third-party software that can interface with WLED!
"},{"location":"basics/compatible-software/#controllers","title":"Controllers","text":"Controllers use the WLED API to change the current light settings.
Name Description Home Assistant 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 Home automation system, WLED integration via the D.A.L.O.R. app with automatic discovery. ioBroker adapter Versatile and feature rich home automation system. Out-of-the-box WLED integration with automatic discovery. Lumia Stream Allows for control of your lights from streaming software node-red-contrib-wled Node-RED nodes for WLED OctoPrint-WLED Connect your OctoPrint install to your WLED install using this plugin to show things like printer status, progress and more! openHAB Another more professional feature rich home automation system. WLED integration made easy. Link 2 WLED-GUI This is a cross-platform desktop app for WLED. You can use it on Windows, Linux and Mac. wledQuickControl macOS 11.0+ Menu Bar app for controlling power and brightness."},{"location":"basics/compatible-software/#sources","title":"Sources","text":"Source programs generate light data and stream them to WLED in real time.
Name Description LedFx A music visualization tool written in Python. Connects to WLED via E1.31 or UDP. Dr.Zzs tutorial video Prismatik WLED-WiFi (native) Ambilight via WiFi or serial - natively supports UDP (WARLS, DRGB, DNRGB protocols). Prismatik WLED-WiFi (plugin) Ambilight via WiFi - a Plugin alternative for Prismatik WLED support. xLights xLights is a Light Sequencer and Show scheduler which works with WLED. Dr.Zzs has made some videos to set it up. Intro Video Hyperion.ng 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, Dr.Zzs video Hyperion (Classic) 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+ 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."},{"location":"basics/compatible-software/#various","title":"Various","text":"Name Description Logitech WLED Sync Windows tray application to sync Logitech gaming peripherals to WLED."},{"location":"basics/compiling-wled/","title":"Compiling WLED","text":"Moved, see How to compile WLED
"},{"location":"basics/faq/","title":"FAQ","text":"This page will continually get updated with questions often asked.
"},{"location":"basics/faq/#contents","title":"Contents","text":""},{"location":"basics/faq/#installation","title":"Installation","text":" - What binary should I use?
- I've flashed a bin, but i get no response at all
"},{"location":"basics/faq/#connection-issues","title":"Connection issues","text":" - Once I attach LEDs, I can't connect to the ESP anymore!
- 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 wled-xxx.local address (mDNS) does not work.
- Is it safe to do a port forwarding to the public internet to control the lights from anywhere?
- My device is unresponsive or animations lag!
- I'm 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!
- Still having connection issues/connection dropping: what more can i check?
"},{"location":"basics/faq/#compilation-issues","title":"Compilation issues","text":" - When compiling WLED in VS Code using platformio, I get an error.
"},{"location":"basics/faq/#led-issues","title":"LED issues","text":" - My LEDs don't turn on at all.
- My LEDs don't get as bright as they should!
- My LEDs are unable to be set into an consistent solid color.
- When I select green, the LEDs turn red!
- My LEDs act funny and flicker randomly.
- Not all my LEDs turn on.
- How to turn off the bright blue onboard LED?
- Why is gpio2/D4 the default LED pin?
- Why can I only use 500 LEDs on the ESP8266 GPIO pin 3?
- What LED strip hardware is supported by WLED?
"},{"location":"basics/faq/#general-questions","title":"General questions","text":" - What does the name WLED mean?
- What do the WLED version names mean?
- What is the difference between the brightness sliders in the web UI?
- My Segments are gone after a reboot!
- May I sell a product running WLED?
"},{"location":"basics/faq/#my-question-or-solution-is-not-on-this-page","title":"My question or solution is not on this page","text":" - Check out the WLED forum!
- Look through the Issues
- If I report a new Issue, what do i need to share?
"},{"location":"basics/faq/#installation_1","title":"Installation","text":""},{"location":"basics/faq/#what-binary-should-i-use","title":"What binary should I use?","text":"Please see this page.
"},{"location":"basics/faq/#ive-flashed-a-bin-but-i-get-no-response-at-all","title":"I've flashed a bin, but i get no response at all","text":"Some users report first erasing the flash (yes, even on a new device) sometimes helps .
"},{"location":"basics/faq/#connection-issues_1","title":"Connection issues","text":""},{"location":"basics/faq/#once-i-attach-leds-i-cant-connect-to-the-esp-anymore","title":"Once I attach LEDs, I can't connect to the ESP anymore!","text":"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!
"},{"location":"basics/faq/#i-have-entered-my-wifi-credentials-and-rebooted-but-i-can-not-connect-to-the-module-now","title":"I have entered my WiFi credentials and rebooted, but I can not connect to the module now!","text":"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 Android app which features automatic discovery!
"},{"location":"basics/faq/#the-module-once-was-connected-but-i-can-no-longer-reach-it","title":"The module once was connected, but I can no longer reach it","text":"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.
"},{"location":"basics/faq/#the-wled-xxxlocal-address-mdns-does-not-work","title":"The wled-xxx.local address (mDNS) does not work","text":"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. I highly recommend you install the WLED app, which makes automatic discovery easy!
"},{"location":"basics/faq/#is-it-safe-to-do-a-port-forwarding-to-the-public-internet-to-control-the-lights-from-anywhere","title":"Is it safe to do a port forwarding to the public internet to control the lights from anywhere?","text":"See this page.
"},{"location":"basics/faq/#my-device-is-unresponsive-or-animations-lag","title":"My device is unresponsive or animations lag!","text":"You are probably using too many sync interfaces. Please only enable one of Hue sync, MQTT, or Blynk 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.
"},{"location":"basics/faq/#im-having-a-bootloop-leds-turn-on-every-5seconds","title":"I'm having a bootloop! (LEDs turn on every ~5seconds)","text":"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!
"},{"location":"basics/faq/#still-having-connection-issuesconnection-dropping-what-more-can-i-check","title":"Still having connection issues/connection dropping: what more can i check?","text":"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.
"},{"location":"basics/faq/#i-am-running-realtime-eg-e131-and-not-all-of-my-leds-are-driven-fluently","title":"I am running realtime (e.g. E1.31) and not all of my LEDs are driven fluently!","text":"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.
"},{"location":"basics/faq/#compilation-issues_1","title":"Compilation issues","text":""},{"location":"basics/faq/#when-compiling-wled-in-vs-code-using-platformio-i-get-an-error","title":"When compiling WLED in VS Code using platformio, I get an error","text":"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!
"},{"location":"basics/faq/#led-issues_1","title":"LED issues","text":""},{"location":"basics/faq/#my-leds-dont-turn-on-at-all","title":"My LEDs don't turn on at all.","text":"Please make sure you have connected the strip to GPIO2 and it is sufficiently powered.
"},{"location":"basics/faq/#my-leds-dont-get-as-bright-as-they-should","title":"My LEDs don't get as bright as they should!","text":"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.
"},{"location":"basics/faq/#my-leds-are-unable-to-be-set-into-an-consistent-solid-color","title":"My LEDs are unable to be set into an consistent solid color","text":"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.
"},{"location":"basics/faq/#when-i-select-green-the-leds-turn-red","title":"When I select green, the LEDs turn red!","text":"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.
"},{"location":"basics/faq/#my-leds-act-funny-and-flicker-randomly","title":"My LEDs act funny and flicker randomly","text":""},{"location":"basics/faq/#reason-1","title":"Reason 1","text":"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.
"},{"location":"basics/faq/#reason-2","title":"Reason 2","text":"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.
"},{"location":"basics/faq/#reason-3","title":"Reason 3","text":"Your data line can only be so long. 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 ;-)).
"},{"location":"basics/faq/#reason-4","title":"Reason 4","text":"If they don't flicker, but display funny colors, try switching between RGB/RGBW modes in LED settings.
"},{"location":"basics/faq/#not-all-my-leds-turn-on","title":"Not all my LEDs turn on","text":""},{"location":"basics/faq/#reason-1_1","title":"Reason 1","text":"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 here for maximum recommended LED counts.
"},{"location":"basics/faq/#reason-2_1","title":"Reason 2","text":"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!
"},{"location":"basics/faq/#how-to-turn-off-the-bright-blue-onboard-led","title":"How to turn off the bright blue onboard LED?","text":"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
"},{"location":"basics/faq/#why-is-gpio2d4-the-default-led-pin","title":"Why is gpio2/D4 the default LED pin?","text":"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.
"},{"location":"basics/faq/#why-can-i-only-use-500-leds-on-the-esp8266-gpio-pin-3","title":"Why can I only use 500 LEDs on the ESP8266 GPIO pin 3?","text":"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.
"},{"location":"basics/faq/#what-led-strip-hardware-is-supported-by-wled","title":"What LED strip hardware is supported by WLED?","text":"The compatible chipsets for the color-coding are
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.
"},{"location":"basics/faq/#general-questions_1","title":"General Questions","text":""},{"location":"basics/faq/#what-does-the-name-wled-mean","title":"What does the name WLED mean?","text":"WiFi Lighting Effects Driver. Also it has LED in the name and is similar to the official term for WiFi, WLAN!
"},{"location":"basics/faq/#what-do-the-wled-version-names-mean","title":"What do the WLED version names mean?","text":"WLED version names are Japanese! Here is a nice list of their meanings:
Version Name Kanji Meaning 0.10 Namigai \u6d6a\u8c9d Geoduck (don't google it!) 0.11.0 Mirai \u672a\u6765 Future 0.11.1 Fumikiri \u8e0f\u5207 Railroad crossing 0.12 Hikari \u5149 Light 0.13 Toki \u6642 Time N/A Kuuhaku \u7a7a\u767d Blank"},{"location":"basics/faq/#what-is-the-difference-between-the-brightness-sliders-in-the-web-ui","title":"What is the difference between the brightness sliders in the web UI?","text":"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. Please note that this does not override the master brightness, but instead is an additional downscaling. (If you set both Master and Segment brightness sliders to 50%, the resulting brightness is 25%)
"},{"location":"basics/faq/#my-segments-are-gone-after-a-reboot","title":"My Segments are gone after a reboot!","text":"Segments are non-persistant 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 Favorites tab in the web UI, click the save checkbox and save the config to preset slot number
16 - In LED settings, set
Boot Preset to 16
This will be improved in a future release, so that you will be able to save multiple segment configurations!
"},{"location":"basics/faq/#may-i-sell-a-product-running-wled","title":"May I sell a product running WLED?","text":"WLED is licensed under the MIT license, thus you are free to use it in any way you wish as long as you retain the copyright notice and accept that I am not to be held liable for anything regarding your use of the software. For product pages, a link to the WLED GitHub repository would be hugely appreciated !
"},{"location":"basics/faq/#my-question-or-solution-is-not-on-this-page_1","title":"My question or solution is not on this page","text":""},{"location":"basics/faq/#check-out-the-wled-forum","title":"Check out the WLED forum!","text":"You can check out and use the WLED Discourse forum.
"},{"location":"basics/faq/#look-through-the-issues","title":"Look through the Issues","text":"Maybe someone already reported your issue, so everybody supplying support would be grateful if you take some time to search through the existing issues.
"},{"location":"basics/faq/#if-i-report-a-new-issue-what-do-i-need-to-share","title":"If I report a new Issue, what do i need to share?","text":"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 https://docs.wled.me?
- 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?
"},{"location":"basics/getting-started/","title":"Getting Started","text":""},{"location":"basics/getting-started/#welcome-to-the-wled-wiki","title":"Welcome to the WLED wiki!","text":"Version Info
Unless noted otherwise, all information applies to the latest release (v0.13.3).
"},{"location":"basics/getting-started/#quick-start-guide","title":"Quick start guide","text":"1. Connect a WS2812B-compatible RGB(W) led strip to GPIO2. On most ESP8266 based development boards this pin is labeled D4, on ESP32 based boards use IO16 or G16 or 16. If the connecting wire cannot be kept short, use a level shifter/translator. Optionally connect a normally open pushbutton to GPIO0 (NodeMCU/Wemos pin D3, on ESP32 use IO17) and ground for configurable actions. Note: 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!
While using an ESP8266 and LEDs that have clock and data, you can either use hardware SPI (mostly faster) or software SPI. - hardware SPI: use GPIO14 (SCLK) for clock and GPIO13 (MOSI) for data. - software SPI: since all pins can be changed in the Hardware section of LED settings, you can use any pins. Recommend is to use GPIO1 (TxD) for clock and GPIO2 (D4) for data.
For safe operation it is recommended to size your power wires correctly and to integrate fuses. For reference, you may use this LED power, wiring and fuse calculator.
For analog LEDs, the MOSFETs IRLZ44N or STP55NF06L are good candidates. Partial, example circuit...
2. Flash the software to your ESP module! There are two options for this step:
I just want to use WLED! (install release binary)
I want to modify WLED (compile from source code)
If everything worked the first thirty LEDs will light up in bright orange to stimulate courage, friendliness and success!
3. Use a WiFi device to connect to the access point WLED-AP using the default password wled1234. You can also just scan this QR code:
WLED-AP is not showing up!
If you do not see the WLED-AP SSID, the default SSID may have been changed at compile time.
Go to the IP 4.3.2.1 in your browser to control your lights! You should also be able to connect to wled.me if in access point mode (embedded DNS server).
"},{"location":"basics/getting-started/#wifi-setup","title":"Wifi Setup","text":"To connect your WLED module to your home Wifi:
1. Click on the Config (gear) icon to edit your WLED module settings and choose 'Wifi Setup'.
2. For most home networks, simply enter your Wifi network's name and network password. You can also change the mDNS address for your WLED module here.
3. Click Save & Connect at the bottom of the page.
4. Reconnect your device to your home's Wifi network.
5. Check the device list in your router's user interface for the IP of the WLED device within your local network. For easy automatic discovery, use the WLED app! Have fun with the WLED software!
"},{"location":"basics/getting-started/#default-gpio-usage","title":"Default GPIO Usage","text":"These are only defaults
All pins can be changed in the Hardware section of LED settings. Please note that these are GPIO numbers, please consult a pinout for your board to find the labeled pin (e.g D4 = GPIO2 on most ESP8266 boards). When using an ESP8266 board, it's recommended to use pins GPIO1, GPIO2, or GPIO3 for LED Data; using other pins will require bit-banging and may cause slow performance and/or issues elsewhere (such as with IR decoding).
Function GPIO Suggested pin LED Data 2 ESP8266: 1, 2 (3 if <= 100 LEDs), ESP32: 1, 2, 3, 4, 16 Button 0 IR Remote None 4 Relay None 12"},{"location":"basics/getting-started/#software-update-procedure","title":"Software update procedure","text":"Method 1: Reflashing the new update like a new install (see above).
Method 2: The software has an integrated OTA software update capability. First you have to enable it by typing in the correct OTA passphrase (default: \"wledota\") in the settings menu. Remove the tick in the checkbox \"OTA locked\". Then save settings and reboot the ESP. Then you can select \"Manual OTA update\" in Security settings and upload a release binary. After you are done, it is recommended to lock the OTA function again. To do so, tick the checkbox again (you can change the passphrase by typing in a new one now). Reboot. If you try to access the update page now, you should see the message \"OTA lock active\".
Method 3: ArduinoOTA is also supported.
If you own multiple devices and want to update them
Since v0.13 of WLED source code includes shell/command prompt scripts which is allow you to update multiple devices with a single command. Please check tools subfolder for multi-update scripts (.cmd or .sh). You will need to modify them to include IP addresses of your WLED devices and assign firmware binary file for each device. If you are using Windows, make sure you install curl utility somewhere in your PATH (curl is included with Windows 10 since build 17063). This will only work if \"OTA Lock\" is disabled.
"},{"location":"basics/install-binary/","title":"Install WLED Binary","text":""},{"location":"basics/install-binary/#flashing-method-1-wled-web-installer","title":"Flashing method 1: WLED web installer","text":"Tip
This is by far the easiest and fastest way to get WLED up and running!
Make sure you are running a recent desktop Chrome or Edge browser and head over to the WLED installer site! If you are updating an existing version of WLED, make sure to uncheck \"Clean install\" so that your settings are kept. 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/. After using the standard WLED installer, microphone hardware sometimes cannot be initialized properly by WLED.
"},{"location":"basics/install-binary/#flashing-method-2-esptool","title":"Flashing method 2: esptool","text":" - First of all, please follow the steps to install esptool.py here.
- Download the latest release binary 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 after write_flash - Execute this command:
"},{"location":"basics/install-binary/#esp8266","title":"ESP8266","text":"esptool.py write_flash 0x0 ./WLED_XXX.bin\n
"},{"location":"basics/install-binary/#esp32","title":"ESP32","text":"Firstly, flash the version 4 bootloader file, which you can find here. This step only has to be done once, to update afterwards the bootloader does not have to be re-installed.
esptool.py write_flash 0x0 ./esp32_bootloader_v4.bin\n
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.
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!)
esptool.py erase_flash\n
If you have a MagicHome controller, here is a good video tutorial on how to flash it.
"},{"location":"basics/install-binary/#esp8266-flashing-method-3-esp-home-flasher-tool","title":"ESP8266 Flashing method 3: ESP Home Flasher tool","text":"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, 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: https://www.wemos.cc/en/latest/ch340_driver.html 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 instead of ESP Home Flasher.
"},{"location":"basics/install-binary/#flashing-method-4-ota-update","title":"Flashing method 4: OTA update","text":"You can alternatively use my basic HTTP OTA updater 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.
"},{"location":"basics/install-binary/#what-binary-should-i-use","title":"What binary should I use?","text":"I always recommend to use the latest release. Starting from WLED 0.12.0, pins can be configured in LED settings and specific binaries for different LED pins or types are no longer needed. Please use the following binary for these boards respectively:
Binary Name For devices WLED_0.x.x_ESP8266.bin NodeMCU, Wemos D1 mini, ESP-12, all ESP8266 with 4MB flash. Recommended. WLED_0.x.x_ESP32.bin All ESP32 devices (try this if the WLED-AP doesn't appear after flashing) WLED_0.x.x_ESP32_Ethernet.bin ESP32 devices with an Ethernet interface. Also works with WiFi only. WLED_0.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_0.x.x_ESP02.bin All ESP8266 with 2MB flash, Athom bulbs esp32_bootloader.bin Not a WLED release. To be flashed to a brand new ESP32 before flashing the WLED binary itself. Legacy binary format (up to 0.11.1)
Binary Name For devices WLED_0.x.x_ESP8266_1M_ota.bin ESP-01 (black PCB), most Sonoff devices, ESP8265, all ESP8266 with 1MB flash. This binary has some interfaces disabled (Alexa, Blynk, Hue sync, Infrared) in order for wireless updates to continue working. WLED_0.x.x_ESP8266_1M_full.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_0.x.x_ESP8266_512k.bin ESP-01 (blue PCB), older Sonoff devices, all ESP8266 with 512kB flash. Interfaces (Alexa, Blynk, Hue sync, Infrared) disabled, no OTA. Support will not be possible in future versions. WLED_0.x.x_ESP8266_ledpinY.bin Custom build for 4MB flash ESP8266 and WS2812B. LED pin is changed (default is GPIO2). (This is GPIOY and not DY for the D to GPIO mapping, check your boards spec!) WLED_0.x.x_ESP8266_apa102.bin Custom build for 4MB flash ESP8266 and APA102 LEDs (clock pin GPIO0, data GPIO2). WLED_0.x.x_ESP8266_ws2801.bin Custom build for 4MB flash ESP8266 and WS2801 LEDs (clock pin GPIO0, data GPIO2). WLED_0.x.x_ESP32_ledpinY.bin Custom build for ESP32 and WS2812b. LED pin is changed (default is GPIO2). LED pin 16 is useful for the QuinLed-Dig-Uno board with ESP32."},{"location":"basics/install-gui/","title":"Installation using ESP GUI","text":""},{"location":"basics/install-gui/#1-downloading-the-firmware-bin-file","title":"1. Downloading the firmware bin file","text":"You can find precompiled .bin files on the release page. 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?
"},{"location":"basics/install-gui/#2-downloading-the-flash-download-tools","title":"2. Downloading the Flash Download Tools","text":"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! (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.
"},{"location":"basics/install-gui/#3-flashing-the-firmware-bin-files","title":"3. Flashing the firmware bin files","text":"After starting flash_download_tools_v[...].exe there should pop up two small windows. Now just click on the Developer Mode andESP8266 DownloadTool button. Now a new window opens.
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
"},{"location":"basics/install-wled-flasher/","title":"Installation using ESP GUI","text":""},{"location":"basics/install-wled-flasher/#1-downloading-wled-firmware-bin-file","title":"1. Downloading WLED firmware bin file","text":"You can find precompiled .bin files on the official release page. Also available alternative with precompiled usermods
If you are not sure what binary you should use look at this page: What binary should I use?
"},{"location":"basics/install-wled-flasher/#2-downloading-the-esp-wled-flasher","title":"2. Downloading the ESP WLED Flasher","text":"You can find and download flasher here!
After downloading a file, unzip it and start
"},{"location":"basics/install-wled-flasher/#3-flashing-firmware-bin-files","title":"3. Flashing firmware bin files","text":"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
"},{"location":"basics/tutorials/","title":"Tutorials","text":"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:
"},{"location":"basics/tutorials/#wled-specific-tutorials","title":"WLED specific tutorials","text":"Resource Maker Type Date Info Beginner's guide to freak'n cool Holiday LEDs 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 DrZzs Video (23:39) 29 Oct 2019 Learn about some cool additional WLED features! Make your LEDs dance to music! 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 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) 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 Quindor Video (11:13) 21 Sept 2019 Initial flash and setup of WLED on QuinLED-Dig-Uno board Integrating WLED into Home Assistant 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 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 KPeyanski Article 23 Jul 2022 Same as the above video, but in text form! Smart Ping Pong LED Lamp - Quick&Simple DIY 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/\u043d\u0430 \u0440\u0443\u0441\u0441\u043a\u043e\u043c) Gelmer Article Series 11 Jun 2023 \u0421\u0435\u0440\u0438\u044f \u0440\u0443\u043a\u043e\u0432\u043e\u0434\u0441\u0442\u0432 \u043f\u043e \u0443\u0441\u0442\u0430\u043d\u043e\u0432\u043a\u0435 \u0418\u043d\u0441\u0442\u0440\u0443\u043a\u0446\u0438\u044f \u043d\u0430 \u0440\u0443\u0441\u0441\u043a\u043e\u043c: \u041a\u0430\u043a \u043f\u0440\u043e\u0448\u0438\u0442\u044c WLED \u0438 LED FX \u0432 ESP01 \u041f\u0440\u0438\u043c\u0435\u0440 \u043f\u0440\u0438\u043c\u0435\u043d\u0435\u043d\u0438\u044f WLED: \u0411\u0435\u0441\u043a\u043e\u043d\u0435\u0447\u043d\u044b\u0439 \u0437\u0435\u0440\u043a\u0430\u043b\u044c\u043d\u044b\u0439 \u0442\u0443\u043d\u043d\u0435\u043b\u044c \u0432\u043d\u0443\u0442\u0440\u0438 \u0441\u0442\u043e\u043b\u0438\u043a\u0430 IKEA Lack Alchemist Video (9:16) / Video (13:09) 19 Aug 2022 \u041f\u0440\u043e\u0448\u0438\u0432\u043a\u0430, \u0443\u0441\u0442\u0430\u043d\u043e\u0432\u043a\u0430 \u043d\u0435\u043e\u0431\u0445\u043e\u0434\u0438\u043c\u044b\u0445 \u0434\u0440\u0430\u0439\u0432\u0435\u0440\u043e\u0432 \u0438 \u0434\u0435\u043c\u043e\u043d\u0441\u0442\u0440\u0430\u0446\u0438\u044f \u0440\u0435\u0436\u0438\u043c\u043e\u0432 \u0440\u0430\u0431\u043e\u0442\u044b. \u041f\u0440\u0438\u043c\u0435\u0440 \u044d\u043b\u0435\u043a\u0442\u0440\u043e\u043d\u043d\u043e\u0439 \u0441\u0445\u0435\u043c\u044b. ESP8266 based LED controller for WS2812b strip. WLED Firmware + OpenHAB (in Russian) Room31 Video (17:04) 11 Mar 2020 How to use WLED on an ESP32 (German) Bitbastelei/Adlerweb Video (11:00) 1 Nov 2020 DIY Ambilight using WLED and a Relay jangrewe Article ? Wiki page with schematics and instructions for Hyperion, etc. Adding Smarts and Color to an IKEA Lamp apop880 Article 21 May 2021 Tutorial on upgrading a basic IKEA lamp with WLED"},{"location":"basics/tutorials/#digital-led-knowledge","title":"Digital LED knowledge","text":"Resource Maker Type Info Adafruit NeoPixel \u00dcberguide Adafruit Article Everything that's important at a glance. Highly recommended for newcomers to digital LEDs Digital LED Power Usage Quindor Article/Spreadsheet/Video Helps you plan the power usage of your installation Power calculation and injection live stream 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 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 The Hook Up Video (12:14) Make your project look much better! Power Injection demystified Spiker Lights Article What is power injection and how much do I need? Common(sharing) Ground / Multiple power supplies Article When using more than one power supply."},{"location":"basics/tutorials/#tools-skills","title":"Tools & Skills","text":"Resource Maker Type Info How to Solder Beauty and the Bolt Video (9:50) Soldering new leads to LED strip Quindor Video (8:24) Soldering Tutorial Part 2 EEVblog Video (34:05) Detailed tutorial on soldering, see parts 1 and 3 for even more info) Voltage Drop Calculator Tool Another Voltage Drop Calculator Tool Pixel/Bullet Voltage Drop Calc Tool 5 and 12V Combined Wire Gauge Calculator Tool Wire Size/Ampacity Tool Use chassis wiring Add more categories as needed :)
"},{"location":"features/cct/","title":"White handling","text":""},{"location":"features/cct/#white-channels-handling","title":"White channel(s) handling","text":"Besides addressable RGB and RGBW bus types, WLED 0.13.0 also supports PWM CCT (correlated color temperature) lights.
"},{"location":"features/cct/#auto-white-handling","title":"Auto white handling","text":"Many effects and realtime sources are based on an RGB color model, which necessitates a method to calculate a white channel value from the RGB value for lights that support more than RGB.
WLED offers four auto white modes, one of which can be selected in LED settings using the option Auto-calculate white channel from RGB. This option is only shown if at least one bus with White channel support is present.
Auto White mode Description Accurate This mode subtracts the calculated white value from the RGB channels. This gets rid of the \"RGB-white\" but means that the light is less bright with only the white channel and not the RGB channels being utilized for pure white. Brighter This does the exact opposite and not touch the RGB channels at all, just mix in the dedicated white. None No auto white calculation is performed. The white channel of colors can be manually set using the White channel slider in the user interface, RGB-only effects and most realtime sources will leave the white channel off. Dual The White channel slider is present in the UI and works the same as in None mode, however if the slider value is 0 (far left), the Brighter mode is used for auto white calculation. This is the default auto white mode. Accurate and Brighter methods are applied on a per-pixel basis, so they also work in color palettes and realtime effects!
"},{"location":"features/cct/#white-balance-correction","title":"White Balance correction","text":"If enabled in LED settings, WB correction allows either making all pixels colder or warmer on a per-segment basis using a slider in the main user interface. This is applied to the RGB color only, after the auto white channel calculation.
"},{"location":"features/cct/#cct-handling","title":"CCT handling","text":"WLED starting with version 0.13.0 also supports bus types with two white channels, one with a warm color temperature (e.g. 2700 Kelvin, reddish white) and one with a cold white color temperature (e.g. 8000 Kelvin, bluish white).
Since as of the release of version 0.13.0 no adjustable CCT addressable LEDs are supported*, this only applies to PWM analog LED outputs.
*SK6812 WWA (with 3 channels, warm white, cold white and amber) are supported, but treated as if RGB using the WS281x bus type. White spectrum support for this LED type will be added at a later point.
The overall brightness of the white channels is determined from the auto-white calculation outlined above, and as such is identical in behavior to that of single white channel busses.
The color temperature is set either on a per-segment basis via a dedicated slider in the UI, or if Calculate CCT from RGB is enabled in LED settings, is estimated on a per-pixel basis from the set RGB color (e.g. setting Red results in the warmest, setting Blue results in the coldest possible white). The former has the advantage of granular white spectrum control independent of the set RGB color, while the latter enables control of the color temperature from all effects and realtime sources.
"},{"location":"features/cct/#cct-additive-blending","title":"CCT additive blending","text":"Setting this to 0% results in a more even brightness output across the supported temperature range, as the fading between the warm and cold white channels is linear.
Setting this to 100% results in the highest peak brightness output at the neutral white point (CCT value 127), as both white channels are active at 100%.
Warning
Make sure your setup can handle driving both white channels at maximum output simultaneously. This results in a higher heat output and might reduce the lifetime of your LEDs. For example, bulbs by Athom are designed for linear blending (0%) and may be damaged by attempting to use additive blending.
You can limit the maximum allowed additive blending at build time using the WLED_MAX_CCT_BLEND macro. For example, add -D WLED_MAX_CCT_BLEND=0 to your build flags to force linear blending only.
"},{"location":"features/cct/#ic-cct","title":"IC CCT","text":"By default, PWM CCT bus types set the value of the warm and cold white channels. If your hardware uses an IC that controls the color temperature based on one PWM signal and the overall brightness on the other, please use the build flag -D WLED_USE_IC_CCT in a custom compilation. (the 15W bulb by Athom uses this method)
"},{"location":"features/cct/#cct-in-the-json-api","title":"CCT in the JSON API","text":"Please see here for more info on how to handle WLED CCT from integrations.
"},{"location":"features/effects/","title":"Effects","text":"Version Info
Effects above 117 are only available 0.14+ or Sound Reactive forks. Retired Effects - Can't find an old favorite? Look here.
"},{"location":"features/effects/#effect-overlay","title":"Effect Overlay","text":"Some effects can be overlaid on the background of another effect. To use overlay, set up segments with overlapping pixels. The overlay effect must be playing on the segment with the higher id. If the Overlay option is checked, the background will not be painted and the effect from the lower segment will be displayed.
To aid in showing where colors vs palettes are used, all effects are rendered with the Party palette and the colors: Primary (Fx) (or black) Secondary (Bg) Tertiary (Cs).
ID Effect Description Flags Colors Parms 0 Solid Solid primary color on all LEDs \u22ee 1 Blink Blinks between primary and secondary color \u22ee \ud83c\udfa8 Fx, Bg Speed, Duty cycle 2 Breathe Fades between primary and secondary color \u22ee \ud83c\udfa8 Fx, Bg Speed 3 Wipe Switches between primary and secondary, switching LEDs one by one, start to end \u22ee \ud83c\udfa8 Fx, Bg Speed, Intensity 4 Wipe Random Same as Wipe, but uses random colors \u22ee \ud83c\udfa8 Speed 5 Random Colors Applies a new random color to all LEDs \u22ee \ud83c\udfa8 Speed, Fade time 6 Sweep Switches between primary and secondary, switching LEDs one by one, start to end to start \u22ee \ud83c\udfa8 Fx, Bg Speed, Intensity 7 Dynamic Sets each LED to a random color \u22ee \ud83c\udfa8 Speed, Intensity, Smooth 8 Colorloop Cycle all LEDs through the rainbow colors \u22ee \ud83c\udfa8 Speed, Saturation 9 Rainbow Displays rainbow colors along the whole strip \u22ee \ud83c\udfa8 Speed, Size 10 Scan A single primary colored light wanders between start and end \u22ee \ud83c\udfa8 Fx, Bg, Cs Speed, # of dots, Overlay 11 Scan Dual Same as Scan but uses two lights starting at both ends \u22ee \ud83c\udfa8 Fx, Bg, Cs Speed, # of dots, Overlay 12 Fade Fades smoothly between primary and secondary color \u22ee \ud83c\udfa8 Fx, Bg Speed 13 Theater Pattern of one lit and two unlit LEDs running \u22ee \ud83c\udfa8 Fx, Bg Speed, Gap size 14 Theater Rainbow Same as Theater but uses colors of the rainbow \u22ee \ud83c\udfa8 Bg Speed, Gap size 15 Running Sine Waves scrolling \u22ee \ud83c\udfa8 Fx, Bg Speed, Wave width 16 Saw Sawtooth Waves scrolling \u22ee \ud83c\udfa8 Fx, Bg Speed, Width 17 Twinkle Random LEDs light up in the primary color with secondary as background \u22ee \ud83c\udfa8 Fx, Bg Speed, Intensity 18 Dissolve Fills LEDs with primary in random order, then off again \u22ee \ud83c\udfa8 Fx, Bg Repeat speed, Dissolve speed, Random 19 Dissolve Rnd Fills LEDs with random colors in random order, then off again \u22ee \ud83c\udfa8 Bg Repeat speed, Dissolve speed 20 Sparkle Single random LEDs light up in the primary color for a short time, secondary is background \u22ee \ud83c\udfa8 Fx, Bg Speed, Overlay 21 Sparkle Dark All LEDs are lit in the primary color, single random LEDs turn off for a short time \u22ee \ud83c\udfa8 Bg, Fx Speed, Intensity, Overlay 22 Sparkle+ All LEDs are lit in the primary color, multiple random LEDs turn off for a short time \u22ee \ud83c\udfa8 Bg, Fx Speed, Intensity, Overlay 23 Strobe All LEDs are lit in the secondary color, all LEDs flash in a single short burst in primary color \u22ee \ud83c\udfa8 Fx, Bg Speed 24 Strobe Rainbow Same as strobe, cycles through the rainbow \u22ee \ud83c\udfa8 Bg Speed 25 Strobe Mega All LEDs are lit in the secondary color, all LEDs flash in several short bursts in primary color \u22ee \ud83c\udfa8 Fx, Bg Speed, Intensity 26 Blink Rainbow Same as blink, cycles through the rainbow \u22ee \ud83c\udfa8 Fx, Bg Frequency, Blink duration 27 Android Section of varying length running \u22ee \ud83c\udfa8 Fx, Bg Speed, Width 28 Chase 2 LEDs in primary color running on secondary \u22ee \ud83c\udfa8 Fx, Bg, Cs Speed, Width 29 Chase Random Like Chase but leaves trail of random color \u22ee \ud83c\udfa8 Fx, Cs Speed, Width 30 Chase Rainbow Like 28 but leaves trail of rainbow \u22ee \ud83c\udfa8 Fx, Bg Speed, Width 31 Chase Flash 2 LEDs flash in secondary color while the rest is lit in primary. The flashing LEDs wander from start to end \u22ee \ud83c\udfa8 Bg, Fx Speed 32 Chase Flash Rnd Like Chase Flash, but the 2 LEDs flash in random colors and leaves a random color behind \u22ee \ud83c\udfa8 Fx, Bg Speed 33 Rainbow Runner Like Chase, but the 2 LEDs light up in rainbow colors and leave a primary color trail \u22ee \ud83c\udfa8 Bg Speed, Size 34 Colorful Shifting Red-Amber-Green-Blue pattern \u22ee \ud83c\udfa8 1, 2, 3 Speed, Saturation 35 Traffic Light Emulates a traffic light \u22ee \ud83c\udfa8 Bg Speed, US style 36 Sweep Random Like Sweep, but uses random colors \u22ee \ud83c\udfa8 Speed 37 Chase 2 Pattern of n LEDs primary and n LEDs secondary moves along the strip \u22ee \ud83c\udfa8 Fx, Bg Speed, Width 38 Aurora Simulation of the Aurora Borealis \u22ee \ud83c\udfa8 1, 2, 3 Speed, Intensity 39 Stream Flush bands random hues along the string \u22ee \ud83c\udfa8 Speed, Zone size 40 Scanner Dot moves between ends, leaving behind a fading trail \u22ee \ud83c\udfa8 Fx, Bg Speed, Fade rate 41 Lighthouse Dot moves from start to end, leaving behind a fading trail \u22ee \ud83c\udfa8 Fx, Bg Speed, Fade rate 42 Fireworks Random color blobs light up, then fade again \u22ee \u25a6 \ud83c\udfa8 Fx, Bg Frequency 43 Rain Like Fireworks, but the blobs move \u22ee \u25a6 \ud83c\udfa8 Fx, Bg Speed, Spawning rate 44 Tetrix Falling blocks stack \u22ee \ud83c\udfa8 Fx, Bg Speed, Width, One color 45 Fire Flicker LEDs randomly flickering \u22ee \ud83c\udfa8 Fx Speed, Intensity 46 Gradient Moves a saturation gradient of the primary color along the strip \u22ee \ud83c\udfa8 Fx, Bg Speed, Spread 47 Loading Moves a sawtooth pattern along the strip \u22ee \ud83c\udfa8 Fx, Bg Speed, Fade 49 Fairy Inspired by twinkle style Christmas lights. \u22ee \ud83c\udfa8 Fx, Bg Speed, # of flashers 50 Two Dots Two areas sweeping \u22ee \ud83c\udfa8 1, 2, Bg Speed, Dot size, Overlay 51 Fairytwinkle Like Colortwinkle, but starting from all lit \u22ee \ud83c\udfa8 Fx, Bg Speed, Intensity 52 Running Dual Sine waves in both directions \u22ee \ud83c\udfa8 L, Bg, R Speed, Wave width 54 Chase 3 Like Chase, but with 3 colors \u22ee \ud83c\udfa8 1, 2, 3 Speed, Size 55 Tri Wipe Like Wipe but turns LEDs off as \"third color\" \u22ee \ud83c\udfa8 1, 2, 3 Speed 56 Tri Fade Fades the whole strip from primary color to secondary color to off \u22ee \ud83c\udfa8 1, 2, 3 Speed 57 Lightning Short random white strobe similar to a lightning bolt \u22ee \ud83c\udfa8 Fx, Bg Speed, Intensity, Overlay 58 ICU Two \"eyes\" running on opposite sides of the strip \u22ee \ud83c\udfa8 Fx, Bg Speed, Intensity, Overlay 59 Multi Comet Like Scanner, but creates multiple trails \u22ee 60 Scanner Dual Like Scanner, but with two dots running on opposite sides \u22ee \ud83c\udfa8 Fx, Bg, Cs Speed, Fade rate 61 Stream 2 Flush random hues along the string \u22ee Speed 62 Oscillate Areas of primary and secondary colors move between opposite ends, combining colors where they touch \u22ee 63 Pride 2015 Rainbow cycling with brightness variation \u22ee Speed 64 Juggle Eight colored dots running, leaving trails \u22ee \ud83c\udfa8 Speed, Trail 65 Palette Running color palette \u22ee \ud83c\udfa8 Cycle speed 66 Fire 2012 Simulates flickering fire in red and yellow \u22ee \ud83c\udfa8 Cooling, Spark rate, Boost 67 Colorwaves Like Pride 2015, but uses palettes \u22ee \ud83c\udfa8 Fx Speed, Hue 68 Bpm Pulses moving back and forth on palette \u22ee \ud83c\udfa8 Fx Speed 69 Fill Noise Noise pattern \u22ee \ud83c\udfa8 Fx Speed 70 Noise 1 Fast Noise shift pattern \u22ee \ud83c\udfa8 Fx Speed 71 Noise 2 Fast Noise shift pattern \u22ee \ud83c\udfa8 Fx Speed 72 Noise 3 Noise shift pattern \u22ee \ud83c\udfa8 Fx Speed 73 Noise 4 Noise sparkle pattern \u22ee \ud83c\udfa8 Fx Speed 74 Colortwinkles LEDs light up randomly in random colors and fade off again \u22ee \ud83c\udfa8 Fade speed, Spawn speed 75 Lake Calm palette waving \u22ee \ud83c\udfa8 Fx Speed 76 Meteor The primary color creates a trail of randomly decaying color \u22ee \ud83c\udfa8 Fx Speed, Trail length 77 Meteor Smooth Smoothly animated meteor \u22ee \ud83c\udfa8 Fx Speed, Trail length 78 Railway Shows primary and secondary color on alternating LEDs. All LEDs fade to their opposite color and back again \u22ee \ud83c\udfa8 1, 2 Speed, Smoothness 79 Ripple Effect resembling random water ripples \u22ee \u25a6 \ud83c\udfa8 Bg Speed, Wave #, Overlay 80 Twinklefox FastLED gentle twinkling with slow fade in/out \u22ee \ud83c\udfa8 Speed, Twinkle rate 81 Twinklecat Twinkling with fast in / slow out \u22ee \ud83c\udfa8 Speed, Twinkle rate 82 Halloween Eyes One Pair of blinking eyes at random intervals along strip \u22ee \u25a6 \ud83c\udfa8 Fx, Bg Duration, Eye fade time, Overlay 83 Solid Pattern Speed sets number of LEDs on, intensity sets off \u22ee \ud83c\udfa8 Fg, Bg Fg size, Bg size 84 Solid Pattern Tri Solid Pattern with three colors \u22ee 1, 2, 3 Size 85 Spots Solid lights with even distance \u22ee \ud83c\udfa8 Fx, Bg Width, Overlay 86 Spots Fade Spots, getting bigger and smaller \u22ee \ud83c\udfa8 Fx, Bg Spread, Width, Overlay 87 Glitter Rainbow with white sparkles \u22ee \ud83c\udfa8 1, 2, Glitter color Speed, Intensity, Overlay 88 Candle Flicker resembling a candle flame \u22ee \ud83c\udfa8 Fx, Bg Speed, Intensity 89 Fireworks Starburst Exploding multicolor fireworks \u22ee \ud83c\udfa8 Bg Chance, Fragments, Overlay 90 Fireworks 1D one dimension fireworks with flare \u22ee \u25a6 \ud83c\udfa8 Fx, Bg Gravity, Firing side 91 Bouncing Balls Bouncing ball effect \u22ee \ud83c\udfa8 Fx, Bg, Cs Gravity, # of balls, Overlay 92 Sinelon Fastled sinusoidal moving eye \u22ee \ud83c\udfa8 Fx, Bg, Cs Speed, Trail 93 Sinelon Dual Sinelon from both directions \u22ee \ud83c\udfa8 Fx, Bg, Cs Speed, Trail 94 Sinelon Rainbow Sinelon in rainbow colours \u22ee \ud83c\udfa8 Cs Speed, Trail 95 Popcorn popping kernels \u22ee \ud83c\udfa8 Fx, Bg, Cs Speed, Intensity, Overlay 96 Drip Water dripping effect \u22ee \ud83c\udfa8 Fx, Bg Gravity, # of drips, Overlay 97 Plasma Plasma lamp \u22ee \ud83c\udfa8 Fx Phase, Intensity 98 Percent Lights up a percentage of segment \u22ee \ud83c\udfa8 Fx, Bg % of fill, One color 99 Ripple Rainbow Like ripple, but with a dimly lit changing background \u22ee \u25a6 \ud83c\udfa8 Speed, Wave # 100 Heartbeat led strip pulsing rhythm similar to a heart beat \u22ee \ud83c\udfa8 Fx, Bg Speed, Intensity 101 Pacifica Gentle ocean waves \u22ee \ud83c\udfa8 Speed, Angle 102 Candle Multi Like candle effect, but each LED has it's own flicker pattern \u22ee \ud83c\udfa8 Fx, Bg Speed, Intensity 103 Solid Glitter Like Glitter, but with solid color background \u22ee Bg, Glitter color Intensity 104 Sunrise Simulates a gradual sunrise or sunset. Speed sets: 0 - static sun, 1 - 60: sunrise time in minutes,60 - 120: sunset time in minutes - 60, above: \"breathing\" rise and set \u22ee \ud83c\udfa8 Time [min], Width 105 Phased Sine waves (in sourcecode) \u22ee \ud83c\udfa8 Fx, Bg Speed, Intensity 106 Twinkleup Twinkle effect with fade-in \u22ee \ud83c\udfa8 Fx, Bg Speed, Intensity 107 Noise Pal Peaceful noise that's slow and with gradually changing palettes \u22ee \ud83c\udfa8 Speed, Scale 108 Sine Controllable sine waves \u22ee 109 Phased Noise Noisy sine waves \u22ee \ud83c\udfa8 Fx, Bg Speed, Intensity 110 Flow Blend of palette and spot effects \u22ee \ud83c\udfa8 Speed, Zones 111 Chunchun Birds flying in a circle formation \u22ee \ud83c\udfa8 Fx, Bg Speed, Gap size 112 Dancing Shadows Moving spotlights \u22ee \ud83c\udfa8 Fx Speed, # of shadows 113 Washing Machine Spins, slows, reverses directions \u22ee \ud83c\udfa8 Speed, Intensity 115 Blends Blends random colors across palette \u22ee \ud83c\udfa8 Shift speed, Blend speed 116 TV Simulator TV light spill simulation \u22ee Speed, Intensity 117 Dynamic Smooth Like Dynamic, but with smooth palette blends \u22ee \ud83c\udfa8 Speed, Intensity 118 Spaceships Circling ships with fading trails. Homage to 80s spaceship shooter games. \u25a6 \ud83c\udfa8 Speed, Blur 119 Crazy Bees Bees darting from flower to flower. \u25a6 Speed, Blur 120 Ghost Rider Color changing ghost riding a kite... in a tornado. \u25a6 \ud83c\udfa8 Fade rate, Blur 121 Blobs No really, they are blobs. \u25a6 \ud83c\udfa8 Fx Speed, # blobs, Blur 122 Scrolling Text Edit segment name to set text (#DATE and #TIME to include those) \u25a6 \ud83c\udfa8 Fx, Bg, Gradient Speed, Y Offset, Trail, Font size, Gradient, Overlay 123 Drift Rose Spinning arms that adds and removes nodes as it winds and unwinds. \u25a6 Fade, Blur 124 Distortion Waves Distorted sine waves with a psychedelic flair. \u25a6 Speed, Scale 125 Soap Like soap bubbles, but lasts longer. \u25a6 \ud83c\udfa8 Speed, Smoothness 126 Octopus A cephalopod stuck in a whirlpool. \u25a6 \ud83c\udfa8 Speed, Offset X, Offset Y, Legs 127 Waving Cell If a bunch of eucaryotes went to a sports stadium and did the wave, it would look exactly like this. \u25a6 \ud83c\udfa8 Speed, Amplitude 1, Amplitude 2, Amplitude 3 128 Pixels Random pixels \u22ee \u266a \ud83c\udfa8 Fx, Bg Fade rate, # of pixels 129 Pixelwave Pixels emanating from center \u22ee \u266a \ud83c\udfa8 Fx, Bg Speed, Sensitivity 130 Juggles Juggling balls. \u22ee \u266a \ud83c\udfa8 Fx, Bg Speed, # of balls 131 Matripix Similar to Matrix. \u22ee \u266a \ud83c\udfa8 Fx, Bg Speed, Brightness 132 Gravimeter Volume reactive vu-meter with gravity and perlin noise. \u22ee \u266a \ud83c\udfa8 Fx, Bg Rate of fall, Sensitivity 133 Plasmoid Sine wave based plasma. \u22ee \u266a \ud83c\udfa8 Fx, Bg Phase, # of pixels 134 Puddles Blast coloured puddles based on volume. \u22ee \u266a \ud83c\udfa8 Fx, Bg Fade rate, Puddle size 135 Midnoise Perlin noise emanating from center. \u22ee \u266a \ud83c\udfa8 Fx, Bg Fade rate, Max. length 136 Noisemeter Volume reactive vu-meter. \u22ee \u266a \ud83c\udfa8 Fx, Bg Fade rate, Width 137 Freqwave Maps the major frequencies from the incoming signal to colors in the HSV color space. \u22ee \u266b Time delay, Sound effect, Low bin, High bin, Pre-amp 138 Freqmatrix The temporal tail for this animation starts at the beginning of the Segment rather than in the center of the segment. \u22ee \u266b Time delay, Sound effect, Low bin, High bin, Sensivity 139 GEQ A 16x16 graphic equalizer. \u25a6 \u266b \ud83c\udfa8 Fx, Peaks Fade speed, Ripple decay, # of bands, Color bars 140 Waterfall A volume AND FFT version of a Waterfall that has 'beat' support. \u22ee \u266b \ud83c\udfa8 Fx, Bg Speed, Adjust color, Select bin, Volume (min) 141 Freqpixels Random pixels coloured by frequency. \u22ee \u266b Fade rate, Starting color and # of pixels 143 Noisefire A perlin noise based volume reactive fire routine. \u22ee \u266a Speed, Intensity 144 Puddlepeak Blast coloured puddles randomly up and down the strand with the 'beat'. \u22ee \u266a \ud83c\udfa8 Fx, Bg Fade rate, Puddle size, Select bin, Volume (min) 145 Noisemove Using perlin noise as movement for different frequency bins. \u22ee \u266b \ud83c\udfa8 Fx, Bg Speed of perlin movement, Fade rate 146 Noise2D \u25a6 \ud83c\udfa8 Speed, Scale 147 Perlin Move Using Perlin Noise for movement. \u22ee \ud83c\udfa8 Fx, Bg Speed, # of pixels, Fade rate 148 Ripple Peak Peak detection triggers ripples. \u22ee \u266a \ud83c\udfa8 Fx, Bg Fade rate, Max # of ripples, Select bin, Volume (min) 149 Firenoise Using Perlin Noise for fire. \u25a6 \ud83c\udfa8 X scale, Y scale 150 Squared Swirl Boxes moving around \u25a6 \ud83c\udfa8 Blur 152 DNA A very cool DNA like pattern. \u25a6 \ud83c\udfa8 Scroll speed, Blur 153 Matrix The Matrix, on a 2D matrix. \u25a6 Spawn, Trail Speed, Spawning rate, Trail, Custom color 154 Metaballs A cool plasma type effect. \u25a6 \ud83c\udfa8 Speed 155 Freqmap Map the loudest frequency throughout the length of the LED's. \u22ee \u266b \ud83c\udfa8 Fx, Bg Fade rate, Starting color 156 Gravcenter Volume reactive vu-meter from center with gravity and perlin noise. \u22ee \u266a \ud83c\udfa8 Fx, Bg Rate of fall, Sensitivity 157 Gravcentric Volume reactive vu-meter from center with gravity. Volume provides index to (time rotating) palette colour. \u22ee \u266a \ud83c\udfa8 Fx, Bg Rate of fall, Sensitivity 158 Gravfreq VU Meter from center. Log of frequency is index to center colour. \u22ee \u266b \ud83c\udfa8 Fx, Bg Rate of fall, Sensivity 159 DJ Light An effect emanating from the center to the edges. \u22ee \u266b Speed 160 Funky Plank A 2D wall of reactivity running from bottom to top \u25a6 \u266b Scroll speed, # of bands 162 Pulser Travelling waves. \u25a6 \ud83c\udfa8 Speed, Blur 163 Blurz Flash an fftResult bin per frame and then blur/fade. \u22ee \u266b \ud83c\udfa8 Fx, Color mix Fade rate, Blur 164 Drift A rotating kaleidoscope. \u25a6 \ud83c\udfa8 Rotation speed, Blur amount 165 Waverly Noise waves with some sound. \u25a6 \u266a \ud83c\udfa8 Amplification, Sensitivity 166 Sun Radiation The sun! Doesn't support segments. \u25a6 Variance, Brightness 167 Colored Bursts Rotating rays of color. \u25a6 \ud83c\udfa8 Speed, # of lines, Blur, Gradient, Dots 168 Julia Animated Julia set fractal named after mathematician Gaston Julia. \u25a6 \ud83c\udfa8 Fx Max iterations per pixel, X center, Y center, Area size 172 Game Of Life Scrolling game of life. \u25a6 \ud83c\udfa8 Fx, Bg Speed 173 Tartan Plaid pattern of horizontal and vertical bands. Makes a great kilt. \u25a6 \ud83c\udfa8 X scale, Y scale 174 Polar Lights The northern lights. \u25a6 Speed, Scale 175 Swirl Several blurred circles. Looks good with pink plasma palette. Supports AGC. \u25a6 \u266a \ud83c\udfa8 Bg Swirl Speed, Sensitivity, Blur 176 Lissajous A frequency based Lissajous pattern. \u25a6 \ud83c\udfa8 Fx X frequency, Fade rate 177 Frizzles Moving patterns. \u25a6 \ud83c\udfa8 X frequency, Y frequency, Blur 178 Plasma Ball A ball of plasma. \u25a6 \ud83c\udfa8 Speed, Fade, Blur 179 Flow Stripe Strip with rotating colours. \u22ee Hue speed, Effect speed 180 Hiphotic A moving plasma. \u25a6 \ud83c\udfa8 Fx X scale, Y scale, Speed 181 Sindots Dots revolving in a circle while the 'camera' \u25a6 \ud83c\udfa8 Speed, Dot distance, Fade rate, Blur 182 DNA Spiral Spiraling DNA pattern \u25a6 \ud83c\udfa8 Scroll speed, Y frequency 183 Black Hole Colorful dots orbiting a white black hole. \u25a6 Fade rate, Outer Y freq., Outer X freq., Inner X freq., Inner Y freq. 184 Wavesins Beat waves and phase shifting. Looks OK in 2D'ish as well. \u22ee \ud83c\udfa8 Fx Speed, Brightness variation, Starting color, Range of colors, Color variation 185 Rocktaves Colours the same for each note between octaves, with sine wave going back and forth. \u22ee \u266b \ud83c\udfa8 Fx, Bg 186 Akemi The WLED mascot rocking to your tunes. \u25a6 \u266b Head palette, Arms & Legs, Eyes & Mouth Color speed, Dance"},{"location":"features/effects/#retired-effects","title":"Retired Effects","text":"Some effects get retired when they can be recreated with newer, more general effects.
Removed Effect Replacement Retired After Candy Cane Chase 2 0.14.0 Dissolve Rnd Dissolve 0.14.0 Dynamic Smooth Dynamic 0.14.0 Halloween Chase 2 0.14.0 Merry Christmas Chase 2 - red/green 0.12.0 Police Two Dot 0.14.0 Police All Two Dots - red/blue w/ full intensity 0.13.0 Two Areas Two Dots - full intensity 0.13.0"},{"location":"features/macros/","title":"Macros","text":"Info
Also see Presets for 0.11.0+.
You are able to set custom actions (\"Macros\") in Time & Macro settings for the following events:
- Specific time of day
- Button short/long/double press
- HTTP API call executing a macro with
&M= - Alexa On/Off
- Countdown over
- Timed light duration over
- Device (re)boot (up to 0.10.2, use LED settings
Boot preset in 0.11)
Each macro has the format of a standard HTTP API call without the IP. Optionally, the \"win&\" may be omitted. For example, the macro \"A=255\" sets the brightness to maximum. \"R=255&G=160&B=0\" sets the color to orange. You can specify up to 16 macros. (up to 250 in WLED 0.11 since the Macro functionality has been merged into the Presets feature)
Examples of how to use API-calls and define macros can be found in this issue and in this one.
The simplest macro example is getting a button to do your bidding. The default pin to which a button can be connected is GPIO 0 (D3 on NodeMCU, D1 Mini and others). Even though WLED uses the internal pull up resistors on input pins, this pin is ideally externally pulled high to 3.3V with a 10k resistor. The configured macro executes when the pin is pulled low (grounded). The desired macro is entered on the Time/Macros configuration page and then assigned to a short, long or double press. Like this:
The \"T=2\" macro toggles power to the LEDs (in this case long press). The \"FX=~\" macro steps through the effects (in this case short press).
You can set a preset to P1=1&P2=3&PL=~, enter the preset number for your button, and this will step through presets 1 and 3. Change the \"3\" to whatever your highest preset is that you want to include.
The default (built-in) actions for button 0 are short-press: toggle on/off and long-press: select random color. Long-pressing for more than 6 seconds will open the WLED-AP with the default password (wled1234). For further buttons, the default action for short press is cycling effects, long press ramp brightness, and double press cycle palettes.
"},{"location":"features/macros/#buttons","title":"Buttons","text":"Multiple buttons are implemented since 0.13 and allow a few different types of buttons to be connected to the ESP:
- momentary push-buttons that are normally open and short GPIO pin to ground (active low)
- momentary push-buttons that are normally closed and release the connection from GPIO pin to GND (inverted, active high)
- switches (be careful with selection of GPIO for switch since some GPIOs will prevent successful boot of ESP if held LOW or HIGH at boot)
- PIR switch AKA motion detection sensor (they set GPIO HIGH when motion is detected, this type of buttons will also trigger MQTT message with /motion topic if \"Publish on button press\" is set on MQTT config)
- some GPIO pins on ESP32 can act as momentary touch buttons with no additional hardware
- analog \"buttons\" (also with inverted logic) those can be used as potentiometers or analog input buttons
Button GPIO pin and type can be selected in the LED Settings page.
Each momentary button can have 3 different Presets assigned, for short press, long press or double press. Momentary push-buttons by default trigger shortly after the release of a button, to be able to detect if it has been pressed short, long or twice. When configuring the same preset number for short, long and double press, it will trigger directly when being pressed as of WLED 0.14.0-b2-2306020.
For switch type buttons you can assign only 2 presets, one for transition of switch from LOW to HIGH and second for the opposite transition from HIGH to LOW.
Selecting 0 for preset will use the default action. If you find that the default action is inverted for switch, please create presets for On and Off actions and assign them appropriately.
For assigning Presets to buttons use Time & Macros settings page.
Note: Button 0 has two, built-in functions. 1. Hold it down for >6 seconds and the Wi-Fi settings will be reset to default. 2. Hold it down for >12 seconds and flash memory is erased.
"},{"location":"features/macros/#analog-button","title":"Analog button","text":"Starting in WLED 0.13, analog \"buttons\" (e.g. a potentiometer) are supported. With the Short and Long columns set to 0, set the Double column in Button Actions to one of these values to configure:
Property Value Global brightness 250 Effect speed 249 Effect intensity 248 Palette 247 Primary color hue 200 Segment N opacity 0-32 This potentiometer should be supplied 3.3V and GND, with it's output supplied to A0 (or any other ADC pin you specify), recommended 10K\u03a9 or greater.
Do not use ESP32 ADC2 GPIO pins for analog buttons
On ESP8266, you can only have a single analog button on pin A0, the pin set in the settings UI is ignored. On ESP32, only ADC1 pins will work for analog input while WiFi is active (pins 32-39). ADC2 pins will not work.
"},{"location":"features/macros/#global-brightness","title":"Global brightness","text":"Users planning to use a potentiometer for global brightness should be aware that wled is configured to turn off when the potentiometer is adjusted to either extreme - both maximum and minimum adjustments. Users who desire to disable this functionality may do so on the hardware side by adding resistors between the potentiometer and the rails.
Adding a resistor between the potentiometer and 3.3V prevents A0 from fully reaching 3.3V and allows the potentiometer to be adjusted to the maximum adjustment without powering off wled. A value of 7.5%-10% of the potentiometer value should be sufficient for this (~750\u03a9 for a 10K\u03a9 potentiometer). Similarly, added resistance between the potentiometer and GND prevents A0 from reaching 0V, and allows the potentiometer to be adjusted to the minimum adjustment without powering off wled. A value of 3-5% of the potentiometer value should be sufficient (~500\u03a9 for a 10K\u03a9 potentiomenter).
In both instances, the added resistances will slightly reduce the overall adjustment range, with a larger reduction for larger resistor choices. As such, A user who desires the maximum possible adjustment range should determine their needed resistance values experimentally by installing the potentiometer, adjusting for stable behavior at the desired extrema, measuring the voltage on A0, using the voltage divider equation to determine the optimal resistance, then retesting for confirmation.
"},{"location":"features/multi-strip/","title":"Multi-strip Support","text":""},{"location":"features/multi-strip/#multi-strip-support","title":"Multi strip support","text":"Starting in WLED 0.12.0, you are able to use multiple LED outputs from one ESP board! Pins and LED numbers can be easily configured in LED settings, you don't need to re-compile code for your specific setup. Custom binaries for multiple pins are now also a thing of the past!
There are a few tips and recomendations to keep in mind when designing your setup:
"},{"location":"features/multi-strip/#general","title":"General","text":" - It is highly recommended to use an ESP32 when using more than 1 output
- You may freely choose the LEDs type, pin numbers, length and color order of your LED strips at runtime in the LED settings page
- Highly recommeded to size power supply correctly according to your setup and disable the WLED brightness limiter setting to increase framerate with very large LED counts
- Most strip types have yet to be tested. Add confirmed working below:
- Confirmed working: WS281x, SK6812 RGBW, PWM white
"},{"location":"features/multi-strip/#esp8266","title":"ESP8266","text":" - There is a maximum of 3 strips supported.
- It is highly recommended to use two specific LED pins, GPIO1 (TX) and GPIO2 (D4), since they allow for hardware driving.
- It is recommended to use 512 LEDs/pin for good performance for a total of 1024 LEDs.
- 800 LEDs/pin for a total of 1600 has been confirmed working, but is not recommended for good performance and reliability.
- Using GPIO1 will disable serial debugging. If you need it, you can't use a strip on this pin.
- GPIO3 (RX) is the third pin that allows hardware driving on ESP8266. However, it uses 5 times as much memory per LED as GPIO 1 and 2, so use it only for low LED counts (recommended <50)
- You can use any other pin, but it will use the bitbang method, which is not recommended for reliability. It is best to stick to GPIO 1, 2, and if need be, 3.
- Using pin GPIO16 for WS2812b LEDs did not work in my testing.
- ESP8266 can calculate about 15k LEDs per second (that means 250LEDs @~60fps, 500 LEDs @~30fps, 1000 LEDs @~15fps)
- The LED settings will give you a bar that shows how much memory you can allocate.
"},{"location":"features/multi-strip/#esp32","title":"ESP32","text":" - There is a maximum of 10 strips supported
- Contrary to the ESP8266, the pin usage does not matter on ESP32, feel free to use any available pin
- For perfect performance, it is recommeded to use 512 LEDs/pin with 4 outputs for a total of 2048 LEDs.
- For very good performance, it is recommended to use 800 LEDs/pin with 4 outputs for a total of 3200 LEDs.
- For good performance, you can use 1000 LEDs/pin with 4 outputs for a total of 4000 LEDs.
- For okay performance, you can use 1000 LEDs/pin with 5 outputs for a total of 5000 LEDs.
- For okay performance, you can use 800 LEDs/pin with 6 outputs for a total of 4800 LEDs.
- ESP32 can calculate about 65k-85k LEDs per second (that means 1000 LEDs @~70fps, 2000 LEDs @~35fps, 4000 LEDs @~18fps)
- 4 outputs seem to be the sweet spot.
"},{"location":"features/multi-strip/#virtual-leds-ddp","title":"Virtual LEDs (DDP)","text":"See Virtual Leds
"},{"location":"features/palettes/","title":"Palettes","text":"Version Info
Beginning in 0.14 up to 10 Custom Palletes can be uploaded.
PaletteID Name Description 0 Default The palette is automatically selected depending on the effect. For most effects, this is the primary color 1 Random Cycle The palette changes to a random one every few seconds. Subject to change 2 Color 1 A palette consisting only of the primary color 3 Colors 1 & 2 Consists of the primary and secondary color 4 Color Gradient A palette which is a mixture of all segment colors 5 Colors Only Contains primary, secondary and tertiary colors 6 Party Rainbow without green hues 7 Cloud Gray-blueish colors 8 Lava Dark red, yellow and bright white 9 Ocean Blue, teal and white colors 10 Forest Yellow and green hues 11 Rainbow Every hue 12 Rainbow bands Rainbow colors with black spots in-between 13 Sunset Dark blue with purple, red and yellow hues 14 Rivendell Desaturated greens 15 Breeze Teal colors with varying brightness 16 Red & Blue Red running on blue 17 Yellowout Yellow, fading out 18 Analoguous Red running on blue 19 Splash Vibrant pink and magenta 20 Pastel Different hues with very little saturation 21 Sunset 2 Yellow and white running on dim blue 22 Beech Different shades of light blue 23 Vintage Warm white running on very dim red 24 Departure Greens and white fading out 25 Landscape Blue, white and green gradient 26 Beach Teal and yellow gradient fading out 27 Sherbet Bright white, pink and mint colors 28 Hult White, magenta and teal 29 Hult 64 Teal and yellow hues 30 Drywet Blue and yellow gradient 31 Jul Pastel green and red 32 Grintage Yellow fading out 33 Rewhi Bright orange on desaturated purple 34 Tertiary Red, green and blue gradient 35 Fire White, yellow and fading red gradient 36 Icefire Same as Fire, but with blue colors 37 Cyane Desaturated pastel colors 38 Light Pink Desaturated purple hues 39 Autumn Three white fields surrounded by yellow and dim red 40 Magenta White with magenta and blue 41 Magred Magenta and red hues 42 Yelmag Magenta and red hues with a yellow 43 Yelblu Blue with a little yellow 44 Orange & Teal An Orange - Gray - Teal gradient 45 Tiamat A bright meteor with blue, teal and magenta hues 46 April Night Dark blue background with colorful snowflakes 47 Orangery Orange and yellow tones 48 C9 Christmas lights palette. Red - amber - green - blue 49 Sakura Pink and rose tones 50 Aurora Greens on dark blue 51 Atlantica Greens & Blues of the ocean 52 C9 2 C9 plus yellow 53 C9 New C9, but brighter and with a less purple blue 54 Temperature Temperature mapping 55 Aurora 2 Aurora with some pinks & blue 56 Retro Clown Yellow to purple gradient 57 Candy Vivid yellows, magenta, salmon and blues 58 Toxy Reaf Vivid aqua to purple gradient 59 Fairy Reaf Bright aqua to purple gradient 60 Semi Blue Dark blues with a bright blue burst 61 Pink Candy White, pinks and purple 62 Red Reaf Blue, aqua and red gradient 63 Aqua Flash Aqua gradient with a flash of yellow and white 64 Yelblu Hot Yellow, red, blue spectrum 65 Lite Light Faint white and purple 66 Red Flash Red gradient with burst of white in the center 67 Blink Red Dark blue to dark red gradient with burst of purple 68 Red Shift Vibrant yellow to blue gradient with magenta, purple and red 69 Red Tide Waves of yellow, orange and red 70 Candy2 Faded gradient of yellow, salmon and blue"},{"location":"features/palettes/#custom-palettes","title":"Custom Palettes","text":"As of 0.14, up to 10 custom palettes can be uploaded by the user in JSON files named palette0.json through palette9.json The format closely resembles that of the palettes defined in palettes.h with a position (0-255), red, green, blue for each color. An example of the content would be:
{\"palette\":[ \n 0, 255, 33, 4, \n 43, 255, 68, 25,\n 86, 255, 7, 25,\n 127, 255, 82, 103,\n 170, 255, 255, 242,\n 209, 42, 255, 22,\n 255, 87, 255, 65]}\n
Once a palette[0-9].json file has been created, it can be uploaded to the controller using the /edit page (http://[controller-ip]/edit). The controller must be rebooted (/win&RB) before the newly uploaded palettes will be available. After reboot, the custom palette(s) will be named ~ Custom [0-9] ~ in the Palettes section of the user interface.
"},{"location":"features/pixel-art-converter/","title":"Pixel Art Converter","text":"The Pixel Art Converter tool aims to make it easier to show pixel art on a LED matrix panel, by converting any image to 2D pixel art and sending it to the WLED device. The file types PNG, JPG, WEBP and GIF have been tested to work with the tool.
"},{"location":"features/pixel-art-converter/#installation-approaches","title":"Installation Approaches","text":"There are three ways to install the pixel art converter:
- Local web browser. Will a web page run on the local machine connecting to the WLED device but will require fetching an extra file. Supported from WLED release v0.14.0-b1 or later
- Include the pixel art converter in the binary and compile it from the source code. Allows access to the pixel art converter on any device that has a connection to the WLED device. Supported from WLED release v0.14.0-b2 (PR #3042)
- WLED editor mode. Upload the web page to your WLED device while it is running
"},{"location":"features/pixel-art-converter/#approach-1-local-browser","title":"Approach 1: Local Browser","text":" - Download the
pixartmin.htm from the WLED-PixelArtConverter repository - Open
pixartmin.htm in a browser - Head over to the Setup 2D Matrix point
"},{"location":"features/pixel-art-converter/#approach-2-include-pixart-converter-in-build-files","title":"Approach 2: Include Pixart Converter In Build Files","text":"Compilation required
Compiling WLED from the source code is required. Follow the instructions on compiling WLED to do this.
- Follow the instructions under Making a custom environment and set the flag
-D WLED_ENABLE_PIXART under the line that starts with build_flags = in platformio_override.ini - Compile and flash the binary to the ESP board
- Power on board and connect via WiFi using the default login
- It is now time to Setup the 2D Matrix
"},{"location":"features/pixel-art-converter/#approach-3-wled-editor-mode","title":"Approach 3: WLED Editor Mode","text":"Network connection
A network connection is required to connect to the CDN, hosting the JS library Ace, an embedded code editor.
- Download the
pixartmin.html file from the WLED-PixelArtConverter repository - Go to the URL
http://[device_ip_address]/edit - Upload the
pixartmin.html file using the UI - Go to
http://[device_ip_address]/pixartmin.html - Now head to the Setup 2D Matrix point
"},{"location":"features/pixel-art-converter/#setup-2d-matrix","title":"Setup 2D Matrix","text":"2D LED panels are natively supported by WLED but need some configuration for the software to show the 2D grid correctly.
- Head into the
2D Configuration settings menu in WLED - Set the option \"Strip or panel\" to
2D Matrix - Setup rest of the LED panel layout according to the specifics of your LED panel
Serpentine option
Setting the serpentine LED panel option incorrectly can lead to very confusing results that look almost correct but not quite. Enabling or Disabling the option depends on the characteristics of the 2D matrix
"},{"location":"features/pixel-art-converter/#usage","title":"Usage","text":"The Pixel Art Generator does not yet have a link in the WLED front-end, therefore head over to the web page: http://[device_ip_address]/pixart.htm (default DHCP IP-address link).
On the web page:
- Set the option \"LED setup\" to 2D matrix or serpentine accordingly.
-
Select an image that should be shown on the matrix display
This example uses a 16x16 pixel, happy version of the WLED mascot Akemi by Aircoookie.
-
A preview is displayed further down the web page.
Scaling option
It can help to use the Scale image option, depending on the image size used.
-
Click on \"Send to device\" to push the generated image to the WLED device.
"},{"location":"features/presets/","title":"Presets","text":"Presets can be used to save your favorite light configurations to apply later! You can compare them to the \"scenes\" feature present in some other smart devices.
"},{"location":"features/presets/#new-version-011","title":"New version (0.11+)","text":""},{"location":"features/presets/#overview","title":"Overview","text":"WLED 0.11.0 contains a major overhaul of presets, storing them in a /presets.json file in an internal filesystem. This enables many new features, you can now have up to 250 presets and each of them can save all segments which are set up! Speaking of segments, the maximum number has been increased to 12 on ESP8266 and 16 on ESP32! Presets can now also contain both HTTP and JSON API commands, replacing the previous Macro functionality. Each preset can be named, so you'll be able to access it more easily!
"},{"location":"features/presets/#how-to-use","title":"How to use","text":"The new preset system is quite a bit more advanced than the previous one, thus it is likely not as self-explanatory to use. Here you can find what each setting does and how to make best use of it!
\"Create Preset\" button Use this to save the current state as a permanent preset, or to add a new API macro.
Preset name Enter a nice name for your preset here. I would recommend putting something short, but to the point here, like Epic fireworks or Slow fade. All special characters and emoji are permitted (however, there must not be more than 6 consecutive whitespaces) If you leave this empty, you'll get a name based on the preset ID number, like Preset 16.
Quick load label You can optionally add a short label up to 2 characters or 1 emoji long. It will show up in a small circle on top of the preset list for extra quick access without scrolling! I recommend using this for the presets you truly love.
Use current state/Overwrite with state This is enabled by default when adding a new preset and disabled when editing an existing preset. When enabled, it will write the current segment config, including all colors and effect, to the preset. When disabled, it will instead give you a textfield to enter a custom API command or show you the command currently saved.
Include brightness If disabled, the brightness value is not included in the preset. This can be useful e.g. when you want to control the brightness manually and want the preset to only set the effect.
Save segment bounds This is an important one. Make sure it is enabled for your boot preset, so that your segment config is properly restored on boot! When disabled, the segment start and stop LEDs are not included in the preset. This can be useful if you plan to make changes to your segment setup and don't want your presets to always reset it to the point it was when the preset was saved.
API command This accepts any HTTP or JSON API command! (only visible if the current state checkbox is unchecked) It replaces the previous macro functionality. If you know your JSON, you can even create playlists of other presets!
Save to ID This is the ID the preset will be saved to. When creating a new preset, you likely won't have to change it as the lowest unused ID will be chosen automatically. If you change the ID on an existing preset and save, you can copy it to the new ID - change the name though.
Save and Delete buttons Now these are self-explanatory, but I said I'd cover each point :)
ID This is the number you'll want to use to apply this preset from a timed macro or automation!
"},{"location":"features/presets/#a-note-on-performance","title":"A note on performance","text":"This new preset system is quite fast where it matters, reading the presets. Applying a preset will typically take less than a tenth of a second.
However, due to a design choice of the LittleFS filesystem used by WLED, random writes to the preset file are very resource intensive. This means that while updating your presets, you might notice your light freezing and becoming unresponsive for up to a few seconds. Adding new presets is usually very fast, those performance issues will occur once you delete/edit/overwrite older presets and your preset file becomes very large, or when adding presets after deleting older ones.
I'm looking into ways to mitigate this situation as soon as possible! Meanwhile, to keep things snappy, I would recommend not having more than 50-ish single segment or a dozen of multi-segment presets.
"},{"location":"features/presets/#what-about-my-cool-presets-from-earlier-versions","title":"What about my cool presets from earlier versions?","text":"Don't worry, they (as well as your settings) will be automatically imported to the new system! And if you ever need to downgrade to v0.10 for some reason, they will still be there (although any changes made in v0.11 won't be applied)
"},{"location":"features/presets/#obtaining-preset-list","title":"Obtaining preset list","text":"Obtaining the preset list is possible with the /presets.json file Seeing the name of the current preset with the API only is not possible, you can only obtain its ID. Then you'd need some code to match it with the entries from presets.json (this is also what the UI does). See section \"Backing up/restoring presets\".
"},{"location":"features/presets/#saving-named-presets","title":"Saving named presets","text":"Save a named preset with {\"psave\":<preset number here>;\"n\":\"Preset name\",\"ib\":true,\"sb\":true}
"},{"location":"features/presets/#backing-uprestoring-presets","title":"Backing up/restoring presets","text":"To backup all presets, go to [WLED-IP]/edit (OTA lock must be off), right click the presets.json file and download! To restore, use the Choose file and Upload buttons.
"},{"location":"features/presets/#applying-presets-at-a-certain-time-of-day","title":"Applying presets at a certain time of day","text":"Tip
If you want to create a preset that turns on the light to the last effect displayed, uncheck Use current state and enter T=1 into the API Command field.
WLED supports schedules - that is, applying presets at a certain time automatically. Here is a simple guide to get it set up quickly!
- Creates the preset(s) you want to load at specific time(s)
- Note the preset ID - the small gray number to the left of the preset name (or, in the bottom of the preset menu)
- Go to the
Time & Macros section in the WLED settings. - Make sure the time displayed is correct and accurate. It is highly recommended to enable NTP for a reliable schedule. Do not forget to set the correct timezone. If applicable, daylight saving time is handled automatically.
- Scroll down to
Time-controlled presets. There are 8 different timer slots available. - Enter the hour, minute, and weekdays you want the preset to activate. In the
Preset column, enter the preset ID you noted earlier. - Save the settings page! You have successfully set up a schedule :)
Note
This only applies the preset at the start of the specified minute. If you set up two presets, one to turn on the light at 7 and another to turn it off at 8, if WLED is booted at 7:30, the light will not turn on. This should not be an issue in most applications.
"},{"location":"features/presets/#applying-presets-at-sunrise-and-sunset","title":"Applying presets at sunrise and sunset","text":"Applying a preset at sunrise and/or sunset is also supported, the last two timed preset slots are used for this. To calculate the times, WLED needs your location. This is possible with the \"Get Location\" button in Time & Macro settings if accessed via a browser. If you are using the WLED app, you will need to open locate.wled.me in your browser and copy the coordinates over to the settings page manually. With the Minutes input field, you may specify an offset of up to 59 minutes before or 59 minutes after the actual sunrise/set time.
Location
Sunrise and sunset calculation do not work if you live in the polar circles (latitude >66.6N or >66.6S).
"},{"location":"features/presets/#earlier-versions-up-to-010","title":"Earlier versions (up to 0.10)","text":"There are 16 preset slots in total. In 0.9.0, the last preset (16) is capable of saving the entire segment configuration. All other presets only save a single segment (main segment, the first one by default) and restore that preset to all selected segments.
In the Favorites tab, the number buttons from 1-16 are the different save slots. Find a config you like, then toggle Saving mode on and click on a number to save the preset to that slot. If Saving mode is toggled off, you can restore presets with a single click.
"},{"location":"features/presets/#preset-cycle-up-to-0121","title":"Preset cycle (up to 0.12.1)","text":"With this feature, you can create an animation by automatically swapping between presets within a specified range. Keep in mind that any changes you make to effects/colors will be overridden once the system applies the next preset.
If you want to start the preset cycle on boot, go to LED settings and tick \"Save current preset cycle configuration as boot default
To modify the duration of the preset cycle, ensure the preset cycle box is unchecked before entering a new time value. Once updated, the preset cycle can be enabled again\"
Playlists supersede Preset cycle in 0.13.
"},{"location":"features/relay-control/","title":"Control a Relay","text":"Digital LED strips still use power when seemingly switched off, about 1W per 200 LEDs. In case you want to prevent that, you can completely cut power to the LEDs by adding a relay to your circuit. It is toggled by WLED when WLED is turned on/off (in the UI, or through other interfaces). No pin is allocated for a relay by default, but can be easily set in the LED preferences page. Previously, GPIO12 (Pin D6 on many devices) was set as the default and is confirmed to work well on most boards except the ESP32-C3.
When you decide that you want WLED to control a relay, make sure you buy a suitable relay board. Check what voltage you can supply from your controller to relay (available 3.3V or 5V pin or different voltage from external power source), and make sure the relay can be controlled by voltage level your board is providing (3.3V CMOS, 5V TTL). Note, some relays come with a jumper that lets you configure whether the relay switches at high or low level of signal, giving you maximum flexibility.
This page gives a clear description using a light bulb instead of a LED strip. And instead of the D1 mentioned there, with WLED, you use the pin you set.
The default WLED behavior is to turn the relay pin on (high) when the LEDs are on and off (low) when the LEDs are off. This can be changed in the LED Preferences page. Many relays are powered when the signal is LOW. See this thread.
Sometimes people ask whether they can control more than one relay through WLED, including controlling this all via Alexa. Controlling an extra relay separately from the RGB lights is not something WLED is designed to do, however you can modify the code to add that functionality. For that, make sure you can compile WLED from source unmodified first. Then, change #define ESPALEXA_MAXDEVICES 1 in line 71 of the wled.h file to 2. After that, just follow the API documentation on https://github.com/Aircoookie/Espalexa to add a new EspalexaDevice to the alexa.cpp file
Second option for controlling multiple relays is using a Multi Relay usermod. As with Alexa you will need to compile WLED from source an include Multi Relay usermod either by including -D USERMOD_MULTI_RELAY in PlatformIO.ini or adding #define USERMOD_MULTI_RELAY in wled.h or my_config.h. You can also override default number of relays by defining MULTI_RELAY_MAX_RELAYS. Configuring usermod is done using Usermod settings page where you can define GPIO pins used, wether relay activates on HIGH or LOW logic, if the activation has any delay and if the relay can be controlled from the outside using MQTT message (external). MQTT topic for controlling relays is wled/[device]/relay/[relay_id]/command and accepts on, off and toggle messages. When the relay changes state a message with on or off is sent with the topic wled/[device]/relay/[relay_id].
How To: Use WLED to switch external relay with PIR sensor without affecting WLED state
If you do not want PIR (motion) sensor attached to WLED controller to trigger change of WLED state, but still want to control a legacy light, fan, etc. use the Multi Relay usermod and another relay attached to WLED controller. Create two presets for relay control (shown for switching relay off) and set up PIR and multi relay usermods as shown.
If you do not want button relay control just leave relay button at -1, the same goes for PIR sensor parameters (leave nighttime-only and/or off-only unchecked). Adjust preset numbers and GPIO pins to your liking. Multi relay usermod can also switch relay using MQTT messages or HTTP requests (check source code for available commands). Of course if you configured MQTT on your WLED device PIR sensor usermod will publish /motion topic to MQTT broker for your HA integration.
"},{"location":"features/segments/","title":"Segments","text":"Info
Starting in WLED 0.9.0, Segments are supported.
This feature allows you to set different zones on the LED strip, each running a different effect or color.
A segment is selected if the checkmark next to the segment number is checked. Changes you make to color or effects will apply to all selected segments. The color/effect that is shown in the web UI is that of the first selected segment.
There is one main segment, Segment 0 by default. This segment has a few important differences to the rest of the segments. - Color transitions only work on the main segment - The main segment's color is the one that will be reported to HTTP and MQTT APIs
Tip: If you divide your strip into two segments, reverse the second one and select both, you can achieve very nice symmetrical effects!
Segment 0 has a Start LED of 0 and a Stop LED equal to the LED Count you defined in Configuration, LED Preferences. The Stop LED is not included in the Segment. Currently you can create a maximum of 10 segments. Presets 1-15 use only Segment 0 by default. Preset 16 is the only Preset that saves settings for Segments 1-10.
To display segment information select the down arrow in the Segment box. To add a Segment select \u201c+ Add Segment\u201d. Enter the Start and Stop LED as appropriate. Grouping and Spacing control the organization of the LEDs within the selected effect. To reverse the direction of an effect select Reverse Direction. To delete a Segment select the trash can. To save your Segment settings select the checkmark to the right of the Start and Stop LED numbers.
"},{"location":"features/segments/#grouping-and-spacing","title":"Grouping and Spacing","text":"When an effect changes the color of one LED, it is really changing the color of one LED group. Since the default group size is one, the effect normally only changes a single LED. When Grouping is set to two, the effect will light two LEDs using the same color. The two LEDs are treated as a single virtual LED.
To illustrate this, we can create a segment with 12 LEDS (physically referred to as LED 0 to LED 11) and select an effect that repeats three colors. When Grouping is set to one we see a repeating pattern of one red LED, one blue LED, and one green LED. When Grouping is set to two the segment of 12 physical LEDs becomes a segment of 6 virtual LEDs (virtualLED 0 to virtualLED 5). The same effect will now set the color of each virtual LED (which consists of two physical LEDs). The pattern becomes two red LEDs followed by two blue LEDs then two green LEDs.
Setting LED Output Grouping 1 Spacing 0 Grouping 2 Spacing 0 As the pattern cycles, the group of LEDs will move together.
Setting LED Output Grouping 1 Spacing 0 Grouping 2 Spacing 0 Spacing controls the space or gap between LEDs. The default spacing is zero, so normally there is no space between LEDs. When Spacing is set to one, every other LED will be lit. The number of virtual LEDs in the strip will be half the number of physical LEDs.
Again, we can create a segment with 12 LEDS (physically referred to as LED 0 to LED 11) and select an effect that repeats three colors. When Spacing is set to zero we see a repeating pattern of one red LED, one blue LED, and one green LED. When Spacing is set to one the segment of 12 physical LEDs becomes a segment of 6 virtual LEDs (virtualLED 0 to virtualLED 5). The same effect will now set the color of each virtual LED (which consists of the even numbered physical LEDs). The pattern becomes one red LED followed by a blank LED, one blue LED followed by a blank LED, then one green LED followed by a blank LED.
Setting LED Output Grouping 1 Spacing 0 Grouping 1 Spacing 1 As the pattern cycles, only the virtual LEDs will be lit - the blank LEDs in between the virtual LEDs will always be off.
Setting LED Output Grouping 1 Spacing 0 Grouping 1 Spacing 1 Grouping and Spacing can be combined to create many different custom LED layouts. In the example below, the strip of 12 physical LEDs has been configured to function as four virtual LEDs with a small gap between them.
Setting LED Output Grouping 2 Spacing 1 Grouping 2 Spacing 1"},{"location":"features/segments/#interleaving","title":"Interleaving","text":"This is an easy way to get a repeating pattern of colors using one segment per color.
"},{"location":"features/segments/#offset-in-a-segment","title":"Offset in a segment","text":"By default effects start in the first LED in the segment and finish in the last one. If the offset parameter in a segment is used, the effect start will be moved by the number of positions entered. It will continue to the last LED and then finish with the initial positions that were skipped.
For instance, let's assume assume a strip of 12 LEDs with the positions numbered as follows (like the examples above):
An offset value of 5 will make the effect start in the physical position 5, continue to position 11 and then finish with positions 0 through 4, like this:
A negative offset value is allowed and represents an offset starting from the last position in the segment. In our previous example, an offset of -2 will start the effect in position 10, like this:
The offset values is prioritized over grouping and/or spacing. For example, if the offset is 2, grouping 4 and spacing 1, the first group of 4 LEDs will start at the physical position number 2.
"},{"location":"features/segments/#effect-overlay","title":"Effect Overlay","text":"Some effects can be overlaid on the background of another effect. To use overlay, set up segments with overlapping pixels. The overlay effect must be playing on the segment with the higher id. If the Overlay option is checked, the background will not be painted and the effect from the lower segment will be displayed.
"},{"location":"features/settings/","title":"Settings","text":"All web configurable settings are split in 5 sub-pages. This page is meant to clarify the purpose of each setting. This documentation applies to WLED 0.8.5.
"},{"location":"features/settings/#settings-overview","title":"Settings overview","text":""},{"location":"features/settings/#wifi-settings","title":"WiFi Settings","text":"This sub-page offers options to connect the ESP to different WiFi/WLAN devices.
Setting name Value Range Description Network Name String 0..32 The name (SSID) of your home WiFi. Spaces and some other characters are not supported. Network password String 0..64 The password of your home WiFi Static IP 4x 0..256 An optional static IPv4 address Static gateway 4x 0..255 In a static config, your gateway's IPv4 address Static subnet 4x 0..255 In a static config, this normally is 255.255.255.0 mDNS address String 0..32 Name of your device for the Bonjour/Zeroconf protocol Client IP - The current IP of the ESP in the home network AP SSID String 0..32 The name of the ESPs internal WiFi hotspot (Access Point) Hide AP name Y/N The ESPs Access Point won't appear in WiFi lists of other devices AP password String 0..64 The password of the ESPs WiFi Access Point AP WiFi channel 1..13 The 2.4G WiFi band of the AP. For advanced users AP opens select Condition on when to open the AP AP IP - The Access Point IPv4 address of the ESP (is 192.168.4.1 in most cases) WiFi sleep Y/N Disabling WiFi sleep can increase reliability, but increases power consumption"},{"location":"features/settings/#led-settings","title":"LED settings","text":"This sub-page configures the state of your lights.
Setting name Value Range Description LED count 1..1500 How many LEDs are in your WS2812B strip Automatic brightness limiter Y/N Limit brightness to stay in a given current range Maximum current 300..65000 Current limit im milliamps LED voltage select Voltage/type of LEDs Custom max. current 1..255 Custom current per LED on full white 4-channel LEDs (RGBW) Y/N Support for SK6812 LEDs with white channel Color order select If your LEDs display incorrect colors (red and green swapped), try changing it Auto-calculate white select Get white channel from RGB automatically (only applicable for RGBW) Details Turn on after power up Y/N Whether the lights should turn on after a reset Apply preset 0..16 Preset to load at boot (0 = none) Set current preset cycle... Y/N The current preset cycle configuration will be used as boot default Use Gamma for brightness Y/N Will correct brightness changes to make it appear more linear. Advised to leave off Use Gamma for color Y/N Will correct colors to match those on a monitor. Strongly advised to keep on Brightness factor 1..255 Factor to change master brightness if it is to dim/bright for a certain configuration Crossfade Y/N Whether to have a smooth fading transitional effect when changing colors/brightness Transition time 0..65535 How many milliseconds the transition lasts Enable transition for secondary color Y/N Enable Palette transitions Y/N Enable transitions for palettes (not affected by transition time) Timed light duration 1..255 How long the nightlight should stay on Target brightness 0..255 What brightness the light should have after time is over. 0=off. Fade down Y/N Gradually fades down the light over the duration instead of turning it off at the end Palette blending select Choose how the palette wraps at the end (seam) Reverse LED order Y/N Mirrors the LEDs (last LED is first) Skip first LED Y/N Will turn off the first LED and shift the remaining by 1 (1st LED used as a signal repeater)"},{"location":"features/settings/#user-interface-settings","title":"User Interface settings","text":"This sub-page changes the look of the web interface.
Setting name Value Range Description Server description String 1..32 The name of the device as shown on the top of the UI. Differs from Alexa device name Sync button toggles... Y/N If enabled, both send and receive are toggled by the button in UI. If disabled, only sending is toggled and receiving is kept as configured in Sync settings."},{"location":"features/settings/#sync-settings","title":"Sync settings","text":"This sub-page configures external software synchronization interfaces.
Setting name Value Range Description On/Off button enabled Y/N Check if there is a physical pushbutton connected to GPIO0 Infrared receiver type select Type of infrared receiver Broadcast UDP port 1..65535 All WLED lights you want to group together must have the same port Receive Brightness Y/N If there is a sync notification, whether its brightness should be applied Color Y/N Whether the color of the synced device should be applied Effects Y/N Whether the effect settings should be applied Send on direct change Y/N Whether to send a sync notification when state changed via web UI or API Send on button press Y/N Whether to send sync when toggled by button or IR Send Alexa notifications Y/N Whether to send sync after changed by Alexa (you may use Alexa groups instead) Send Hue notifications Y/N Whether to send sync after a connected Philips light changed Send Macro notifications Y/N Whether to send sync after a macro was triggered Send notifications twice Y/N Sends notifications twice (if you have issues with UDP packet loss) Receive UDP realtime Y/N Receive live UDP stream data (DRGB, WARLS, ...) Use E1.31 multicast Y/N Listen on multicast IP instead of unicast E1.31 start universe 1..63000 Only applies for multicast. If you want to set different content, set ESPs at least 8 universes apart Timeout 100..65000 Time after which to resume normal mode once stream has stopped. 65000 will keep the data indefinitely Force max brightness Y/N Realtime stream with max. brightness (unless limited by power brightness limiter) Disable realtime gamma correction Y/N Check if your host software does gamma correction already Realtime LED offset -255..255 Shift the realtime input by how many LEDs Emulate Alexa device Y/N Allows you to control the light via the Amazon Echo voice assistant. Requires reboot Alexa Invocation name String 1..32 The name you want the device to have for control via Alexa. Choose something easy she can understand Device Auth token String 40 You will get this in an e-mail during Blynk setup MQTT Broker IP or String 0..32 Connect to this host MQTT broker Device topic String 0..32 MQTT topic unique to this light Group topic String 0..32 MQTT topic for all lights in a group (room, floor, ...) Hue Bridge IP 4x 0..255 Your Hue bridge IPv4 address. Should be static to avoid reassigning Poll Hue light 0..99 The ID of the hue lamp you want to sync WLED to every x ms 100..65000 How often to poll. Smaller numbers decrease lag but might hurt bridge responsiveness ... Y/N Turn polling on/off Receive On/Off Y/N Turn on/off like the hue light Brightness Y/N Set brightness to that of the hue light Color Y/N Set color to that of the hue light Hue status - Shows the current connection status to a hue bridge Baud rate Various Set the default Serial connection Baud Rate"},{"location":"features/settings/#time-settings","title":"Time settings","text":"This sub-page configures automation tasks.
Setting name Value Range Description Get time from NTP Y/N Whether to get the current time from the internet Use 24h format Y/N Use 24h clock format instead of AM/PM Time zone - Your time zone. Open an issue if yours is unsupported. DST is applied automatically UTC offset -65000..65000 Seconds to offset. If you want e.g. 1h offset, use 3600 Current local time - The local time the ESP has acquired. If set up correctly, should equal actual time Clock overlay - The special overlay to use. Allows to display a clock on the strip Countdown mode Y/N Allows to have a visual countdown towards a specific date API macro fields 16x String 0..64 Allows you to define custom API calls which can be triggered by events Boot Macro 0..16 Which macro to trigger after WiFi connected (0 is default action) Alexa On/Off Macros 2x 0..16 Which macros to trigger when turning on/off via Alexa Button Macro 0..16 Macro to trigger if button is short pressed. Default action is on/off toggle. Long Press 0..16 Macro to trigger if button is long pressed (>0.7s). Default action is random color. Double press 0..16 Macro for double click on button. Countdown-Over Macro 0..16 Macro to trigger when the countdown is over Timed-Light-Over Macro 0..16 Macro to trigger when timed light is done"},{"location":"features/settings/#security-settings","title":"Security settings","text":"This sub-page manages permissions and updates.
Setting name Value Range Description Enable OTA lock Y/N If enabled, no firmware updates may be done via WiFi and some settings can't be changed. Passphrase String 0..32 To disable OTA lock, you need a password. The default is \"wledota\". Change it! Deny access to WiFi settings Y/N Disables changes to WiFi settings while locked Disable recovery AP Y/N If enabled, the module will not open an Access Point if connection to home WiFi failed. Factory reset Y/N Deletes all custom settings data (passwords, configuration, macros, presets) Manual OTA - If OTA is enabled, you can upload new binary firmware Enable ArduinoOTA Y/N Useful for developers. Be careful, can even be left on when OTA locked!"},{"location":"features/subpages/","title":"Web GUI Sitemap","text":"This is the sitemap of the module server. Access with \\<ESP-IP>/path (Example: 192.168.8.4/settings)
Path Description OTA rights required Since version / Default UI, index page No 0.2 /update Upload new firmware Yes 0.3 /win HTTP Request API (since 0.3) No 0.3 /json JSON API No 0.8.4 /json/state JSON state object No 0.8.4 /json/info JSON information No 0.8.4 /json/eff Effect name list No 0.8.4 /json/pal Palette name list No 0.8.4 /json/live Current colors of LEDs No 0.9.0 /liveview Live preview of current LEDs No 0.9.0 /settings Settings index page No 0.2 /settings/wifi WiFi Settings page Cnfg 0.5.0 /settings/led LED Settings page No 0.5.0 /settings/ui UI Settings page No 0.5.0 /settings/sync Sync Settings page No 0.5.0 /settings/time Time Settings page No 0.5.0 /settings/sec Security Settings page Yes 0.5.0 /welcome New User Welcome page No 0.5.0 /sliders UI, index page No 0.5.0 /reset Reboot module No 0.3 /version Returns build version No 0.3 /uptime Returns runtime in ms No 0.4 /freeheap Returns free memory No 0.4 /favicon.ico Page icon No 0.2 /teapot :) No 0.5.0 /edit Filesystem editor Yes 0.2 /u Custom usermod page 0.8.4 (?) /cpal.htm Custom palette editor 0.14.0-b3 /pixart.htm 2D Pixel Art converter (not compiled by default) 0.14.0-b3 /pxmagic.htm 2D Image converter 0.14.0-b4"},{"location":"features/subpages/#removed-sites","title":"Removed sites","text":"Path Description OTA rights required Versions /list Lists SPIFFS contents (if USEFS) Yes 0.2-0.8.3 /easter Joke page No 0.6.2 only /power Returns an estimate of used LED current No 0.5.0-0.8.3 /build Returns details about the build No 0.5.0-0.8.3 /cleareeprom Resets to factory defaults Yes 0.3-0.6.4 /down Kills software. Hard reset required. Yes 0.3-0.6.4 /url Returns current light setup API url No 0.9.1-0.14.0-b3"},{"location":"interfaces/blynk/","title":"Blynk","text":"Warning
The official Blynk v1 server is shut down as of January 2023. WLED v0.14.0-b1 binaries no longer have Blynk support enabled by default. This only works with the legacy Blynk app, for which new signups have been closed by the Blynk developer. WLED will either move to Blynk 2.0 or a different solution soon.
You can use the free (if you only use it for 1 WLED light) IoT cloud Blynk to control your WLED Lights with the beautiful Blynk app for Android and iOS!
With Blynk, you can also even control your lights when you are not connected to your home network!
"},{"location":"interfaces/blynk/#installation","title":"Installation","text":" - Download the Blynk (legacy) app from the Play Store or the App Store
- Scan this QR code with the app:
- Paste the device auth token Blynk sends to your e-mail into the WLED sync settings (only one ESP!)
You can use the sync button in Blynk to sync other WLED ESPs, just like with the web UIs!
If you have doubts about the security of using a 3rd party IoT cloud, don't worry. WLED will only attempt to connect to Blynk if you put the device token string into Sync settings! Keep in mind that your ESP needs to connect to an external server, which may cause lag.
"},{"location":"interfaces/dmx-output/","title":"DMX","text":""},{"location":"interfaces/dmx-output/#dmx-output","title":"DMX output","text":"Version Info
As of version 0.9.2 WLED supports DMX output via MAX485. This is great for controlling DMX LED PAR lamps with WLED patterns.
"},{"location":"interfaces/dmx-output/#features-and-limitations","title":"features and limitations","text":" - up to 15 DMX channels per fixture
- channels can be set to dimmer (brightness), red, green, blue, white, 0, 255
- supports channel spacing between fixtures
- outputs a DMX channel map
- one universe (512 channels)
- type of fixture
"},{"location":"interfaces/dmx-output/#software-setup","title":"software setup","text":"For the DMX feature to work, you'll need to compile WLED from source. It's not a big deal, you can do it! Here is the Quick Start guide. There you'll find the section \"i want to modify WLED\".
-
make sure, you can compile the latest version of WLED without any issues. Then continue.
-
Once that works, in wled00/wled.h you need to change the line //#define WLED_ENABLE_DMX to #define WLED_ENABLE_DMX Yes, you just remove the //, which enables the line and therefore DMX support.
-
Once you successfully uploaded the sketch to your board, you'll find a new entry \"DMX Output\" in your settings menu.
-
Grab the manual for your lamp and maybe some snacks, look up the dmx channels and set everything up accordingly.
"},{"location":"interfaces/dmx-output/#hardware-setup","title":"hardware setup","text":"The DMX output required the use of a MAX485 transceiver connected to the TX-pin of the ESP in order to produce DMX output.
I am currently working on an open source PCB design to go along with this feature.
For information about the use of DMX with ESP8266, you might like to read this tutorial by Robert Oostenveld. Note this is just background information about the hardware and you do not need any of the code listed here when using WLED output.
If you need to use another pin for output than the TX-pin, you'll need to change this in the ESP-Dmx library itself. This setting is located in src/dependencies/dmx/ESPDMX.cpp on line 31.
"},{"location":"interfaces/dmx-output/#questions","title":"questions","text":"If you have further questions about this feature, you can reach me via github (@jwingefeld), ICQ (30914656) or via WLED Discord (JvPeek).
"},{"location":"interfaces/e1.31-dmx/","title":"E1.31 (DMX) / Art-Net","text":""},{"location":"interfaces/e1.31-dmx/#e131","title":"E1.31","text":"WLED supports the E1.31 (sACN) realtime light protocol.
Version Info
As of WLED v0.10.0, Art-Net is alternatively supported. All information on this page applies for Art-Net as well. You will need to switch to Art-Net mode in Sync settings and reboot once.
Version Info
As of WLED v0.11.0, DDP is alternatively supported. Using DDP, the Multi RGB DMX mode is always used regardless of the DMX mode setting (as it is no DMX) You will need to switch to DDP mode in Sync settings and reboot once.
Version Info
As > WLED 0.14.0-b1, DMX Effect mode channel mapping changed. This is a breaking change in E131 sync behavior. Existing DMX setups using WLED Effect mode are likely to break. Solution: Adopt external DMX channel mappings according to the new Effect mode channel layout.
"},{"location":"interfaces/e1.31-dmx/#features","title":"Features","text":" - 170 LEDs (510 DMX channels) are supported per universe.
- You can use up to 9 adjacent universes which is a total of more than the maximum 1500 LEDs WLED can drive.
- E1.31 priority handling. HTP for multiple senders with same priority is not implemented!
Note: WLED > 0.14.0-b1 implements a basic priority handling. To enable it set E1.31 port priority UI config > 0. Packages < config priority will always be skipped. Higher priority senders will overrule lower priority package senders (timeout 3 seconds). Non-zero start code and E1.31 preview data is ignored.
Note: If you see issued with lag, you may see better performance if you disable Wi-Fi Multimedia (WMM) Mode QoS on your router
"},{"location":"interfaces/e1.31-dmx/#general-recommendations","title":"General Recommendations","text":" - For a fluent 25ms (40fps) or more framerate, it is recommended to use no more than 3 universes (510 LEDs).
- Using multiple E1.31 sources to control a single WLED controller will impact performance. If possible it's recommended to avoid this.
- Configure WLED to connect to a WiFi Network. It was observed that sending E1.31 from a computer to WLED when accessed as access point (WLED-AP) may not work, see forum post.
- When using an ESP32, disabling WiFi sleep in the WiFi settings of WLED can reduce/eliminate visual stuttering/lag of effects, and significantly reduce ping times. Note: disabling WiFi sleep will increase power consumption.
"},{"location":"interfaces/e1.31-dmx/#using-ledfx","title":"Using LedFX","text":"We highly recommend the LedFx project in combination with WLED! Configure WLED first, ensure devices are powered on and connected to your WiFi. To add WLED devices, in the 'Device Management', click on the Find WLED devices button. If you want to manually add devices, use more than 170 LEDs with LedFx, you need to go to additional settings and set \"Universe Size\" to 510 when adding the WLED device!
"},{"location":"interfaces/e1.31-dmx/#settings","title":"Settings","text":""},{"location":"interfaces/e1.31-dmx/#dmx-types","title":"DMX types","text":"Select the mode you want to use in Sync settings.
"},{"location":"interfaces/e1.31-dmx/#disabled","title":"Disabled","text":"Incoming E1.31 packets will be ignored.
"},{"location":"interfaces/e1.31-dmx/#single-rgb","title":"Single RGB","text":"All LEDs are set to the same color. 3 Channels: Red, Green, Blue
"},{"location":"interfaces/e1.31-dmx/#single-drgb","title":"Single DRGB","text":"All LEDs are set to the same color. 4 Channels: Master Dimmer, Red, Green, Blue
"},{"location":"interfaces/e1.31-dmx/#effect","title":"Effect","text":"Not a realtime mode & only support 1 universe. Allows setting WLED effect properties over E1.31 with 15 channels.
Channel Property 1 Master Dimmer 2 Effect mode ID 3 Effect speed 4 Effect intensity 5 Effect palette ID 6 Effect option 7 Red Primary 8 Green Primary 9 Blue Primary 10 Red Secondary 11 Green Secondary 12 Blue Secondary 13 Red Tertiary 14 Green Tertiary 15 Blue Tertiary The effect option channel is divided into 4 macro parts to control mirror and reverse states:
value mirror reverse 0..63 false false none 64..127 false true reverse 128..191 true false mirror 192..255 true true mirror & reverse"},{"location":"interfaces/e1.31-dmx/#effect-white","title":"Effect + White","text":"Same as Effect with additional whites = 18 channels.
Channel Property .. .. 16 White Primary 17 White Secondary 18 White Tertiary"},{"location":"interfaces/e1.31-dmx/#effect-segment","title":"Effect Segment","text":"Same as Effect with 15 channels per segment; expect channel 1 = \"Segment Dimmer\".
All effect segment modes introduce an additional DMX segment spacing. If spacing s = 0 subsequent DMX addresses for all segments are created. When s > 0 a gap of s DMX addresses between segments is used. To calculate segment DMX fixture addresses:
Segment DMX Address (i) = DMXAddress + i * (dmxEffectChannels + s)\n
Where DMXAddress = start address as configured in UI, dmxEffectChannels = 15|18 depending on selected effect segment mode, s = address gap as configured in UI and i is the index id of each segment as existing.
Note: 1 DMX universe = max 512 DMX addresses. So max number of segments depends on start address, selected segment mode and configured DMX segment spacing. To calculate how many segments can be controlled:
Max segments = floor[ (512 - DMXAddress) / (dmxEffectChannels + s) ]\n
"},{"location":"interfaces/e1.31-dmx/#effect-segment-white","title":"Effect Segment + White","text":"Same as Effect Segment including whites, so it uses 18 DMX channels per segment.
"},{"location":"interfaces/e1.31-dmx/#multiple-rgb","title":"Multiple RGB","text":"3 Channels per LED in sequence. LED 0 Red, LED 0 Green, LED 0 Blue, LED 1 Red, ... Default mode, equivalent to pre-0.9.1 E1.31. This is the mode you want to use for xLights and LedFx.
"},{"location":"interfaces/e1.31-dmx/#multiple-rgbw","title":"Multiple RGBW","text":"Like Multiple RGB + additional white channels.
"},{"location":"interfaces/e1.31-dmx/#dimmer-multi-rgb","title":"Dimmer + Multi RGB","text":"Like Multiple RGB, but the first channel is a brightness control. Master Dimmer, LED 0 Red, LED 0 Green, ...
"},{"location":"interfaces/e1.31-dmx/#preset","title":"Preset","text":"Trigger presets and control brightness. 2 Channels: Brightness, Preset ID
"},{"location":"interfaces/http-api/","title":"HTTP Request API","text":"Hint
While this API is not deprecated, it is highly recommended to use the JSON API instead of the HTTP API for new integrations, as it is structured in a better way and allows efficient use of newer features like segments, presets, and playlists.
WLED's HTTP API allows you to set many properties of your lights, even more than the index page UI supports, via a simple GET web request.
Help
Unsure how all this API stuff works? Check out this amazing guide by tynick!
The basic URL scheme is: [ipadress]/win. This will return an XML file with some current values (see bottom of page). Parameters can be added to control some of the variables.
- Example (AP):
192.168.4.1/win&A=255 sets the brightness to maximum - Example (mdns):
led.local/win&A=128&FX=0 sets the brightness to half and the effect to Solid
In conjunction with a router port forwarding this can be used to automate WLED, for example via IFTTT.
Add one or multiple of the following parameters after the base URL/IP to change values: (if the parameter is unknown or the value illegal nothing will happen)
"},{"location":"interfaces/http-api/#led-control","title":"LED control","text":"Parameter Value Range Description Since Version &A= 0 to 255 Master brightness 0.2 &T= 0, 1, or 2 Master Off/On/Toggle 0.3 &R= 0 to 255 Primary Red value 0.2 &G= 0 to 255 Primary Green value 0.2 &B= 0 to 255 Primary Blue value 0.2 &W= 0 to 255 Primary White value 0.4 &FX= 0 to 101 LED Effect Index 0.3 &SX= 0 to 255 Effect Speed 0.3 &IX= 0 to 255 Effect Intensity 0.5.0 &FP= 0 to 46 FastLED Palette 0.8.0 &NL= 0 to 255 Nightlight active and duration in minutes 0.3 &ND none Toggles nightlight on but uses default duration 0.6.3 &NT= 0 to 255 Nightlight target brightness 0.5.0 &NF= 0 to 2 Fade Nightlight, 1 = fade brightness only, 2 = additionaly fade color from primary to secondary color 0.5.0"},{"location":"interfaces/http-api/#advanced","title":"Advanced","text":"Parameter Value Range Description Since Version &CL= HEX/DEC Primary color 0.8.0 &C2= HEX/DEC Secondary color 0.8.0 &C3= HEX/DEC Third color 0.8.0 &R2= 0 to 255 Secondary Red value 0.4 &G2= 0 to 255 Secondary Green value 0.4 &B2= 0 to 255 Secondary Blue value 0.4 &W2= 0 to 255 Secondary White value 0.4 &HU= 0 to 65535 Hue 0.5.1 &SA= 0 to 255 Saturation (only in conjunction with Hue) 0.5.1 &H2 none Hue + Saturation will set secondary color 0.5.1 &SR= 0 or 1 Set Primary/Secondary color to random hue 0.4 &SC none Swap primary and secondary color 0.4"},{"location":"interfaces/http-api/#use-of-hex-values","title":"Use of hex values","text":"Hex values need to be prefaced with the character h or H. The normal format is RRGGBB. If the led strip is RGBW, the hex format is WWRRGGBB. Note: In the UI the format is RRGGBBWW, so the values cannot be copied without a transformation.
"},{"location":"interfaces/http-api/#loxone-commands","title":"Loxone commands","text":"Loxone offers two commands. One for RGB values and one for brightness and color temperature.
Parameter Syntax Range Description Since Version &LX= BBBGGGRRR 0 - 100100100 Loxone RGB value for primary color. Each color (RRR,GGG,BBB) is specified in the range from 0 to 100%. 0.11 &LX= 20bbbtttt 200002700 - 201006500 Loxone brightness and color temperature values for primary color. Brightness bbb is specified in the range 0 to 100%. tttt defines the color temperature in the range from 2700 to 6500 Kelvin. 0.11 &LY= BBBGGGRRR 0 - 100100100 Loxone RGB value for secondary color. Each color (RRR,GGG,BBB) is specified in the range from 0 to 100%. 0.11 &LY= 20bbbtttt 200002700 - 201006500 Loxone brightness and color temperature values for secondary color. Brightness bbb is specified in the range 0 to 100%. tttt defines the color temperature in the range from 2700 to 6500 Kelvin. 0.11"},{"location":"interfaces/http-api/#notifications","title":"Notifications","text":"Parameter Value Range Description Since Version &RN= 0 or 1 Receive UDP Notifications 0.3 &SN= 0 or 1 Send UDP Notifications 0.3 &NN none No notification for this request 0.3 &HP= 0 to 99 Sets Hue polling light ID (0 is off) 0.5.1"},{"location":"interfaces/http-api/#presets","title":"Presets","text":"Parameter Value Range Description Since Version &PS= 1 to 16 Saves current setup to preset. Preset 255 can be used and is temporary/not persistent. 0.4 &PL= 1 to 250 Applies entire preset 0.4 &P1= 1 to 249 First cycle preset 0.6.3 &P2= 2 to 250 Last cycle preset 0.6.3 &TT= 0 to 65000 Set transition time (ms) 0.6.3"},{"location":"interfaces/http-api/#macros","title":"Macros","text":"Parameter Value Range Description Since Version &M= 1 to 16 Apply macro (deprecated, added for compatibility with pre-0.11 automations) 0.5.0"},{"location":"interfaces/http-api/#segments","title":"Segments","text":"It is highly recommended to use the JSON API when dealing with Segments.
Parameter Value Range Description Since Version &SM= 0 to 9 Set the main segment (values are reported to XML) 0.9.0 &SS= 0 to 9 Select segment to apply THIS api call to 0.9.0 &SV= 0, 1, or 2 Set segment selected (2 unselects others) 0.9.0 &S= 0 to ledcount-1 Set segment start 0.9.0 &S2= 0 to ledcount Set segment stop 0.9.0 &GP= 1 to 255 Set segment grouping 0.9.1 &SP= 0 to 255 Set segment spacing 0.9.1 &RV= 0 or 1 Reverse/Flip Segment direction 0.9.1 &SB= 0 to 255 Segment brightness 0.10.0"},{"location":"interfaces/http-api/#general-and-experimental","title":"General and Experimental","text":"Parameter Value Range Description Since Version &RB none Reboot WLED 0.10.0 (?) &ST= 32bit Current UTC time in Unix epoch 0.4 &CT= 32bit UTC time for countdown end 0.4 &MD= 0 or 1 Set slider mode to RGB/HSB 0.3 &AX= 0 to 255 Debug feature, can be configured for general IO 0.3 &IN none Server will not respond to this request (internal) 0.3 &OL= 0 to 255 Experimental overlays 0.3 &L= 0 to 255 Lock pixel 0.4 &L2= 0 to 255 Lock pixel range L to L2 0.4 &UL none Unlock instead (used in conjunction with L and L2) 0.4 &NX= String 1..6 Cronixie clockface 0.4 &NM= 0 or 1 Cronixie Time or Countdown mode 0.4 &NB= 0 or 1 Cronixie Backlight 0.4 &IT none Include UI color theme in API response 0.8.2 &RD= 0 or 1 Toggle realtime UDP 0.8.4 &LO= 0-2 Live data override. 0 is off, 1 is override until live data ends, 2 is override until ESP reboot 0.10.2"},{"location":"interfaces/http-api/#xml-response","title":"XML response","text":"This is the XML file sent as response to every API call.
Parameter Value Range Description ac 0 to 255 Master Brightness cl 3x 0..255 Primary Color RGB cs 3x 0..255 Secondary RGB ns 0 or 1 Notification Sending on nr 0 or 1 Notification Receive on nl 0 or 1 Nightlight active nf 0 or 2 Nightlight Fade type nd 0 to 255 Nightlight delay nt 0 to 255 Nightlight target brightness fx 0 to 73 Effect index sx 0 to 255 Effect speed ix 0 to 255 Effect intensity fp 0 to 43 FastLED palette wv -1 to 255 Primary White value ws 0 to 255 Secondary White ps 0 to 255 Current Preset cy 0 or 1 Preset Cycling enabled md 0 or 1 RGB or HSB UI mode ds String 0..32 Server description ss 0 to 12 Segment ID"},{"location":"interfaces/http-api/#in-decrementing-values","title":"In-/decrementing values","text":"You can use the ~ character to easily set values relative to their current value. This is currently supported for the following parameters: A, R, G, B, W, R2, G2, B2, W2, FX, SX, IX, FP, PL
For example, use PL=~ to go to the next preset. Using just ~ without a number will increase the value by 1, ~- will decrease it by 1. The value will then wrap around, so using A=~- when A is 0 will set A to 255.
You can also specify by how much to change the value. For example, using A=~10 will increase the brightness by 10. In case of using a number behind ~, the value will clip (so it will not wrap around, if the maximum brightness is set, A=~10 will not have any effect)
To setup a Macro for a Button to advance to the next Preset, use win&P1=1&P2=30&PL=~ P1 will equal the first Preset of the rotation while P2 will be the last Preset.
"},{"location":"interfaces/infrared/","title":"Infrared","text":"Version Info
Since v0.8.2, infrared control from various IR remotes is supported for ESP8266 and since v0.9.0 for ESP32, too.
A dedicated infrared receiver module is required and must be connected to the WLED Controller. For example, KY-022 or TSOP38238 are confirmed to work and inexpensive. These receivers each have three pins: 3.3V, GND and IR data. IR data pin must be connected to a free GPIO pin. This GPIO must then be set as IR GPIO under \"Config->LED Preferences\" (The default sensor pin is GPIO4).
Warning
IR receiving will not work on ESP8266 if you use any LED pin other than GPIO 1, 2, or 3 for digital LED strips.
"},{"location":"interfaces/infrared/#supported-ir-remotes","title":"Supported IR remotes","text":"To use IR remote go to Settings, Sync Interfaces and change the value for Infrared receiver type according to the IR remote type of the following list:
- white 24-key IR remote with R,G,B + 12 color-tones
- white 24-key IR remote with CT+ / CT- buttons
- blue 40-key IR remote with keys for 25%, 50%, 75% and 100%
- white 44-key IR remote with up/down arrows for the colors R,G and B
- white 21-key IR remote with R,G,B + 9 color-tones
- black 6-key IR remote with CH up/down + Vol up/down
- JSON IR remote - Easily configure and use any IR remote.
"},{"location":"interfaces/infrared/#esp-now-based-remote-control","title":"ESP-NOW based remote control","text":"Since version WLED 14.0-beta3: An ESP-NOW compatible remote control is supported. An example of this is the \u201eWIZmote\u201c remote control. This is based on an ESP microcontroller. ESP-NOW can be activated in WLED settings. You have to enter the Hardware MAC address of the remote control. This is determined by clicking on any button on the remote control and copying the last received MAC address from the \"Last Seen\" field to the \"Hardware MAC\" field in WLED ESP-NOW settings (\u201cConfig->WiFi Setup\u201d) and saving it with \"Save\". Advantages: no special receiver needs to be attached to the WLED controller and the signals are transmitted via radio network. Therefore there is no line of sight between the remote control and the WLED controller required, as is the case with an IR remote control. The 4 buttons \"1\"-\"4\" of the WIZmote remote control are linked to presets 1 to 4. The meaning of other keys is self-explanatory. Attention: WIZmote needs two good quality AAA batteries to work properly. If the batteries are too weak, the correct signal will not be sent, even if the blue LED on the remote control lights up briefly, actually indicating signal transmission.
"},{"location":"interfaces/json-api/","title":"JSON API","text":"WLED versions since 0.8.4 implement a powerful JSON API over HTTP. It is accessible using the /json subpage.
"},{"location":"interfaces/json-api/#obtaining-light-information","title":"Obtaining light information","text":"Sending a GET request will return an object similar to the sample below The response consists of four objects:
state contains the current state of the light. All values may be modified by the client (see below)info contains general information about the device. No value can be modified using this APIeffects contains an array of the effect mode namespalettes contains an array of the palette names
You may also obtain those objects individually using the URLs /json/state /json/info /json/eff, and /json/pal.
Reserved effect IDs
In WLED versions 0.14+, some effects are unsupported in certain builds (e.g. some audio reactive effects may only work on ESP32). In order for each effect to have an unique ID on all devices, having unsupported ones in between supported ones is possible. If called, these will fallback to the Solid effect, in the effects list they have the name RSVD or -. To improve user experience, it is recommended to remove effects with the names RSVD or - form the UI effect selection.
"},{"location":"interfaces/json-api/#setting-new-values","title":"Setting new values","text":"Sending a POST request to /json or /json/state with (parts of) the state object will update the respective values. Example: {\"on\":true,\"bri\":255} sets the brightness to maximum. {\"seg\":[{\"col\":[[0,255,200]]}]} sets the color of the first segment to teal. {\"seg\":[{\"id\":X,\"on\":\"t\"}]} and replacing X with the desired segment ID will toggle on or off that segment.
CURL example
This will toggle on and off and return the new state (v0.13+): curl -X POST \"http://[WLED-IP]/json/state\" -d '{\"on\":\"t\",\"v\":true}' -H \"Content-Type: application/json\"
Sample JSON API response (v0.8.4):
{\n\"state\": {\n\"on\": true,\n\"bri\": 127,\n\"transition\": 7,\n\"ps\": -1,\n\"pl\": -1,\n\"nl\": {\n\"on\": false,\n\"dur\": 60,\n\"fade\": true,\n\"tbri\": 0\n},\n\"udpn\": {\n\"send\": false,\n\"recv\": true\n},\n\"seg\": [{\n\"start\": 0,\n\"stop\": 20,\n\"len\": 20,\n\"col\": [\n[255, 160, 0, 0],\n[0, 0, 0, 0],\n[0, 0, 0, 0]\n],\n\"fx\": 0,\n\"sx\": 127,\n\"ix\": 127,\n\"pal\": 0,\n\"sel\": true,\n\"rev\": false,\n\"cln\": -1\n}]\n},\n\"info\": {\n\"ver\": \"0.8.4\",\n\"vid\": 1903252,\n\"leds\": {\n\"count\": 20,\n\"rgbw\": true,\n\"pin\": [2],\n\"pwr\": 0,\n\"maxpwr\": 65000,\n\"maxseg\": 1\n},\n\"name\": \"WLED Light\",\n\"udpport\": 21324,\n\"live\": false,\n\"fxcount\": 80,\n\"palcount\": 47,\n\"arch\": \"esp8266\",\n\"core\": \"2_4_2\",\n\"freeheap\": 13264,\n\"uptime\": 17985,\n\"opt\": 127,\n\"brand\": \"WLED\",\n\"product\": \"DIY light\",\n\"btype\": \"src\",\n\"mac\": \"60019423b441\"\n},\n\"effects\": [\n\"Solid\", \"Blink\", \"Breathe\", \"Wipe\", \"Wipe Random\", \"Random Colors\", \"Sweep\", \"Dynamic\", \"Colorloop\", \"Rainbow\",\n\"Scan\", \"Dual Scan\", \"Fade\", \"Chase\", \"Chase Rainbow\", \"Running\", \"Saw\", \"Twinkle\", \"Dissolve\", \"Dissolve Rnd\",\n\"Sparkle\", \"Dark Sparkle\", \"Sparkle+\", \"Strobe\", \"Strobe Rainbow\", \"Mega Strobe\", \"Blink Rainbow\", \"Android\", \"Chase\", \"Chase Random\",\n\"Chase Rainbow\", \"Chase Flash\", \"Chase Flash Rnd\", \"Rainbow Runner\", \"Colorful\", \"Traffic Light\", \"Sweep Random\", \"Running 2\", \"Red & Blue\",\"Stream\",\n\"Scanner\", \"Lighthouse\", \"Fireworks\", \"Rain\", \"Merry Christmas\", \"Fire Flicker\", \"Gradient\", \"Loading\", \"In Out\", \"In In\",\n\"Out Out\", \"Out In\", \"Circus\", \"Halloween\", \"Tri Chase\", \"Tri Wipe\", \"Tri Fade\", \"Lightning\", \"ICU\", \"Multi Comet\",\n\"Dual Scanner\", \"Stream 2\", \"Oscillate\", \"Pride 2015\", \"Juggle\", \"Palette\", \"Fire 2012\", \"Colorwaves\", \"BPM\", \"Fill Noise\", \"Noise 1\",\n\"Noise 2\", \"Noise 3\", \"Noise 4\", \"Colortwinkle\", \"Lake\", \"Meteor\", \"Smooth Meteor\", \"Railway\", \"Ripple\"\n],\n\"palettes\": [\n\"Default\", \"Random Cycle\", \"Primary Color\", \"Based on Primary\", \"Set Colors\", \"Based on Set\", \"Party\", \"Cloud\", \"Lava\", \"Ocean\",\n\"Forest\", \"Rainbow\", \"Rainbow Bands\", \"Sunset\", \"Rivendell\", \"Breeze\", \"Red & Blue\", \"Yellowout\", \"Analogous\", \"Splash\",\n\"Pastel\", \"Sunset 2\", \"Beech\", \"Vintage\", \"Departure\", \"Landscape\", \"Beach\", \"Sherbet\", \"Hult\", \"Hult 64\",\n\"Drywet\", \"Jul\", \"Grintage\", \"Rewhi\", \"Tertiary\", \"Fire\", \"Icefire\", \"Cyane\", \"Light Pink\", \"Autumn\",\n\"Magenta\", \"Magred\", \"Yelmag\", \"Yelblu\", \"Orange & Teal\", \"Tiamat\", \"April Night\"\n]\n}\n
"},{"location":"interfaces/json-api/#overview-of-values","title":"Overview of values","text":""},{"location":"interfaces/json-api/#state-object","title":"State object","text":"JSON key Value range Description on bool On/Off state of the light bri 0 to 255 Brightness of the light. If on is false, contains last brightness when light was on (aka brightness when on is set to true. Setting bri to 0 is supported but it is recommended to use the range 1-255 and use on: false to turn off. The state response will never havethe value 0 for bri. transition 0 to 255 Duration of the crossfade between different colors/brightness levels. One unit is 100ms, so a value of 4 results in atransition of 400ms. tt 0 to 255 Similar to transition, but applies to just the current API call. Not included in state response. ps -1 to 65535 ID of currently set preset. 1~17~ can be used to iterate through presets 1-17. pss 0 to 65535 Bitwise indication of preset slots (0 - vacant, 1 - written). Always 0 in 0.11. Not changable. Removed as of v0.11.1 psave 1 to 16 (250 in 0.11) Save current light config to specified preset slot. Not included in state response. pl -1 to 0 ID of currently set playlist. For now, this sets the preset cycle feature, -1 is off and 0 is on. nl.on bool Nightlight currently active nl.dur 1 to 255 Duration of nightlight in minutes nl.fade bool If true, the light will gradually dim over the course of the nightlight duration. If false, it will instantly turn to the target brightness once the duration has elapsed. Removed in 0.13.0 (use mode instead) nl.mode 0 to 3 Nightlight mode (0: instant, 1: fade, 2: color fade, 3: sunrise) (available since 0.10.2) nl.tbri 0 to 255 Target brightness of nightlight feature nl.rem -1 to 15300 Remaining nightlight duration in seconds, -1 if not active. Only in state response, can not be set. udpn.send bool Send WLED broadcast (UDP sync) packet on state change udpn.recv bool Receive broadcast packets udpn.nn bool Don't send a broadcast packet (applies to just the current API call). Not included in state response. v bool If set to true in a JSON POST command, the response will contain the full JSON state object. Not included in state response rb bool If set to true, device will reboot immediately. Not included in state response. live bool If set to true, enters realtime mode and blanks the LEDs. The realtime timeout option does not have an effect when this command is used, WLED will stay in realtime mode until the state (color/effect/segments, excluding brightness) is changed. It is expected that {\"live\":false} is sent once live data sending is terminated. Not included in state response. lor 0, 1, or 2 Live data override. 0 is off, 1 is override until live data ends, 2 is override until ESP reboot (available since 0.10.0) time uint32 Set module time to unix timestamp. Not included in state response. mainseg 0 to info.leds.maxseg-1 Main Segment seg Array of segment objects Segments are individual parts of the LED strip. In 0.9.0 this will enables running different effects on differentparts of the strip. playlist object Custom preset playlists. Not included in state response (available since 0.11.0) tb uint32 Sets timebase for effects. Not reported."},{"location":"interfaces/json-api/#contents-of-the-segment-object","title":"Contents of the segment object","text":"Notice: start, stop, and len are not changeable in 0.8.4. Any segment with id > 0 is ignored. Unless stated otherwise, every value may be changed via an HTTP POST request. The tertiary color is not gamma-corrected in 0.8.4, but is in subsequent releases.
JSON key Value range Description id 0 to info.maxseg -1 Zero-indexed ID of the segment. May be omitted, in that case the ID will be inferred from the order of the segment objects in the seg array. start 0 to info.leds.count -1 LED the segment starts at. stop 0 to info.leds.count LED the segment stops at, not included in range. If stop is set to a lower or equal value than start (setting to 0 is recommended), the segment is invalidated and deleted. len 0 to info.leds.count Length of the segment (stop - start). stop has preference, so if it is included, len is ignored. grp 0 to 255 Grouping (how many consecutive LEDs of the same segment will be grouped to the same color) spc 0 to 255 Spacing (how many LEDs are turned off and skipped between each group) of -len+1 to len Offset (how many LEDs to rotate the virtual start of the segments, available since 0.13.0) col array of colors Array that has up to 3 color arrays as elements, the primary, secondary (background) and tertiary colors of the segment. Each color is an array of 3 or 4 bytes, which represent an RGB(W) color. fx 0 to info.fxcount -1 ID of the effect or ~ to increment, ~- to decrement, or r for random. sx 0 to 255 Relative effect speed. ~ to increment, ~- to decrement. ~10 to increment by 10, ~-10 to decrement by 10. ix 0 to 255 Effect intensity. ~ to increment, ~- to decrement. ~10 to increment by 10, ~-10 to decrement by 10. c1 0 to 255 Effect custom slider 1. Custom sliders are hidden or displayed and labeled based on effect metadata. c2 0 to 255 Effect custom slider 2. c3 0 to 31 Effect custom slider 3. o1 bool Effect option 1. Custom options are hidden or displayed and labeled based on effect metadata. o2 bool Effect option 2. o3 bool Effect option 3. pal 0 to info.palcount -1 ID of the color palette or ~ to increment, ~- to decrement, or r for random. sel bool true if the segment is selected. Selected segments will have their state (color/FX) updated by APIs that don't support segments (e.g. UDP sync, HTTP API). If no segment is selected, the first segment (id:0) will behave as if selected. WLED will report the state of the first (lowest id) segment that is selected to APIs (HTTP, MQTT, Blynk...), or mainseg in case no segment is selected and for the UDP API. Live data is always applied to all LEDs regardless of segment configuration. rev bool Flips the segment, causing animations to change direction. on bool Turns on and off the individual segment. (available since 0.10.0) bri 0 to 255 Sets the individual segment brightness (available since 0.10.0) mi bool Mirrors the segment (available since 0.10.2) cct 0 to 255 or 1900 to 10091 White spectrum color temperature (available since 0.13.0) lx BBBGGGRRR: 0 - 100100100 Loxone RGB value for primary color. Each color (RRR,GGG,BBB) is specified in the range from 0 to 100%. lx 20bbbtttt: 200002700 - 201006500 Loxone brightness and color temperature values for primary color. Brightness bbb is specified in the range 0 to 100%. tttt defines the color temperature in the range from 2700 to 6500 Kelvin. (available since 0.11.0, not included in state response) ly BBBGGGRRR: 0 - 100100100 Loxone RGB value for secondary color. Each color (RRR,GGG,BBB) is specified in the range from 0 to 100%. ly 20bbbtttt: 200002700 - 201006500 Loxone brightness and color temperature values for secondary color. Brightness bbb is specified in the range 0 to 100%. tttt defines the color temperature in the range from 2700 to 6500 Kelvin. (available since 0.11.0, not included in state response) i array Individual LED control. Not included in state response (available since 0.10.2) frz bool freezes/unfreezes the current effect m12 0 to 4 [map1D2D.count] Setting of segment field 'Expand 1D FX'. (0: Pixels, 1: Bar, 2: Arc, 3: Corner) si 0 to 3 Setting of the sound simulation type for audio enhanced effects. (0: 'BeatSin', 1: 'WeWillRockYou', 2: '10_3', 3: '14_3') (as of 0.14.0-b1, there are these 4 types defined)"},{"location":"interfaces/json-api/#info-object","title":"Info object","text":"No value may be changed by means of this API.
JSON key Value range Description ver string Version name. vid uint32 Build ID (YYMMDDB, B = daily build index). leds object Contains info about the LED setup. leds.cct bool true if the light supports color temperature control (available since 0.13.0, deprecated, use info.leds.lc) leds.count 1 to 1200 Total LED count. leds.fps 0 to 255 Current frames per second. (available since 0.12.0) leds.rgbw bool true if LEDs are 4-channel (RGB + White). (deprecated, use info.leds.lc) leds.wv bool true if a white channel slider should be displayed. (available since 0.10.0, deprecated, use info.leds.lc) leds.pin byte array LED strip pin(s). Always one element. Removed as of v0.13 leds.pwr 0 to 65000 Current LED power usage in milliamps as determined by the ABL. 0 if ABL is disabled. leds.maxpwr 0 to 65000 Maximum power budget in milliamps for the ABL. 0 if ABL is disabled. leds.maxseg byte Maximum number of segments supported by this version. leds.lc byte Logical AND of all active segment's virtual light capabilities leds.seglc byte array Per-segment virtual light capabilities str bool If true, an UI with only a single button for toggling sync should toggle receive+send, otherwise send only name string Friendly name of the light. Intended for display in lists and titles. udpport uint16 The UDP port for realtime packets and WLED broadcast. live bool If true, the software is currently receiving realtime data via UDP or E1.31. lm string Info about the realtime data source lip string Realtime data source IP address ws -1 to 8 Number of currently connected WebSockets clients. -1 indicates that WS is unsupported in this build. fxcount byte Number of effects included. palcount uint16 Number of palettes configured. wifi object Info about current signal strength wifi.bssid string The BSSID of the currently connected network. wifi.signal 0 to 100 Relative signal quality of the current connection. wifi.channel 1 to 14 The current WiFi channel. fs object Info about the embedded LittleFS filesystem (since 0.11.0) fs.u uint32 Estimate of used filesystem space in kilobytes fs.t uint32 Total filesystem size in kilobytes fs.pmt uint32 Unix timestamp for the last modification to the presets.json file. Not accurate after boot or after using /edit ndc -1 to 255 Number of other WLED devices discovered on the network. -1 if Node discovery disabled. (since 0.12.0) arch string Name of the platform. core string Version of the underlying (Arduino core) SDK. lwip 0, 1, or 2 Version of LwIP. 1 or 2 on ESP8266, 0 (does not apply) on ESP32. Deprecated, removal in 0.14.0 freeheap uint32 Bytes of heap memory (RAM) currently available. Problematic if <10k. uptime uint32 Time since the last boot/reset in seconds. opt uint16 Used for debugging purposes only. brand string The producer/vendor of the light. Always WLED for standard installations. product string The product name. Always FOSS for standard installations. btype string The origin of the build. src if a release version is compiled from source, bin for an official release image, dev for a development build (regardless of src/bin origin) and exp for experimental versions. ogn if the image is flashed to hardware by the vendor. Removed as of v0.10 mac string The hexadecimal hardware MAC address of the light, lowercase and without colons. ip string The IP address of this instance. Empty string if not connected. (since 0.13.0)"},{"location":"interfaces/json-api/#per-segment-individual-led-control","title":"Per-segment individual LED control","text":"Using the i property of the segment object, you can set the LED colors in the segment using the JSON API. Keep in mind that this is non-persistent, if the light is turned off the segment will return to effect mode. The segment is frozen when using individual control, the set effect will not run. To unfreeze the segment, click the \"eye\" icon, change any property of the segment or turn off the light.
To set individual LEDs starting from the beginning, use an array of Color arrays [255, 0, 0] or hex values \"FF0000\". Hex values are more efficient than Color arrays and should be preferred when setting a large number of colors. {\"seg\":{\"i\":[\"FF0000\", \"00FF00\", \"0000FF\"]}} or {\"seg\":{\"i\":[[255,0,0], [0,255,0], [0,0,255]]}} will set the first LED red, the second green and the third blue.
To set individual LEDs, use the LED index followed by its color value. {\"seg\":{\"i\":[0,\"FF0000\", 2,\"00FF00\", 4,\"0000FF\"]}} is the same as above, but leaves blank spaces between the lit LEDs.
To set ranges of LEDs, use the LED start and stop index followed by its color value. {\"seg\":{\"i\":[0,8,\"FF0000\", 10,18,\"0000FF\"]}} sets the first eight LEDs to red, leaves out two, and sets another 8 to blue.
To set a large number of colors, send multiple api calls of 256 colors at a time. {\"seg\": {\"i\":[0,\"CC0000\", \"00CC00\", \"0000CC\", \"CC0000\"...]}} {\"seg\": {\"i\":[256, \"CC0000\", \"00CC00\", \"0000CC\", \"CC0000\"...]}} {\"seg\": {\"i\":[512, \"CC0000\", \"00CC00\", \"0000CC\", \"CC0000\"...]}}
Do not make several calls in parallel, that is not optimal for the device. Instead make your call in sequence, where each call waits for the previous to complete before making a new one. How this is done depends on your choice of tool, but with CURL you que your commands by separating then with && i.e. CURL [command 1] && CURL [command 2] && CURL [command 3].
Command buffer size
If you are trying to set many LEDs and it fails to work, you can check your request here for length. Select ESP32 and Deserialize. If the required buffer size is above 10K for ESP8266 and 24K for ESP32, please split it into multiple sequential requests and consider using the Hex string syntax.
Keep in mind that the LED indices are segment-based, so LED 0 is the first LED of the segment, not of the entire strip. Segment features, including Grouping, Spacing, Mirroring and Reverse are functional.
Matrices are handled as a non-serpentine layout.
Brightness interaction
For your colors to apply correctly, make sure the desired brightness is set beforehand. Turning on the LEDs from an off state and setting individual LEDs in the same JSON request will not work!
"},{"location":"interfaces/json-api/#playlists","title":"Playlists","text":"(Available since 0.11.0)
Sample playlist API call:
{\n\"playlist\": {\n\"ps\": [26, 20, 18, 20],\n\"dur\": [30, 20, 10, 50],\n\"transition\": 0,\n\"repeat\": 10,\n\"end\": 21\n}\n}\n
This example applies preset ID 26 for 3 seconds, then preset 20 for 2 seconds, then preset 18 for 1 second, lastly preset 20 again for 5 seconds.This repeats 10 times, then preset 21 is applied.
Playlist object:
JSON key Description ps Array of preset ID integers to be applied in this order. dur Array of time each preset should be kept, in tenths of seconds. If only one integer is supplied, all presets will be kept for that time.Defaults to 10 seconds if not provided. transition Array of time each preset should transition to the next one, in tenths of seconds. If only one integer is supplied, all presets will transition for that time. Defaults to the current transition time if not provided. repeat How many times the entire playlist should cycle before finishing. Set to 0 for an indefinite cycle. Default to indefinite if not provided. end Single preset ID to apply after the playlist finished. Has no effect when an indefinite cycle is set. If not provided, the light will stay on the last preset of the playlist."},{"location":"interfaces/json-api/#light-capabilities","title":"Light capabilities","text":"In order to e.g. only show color controls relevant to a given setup, it is necessary to obtain the color capabilities of the light. The info.leds.seglc array can be used to do so on a per-segment level. It contains n+1 8-bit integers, where n is the id of the last active segment, each index corresponds to the segment with that ID. This integer indicates whether a given segment supports (24 bit) RGB colors, an extra (8 bit) white channel and/or adjustable color temperature (CCT):
Bit Capability 0 Segment supports RGB color 1 Segment supports white channel 2 Segment supports color temperature 3-7 Reserved (expect any value) Therefore:
lc value Capabilities 0 None. Indicates a segment that does not have a bus within its range, e.g. because it is not active. 1 Supports RGB 2 Supports white channel only 3 Supports RGBW 4 Supports CCT only, no white channel (unused) 5 Supports CCT + RGB, no white channel (unused) 6 Supports CCT (including white channel) 7 Supports CCT (including white channel) + RGB Note that CCT is controllable per-segment, while RGB color and white channel have 3 color slots each per segment.
info.leds.lc contains this info on a global level, and is a bitwise AND of the per-segment light capability values.
"},{"location":"interfaces/json-api/#cct-control","title":"CCT control","text":"Please also see the general info about CCT.
"},{"location":"interfaces/json-api/#supported-value-ranges","title":"Supported value ranges","text":"Given that the white spectrum handling is agnostic to the true color temperature of the LEDs used, a relative range is preferred for the time being, where a value of 0 indicates the warmest possible color temperature, while a value of 255 indicates the coldest temperature.
It is also possible to pass a value in the range of 1900 to 10091, in which case it is treated as a Kelvin color temperature, where 1900 is mapped to a relative value of 0 and 10091 to a relative value of 255.
As such, it is unlikely to match the actual color temperature output by the light, therefore the relative values 0-255 are preferred for the time being.
In the future, an option to specify the Kelvin temperatures of the utilized hardware may be added, once this is done, a color temperature can be set to more accurately match other lights.
Therefore, for forward compatibility, your integration should expect both either a 0-255 value for seg.cct, in which case it is a relative value, or an absolute Kelvin value in the range 1000-16000 K. In case a Kelvin value is provided, you can consider the color temperature as accurate, which is not possible with relative 0-255 values as the Kelvin points of the white channels are unknown. It is preferred that you set a new CCT value in the same range as received from WLED, that is, use 0-255 if the original value was within this range, and 1000-20000 K otherwise.
If your code relies on absolute Kelvin values, a reasonable estimate for the warm white point (relative 0) could be 2700K, while cold white (relative 255) could commonly be 6500K.
"},{"location":"interfaces/json-api/#effect-of-the-segcct-value","title":"Effect of the seg.cct value","text":"seg.cct can always be set, but only has an effect on the physical state of the light if one or both of the following conditions is met:
- White Balance correction is enabled
- A bus supporting CCT is configured and
Calculate CCT from RGB is not enabled
CCT support is indicated by info.leds.cct being true, in which case you can regard the instance as a CCT light and e.g. display a color temperature control.
"},{"location":"interfaces/json-api/#effect-metadata","title":"Effect metadata","text":"Why effect metadata?
Prior to 0.14, user interfaces showed Speed and Intensity slider, palette controls, and all three color slots regardless of the effect selected. This may cause confusion to the user because controls are displayed that have no immediate effect in the current configuration. Effect metadata allows you to dynamically hide certain controls, so that the user only sees controls actually utilized by the selected effect mode.
Starting with WLED 0.14, effect metadata is available under the /json/fxdata URL. This returns an array of strings with info.fxcount entries. The string at a given index corresponds to the metadata of the effect with the same ID as that index. Metadata is stored in a memory-optimized string format, for example the Aurora effect has the metadata !,!;;!;1;sx=24,pal=50.
The metadata string consists of up to five sections, separated by semicolons: <Effect parameters>;<Colors>;<Palette>;<Flags>;<Defaults>
"},{"location":"interfaces/json-api/#effect-parameters","title":"Effect parameters","text":"The first section specifies the number and labels of effect parameters (e.g. speed, intensity). Up to 5 sliders and 3 checkboxes are supported (sx,ix,c1,c2,c3,o1,o2,o3 parameters in the seg object). Slider/checkbox labels are comma separated. An empty or missing label disables this control. ! specifies the default label is used:
Parameter Default tooltip label sx Effect speed ix Effect intensity c1 Custom 1 c2 Custom 2 c3 Custom 3 o1 Option 1 o2 Option 2 o3 Option 3 The fallback value if this section is missing is two sliders, Effect speed and Effect intensity.
Examples:
Parameter string Displayed controls <empty> No effect parameters ! 1 slider: Effect speed !,! 2 sliders: Effect speed + Effect intensity !,Phase 2 sliders: Effect speed + Phase ,Saturation,,,,Invert 1 slider (sets ix parameter) and 1 checkbox: Saturation + Invert ,,,,,Random colors 1 checkbox: Random colors"},{"location":"interfaces/json-api/#colors","title":"Colors","text":"Up to 3 colors can be used. Please note that only the first two characters of the label are visible in the WLED UI. ! specifies the default label is used. The default labels for the color slots are Fx, Bg, and Cs.
The fallback value if this section is missing is 3 colors: Fx + Bg + Cs.
Examples:
Colors string Displayed controls <empty> No color controls ! 1 color: Fx ,! 1 color: Bg !,! 2 colors: Fx + Bg 1,2,3 3 colors: 1 + 2 + 3"},{"location":"interfaces/json-api/#palette","title":"Palette","text":"If empty, the effect does not use palettes. If !, palette selection is enabled.
The fallback value if this section is missing is palette selection enabled.
"},{"location":"interfaces/json-api/#flags","title":"Flags","text":"Flags allow filtering for effects with certain characteristics. They are a single character each and not comma-separated. Currently, the following flags are specified:
Flag Effect characteristic 0 Effect works well on a single LED. If flag 0 is present, flags 1/2/3 are omitted. (unused) 1 Effect is optimized for use on 1D LED strips. 2 Effect requires a 2D matrix setup (unless flag 1 is also present) 3 Effect requires a 3D cube (unless flags 1 and/or 2 are also present) (unused) v Effect is audio reactive, reacts to amplitude/volume. f Effect is audio reactive, reacts to audio frequency distribution. For example, a Flag string of 2v denotes a volume reactive effect that is to be used on 2D matrices.
The fallback value if this section is missing is 1, i.e. a 1D optimized effect.
"},{"location":"interfaces/json-api/#defaults","title":"Defaults","text":"Defaults are values for effect parameters that work particularly well on that effect. They are set automatically when the effect is loaded. To specify defaults, use the standard segment parameter name (e.g. ix) followed by an = and the default value. For example, sx=24,pal=50 sets the effect speed to 24 (slow) and the palette to ID 50 (Aurora).
If no default is specified for a given parameter, it retains the current value.
"},{"location":"interfaces/json-api/#sensors","title":"Sensors","text":"Warning
This section about the Sensor API is a DRAFT specification. It is not yet implemented and subject to change.
Various types of sensors (e.g. for Temperature, light intensity, PIR) may be added to WLED via usermods. To allow read access to sensor data via the JSON API in a standardized way, the info.sensor array is used.
If the info.sensor array is missing or empty, no sensor values are exposed.
"},{"location":"interfaces/json-api/#sensor-object","title":"Sensor object","text":"Each sensor/measurement is represented by an object within the info.sensor array.
For example,
{\"type\":\"T\",\"n\":\"Outside\",\"val\":12}\n
refers to a 12 \u00b0C temperature measurement in Celsius with the sensor name \"Outside\".
The object may contain the following properties, of which all are optional, except type.
JSON key Value range Description type string The type of the sensor. n string The name of the sensor. If omitted, the client may generate a suitable name (e.g. \"Temperature sensor 1\") val any The most current sensor reading. May be of any JSON type depending on the type of the sensor, this is a number for all sensor types pre-defined below except for the \"b\" and \"CL\" types and custom type sensors. null if the reading is invalid, either due to an error or because the first reading has not yet completed. unit string An explicit human-readable unit string for the measurement. If omitted, the default for the sensor type is used. error int or string If present and not null,false,0 or an empty string, a sensor error is indicated. May either be an integer error code or an error string. tc number Seconds of WLED uptime when the value last changed substantially. The threshold for a \"substantial\" change is up to the implementation. This can for example be used to find when a PIR sensor was last activated. tm number Seconds of WLED uptime when the last reading given by val was obtained. ts number Seconds of WLED uptime at the first measurement / start of measurement period. (required for Energy sensor type) min number Lower bound of possible value range max number Upper bound of possible value range u number Absolute uncertainty of the measurement model string Identification of the sensor hardware used"},{"location":"interfaces/json-api/#sensor-types","title":"Sensor types","text":"These are the standardized sensor types that may be implemented by usermods:
Type ID string Measurement type Default unit \"\" (empty string) Invalid sensor (reserved) - b Button/Boolean true/false c Custom user-defined sensor - q Electric charge As t Time s BL Battery Level % CL 24-bit RGB color hex string E Energy (ts property required) J I Electric current A J Illuminance lx L Distance m Lp Sound pressure level dB M Mass kg N Number/count - P Power W Pe General purpose percentage % PL Power Level (signal strength) dBm Pr Pressure Pa R Electric Resistance Ohms RH Relative Humidity % T Temperature \u00b0C U Voltage V (other strings) Reserved, let us know if you need a new type added - If a client is only interested in certain sensor types (e.g. Temperature), it may disregard all other sensor objects.
"},{"location":"interfaces/mqtt/","title":"MQTT","text":"Important
Notice: The MQTT implementation is currently being restructured to provide a better experience for users of Home Assistant and other automation software. This will be a breaking change. For details regarding the rework, please see #207!
WLED versions from 0.8.0 up are able to connect to an MQTT broker for smart home control. Connection to both domains and IP servers is supported on port 1883.
Warning
Secure connections are not currently supported. I recommend only connecting to local MQTT brokers. In v0.8.4-0.8.6 only, WLED supports MQTT autodiscovery by the HomeAssistant software. This has been removed because of bootloop issues and in favor of the native HomeAssistant integration.
WLED will subscribe to up to six topics to change the state of the lights.
The topic paths [mqttDeviceTopic] and [mqttGroupTopic] are customizable in Sync settings. If [mqttGroupTopic] is left empty, it will not subscribe to anything. An empty [mqttDeviceTopic] will instead be replaced with the default \"wled/macaddr\". [mqttDeviceTopic] is intended to be unique to one WLED device and just control that device. [mqttGroupTopic] is intended to control a group of or all WLED devices.
UDP notifications will be sent just as if the change was done via the UI or HTTP API.
Additionally, on light change, WLED will publish to 3 topics for MQTT clients to query the state of the light.
-
[mqttDeviceTopic]/g -> Contains current brightness as ASCII number 0-255
-
[mqttDeviceTopic]/c -> Contains current color as HEX (#RRGGBB if white is 0, else #WWRRGGBB)
-
[mqttDeviceTopic]/v -> Contains XML API response (same as HTTP API)
There is support for client ID and authentication, but this is presently transmitted over an unencrypted connection, so please do not use the same password for other services.
Attention
The maximum length of an MQTT message for WLED is only limited by free RAM.
"},{"location":"interfaces/philips-hue/","title":"Philips Hue","text":"WLED can sync to your Philips hue lights.
Info
This feature allows your WLED light to set it color to that of one of your Hue lights. It does NOT enable individual control of your WLED light from the hue app.
To activate it, please go to Sync settings, fill in the IP of your hue bridge. Also you need to fill in the numeric ID of the hue light you want to sync to. Newer versions of the Hue app do not display light IDs in the \"About\" section of the app anymore, to find it, the app Hue Config Viewer is highly recommended. It is available on the Play Store as well as the App Store. After pairing the app to your Hue bridge, you can see the numeric IDs of all your Hue lights in the Lights menu.
The poll interval specifies how often WLED asks the hue bridge for a light change. Lower values will mean a quicker response of WLED to hue light changes, but also decrease responsiveness and stability of WLED and potentially the hue bridge. It is recommended to set it to 1000-2000ms.
Due to the nature of the hue protocol, WLED can only sync itself to a native hue bulb. At this time, there is no way to add WLED to the hue bridge and control it individually as if it was a native light.
Please don't expect the same level of stability with this feature active, the ESP may reset itself because of the increased traffic it needs to handle.
With DiyHue you can emulate a hue bridge that will show all WLED strips as Hue Strip Plus which will work with Hue Sync in realtime.
"},{"location":"interfaces/serial/","title":"Serial","text":"WLED 0.13.0 supports multiple protocols over Serial. Serial is available via USB, and on most boards, GPIO1 for TX and GPIO3 for RX.
Pin usage limitation
If GPIO3 is allocated (e.g. for LED output), all Serial functionality except debug output is unavailable. If GPIO1 is allocated, all Serial output is disabled, including the JSON API response, Improv, and tpm2 output.
"},{"location":"interfaces/serial/#adalight-and-tpm2","title":"Adalight and tpm2","text":"Both these protocols are supported and can be used to stream realtime LED data to WLED for direct display, e.g. from an bias lighting program. For tpm2, only data packets are supported and data in 24-bit RGB format is expected. If you want to drive a large amount of LEDs, you may need to increase the Baud rate in WLED Sync settings, as the default baud rate of 115200 is only sufficient for about 50-100 LEDs depending on the refresh rate. Adalight is supported since WLED 0.6.3, tpm2 since version 0.10.2.
"},{"location":"interfaces/serial/#json-over-serial","title":"JSON over Serial","text":"You can send commands to the WLED instance via Serial using the JSON API. To request a JSON response containing the state and info objects, send {\"v\":true}.
"},{"location":"interfaces/serial/#improv","title":"Improv","text":"Improv Serial is supported and can be used to check the installed software version as well as connect your device to WiFi without needing to connect to the WLED access point. Improv is used by the WLED web installer for an easy installation and setup process. Note that the baud rate must remain at the default 115200 setting for the device to be detected as Improv-capable.
"},{"location":"interfaces/serial/#other","title":"Other","text":""},{"location":"interfaces/serial/#version-query","title":"Version query","text":"Send a lowercase 'v' character (byte 0x76) to obtain the ID of the installed WLED version.
"},{"location":"interfaces/serial/#led-data-query","title":"LED data query","text":"To get the colors currently displayed by LEDs:
-
Send an uppercase 'L' (byte 0x4C) to request the current LED data as a tpm2 data packet in 24-bit RGB format.
-
Send a lowercase 'l' (byte 0x6C) to request the current LED data in JSON format. This returns the LED colors as 32-bit integers, of which the lowest byte is the Blue value, then Green, then Red, and the highest byte is the White channel value.
For both of these methods, you may need to increase the baud rate if you have a large amount of LEDs. However, tpm2 requires on average 2-4x less bandwidth than JSON, and should therefore be preferred if your application can parse binary data.
"},{"location":"interfaces/serial/#changing-baud-rate","title":"Changing Baud Rate","text":"There are 2 main method for changing Baud Rate for the serial connection - Persistant: Configure in App under Sync Interfaces. This setting will persist, and WLED will use specified Baud Rate from this point forward. - Temporary: Utilizing the serial connection at the existing Baud Rate, send the specific command byte to have WLED temporarily change to new Baud Rate. This Baud Rate is temporary and will be reset to default or peristant setting on reboot.
Byte Baud Rate 0xB0 115200 0xB1 230400 0xB2 460800 0xB3 500000 0xB4 576000 0xB5 921600 0xB6 1000000 0xB7 1500000 - Note: Keep at 115200 to use Improv. Some boards may not support high rates."},{"location":"interfaces/serial/#debugging","title":"Debugging","text":"Compile with the -D WLED_DEBUG build flag to enable serial debugging using DEBUG_PRINTLN(x) macros. This will reserve pin GPIO1, therefore it cannot be used for other purposes when debugging.
"},{"location":"interfaces/udp-notifier/","title":"WLED UDP Sync","text":""},{"location":"interfaces/udp-notifier/#usage","title":"Usage","text":"The UDP notifier function of WLED makes it easy to sync multiple lights to the same color/effect, enabled by default. You can set the specific behavior of it in Sync settings, also you can choose if all aspects or only brightness/color/effects are applied.
Additionally, there is a \"Sync\" quick toggle for it in the main control UI! In UI settings, you can set whether this button only turns on/off sending (default) or also receiving, with the option Sync button toggles both send and receive.
If your sync settings are not the way you like on boot, check the WLED Broadcast section in Sync settings, where you can specify what is sent and received by default:
"},{"location":"interfaces/udp-notifier/#receiving-settings","title":"Receiving settings","text":"Setting Description Receive Brightness If there is a sync notification, whether its brightness should be applied Color Whether the color of the synced device should be applied Effects Whether the effect settings should be applied If all checkboxes are disabled, nothing is received by default after each boot. If the sync is toggled on in the main UI and the corresponding checkbox in UI settings is checked, everything is received.
A sync receiver will not assume the state of the last sender directly after booting, a new packet must be send for it to react.
"},{"location":"interfaces/udp-notifier/#sending-settings","title":"Sending settings","text":"Setting Description Send on direct change Whether to send a sync notification when state changed via the web UI or API Send on button press Whether to send sync when toggled by the physical hardware button Send Alexa notifications Whether to send sync after changed by Alexa (you may use Alexa groups instead) Send Hue notifications Whether to send sync after a connected Philips light changed Send Macro notifications Whether to send sync after a macro was triggered Send notifications twice Sends notifications twice (if you have issues with UDP packet loss) The quick toggle in the main UI will only apply to direct changes (UI + API), all other sync type sending behavior remains unaffected.
You can easily group WLED devices (for example all in one room) by changing the UDP port of all devices you want in that group.
"},{"location":"interfaces/udp-notifier/#sync-groups","title":"Sync groups","text":"From v0.13.0, 8 Sync groups are available. This allows syncing select instances only without changing the UDP port. For example, you might use one sync group per room you use WLED devices in. Make sure the sender and receiver you want to sync both have the same sync group ticked (a sender can send to multiple groups and a receiver can listen to multiple groups).
Sync packets received from pre-0.13.0 instances are treated as if sent in sync group 1 only.
"},{"location":"interfaces/udp-notifier/#protocol-description","title":"Protocol description","text":"Warning
Note: this info is partly out of date, see updated functionality in the code (udp.cpp)
When enabled, the module where a value was changed will send an UDP broadcast to a port (default 21324). Other modules that listen on this port will set themselves to the same color.
For interoperability, the protocol was designed so that even modules with different WLED versions can sync. Therefore, if a WLED 0.4 system receives a WLED 0.3 UDP notification it will apply the primary color but keep its current secondary color.
The UDP packet is currently 24 bytes long. It is laid out in the following:
Byte Index Var Name Description Notifier Version 0 - Packet Purpose Byte* 0 1 callMode Packet Reason** 0 2 bri Master Brightness 0 3 col[0] Primary Red Value 0 4 col[1] Primary Green Value 0 5 col[2] Primary Blue Value 0 6 nightlightActive Nightlight running? 0 7 nightlightDelayMins Nightlight Time 0 8 effectCurrent Effect Index 0 9 effectSpeed Effect Speed 0 10 white Primary White Value 1 11 - Version Byte*** 1 12 colSec[0] Secondary Red Value 2 13 colSec[1] Secondary Green Value 2 14 colSec[2] Secondary Blue Value 2 15 whiteSec Secondary White Value 2 16 effectIntensity Effect Intensity 3 17 transitionDelay Transition Duration Upper 4 18 transitionDelay Transition Duration Lower 4 19 effectPalette FastLED palette 5 20-23 - Zeros - *The notifier protocol is only used if this byte is 0. Otherwise, one of the UDP Realtime protocols will be used.
**The callMode variable specifies the reason for the notification. Every color update has the potential to trigger a notification.
callMode Description Behavior 0 Initial Boot Do not notify 1 Direct Change via UI or API notifyDirect? 2 Button was pressed notifyButton? 3 Update by other notification Do not notify 4 Nightlight activated notifyDirect? 5 Other (Req. with &NN) Do not notify 6 Effect changed notifyDirect? 7 Hue light changed notifyHue? 8 Preset Cycle active notifyDirect? 9 Updated via Blynk notifyDirect? ***This is the version of the UDP protocol.
UDP Version Description WLED Version 0 Basic Support 0.3 1 White Value supported 0.4p 2 Secondary Color supported 0.4 3 Effect Intensity supported 0.5.0 4 Transition Time supported 0.6.0 5 Palettes supported 0.8.0"},{"location":"interfaces/udp-realtime/","title":"UDP Realtime / tpm2.net","text":""},{"location":"interfaces/udp-realtime/#hyperion","title":"Hyperion","text":"You can now use WLED with the popular Ambilight software Hyperion. Just configure Hyperion to use an UDP device with protocol 0 on port 19446! The maximum number of LEDs supported in this mode is 490. (WLED 0.8.0 and lower: 341)
"},{"location":"interfaces/udp-realtime/#prismatik","title":"Prismatik","text":"Prismatik is another Ambilight option. Select one of the UDP options in the device configuration wizard.
"},{"location":"interfaces/udp-realtime/#tpm2net","title":"TPM2.NET","text":"Supported in latest master and will be available in WLED 0.10.1. Please set the WLED broadcast UDP port to 65506 in Sync settings to enable receiving TPM2.NET data.
"},{"location":"interfaces/udp-realtime/#udp-realtime","title":"UDP Realtime","text":"Additionally, WLED offers a way to directly drive the connected LEDs via UDP. The protocol is referred to as WLED Audio-Reactive-Led-Strip (WARLS), since the support of that project was its primary goal. However, it can also be used for other realtime applications like an ambilight.
WARLS uses the same UDP port the notifier uses (default 21324, can be changed in settings). At the moment, the web UI will be disabled while active, the HTTP API, Alexa and button control remains functional. It uses the current brightness and gamma correction settings.
Byte 0 of the UDP packet tells the server which realtime protocol to use.
Value Description Max. LEDs 1 WARLS 255 2 DRGB 490 3 DRGBW 367 4 DNRGB 489/packet 0 WLED Notifier - In every protocol, Byte 1 tells the server how many seconds to wait after the last received packet before returning to normal mode, in practice you should use 1-2 (seconds) here in most cases so that the module returns to normal mode quickly after the end of transmission. Use 255 to stay on the UDP data without a timeout until a request is requested via another method.
After this the LED color information is transmitted like this:
WARLS
Byte Description 2 + n*4 LED Index 3 + n*4 Red Value 4 + n*4 Green Value 5 + n*4 Blue Value DRGB: This mode has the difference that the LED indices are not part of the packet, instead every LED is updated. This leads to a higher speed when all LEDs are changed, but a drastically lower speed if only one LED is updated per packet.
Byte Description 2 + n*3 Red Value 3 + n*3 Green Value 4 + n*3 Blue Value DRGBW: Like DRGB, but supports the White value for RGBW strips.
Byte Description 2 + n*4 Red Value 3 + n*4 Green Value 4 + n*4 Blue Value 5 + n*4 White Value DNRGB: DRGB, but with 2 additional bytes that signify the starting LED index. This allows for more than 490 LEDs in realtime mode by sending multiple packets.
Byte Description 2 Start index high byte 3 Start index low byte 4 + n*3 Red Value 5 + n*3 Green Value 6 + n*3 Blue Value When realtime mode starts, all LEDs will be black. However, you don't have to change all LEDs using one packet. Changing a single LED therefore only requires a packet of 2+4 bytes. All LEDs maintain their color until it is changed or the module exits WARLS mode because of a timeout.
"},{"location":"interfaces/udp-realtime/#setup-with-arls","title":"Setup with ARLS","text":"The software now supports audio-reactive-led-strip!
- Download audio-reactive-led-strip and follow its installation instruction. You can also use my (untested) fork. In that case, you can skip step 2.
- Insert the following code in led.py after line 66: m.append(1); m.append(2); These are the first two bytes of the protocol.
- In config.py set your led amount, ESP IP and WLED UDP notifier port. For FPS, a setting between 15-30 is recommended.
- Run visualization.py! If you have a low amount of LEDS (e.g. 10) try lowering the sigma values in line 129-131.
- If you have multiple WLED devices, you can sync them all with music. Use the led count of your largest device and set the IP to X.X.X.255 (UDP broadcast). You can adjust the position of the amplitude with the WARLS offset setting. Note that web control currently does not work while it is active.
"},{"location":"interfaces/websocket/","title":"WebSocket","text":"Version Info
Since WLED 0.10.2, a WebSocket server is enabled by default and can be used to access a subset of the JSON API.
The server is available at the /ws endpoint, you can access it like ws://[WLED-IP]/ws.
You may send any JSON state update to the socket. On change of the lighting state, the server will send a JSON object containing the state and info objects (this is equivalent to HTTP GET /json/si) to all connected clients. This object will also be sent to a client upon connecting.
You can also request a live stream of the LED values (e.g. the \"Peek\" feature of WLED-UI) by sending {\"lv\":true} to the websocket. The returned format is the same as for /json/live. Only one client can receive this at a time, if a new client requests it the stream will stop for the previous client (but the websocket will stay connected).
There can be a maximum of 4 clients connected at a time. If a fifth client connects, a different client will be disconnected. On ESP8266, it is recommended to have no more than 2 clients connected simultaneously.
"},{"location":"interfaces/json-ir/json_infrared/","title":"Infrared","text":"Version Info
Since v0.13.0, infrared control for any IR remote compatible with your IR receiver with JSON remote.
A dedicated infrared receiver module is required. (KY-022 or TSOP38238 are confirmed to work and inexpensive)
The default sensor pin is GPIO4. It can be changed in the WLED settings.
"},{"location":"interfaces/json-ir/json_infrared/#json-ir-remote","title":"JSON IR Remote","text":"The JSON IR remote allows users to customize IR remote behavior without writing custom C code or compiling. Using the JSON IR remote, you can map buttons from any compatible remote to any HTTP request API or JSON API command.
The map of IR codes to API commands is stored on your ESP's file system in ir.json. From the \"LED Preferences\" page, set the IR pin and remote type to \"JSON remote\". Once \"JSON remote\" is selected, a file upload control will appear. You can also upload and edit ir.json from the /edit page, which can be reached by going to http://[controller-ip]/edit. If you use the edit page to upload your config file, be sure to name it ir.json.
"},{"location":"interfaces/json-ir/json_infrared/#preconfigured-remotes","title":"Preconfigured Remotes","text":"LED remotes typically are not sold separately. But you can purchase with an RGB controller for $2-4 on AliExpress and $5-10 on Amazon. When purchasing a remote, be sure that it is an infrared (IR) remote and not a radio (RF) remote as they are not supported at this time.
44-key white ir.json
40-key blue ir.json
40-key black ir.json
38-key ir.json (Sold with WLED compatible SP511E controllers)
32-key ir.json (commonly sold with fairy string lights)
24-key (very common, but buttons need repurposed to be very useful with WLED) ir.json v1 gray buttons load presets 1-4 ir.json v2 gray buttons cycle effects, palettes and change speed
24-key grey ir.json
24-key music ir.json v3
21-key ir.json
18-Key Silver ir.json
6-key ir.json
"},{"location":"interfaces/json-ir/json_infrared/#editing-irjson","title":"Editing ir.json","text":"First see if a JSON file already exists for your remote. If not, see if there is a JSON file for a remote with the same number of buttons. Often remotes with the same number of buttons have different labels but emit the same codes. The JSON keys are the hex encoded IR codes emitted by each button. The keys are strings and case is important, be sure to use the same format as the sample below. It is also the same format used when codes are echoed on the serial console.
In the JSON document, each button object should have a cmd attribute containing the HTTP request or JSON API command. In addition to HTTP and JSON API commands, several C functions are supported (!incBrightness, !decBrightness, !presetFallback). The !incBrightness and !decBrightness functions, take smaller steps at the dim end of the range with progressively larger steps at the bright end. The !presetFallback function applies a preset (attribute PL) and falls back to the specified effect and palette (attributes FX and FP) if preset does not exist. (see sample below)
If an IR remote button is pressed rapidly or held down, subsequent presses have a different code (0xFFFFFFFF). If your command is repeatable but does not contain the \"~\" character and is not calling incBrightness or decBrightness, then add a \"rpt\" attribute with a value of true. Label and position attributes are ignored by WLED but useful when making edits.
If an ir.json file does not already exist for your remote, you will need to determine what code each button emits. To do this, connect your ESP8266 or ESP32 to a computer and open Arduino or VSCode serial monitor. Then press each button and record the code printed on the serial monitor. You should see something like this:
IR recv\n0xFFDE10\n
You should get a 24-bit hex encoded integer. If you get 0xFFFFFFFF, that means the button has been pressed repeatedly or held down. Try tapping quickly.
"},{"location":"interfaces/json-ir/json_infrared/#tips","title":"Tips","text":" - Map
play or auto buttons to a playlist. They currently just turn on preset cycling CY=1 or load a playlist of presets 1-5. You can define the playlist in ir.json as in the sample below, or save a playlist as a preset and load that. - Save your 'every day' presets in one range of ids, maybe 1-30; your 'holiday' presets in another range, maybe 31-40. Then you can devote two buttons to cycle through presets. In our example, the command on the 'holiday cycle' button would be
P1=31&P2=40&PL=~ - You can also group your presets by color; for instance reddish animations in 1-10, greenish in 11-20, bluish in 21-30. The 44-key remote has up and down arrows for red, green and blue. So the command on the 'blue down' button would be
P1=21&P2=30&PL=~- - Most of the 24-key and fewer remotes are designed with analog LEDs in mind and do not have very useful labels for WLED. With JSON IR and a fine-tip Sharpie, you can repurpose buttons to make them more useful.
"},{"location":"interfaces/json-ir/json_infrared/#irjson-sample","title":"ir.json sample","text":"{\n\"0xF740BF\": {\n\"label\": \"On/Off\",\n\"cmd\": \"T=2\",\n\"rpt\": true\n},\n\"0xF700FF\": {\n\"label\": \"Speed +\",\n\"cmd\": \"SX=~16\"\n},\n\"0xF720DF\": {\n\"label\": \"Red\",\n\"cmnt\": \"Lava palette + primary, secondary and tertiary colors\",\n\"cmd\": \"FP=8&CL=hFF7F00&C2=hFF0000&C3=hCC3D60\"\n}, \"0xF710EF\": {\n\"label\": \"Timer1\",\n\"cmnt\": \"Timer 60 min\",\n\"cmd\": \"NL=60&NT=0\"\n},\n\"0xF730CF\": {\n\"label\": \"Play\",\n\"cmnt\": \"prime example of a playlist that cycles every 180 seconds and continues to repeat\",\n\"cmd\": {\"playlist\":{\"ps\":[1,3,5,7,11,13,17],\"dur\": 1800,\"transition\":7,\"repeat\":0,\"end\":0}}\n}, \"0xFF9867\": {\n\"label\": \"Bright+\",\n\"cmnt\": \"smaller steps at beginning, larger steps at the end\",\n\"cmd\": \"!incBrightness\"\n},\n\"0xF78877\": {\n\"label\": \"DIY1\",\n\"cmnt\": \"Preset 1, fallback to Saw(16) - Party(6) if it doesn't exist\",\n\"cmd\": \"!presetFallback\",\n\"PL\": 1,\n\"FX\": 16,\n\"FP\": 6\n},\n}\n
"}]}
\ No newline at end of file
diff --git a/sitemap.xml.gz b/sitemap.xml.gz
index 3727ff1ae..06cc8264a 100644
Binary files a/sitemap.xml.gz and b/sitemap.xml.gz differ
