Fully adjustable Home Assistant template light for CW/WW LED strips

TL;DR

I created a template light for Home Assistant to control CW/WW LED strips. Skip to download and install instructions or keep reading to know more about controlling this type of LED strips and how to integrate them best into Home Assistant — an open-source home-automation platform.

CW/WW Led strip

I recently installed a couple of CW/WW (cold-white / warm-white) LED strips. This kind of LED strips can be finely dimmed, and the color temperature can be adjusted to any value between 2700 and 6000 Kelvin. The strip has two independent LED lines for cold-white and warm-white LEDs. Compared to what’s available on the market, I picked this model because:

• It’s powerful: at maximum power it’s way brighter than the lights I used before;
• It’s adaptable: the strip can be cut into shorter pieces every 25 mm;
• Option for waterproof: I got the version that comes already sealed in a waterproof silicone sleeve;
• Price is reasonable: at the time of writing, a 5 m strip waterproof IP67 is sold for around 30$;
• Diffuse light: it’s a FCOB strip (flexible chip-on-board), meaning that a high number of leds is placed directly on a flexible PCB. The sealant on top of the LEDs further diffuses the light (no dots effect). A diffuser profile — a sleeve that trades brightness for a smoother light pattern — is unnecessary. This cuts costs and work, and improves efficiency (less power for the same brightness).

I got the 24V version since it requires lower currents: meaning less heat, fewer losses, cheaper wiring, and higher efficiency.

LED strip controller

LED strips need a controller to be dimmed and to change color. I’m using a WiFi controller that is compatible with Home Assistant. However, the controller only lets me set the brightness level — from 0% to 100% — on each of the two lines of LEDs separately from each other.

The controller doesn’t recognize the LED strip as a single CW/WW light where I can set the color temperature and brightness. For example, I can set the CW line to 60% brightness and WW to 80% (or any other combination). Still, I cannot set the brightness of the whole strip as a single parameter, nor the color temperature of the resulting light.

This means that to switch the strip on or off, I have to turn on/off both lines.

Template lights in Home Assistant

I did some research, and it seems that this issue is common to other LED controllers. People in the Home Assistant community came up with schemas for template lights that combine the two LED lines into a single virtual light that can be controlled as a single entity by setting color temperature and brightness.

I initially used one of these templates from the community. It needed a couple of trivial fixes on the syntax, but the logic worked well to solve the issues I reported so far: I finally had a single light that I could control from Home Assistant by setting color temperature and brightness.

There was however a catch.. that template didn’t allow to set the brightness of the entire LED strip above 50%. The sum of the CW and WW signals sent to the controller could not go above 100%. Translated into electrical power, if the LED strip is rated at a maximum of 20 W (CW + WW power), it’s only possible to get a maximum of 10 W out of it (rough approximation).

For example, these combinations are possible:

• CW 20%, WW 40%
• CW 70%, WW 30%
• CW 0%, WW 100%

But these are not:

• CW 20%, WW 90%
• CW 70%, WW 50%
• CW 100%, WW 100%

This behavior has its advantages though. By limiting the total brightness of the LED strip to 50%, the code in the template light can be simplified. We can rely on the following statements being always true:

• given a selected color temperature, the template light can be set to any brightness on the scale;
• given a selected brightness, the template light can be set to any color temperature on the scale.

CW/WW Template light with full brightness

I wanted to use the LED strip up to its maximum brightness/power, so I created a new template light that — while maintaining the controls over color temperature and brightness — allows reaching the full rated power of the LED strip. The code in the new template is more complex since the statements at the end of the previous section no longer hold.

Let’s take the maximum brightness of the LED strip as an example. There is only one possible combination to achieve it: CW 100%, WW 100%. But this also means that, at maximum brightness, there is only one color temperature available: somewhere halfway between the coldest and warmest temperature of the LED strip. If we want to change the color temperature, we need to lower either the CW or WW brightness, and by doing so, we are not anymore in the maximum brightness state.

The more we lower the LED strip brightness below the maximum, the wider the range of color temperatures we can use (Fig. 1). When the LED strip brightness is at 50% or below, we are back in the previous template light case: the full range of color temperatures is available.

Template use and behavior

Let’s take Fig. 1 as a reference. We can start from a random point representing the color temperature and brightness we can set on the template light, say 2800 K at 30% brightness.

If we move the brightness level up, the template will maintain 2800 K until the maximum possible brightness — for that color temperature — is reached. This corresponds to a point on the edge of the colored region, more specifically, on the left side slope at the top.

If we keep increasing the brightness, the template will shift the color temperature toward the center. Since we are operating on the brightness control, the template will prioritize the brightness level at the expense of a different color temperature (as close as possible to the original 2800 K).

The same strategy is used when operating on the color temperature level. If the desired temperature is not reachable because the brightness is too high, the template will reduce it automatically, just enough to reach the selected color temperature.

Download and installation

I created a Github repository for the template light. Download and installation instructions — as well as implementation details — are included in the README.