How to use WLED to control NeoPixels or DotStars with an ESP8266 or ESP32
Disclosure: This post contains affiliate links. If you click through and make a purchase, I will earn a commission, at no additional cost to you. Read my full disclosure here.
I have previously written about what WLED is and can do. But how does one use it in practice? This guide will cover the basics of connecting NeoPixels (WS2812B, WS2811, SK6812), DotStars (APA102), or other SPI-based chipsets such as the WS2801 and SK9822, to an ESP8266 or ESP32 board, and flashing WLED to that microcontroller.
This WLED guide will also give you a comprehensive overview over what you might need to get started. The goal is to help you decide whether you should use an ESP8266 or ESP32, which LED strips to go for, and what additional components, such as level shifters, resistors, and capacitors, you might need to get things running smoothly.
The ESP32 has some advantages over its predecessor, the ESP8266. It has a faster processor, more RAM, plus it supports Bluetooth. The ESP8266 on the other can be bought for less money. The question is, can WLED make use of the updated specs of the ESP32? The truth is that you likely won't need a ESP32 for your first couple of projects. WLED doesn't use Bluetooth and the better specs are wasted on an LED strip controller.
Keep in mind that WLED isn't comparable to ESPHome. You won't be able to attach any additional sensors that might need the better specs, or use the Bluetooth functionality for presence tracking. All WLED does is control addressable LEDs and nothing more.
All in all, it's fair to say that a cheap ESP8266 is the way to go for close to all personal projects. The ESP8266 can handle powering lamps and accent lighting at ease. Your ESP32 is much better used for complex ESPHome projects, or those that need the power and/or Bluetooth.
How to flash WLED on to an ESP8266 or ESP32
I believe that it is easier to first flash the ESP8266 or ESP32 with WLED, before attaching any of the components or soldering a single wire. This way, the board only connects to your computer, there's nothing attached to it by fragile wires, and you don't have to worry about powering any of the other components.
This is doubly true when using WLED, as there are no code adjustments to be made down the line. Not even the Wi-Fi network has to be entered using an access point the microcontroller creates and not in code. Once you have flashed it, there is no reason to ever connect it to a computer again.
To get your ESP8266/ESP32 flashed, simply connect it to your computer using the Micro-USB port or by using a programmer (adapter board) if using one of the ESP-XX modules from AI-Thinker.
ESPHome flasher can be used to flash WLED on to an ESP8266/ESP32
Wiring a basic WLED-powered LED controller is relatively simple, as there is only one way of doing it, though there are a few extra components you might want to add (detailed in the next chapter). The data pin on the LED strip connects to GPIO2 of the ESP8266 or ESP32 board. But before you do that, read through this guide carefully. Especially the chapter on level shifters should be studied before any wire has been soldered.
Keep in mind that the GPIO pin does not correspond with the pin's label on the board. For example, on a LOLIN (previously WEMOS) D1 mini, GPIO2 is the pin D2. The same goes for a NodeMCU board, but on an ESP32 it is often the pin labelled D4. A quick Google image search should bring up a schematic, detailing which pin does what.
Using a prototype board and screw terminals
How exactly you connect the LED strip's data pin to the ESP8266/ESP32 is your decision to make. There are many ways of doing it, and all have their benefits and drawbacks. If space isn't an issue, I recommend soldering female pin headers to a prototype board and male pin headers to the ESP8266/ESP32.
That way, the microcontroller can nicely slot in, and it can easily be replaced if anything were to break. If you opt to use a level shifter, I would also attach it using male and female pins. The data pin, and power supply, can attach to a screw terminal block which has also been soldered to the board.
WAGO lever nuts and other wire connectors
A popular alternative are WAGO lever-nuts and other wire connectors. You solder a wire to the microcontroller and one to the LED strip, and connect the two using one or the other. I suggest you only use these connectors if there is absolutely no strain on the wires. Solder joints and thin wires are not meant to support any weight. It might make sense to also crimp the ends of the wires using a crimping tool if you were to go down this route.
The final two options are the cheapest and the most extensive. You could solder the LED strip directly to the ESP8266/ESP32 using, though this would make repairs and replacements difficult and might strain the joint or wire. It is also more likely that accidental shorts could occur due to loose wires. Generally, I wouldn't recommend going down this route, unless the size of the project is of essence.
On the other end of the pricing scale is creating a custom PCB (or using one that someone has already designed). A custom PCB makes the whole project neater and is much easier to work with when compared to a prototype board (there is a reason they are called prototypes). A very popular and well documented predesigned custom PCB for WLED can be found in this GitHub repository by srg74.
Hooking up the power supply to a WLED project
It is theoretically possible to power the ESP8266/ESP32 using a Micro-USB cable and phone charger and then hooking up some LED pixels to the board's 5V output. However, you should not do this under any circumstances. The 5V output can only handle a minimal load and is better used as a power input for a WLED project's power supply because you will likely be using a 5V power supply for the LEDs.
I once again suggest that you use a screw terminal for power. Attaching a female barrel jack adapter to the enclosure where your microcontroller will be housed is the easiest way of getting the power inside the enclosure while still being able to remove the cable. You can use a screw terminal to attach the wire coming from the barrel jack adapter. Then run thick traces to the screw terminal where the LED pixel strip will be attached.
This example shows you how to use screw terminals and is not a complete setup of WLED
Capacitors? Level shifters? Resistors? This all sounds a bit complicated.
If you have never built an electronics project, the use of capacitors, level shifters, and resistors might sound a bit daunting. Don't worry, when I started building nodes using the popular LOLIN D1 mini, I had a minimum amount of experience with electronics. Unless you are planning highly complex builds, you will quickly learn what you need and how everything works.
Does WLED need a capacitor?
You will find many debates online, discussing whether you should add a capacitor to the power supply of a WS2812B, SK6812, or other LED strip or not. While I might not be an expert on the subject, I have so far not found any compelling reasons not to do it.
No products found.
Capacitors are cheap for the benefits they offer. A capacitor will smooth the voltage and sudden changes in demand for current from the LEDs. I suggest you buy yourself a handful of 1000uF capacitors and use them whenever needed.
Does WLED need a level shifter?
A level shifter is another component you could potentially get away with leaving out, but I once again advise you use one. The issue is that LED strips such as the WS2812B or SK6812 use a 5V data signal, whereas the ESP8266 and ESP32 one that is only 3.3V. The level shifter allows for clean communication between the two, translating the 3.3V data signal to 5V. When using a level shifter, I advise soldering it and the ESP8266/ESP32 to a perfboard. Another benefit of using a level shifter is that you won't need a resistor.
The bi-directional logic level converter is a small device, which can safely steps down 5V signals to 3.3V and steps up 3.3V to 5V at the same time.
According to the WLED documentation, the level shifter can be left out, if you keep the wire connecting the GPIO and data pin short. How short exactly isn't mentioned, though. The level shifter will need a reference for both 3.3V and 5V. If you are using an ESP8266 board such as the LOLIN D1 mini, which has an on-board 3.3V regulator, its output can be used. The 5V can simply be attached directly to the power supply (if you are using a 5V power supply).
For simplicity's sake, a 5V LED strip is what I recommend you use, as it allows you to power the ESP8266/ESP32 from the same source without the need of a converter. Additionally, most addressable LED strips, such as the WS2812B and SK6812 use 5V, while 12V LED strips are harder to come by.
You might be asking yourself why anyone would ever go with a 12V LED strip, when the ESP8266/ESP32 itself requires 5V. Why go through the trouble of having a 5V and 12V circuit? The argument for 12V LED strips is the voltage drop, and it is the main limiting factor of 5V LED strips.
If you are working with only a short LED strip, the 5V option won't present an issue. But voltage drop can cause LEDs which are at a certain distance from the power supply to look slightly off. There are ways of avoiding this issue, such as power injection at certain points. Though voltage drop isn't exclusive to 5V LED strips, they just occur further along the line on 12V strips.
Which LED strip is best? NeoPixel, DotStar, WS2812B, SK6812, WS2815, or APA102?
In my opinion, there are four types of LED chips you should be considering: WS2812B, SK6812, WS2815, or APA102. Each type has its benefits, be it cost or functionality. You will find the more popular LED pixels in varying shapes and sizes, and not just as strips.
The cheapest: WS2812B and NeoPixels
The WS2812B is by far the most ubiquitous of the three. It's a 5V strip that can be found in many projects, ranging from Nanoleaf clones to music spectrum panels. Due to their popularity, they are available in many forms: Be it an LED strip, individual chips, or Christmas tree lights. LED strips and panels using WS2812B chips have one thing going for them, and that is pricing. WS2812B are far and away the cheapest option.
If you are confused about the use of the term NeoPixel, the explanation is rather simple: NeoPixels are what Adafruit calls WS2812B LEDs. There are also NeoPixels with four LEDs in one, these can produce true white light. The RGBW NeoPixels are nothing more than SK6812s.
It is that missing white LED does make the WS2812B unusable for practical lighting. The way a WS2812B produces white light is by mixing the RGB LEDs, and generally that white light isn't very pleasing to the eye and can have a noticeable colour shift. The WS2812B is fine for accent lighting and little projects, but I wouldn't recommend unscrewing all of your bulbs in favour of these strips just yet.
WS2815: The 12V option
The WS2815 is comparable to the WS2812B, but requires 12V. These LEDs come in useful if you are planning very long runs and are wary of voltage drop. The downside is of course that you will need a buck converter to run the microcontroller of a 12V power supply. Of note is also that 12V LEDs are less efficient than their 5V brethren.
Dual-Signal: If one pixel is damaged, the following LEDs still work.
Voltage: Requires a DC12V power supply.
SK6812: RGB with true a white light
Just like the WS2812B, the SK6812 is a 5V LED with one distinct advantage: It includes a white LED. The problem with RGB LEDs is that the white light they produce isn't very nice, making them unusable as functional lights. With the SK6812, you have a choice of three temperatures for the white LED: cold, neutral, and warm. Adafruit also sells SK6812 LEDs under the NeoPixel branding, as NeoPixel Digital RGBW LEDs.
Individually addressable: 256 brightness levels and 32-bit colour depth
APA102: The best (and priciest)
Finally, we have the APA102 LED, which are also known as “Superled”. These get on to the list because they can be controlled with a standard SPI (Serial Peripheral Interface). There are two flavours of this LED: The APA102C looks strikingly similar to the WS2812B and comes in cheaper than the APA102, with the latter having improved heat conduction.
The wattage of your power supply depends on the number of LEDs you want to power and how much power they draw. Let's say you are using a 5V WS2818B LED strip from BTF-LIGHTING with 100 LEDs per meter (I highly recommend BTF-LIGHTING for all your LED needs). The length of your strip were to be exactly 2 m, which would leave you with a total of 200 LEDs.
In the product's description, we can see that each WS2812B LED on this strip draws 0.1W~0.3W. We will be taking the upper value as a safe measure, and that tells us that the power supply has to be 60W at the very least. To be on the safe side, I would personally go one higher and get a 5V 15A (75W) power supply. After all, the ESP8266 or ESP32 will also draw a little, and you might want to extend your strip at some point.
WLED example wiring using a 5V LED strip
In the example below, you can see how you could wire a 5V LED strip such as the popular WS2812B to a LOLIN (previously WEMOS) D1 mini ESP8266 board. Let's take a look at this circuit in detail:
The power supply feeds both the LOLIN D1 mini and the WS2812B. Do never connect a 5V power supply to 3.3V (labelled 3V3) on the board, or you will fry it.
The capacitor is added to the power supply close to the LED strip. Beware, the capacitor has a positive and negative wire. Incorrect wiring will cause the capacitor to explode.
The 3.3V pin on the LOLIN D1 mini is connected to the LV (low voltage) pin on the level shifter.
Opposite to the 3.3V pin, the HV (high voltage) pin can be connected to the 5V from the power supply.
Both grounds can be connected to the power supply's ground wire.
The D4 pin is connected to the LV side of the level shifter, and the opposite pin is connected to the Din (data in) pin on the WS2812B LED strip.
WLED example wiring using a 12V LED strip
Using a 12V LED strip requires a 12V power supply (thanks, captain obvious). Instead of powering the LOLIN D1 mini ESP8266 board, we can use a buck converter (a DC-to-DC power converter) and create a separate 5V circuit. You will generally find two types of buck converters used in WLED projects: those with a fixed output voltage and those with a variable output voltage.
If you don't have a multimeter and have no interest in owning one, then the fixed output voltage is for you. Buck converters with a variable output voltage use a potentiometer, which can be adjusted using a small screwdriver. The output has to measured using a multimeter and adjusted until it is exactly 5V. There are also buck converters which have an LED display on the board to display the voltage, though I find these a bit wasteful if you're only going to use it once.
As with the level shifter, you can solder the buck converter on to the same perfboard where the rest of your components already are. It sits between the power supply and LOLIN D1 mini. Make sure you never attach the LOLIN D1 mini, or any other ESP8266/ESP32 board, to 12V!
About Liam Alexander Colman
Liam Alexander Colmanis an experienced Home Assistant user who has been utilizing the platform for a variety of projects over an extended period. His journey began with a Raspberry Pi, which quickly grew to three Raspberry Pis and eventually a full-fledged server. Liam's current operating system of choice is Unraid, with Home Assistant comfortably running in a Docker container. With a deep understanding of the intricacies of Home Assistant, Liam has an impressive setup, consisting of various Zigbee devices, and seamless integrations with existing products such as his Android TV box. For those interested in learning more about Liam's experience with Home Assistant, he shares his insights on how he first started using the platform and his subsequent journey.
Comments
Vadim
That’s a great guide, been looking for a way to get into WLED for a while. Quick question: can I use level shifters without tx/rx pins the same way?
I forgot to mention in my previous comment: I always use the capacitor also. I use as 16v 1000uF capacitor in parallel between the positive and negative power supply. My understanding is this is unlikely to cause a problem even if not really needed. It smooths out the power and prevents brief voltage drops.
I was using 6.3V 1000uF because of their smaller size, but if a 12V power supply is attached and there is no protection against that, such as a voltage regulator, then in addition to burning out the first LED you will destroy the capacitor. So 16V is recommended. They are roughly twice the size of 6.3V.
Trial and error, combined with discussions with the community and prolific consumption of blogs and vlogs is the path to enlightenment! I took the time to comment because many articles about the capacitors and resisters don’t explain the why or provide useful specific details.
That’s a great guide, been looking for a way to get into WLED for a while. Quick question: can I use level shifters without tx/rx pins the same way?
I forgot to mention in my previous comment: I always use the capacitor also. I use as 16v 1000uF capacitor in parallel between the positive and negative power supply. My understanding is this is unlikely to cause a problem even if not really needed. It smooths out the power and prevents brief voltage drops.
I was using 6.3V 1000uF because of their smaller size, but if a 12V power supply is attached and there is no protection against that, such as a voltage regulator, then in addition to burning out the first LED you will destroy the capacitor. So 16V is recommended. They are roughly twice the size of 6.3V.
Trial and error, combined with discussions with the community and prolific consumption of blogs and vlogs is the path to enlightenment! I took the time to comment because many articles about the capacitors and resisters don’t explain the why or provide useful specific details.