Stairway to Heaven: Customizing WLED

There have already been several articles about wled on Habr, but they were usually limited to the standard firmware capabilities – garlands with effects, control of RGB backlighting of PC components, and the possibility of integration with a smart home was also mentioned in passing.

Here we will consider a solution to a specific problem – from the idea and attempts to use standard firmware to assembling your own with an increased number of control pins, an extended web interface, an API for debugging, your own logic for controlling the backlight and even a demo on jsfiddle.

Our task is the following: there is a half-outdoor staircase (a glazed veranda), on which we want to make a “stairway to heaven” – alternate illumination of the steps from the side of the person walking.
The working conditions are appropriate – frost in winter, heat in summer, and during the day the backlight is useless due to natural light.

Ready-made solution

In fact, the house already has lighting with simple animation on the internal staircase, but it is implemented on a ready-made controller, on ordinary strips – there it was necessary to pull separate wires to each step.

This time we wanted more, so the requirements were formulated as follows:

• multicolor,

• availability of ready-made effects,

• turning off the backlight when there is sufficient natural light,

• the steps should light up both from the bottom up and from the top down, and the animation should not be interrupted and should go from 2 sides if the movement is simultaneously recorded from both sides.

We will calculate and compare the cost of the first and second solutions closer to the end.

wled base firmware

Wled This is a ready-made firmware for working with addressable LEDs, which in addition to its direct function also contains http api, web interface, support for interaction with external systems (for example, mqtt) and even synchronization of different wled devices.

Also wled is a whole ecosystem, having integrations and plugins, perhaps, to all common smart home systems, and, quite good ones. Home assistant, for example, automatically recognizes wled devices on the network and can update their firmware over the air.

Let's get closer to our task: wled already seems to support everything necessary out of the box:

• groups of LEDs for each step,

• setting up animation for turning on/off groups with timings,

• support for 2 input pins (for wemos d1 mini / esp8266), on which you can hang buttons/switches/motion sensors,

• triggers for changing pin values ​​to start animation.

Actually, it works something like this (here I am connected to a wled WiFi access point from my laptop and am running the animation manually from the web interface):

It looks great, but in practice, not everything is so rosy:

• each time the sensor is triggered, the animation starts again,

• 2 animations cannot work in parallel,

• in the firmware for ESP8266, only 2 input pins are available, the light sensor can no longer be connected,

• even with the expansion of the number of available pins, there is nowhere to connect the light sensor, complex conditions or even a banal if with checking a pair of values ​​cannot be written (and, accordingly, configured in the interface, too).

The problem with the light sensor can be solved by installing a light relay to power the entire device (in my opinion, a crutch, but generally working), but even so, the animation does not suit me at all – with any sensor and timing settings, correct operation is only possible under ideal conditions – a single response of one sensor.

We will gradually solve these problems.

Expanding the number of inputs (buttons)

By default, the wled firmware for wemos d1 mini allows only 2 input ports, despite the fact that the controller and board contain a much larger number of free pins.

Fortunately, this problem easily fixable – you just need to specify the flag WLED_MAX_BUTTONS with the required number of pins and assemble the firmware.

wled firmware assembly

But here the difficulties begin, if you have not encountered such a build scheme before, the experience of flashing Arduino will not help here.
However, everything is described in official instructions. You will only need some software – git, vs code, platformio extension, docker, node, wsl in a windows system. Also several reboots and probably a non-working build button, which, judging by some issues may work randomly and not compile the binary the first time.

If you don't want to build the firmware for all supported platforms at once, you will also need to uncomment line in the config with d1_mini and comment out the line above listing all supported platforms.

Next you need to add the key -D WLED_MAX_BUTTONS=10 V build_flags to expand the number of available “buttons”.

I finally got everything together in a matter of minutes. testthe first stage of which includes build and produces the required firmware binary.

wled customization

Since we've already established that standard functions won't do, let's take a look at what wled offers for customization: right here instructions for implementing your own scripts (usermods), within which you can expand the GUI, write an API, and work with the microcontroller pins in C++.

Initially, I started writing this code according to the instructions, until I accidentally discovered a whole bunch of already existing ones in the depths of the repository. ready usermodsabout which the official documentation says nothing.

In the meantime, there is a lot of stuff here:

My usermod and its description can be found in repositoriesall necessary explanations are in the readme and in the code. The code style (or lack thereof) is a consequence of the implementation based on someone else's solution (and in general the general approach to writing usermods), after receiving the working version I did not have a chance to do refactoring.

And yet, despite the convenient and fast firmware process by microcontroller standards, debugging bugs on the physical device and circuit turned out to be labor-intensive. I honestly tried to do this, but after a couple of dozen iterations, I asked chatGPT (at that time there were still 4 versions) to convert the entire current code into a demo in html/css/js and debugged the logic there.

You can poke the demo here – jsfiddle.

The final logic of the work is as follows:

• Each sensor independently initiates the activation of the steps on its side.

• through on_time_ms After the last sensor response, the steps are switched off (always in one direction).

• repeated triggering of sensors only affects the shutdown time, the animation does not start again.

• In this case, pins and delays are set in the interface, and the states of the sensors are sent to the API.

• A light sensor (a logic module that outputs a high or low level) is connected to a separate pin, which turns off the backlight during daylight hours.

To enable usermod in the firmware, it is enough to include it in /wled00/usermods_list.cpp:

#include "../usermods/usermod_stairs.h":

Wiring diagram

Here is a small lyrical digression regarding the connection diagram.

We connect all sections of the strip in series, but in this case, especially in the version with a 5v strip, there will be a catastrophic lack of power and the strip will, at best, lose brightness from beginning to end. For this reason, it is necessary to supply power to intermediate points of the strip (in my case, this is every 2 steps – I ran the power cable along one side of the stairs).

It is also worth mentioning that WLED developers have taken care of security in the firmware as well. there is a software calculation maximum power consumption by the tape in the selected modes and by default a limitation is set on the maximum possible tape power, calculated based on the direct connection of the tape to the controller pins. If this value is exceeded, the controller will proportionally reduce the brightness of the diodes depending on the effect used.

If your strip is powered according to all the rules, and not directly from the controller, this value must be set equal to the maximum (nominal?) current that your power supply supplies, or the limitation must be removed altogether.

The general connection diagram can be depicted approximately as follows:

Despite the fact that the ESP operates at 3.3 V, and the strip is powered / controlled by 5 V – a direct connection works correctly, partly due to the small distance between the controller and the first section of the strip. If in your case this distance is large and failures occur, and also if the strip is powered by a different voltage and cannot be connected directly (12 V) – a level converter must be added to the circuit according to official recommendations.

As you can see, much less wires are needed here than in the case of a ready-made controller.

Result

The final result looks like this:

I settled on one of the animations that only slightly changes the intensity of the glow of individual diodes, so that it looks dynamic, but at the same time does not interfere with the operation process.

However, you can choose any effect, including using different animations for each step. For example, here is a more dynamic mode:

You can also disable usermod and control the backlight using standard means – suddenly your staircase is in the center of the house and you want to throw a party with color music.

Necessary components and budget

From here on, links to components for searching on Ali, without referrals.

That is, the total costs amounted to approximately 5150 ₽.

Ready-made solution

He also promised a comparison of the finished solution and the described implementation.

At the moment, there is a 2nd version of the controller with support for a light sensor, I have the first version without it.

Total amount minimum 6500 ₽ (without light sensor support).

As you can see, the only small savings are the power supply and sensors. The controller is an order of magnitude more expensive than the one we use.

Conclusions

Despite the wider possibilities of the described implementation, the ready-made solution is still inferior in both price and ease of installation.

Yes, the cost of development is not taken into account here, but the described device is more of a hobbyist nature – I was simply interested in the process, no matter how expensive it turned out to be in the end.

If you have any questions or comments/suggestions, please leave them in the comments.

Useful links