Whether you call them individually addressable RGB LEDs, WS2812B, or NeoPixels, there’s no denying that they are extremely popular and a must-have for any glowy and blinky project.

Writing code to control addressable LEDs isn’t difficult, but what if you just want to add some ambient lighting to your living room or office and manage it all from your smartphone? Currently the best option, hands down, is WLED—A free, feature-rich, open-source mobile app that gives us complete command over a wide variety of RGB LEDs.

The WLED app makes controlling individually addressable LEDs much simpler, convenient, and—most importantly—fun. This app is just too cool not to try.

In this tutorial, we will learn how to install WLED on an ESP8266 board and use it to control a string of addressable LEDs.

Installing WLED on an ESP8266 Board

1. The first step is to download the ESPHome-Flasher tool. Open a browser to the ESPHome-Flasher github page and look for the installer for your operating system, then download it.

2. You also need to download the WLED compiled binary. Navigate to the WLED github page and download the WLED_0.x.x_ESP8266.bin file.

3. Connect your ESP8266 board to your computer using a USB cable. Make sure the USB cable you’re using supports data transfer.

4. Launch the ESPHome-Flasher tool.

5. Select the COM port to which your ESP8266 is connected. If nothing appears in the serial port dropdown, you may need to update your USB-to-serial drivers, or you may not be using a USB cable that supports data transfer.

6. Click the ‘Browse’ button and then select the WLED binary file that you just downloaded.

7. Click ‘Flash ESP’ to flash the firmware to the board. It shouldn’t take more than a few minutes to complete.

8. Once it displays “Done! Flashing is complete!”, you can exit the program.

9. Select the Network icon on the taskbar. You should notice a new wireless access point named WLED-AP.

10. Join that and then enter wled1234 when prompted for a password.

11. When you connect to the network, your default browser will launch automatically and load the WLED home page. If it doesn’t launch for some reason, open a new browser and navigate to http://4.3.2.1, which should take you to the same location.

12. Select WIFI Settings. This will bring up the WIFI Setup section.

13. Change the Network Name and Network Password to the name and password for your WiFi network. Scroll down to mDNS address and set the address to your liking. I called mine http://mylights.local/ – from now on, this is what I’ll be typing into a web browser on my WiFi network to connect to my lights.

14. Click Save and Connect. Your ESP8266 will reboot and connect to your WiFi network. However, it is a good idea to reset your ESP8266 by pressing the RST button.

15. Finally, make sure that you reconnect to your home network.

16. Now navigate to your mDNS address (in my case it’s http://mylights.local/) to access the WLED User Interface (UI).

A Quick Tour of the WLED UI

WLED’s UI is simple, but may appear overwhelming at first. The UI can be divided into five sections.

1. Configuration: Here you can find buttons such as Power (to turn the lights on or off), Timer (to organize the lights to come on and off at certain points during the day), Sync (to sync multiple WLED devices across your network), Peek (to see an animation preview of your lights), Config (to configure the number of LEDs and the GPIO port), and a Brightness slider (to control the overall brightness).

2. Color Picker: This section allows you to change the color of the LEDs, whether they are static or animated. If you scroll down this section, you can access various color palettes for use in effects.

3. Effects/Animation: Here you’ll find a library of ready-made animations for your lights. While each effect has its own color scheme, you can easily customize it in the Color Picker section.

4. Segment: If you have a large array or matrix of LEDs, you can split them into segments and assign a different color, animation, or color scheme to each segment.

5. Presets: Here, you can create presets for your custom light show, as well as a playlist to cycle through the many available animations.

Configuring the WLED

Once the setup is complete it’s a good idea to head to the LED Preferences screen and configure LED lights.

1. Click on Config and select LED Preferences.

2. Scroll down to Hardware Setup and select the type of led strip you have.

4. Set the “Length” to match the number of LEDs. We have a total of 12 LEDs, so I changed the length to 12.

5. Make a note of the GPIO pin number. This pin will be used to send data to the LEDs. By default, GPIO2 (D4) is used.

6. Scroll down to the bottom and click Save.

7. Click Back to return to the main screen.

Connecting a WS2812x Addressable LED Strip to an ESP8266

Once you’ve finished configuring the WLED, unplug the ESP8266 from the USB port. Let’s wire up an addressable LED strip to the ESP8266.

The wiring is relatively simple. There are only three wires to connect: two for power and one for data transmission.

Connect the Red wire (+5V/VCC) of the addressable LED strip to the ESP8266’s VIN pin and the White/Yellow wire (GND) to the ESP8266’s GND pin.

Finally, connect the Green wire (DIN) of the LED strip to the ESP8266’s GPIO2 (D4), via a 330 Ohm resistor. This in-line resistor is there to protect the data pin. A resistor between 220 and 470 Ohm should do nicely. Try to place the resistor as close to your addressable LEDs as possible.

If you have few LEDs you can plug the ESP8266 into your computer using a USB cable and power the strip directly through the board.

If you have a larger project that requires more LEDs, USB power won’t be enough. Instead you should inject power into the strip from an external source. Keep in mind that each RGB LED consumes about 60mA (20mA per color channel), when the brightness is set to full. That means that for every 30 LEDs, your LED strip could be drawing up to 1.8 Amps.

Once wiring is complete, LEDs should come to life and emit a soft yellow light. If this isn’t the case, double-check your wiring before proceeding.

From here everything can now be done via the WLED App.

Using the WLED Mobile App

1. Download the WLED app from the Google Play Store or the Apple App Store on your smartphone or tablet.

2. Open the app and click on the plus icon in the upper right corner to open up the discovery page.

3. Hit Discover Lights. This will search through your WIFI for all connected boards running WLED software.

4. Once it says Found WLED! click the Tick icon in the upper-right corner. This will bring you back to the home page where you will have a list of all the WLED devices on your network.

5. Click on the newly discovered device to open the control panel.

6. Select a color using the color wheel. And voilà, you now have fully operational, remotely activated addressable LEDs!

If the color of the LEDs does not match the color you selected in the app, go to Config > LED Preferences and adjust the Color Order setting under Hardware Setup until it does.

7. If you have multiple WLED devices, you may want to change the name displayed on the app to differentiate them. Go to Config > User Interface and name it whatever you want, then hit Save.

Changing Effects

WLED offers over 180 different effects. This is where the real fun begins.

1. Navigate to the Effects tab and select an effect. The LEDs will respond immediately.

2. You can change the speed and intensity of the effect. The further you move the slider, the faster and more intense the effect.

3. Each effect has its own color scheme, which you can easily change in the Color Picker section. This will keep the animation effect but replace the colors.

Tips and Recommendations

There are a few tips and recommendations to keep in mind when designing your setup with ESP8266:

• ESP8266 can handle up to three strips at a time.
• While most strip types have yet to be tested, the following are known to work: WS281x, SK6812 RGBW, PWM white
• As soon as installation is complete, select the LEDs type, pin numbers, length, and color order of your LED strips in the LED settings page.
• Framerate can be increased significantly by selecting the appropriate power supply for the setup and turning off the WLED brightness limiter setting.
• It is highly recommended to use two LED pins, GPIO1 (TX) and GPIO2 (D4), since they support hardware driving.
• When GPIO1 is used, serial debugging is disabled. If you don’t need it, you can use a strip on this pin.
• GPIO3 is the third pin on the ESP8266 that allows hardware driving. However, it consumes 5 times the memory per LED as GPIO 1 and 2, so it should only be used for low LED counts (recommended <50).
• It is possible to use any other pin, but it will use the bitbang method for that, which is not recommended for reliability. It is best to stick to GPIO 1, 2, and, if necessary, 3.
• The performance is determined by how many LEDs you drive with the ESP8266 and how many ESP8266 output pins you use.
  • For excellent performance, it is recommended to use 512 LEDs/pin with 2 outputs for a total of 1024 LEDs.
  • For marginal performance, you can use 800 LEDs/pin with 2 outputs for a total of 1600 LEDs.
• ESP8266 is capable of calculating approximately 15k LEDs per second (that’s 250LEDs @~60fps, 500 LEDs @~30fps, 1000 LEDs @~15fps)