You want to add custom features to WLED, use non-default pins, or add in a usermod? You've found the right place!
Only want to build the code with some custom defines to e.g. enable a usermod?
Unless you want to do changes yourself, you don't necessarily have to install the development environment.
In the WLED Discord server, there is the WBLD bot which will build your custom PIO environemt with the
./build custom command.
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.
Installation guide (PlatformIO, recommended)
- 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 ideand install the PlatformIO extension
Download the WLED source code by executing
git clone https://github.com/Aircoookie/WLED.gitin some folder. (You can also use GitHub Desktop or download the latest source code from https://github.com/Aircoookie/WLED under the
Codedropdown menu as a .zip file.) Alternatively fork the WLED project first and download it from your fork.
File -> Open Folderand open that root WLED folder (the one that contains
platformio.ini, NOT the
Compilation guide (PlatformIO)
Make sure Git Client is installed on your system. You can get it here.
- In VS Code, open the file
- Add a semicolon in front of the line that says
default_envs = travis_esp8266, travis_esp32to 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_minienvironment is best.
- In the blue bottom bar, hit the checkmark to compile WLED or the arrow pointing right to compile and upload!
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 directory
FileNotFoundError: [WinError 2] The system cannot find the file specified: '[...].sconsign37.dblite'
Making a custom environment
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.sampleinto a new file called
platformio_override.ini. Make sure
platformio_override.iniis in the same folder as
- Replace the line
default_envs = WLED_tasmota_1Mwith the line you uncommented in
platformio.iniin the previous steps (from Compilation guide (PlatformIO)). Example:
default_envs = d1_mini
platformio.iniscroll down until you see
#-------------------- # WLED BUILDS #--------------------
- Find the section that matches the build environment you selected in previous steps. Example:
- Select the whole section (including the first line in brackets [ ] ), and copy and paste it into
platformio_override.inioverwriting the build environment section that was already there.
- Add a new line under the the line that starts with
- Put your
-Doverrides on this new line, giving each
-Dit's own new line.
- Compile your freshly customized WLED image!
Flashing the compiled binary
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.
Compilation guide (Arduino IDE, not recommended)
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:
|ESPAsyncWebServer Aircoookie fork (2.0.0)||All|
|AsyncTCP for 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 Binaryand upload with any ESP flashing tool.)
Compilation settings (Arduino IDE)
- 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
- Arduino Core v1.0.6