Kelvin is not enough: the case for per-entity LED calibration profiles in HA

[roelanddewindt]

Description of proposed core improvement

Add support for user-defined color calibration profiles on light entities operating in rgb or rgbww color mode. The minimum viable form is a manual linear profile: the user provides empirically determined RGB anchor points for at least two color temperatures (e.g. 2700K warm white and 6500K cool white), and Home Assistant interpolates linearly between those anchors for any requested color temperature — substituting the corrected RGB values in place of the generic formula output.

Current limitations

When a user selects a color temperature (e.g. 2700K "warm white") on an RGB LED strip, Home Assistant computes an RGB tuple based on an idealized model of what red, green, and blue LEDs look like. Real RGB strips — particularly inexpensive ones — routinely violate those assumptions. Channel luminances, spectral response curves, and maximum brightness values deviate significantly from the standard primaries the formula assumes. The result is that the same mired value that produces a pleasant warm white on a calibrated bulb produces visibly wrong output on an uncalibrated strip: pink, magenta, or greenish casts that no reasonable user would accept as warm white.

There is currently no mechanism in Home Assistant to correct for this. The only workaround is constructing a template light in YAML that intercepts set_temperature and substitutes hand-tuned RGB values — an approach that is undiscoverable, requires significant YAML expertise, and provides no UI for the calibration process itself.

Technical benefits

Because the color intent originates in Home Assistant's light platform, a calibration profile defined at the entity level would fix the problem universally — regardless of whether the strip is driven via Zigbee, Z-Wave, ESPHome, or MQTT. Every downstream driver and firmware would benefit without independently needing to implement correction.

A two-anchor linear implementation is the minimum useful case and covers the majority of real-world needs. A more complete implementation could support a multi-point lookup table across the full mired range, and eventually a 3×3 color matrix (analogous to an ICC profile's colorant matrix) for full hue accuracy across the color wheel.

Entities without a calibration profile defined would behave identically to today — fully backwards compatible.

Additional context

This problem is not new. The display industry solved it decades ago with device color profiles — ICC profiles and Apple ColorSync. The core insight is fundamental: without knowing a device's actual primary chromaticities and white point, it is mathematically impossible to fire digitally controlled RGB values that reliably produce a target color. ColorSync profiles declare the device's real capabilities and allow the OS to compute corrected channel values for any desired color intent. LED strip controllers have no equivalent mechanism, and the smart home ecosystem has not yet caught up.

The gap is particularly visible on cheap RGB strips where channel balance varies significantly between batches and manufacturers — a known and documented problem in the LED industry, but one that home automation platforms have so far treated as the user's problem to work around rather than a platform capability to address.

[roelanddewindt]

There appears to be a more widespread use case for this profiling functionality. See this post describing the issue with Adaptive Lighting basnijholt/adaptive-lighting#421

Long outstanding. Not getting the love it needs.

[roelanddewindt]

To back up the proposal with something concrete: I built a working proof-of-concept custom component that implements exactly the minimum viable case described above.

Repo: https://github.com/roelanddewindt/ha-calibrated_led

It wraps any existing RGB light entity and intercepts light.turn_on calls with color_temp_kelvin, translating them to calibrated rgb_color values via a user-defined anchor table. The calibration logic lives in a single self-contained file (color_profile.py) with no Home Assistant dependency — linear interpolation between anchor points, linear extrapolation beyond them, 13 passing unit tests.

Tested on HA 2026.3 with a Zigbee RGB strip. Because it goes through the standard light.turn_on service call, Adaptive Lighting (see the linked discussion above) benefits automatically without any changes on its side.

The component is deliberately marked as a PoC throughout — the naming, the version (0.0.1-poc), the README. The intent is to show that the core logic is straightforward and the hook point in the light platform is obvious, not to ship something production-ready.

Happy to discuss where this would live in core.

[roelanddewindt]

but reporting updates in the entities' states it didn't drive is something HA currently does

Given the profile, it should be possible to read the current xy value of the Hue light, and know what that was meant to represent by inverse calculation. No?

[tremby]

Point taken about the Hue control. But then I wonder, how come there was even a need to 'tune' the mired of the Hue lights, aren't they accurate already?

Yes they were good. I'm pointing it out because there may be similar situations which do not involve such good quality lights.

Given the profile, it should be possible to read the current xy value of the Hue light, and know what that was meant to represent by inverse calculation. No?

Absolutely, I think so. This is precisely what I was asking if you were covering.

[roelanddewindt]

I clearly couldn't let our last discussion go...

So those are a couple of situations where HA might not be used to change the lights, and where the user would expect HA regardless to know their new states.

Fair point, and the reverse mapping should handle that — but it should operate on the reported xy from the light, not the reported Kelvin. Here is why that distinction matters.

Kelvin and mired are mathematically equivalent (mired = 1,000,000 / Kelvin) — swapping one for the other changes nothing fundamental. Both describe a point on the Planckian locus, the theoretical curve traced by a perfect blackbody radiator as it heats up. The critical word is theoretical.

A light reporting color_temp_kelvin: 2700 is telling you what it was asked to produce, not what it actually produced. The actual output sits at a specific xy coordinate in the CIE 1931 colour space, and that coordinate may be nowhere near the Planckian locus — especially for cheap RGB strips with non-standard primaries.

The picture shows the difference between an exact xy value (black) and a collection of points all having the same K or mired value (white). The light colour on the short perpendicular lines crossing the ideal black body line (curved) varies, while all having the same K/mired.
The distance from the locus is expressed as Duv. A Duv of 0 means the light sits exactly on the locus — a neutral white at that colour temperature. Positive Duv means above it: greenish cast (especially with higher K). Negative Duv means below it: magenta cast. A light can report 2700K with a Duv of +0.05 — technically warm white by the number, visibly green in reality. Kelvin alone cannot capture this. xy can, because it is a two-dimensional coordinate encoding both the colour temperature and the deviation from the locus simultaneously.

This is precisely why the reverse mapping must work in xy space. With a reported xy and a known calibration profile, HA can determine what colour the light is actually producing — not what it was asked to produce.

And this points to something broader: profiling works in both directions. A profile is not just a forward translation engine (requested Kelvin → correct xy to send) — it is also a reverse translation engine (reported xy → inferred Kelvin). If an external controller sets a light to xy (0.508, 0.426), HA can look that up in the profile, understand it represents 2200K on this device, and reproduce it faithfully on a completely different light source through that source's own profile. The two profiles act as a common language, with xy as the shared coordinate system underneath.

We are on to something beautiful waiting to be implemented.

Yes they were good. I'm pointing it out because there may be similar situations which do not involve such good quality lights.

Exactly — and that distinction is key. High quality CCT lights like Hue use dedicated warm and cool white channels with well-characterised primaries. The value HA reports is a close match to what the light actually produces, and no profiling is needed. The reverse mapping works reliably because the forward mapping was already accurate.

The problem this proposal addresses is the other end of the spectrum: cheap RGB strips where the forward mapping is broken from the start. There, without profiling, neither direction of the mapping can be trusted — the light is not producing what it claims to produce. For those sources, profiling is not optional. It is the prerequisite for any of this to work correctly.

Maybe that's not in your scope and that's fine, but IMO the problem is better solved in Z2M than in HA. If Z2M is the one doing the calibration it solves the problem not only for Home Assistant but for anything using Z2M directly or talking to MQTT directly to control or query the devices.

This point is valid but cuts both ways.

Z2M is one integration among many. Calibrating there solves the problem exclusively for Zigbee devices routed through Z2M. The moment you introduce a WiFi bulb controlled natively, a Hue bridge, an ESPHome device, or any other non-Zigbee source, Z2M calibration offers nothing. Each platform would need its own calibration implementation, with no shared mechanism, no common profile format, and no consistency across sources. The argument that Z2M fixes it for anything talking directly to Z2M or MQTT is true — but it moves the problem rather than solving it.

HA core is the only level where a single calibration mechanism benefits every light source regardless of protocol, integration, or manufacturer. My PoC demonstrates this: intercepting light.turn_on at the HA service level works identically for a Zigbee strip via Z2M, a WiFi strip via its native integration, or anything else HA controls. The calibration is protocol-agnostic by design.

That said, the two approaches are not mutually exclusive. Z2M calibration would benefit Z2M-only setups. HA core calibration benefits everyone using HA. For the scope of this proposal, HA core is unambiguously the right level.

I do intend to look into implementing the reverse xy mapping in a future iteration of the PoC. There are other features on the roadmap first — brightness alignment across strips of different lumen output being the next one. I am not a developer by trade, and this PoC has already grown well beyond what I initially set out to demonstrate. I remain hopeful that this topic attracts attention from people closer to HA core development, who would be better positioned to take these ideas properly to the platform level.

EDIT: annotation in pasted graph

[tremby]

I don't mean to be dismissive, but these details don't matter to me, and on top of that this message has a distinct AI aroma (a general feeling, plus the punctuation style, and particular phrases like "this point is valid but cuts both ways" and "that distinction is key" and "this points to something broader") which, whether that intuition is right or wrong, makes it harder for me to trust. I want to give you the benefit of the doubt, so other than mentioning it I'm doing my very best to ignore that and to assume you simply used an LLM to polish your own thoughts. So I'll say that it's great that so much thought is going into this. The more accurate things are, the better -- no argument there -- so I'm glad somebody who cares about this problem is apparently so knowledgeable about it.

But all I really care about here is that my lights' colours look similar to each other, and that Home Assistant doesn't report a light as looking orange when in fact it looks white (with some of my terrible LED strips it would, without a reverse mapping). How exactly the reverse mapping is implemented doesn't really matter to me as long as it's good enough to my eye. Whenever I say a particular temperature, sure, substitute it for "particular xy value" if you like.

[roelanddewindt]

Full disclosure. My native tongue is not English, so yes, I put the drafts of my ideas and initial writings through AI to make it a better read, and I only post it after multiple iterations match what I am trying to convey. BTW, our "live" discussion earlier" was not AI assisted (nor is this post, resisting my urge), you should sense a difference in linguistic palate and register there. I'm happy you are able to see through this and I will try to get some code pulled together, although I feel someone else would be much better placed to do this.

[roelanddewindt]

Update: v0.0.2-poc — XY output mode + field observations

XY output mode

v0.0.2-poc adds an XY output mode for Zigbee controllers that intercept RGB commands internally (e.g. MiBoxer via Z2M), bypassing the lossy RGB→XY→RGB double conversion. The XY route was necessary because arriving at usable RGB profiles on the MiBoxer controller proved impractical — changing one channel dragged others along unpredictably, making empirical RGB calibration impossible on this hardware.

Why per-entity calibration is necessary

To validate the core premise, I profiled three different LED strips from different brands using a spectrophotometer and the Argyll open-source toolset. The results were striking:

• Sending identical RGB values to each strip produced completely different colour temperatures
• Each strip's channel primaries deviated from standard assumptions to a different degree
• One strip could reach 6500K cleanly; another couldn't get above 4000K without unacceptable colour cast due to an oversaturated green primary, putting a practical ceiling at around 4000K — a hardship most indoor lighting scenarios will survive

The same generic Kelvin→RGB formula that HA applies today produces a different wrong answer on every strip. There is no single correction that works across hardware — per-entity calibration is the only viable approach.

On measurement tooling

I was fortunate to have access to a spectrophotometer and the Argyll open-source toolset. Calibrating by eye alone is possible but unreliable — metamerism means what looks right under one light source may not under another, and you'll never know how far off you are. A spectrophotometer is strongly advisable for anyone serious about this. That said, most users will never have access to one, or the inclination to run measurement sessions against their LED strips.

The bigger picture

This points to two things that would meaningfully improve the situation at scale:

1. A community-maintained profile database — similar in spirit to how printer ICC profiles are shared — so users can look up their strip by brand and model and copy a known-good profile rather than measuring from scratch.

2. Industry-provided profiles — serious LED brands already do this implicitly: a properly engineered CCT strip with dedicated warm and cool white channels handles colour temperature correctly by construction, because the hardware was designed for it. RGB strip manufacturers targeting the smart home market could do the same — shipping a calibration profile alongside the product, the way a display manufacturer ships an ICC profile. Until that happens, HA users are left guessing, and a platform-level calibration mechanism is the most practical mitigation available.

[roelanddewindt]

Also see this related discussion about capping channels to reach the same level of brightness between lights sources. A similar calibration profile, produced by measurement or naked eye, could sit between what the end user asks for and what HA sends out as a command to the light entities.
https://github.com/orgs/home-assistant/discussions/179

[roelanddewindt]

Also see this related issue on the AL repo: basnijholt/adaptive-lighting#1428 — someone independently arrived at the same anchor interpolation approach, which is encouraging validation that this is the right abstraction. One platform-level solution based on per-entity calibration profiles would make all issues go away.

[roelanddewindt]

Tangentially related: a visualisation of average wake-up times across European countries (warning: FB link) illustrates how much circadian rhythms vary by latitude, geography, and culture. Take the data with a pinch of salt, but the directional point holds. If circadian lighting is to be meaningful, accurate colour temperature reproduction is a prerequisite. A perfectly timed activating morning light that actually renders as something else defeats the purpose entirely.

[tremby]

IMO wherever it can't be fixed on the device itself, the remapping belongs in ZHA, Z2M, and anything else which acts as a border between devices and anything which wants to talk to them.

[roelanddewindt]

IMHO, the remapping should not be integration-specific, but at a lower level still: at core level. Whatever the "input" selector of the desired Kelvin temperature(script, manual, scene, AL, ...), or whatever the "output" integration (Z2M, ZHA, Tuya, Lifx, Lutron...). The output device needs profiling so the input can be calibrated to the desired output, whatever the in-between mechanics.

The parallel being no matter what image-generating application (Photoshop, Indesign , Illustrator, Paint) defines a colour, it is the underlying OS that should calibrate the output to a profiled display, whatever the display.

[tremby]

But who says Home Assistant is the only consumer of what's on the other side of the integration? For example, what if I have other things which talk directly to Z2M, or for that matter directly to MQTT to interact with the devices?

[roelanddewindt]

The thing is that HA core will request some xy value from ZHA, Z2M or MQTT. HA arrives at this xy value by using a standard, fixed, internal calculation, oblivious to what Kelvin colour the output light device (controller+led primaries) actually makes of this.
To produce accurate Kelvin, HA would need to send a calibrated xy value for the specific device by using a profile for the device. See my more elaborate example in this thread.

[tremby]

I think perhaps you aren't understanding me.

What I'm trying to point out is that calibrating the values per bulb in Home Assistant, before the modified signals then go off to Z2M or whatever, may fix the issue for Home Assistant and anything using the Home Assistant API, but it does not fix the issue for anything skipping Home Assistant and talking directly to Z2M or to MQTT to control devices. Anything doing that does not get the benefit of the calibrated values. Maybe that's not in your scope and that's fine, but IMO the problem is better solved in Z2M than in HA. If Z2M is the one doing the calibration it solves the problem not only for Home Assistant but for anything using Z2M directly or talking to MQTT directly to control or query the devices.

Or perhaps I'm not understanding you?

[roelanddewindt]

Another related issue that unfortunately got "closed as not planned" is AL#93. Luckily it got a second life as AL#124 in v2 Inbox. There's still hope, but my opinion is this is not an issue AL should fix, as it is an HA core issue.