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.
Table of Contents
- Should I use an ESP8266 or ESP32 for WLED?
- How to flash WLED on to an ESP8266 or ESP32
- How to connect an LED strip to WLED
- Capacitors? Level shifters? Resistors? This all sounds a bit complicated.
- What LED strip voltage is best for WLED?
- Which LED strip is best? NeoPixel, DotStar, WS2812B, SK6812, WS2815, or APA102?
- WLED example wiring using a 5V LED strip
- WLED example wiring using a 12V LED strip
Should I use an ESP8266 or ESP32 for WLED?
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.
Only use an ESP32 for massive projects
Where you will run in to issues is if you are attempting to build a massive project. The ESP8266 will handle 1024 individual LED pixels while sending 30 updates per second. Reduce the updates to 15 per second and the ESP8266 can take care of 2048 LED pixels on your strip.
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.
Once connected, the easiest way of flashing WLED is by using the ESPHome flasher as it has a graphical interface. Download the matching binary file for your board from GitHub (this page has information on which one to choose) and select the binary file in ESPHome flasher, along with the serial port. Flashing is then as easy as hitting the “Flash ESP” button. Once flashed, you can commence with the wiring.
How to connect an LED strip to WLED
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.
Custom WLED PCBs and direct wiring
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.
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).
Why use a resistor?
According to Adafruit, a resistor should be placed between the data pin of the ESP8266/ESP32 and LED strip to protect the first LED from spikes. The WLED wiki recommends a resistor as low as 62 Ω but if you use a level shifter, there is no need for a resistor. I have always opted to use just the level shifter without a resistor and haven’t experienced any issues so far.
What LED strip voltage is best for WLED?
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.
- LED colours: RGB and pure white
- 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 biggest advantage the APA102 has over the WS2812B is its very high PWM frequency. At 19.2 kHz APA102 LEDs are well above the flicker fusion threshold, meaning the human eye will see a constant brightness. For comparison, the PWM frequency of a WS2812B LED is around 400 Hz.
How powerful does the power supply have to be?
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!