WLED Tutorial – Install and Setup a ESP8266 or ESP32 with your WS2812B/WS2811 individually addressable RGB LED strip, animations and effects
Addressable RGB LEDs, or “Neopixels” as Adafruit call them, are a lot of fun. Heck, it is not just a niche hobby but spawned an entire industry.
Did you know you can control them via a web page or your Android/iOS device, or programmatically over serial and WiFi?
In this tutorial we will set up and configure ESP8266 and ESP32 based boards with WLED, hook them up to RGB LEDs, and get them dancing!
Programming Addressable RGB LEDs
Addressable LED projects are everywhere on Arduino tutorial sites and YouTube, and for good reason.
People love the visual effect, of course, but also they are a quick and easy project that gives “wow” results.
I have built more of these projects than I can count, I even did some contract work for a “no-code” RGB LED ecosystem startup called Bekonix for a while back there.
To program these LED effects we might have used an Adafruit library or FastLED under Arduino. You can use Python/MicroPython/CircuitPython too. Plus, of course, there is the brute-force methods of pushing bit-patterns down the wires.
This covers a huge number of chipsets and microcontrollers, from the ATTiny up to the latest boards. Some, like this Pico 2040 board from PiMoroni, are especially designed for the purpose.
When talking about getting your RGB LED project on the internet, or talking to your home automation system, we really focus on the ESP8266 and ESP32, however, and for this there is one community that really stands out; WLED.
WLED and the ESP8266/ESP32
The WLED project is absolutely amazing, and it is the go-to for anyone who wants to hook up some LEDs and just run some effects but with customization not found on the off-the-shelf LED strip products.
WLED is famous for the powerful and friendly web user interface that allows you to quickly configure and test out all kinds of wonderful effects and colour palettes on your LEDs.
What fewer people know, though, is there are many ways to interface with WLED using their various APIs.
Even better, now WLED supports LED Matrix Panels!
Installing WLED on ESP8266 and ESP32
If you have a supported ESP8266 or ESP32 based board, which is nearly all of them, you can just plug your board into USB then go to the web installer page in either Chrome or Edge.
You will need to select your USB connection from the list of detected devices.
If your device doesn’t show up, it probably means you need a driver for your machine to speak serial to it.
Multiple options might appear that seem potentially the correct one, so to eliminate the wrong choices try and disconnect or switch off anything that might confuse the situation.
After a couple of minutes your board will have been wiped, the firmware installed, and you will have the opportunity to choose your WiFi network to connect to.
I find the ESP32, as well as connecting faster, also is more forgiving than the ESP8266 about signal quality, so do not be surprised if it takes a moment and also if you need to raise your board up and wave it around a bit!
Once connected to WiFi, now you can control it from your web browser or one of the apps that have been developed for the platform.
The user interface is responsive, so you can happily use it from your desktop, tablet, or phone, you do not need to install a native app if you don’t want to.
Speaking of responsive, your project can be audio responsive, that is, it can respond to music and sounds. We will look at that in a future project.
As well as connecting via the IP address, you can also give your device a name, for example I called my small matrix http://8x8matrix.local/
Choosing Your RGB LED Strips
For most projects, WS2812B or SK6812 strips are great options. You can find these on Amazon, eBay, or AliExpress.
Pay attention to details like LED type (for this you will want individually addressable, but a lot of cheaper RGB strips are only able to change the entire strip colour at once), strip length, power/voltage, and waterproofing when making your purchase depending on what your project entails.
Personally, I stick to 5v LEDs in most cases, though I have used 12v in the past.
To diffuse the LED light, consider looking at diffuser channels. LED strips with 60 LEDs per meter are better for diffusion.
Connecting the RGB LED Strip
Using breadboard jumper wires, connect your ESP8266 or ESP32 to your LED strip.
Match the following colours for easier setup:
- Voltage (VIN pin) is usually Red
- Data (D2 pin) is usually Green or White
- Ground (GND pin) is usually Black or White.
Personally, even though every schematic demands it, I do not find I need any resistors unless the wires from my board to my strip are like a foot or more apart, since that is when flickering might start happening, but your mileage may vary.
The resistors and capacitors are there to “smooth” things out and mitigate any interference, especially from the ground line or wobbly power.
I would certainly install a 470 ohm resistor between your board data pin and the LED strip in a very long, permanent or commercial installation.
Smaller strips or matrix LEDs can be powered just using the 5V on your microcontroller board, but once you get into larger sets of LEDs, or if your LEDs will be constantly bright, then you need to inject external power supplies …
Powering Your RGB LEDs
These boards can usually only supply around 500 milliamps of power, total. As each RGB LED can draw up to 60 milliamps at full brightness, you can do the math if powering your strip is possible.
If in doubt, add a separate power supply.
You have options for powering your LEDs:
- 5V USB charger or power bank: Suitable for portable setups, while developing, or for smaller projects. USB-C is especially capable of supplying a surprising amount of power, and some boards are designed with RGB projects in mind. Rather than plugging into the USB socket of the board, instead split the 5v power to both the board and the strip independently.
- External power source: Providing more power for longer lengths or brighter LEDs requires a more powerful power source. That could be a DC “wall wart”, all the way up to things like PC power supplies. In these scenarios you will connect data and ground as before, but also connect ground to your power supply, and of course the power line would go from the supply to the RGB strip. Ensure you are using the correct gauge wire for your power usage to prevent accidents.
Keep in mind, while some installations last years and years, these LEDs are not designed to be used at bright levels 24/7. Expect them to burn out sooner if you work them harder.
Configuring WLED
Once everything is connected, power on your board and connect to the WLED interface.
The first thing you need to do before anything else is set which GPIO pin your data line is connected to, because otherwise your strip will not be sent any data, how many LEDs you have, and what type.
In the example below, I am using a cheap Aliexpress “Shiji Lighting” WS2811 strip connected to GPIO 3 on my M5Stack ESP32 board, which on the case is labelled R0, and I am powering off a 5v, 2amp DC power supply.
Now you can test everything is working and configure your preferences in the WLED dashboard, adjusting settings like brightness and effects.
Explore different animations and palettes to customize your lighting and see what the system is capable of!
A partially-complete visual guide to various effects is available on Github by user Aircoookie.
What’s Next?
Now we have our LEDs lit up and making pretty patterns, you could stop there, but being a nerd I don’t want it to just sit there and do its own thing, I want to have remote control, and eventually I want to paint pictures and custom messages on my LED matrix.
WLED API automation is what we shall do next in part 2!
