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.

In the quest to bring vibrant lighting effects into our spaces, WLED stands out as a beacon of creativity and functionality. Following my previous exploration into the exciting world of WLED, it's time to dive deeper into the practical aspects of bringing this technology to life. This comprehensive guide aims to demystify the process of integrating NeoPixels (WS2812B, WS2811, SK6812), DotStar LEDs (APA102), and other SPI-based LED chipsets such as the WS2801 and SK9822, with the widely popular ESP8266 or ESP32 microcontrollers. By flashing WLED onto these devices, you unlock a universe of lighting possibilities.

We'll navigate through the essentials needed to embark on this illuminating journey—from selecting the most suitable ESP8266 or ESP32 controller and LED strips to understanding the critical role of additional components like level shifters, resistors, and capacitors. This guide is your first step towards creating dynamic, customizable lighting setups that not only enhance your environment but also reflect your unique sense of style and creativity.

Wled Setup 04 2
Image of a contemporary bedroom featuring dynamic LED lighting with a spectrum of red at the bed's base transitioning to blue at the ceiling, complementing the modern decor and creating an inviting, atmospheric space.

Contents

Choosing Between ESP8266 and ESP32 for WLED Projects

When considering whether to opt for an ESP8266 or ESP32 for your WLED projects, it's essential to weigh the advantages of each. The ESP32 boasts a more powerful processor, additional RAM, and Bluetooth capability, surpassing the ESP8266 in terms of performance. However, the ESP8266 offers a more cost-effective solution. Given that WLED does not utilize Bluetooth and the enhanced specifications of the ESP32 might not be fully exploited in LED strip control, the ESP8266 emerges as a practical choice for beginners and most personal projects.

It's crucial to understand that WLED's functionality is specifically tailored to controlling addressable LEDs, without the capacity to integrate additional sensors or utilize Bluetooth for presence tracking, setting it apart from platforms like ESPHome. For extensive projects involving more than 1024 LED pixels requiring frequent updates, the ESP32 becomes necessary due to its superior processing capabilities. However, for the majority of personal endeavours, the ESP8266 is perfectly capable and should be your go-to choice, reserving the ESP32 for more complex applications or those requiring its specific features.

How to flash WLED on to an ESP8266 or ESP32

I recommend 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 and there's nothing attached to it by fragile wires. You also won't have to worry about powering any of the other components. If you're using one of the ESP-XX modules from AI-Thinker, simply attach the programmer (adapter board).

The beauty of starting with WLED is its no-fuss configuration process. There's no need for subsequent code adjustments or manual entry of Wi-Fi network credentials through code. WLED facilitates a seamless, user-friendly setup by generating its own Wi-Fi access point for initial configuration. Once the flashing process is complete, the necessity to reconnect the device to a computer for programming is virtually eliminated, streamlining the setup further.

For the flashing itself, the ESPHome flasher tool is highly recommended due to its intuitive graphical user interface, simplifying what might otherwise be a daunting task. Begin by downloading the appropriate WLED firmware binary file for your specific board from the official GitHub repository. This selection process is made easier with guidance available on the WLED Wiki, helping you choose the right firmware version tailored to your device.

Once the binary file is selected within the ESPHome flasher tool and your device is correctly connected, initiating the flash is as straightforward as clicking the “Flash ESP” button. This simplicity in execution belies the transformative effect it has, readying your ESP8266 or ESP32 for its role in powering your LED lighting creations.

Screenshot of the esphome-flasher program interface, with options to select a serial port, browse for firmware files, and buttons to initiate the flash process and view logs, with a large console area for output messages.

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.

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.

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.

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.

Wled Setup 09 2

APA102: The best (and priciest)

Finally, we have the APA102 LED, which is also known as “Superled”. These get on 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 (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 have a look at this circuit in detail:

Circuit diagram for a smart lighting project featuring a Wemos D1 Mini connected to a DC power jack on the left and a USB-controlled LED strip on the right, with wires for data, power, and ground linking the components on a protoboard.

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!

A portrait photo oif Liam Alexander Colman, the author, creator, and owner of Home Assistant Guide wearing a suit.

About Liam Alexander Colman

is 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

  1. 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?

    Reply
  2. 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.

    Reply

Leave a Reply to Rich Sadowsky Cancel reply

Share to...