Tunable White LED Lighting Control

Who it’s for

Anyone commissioning or overriding tunable-white lighting from a dashboard — a grower setting spectrum and intensity per zone and growth stage, a building or hospitality operator running warm-to-cool circadian white, a street-lighting team holding a segment under a dark-sky colour temperature cap. They ask what colour temperature and what level a zone is running at, and they want to change it in the unit they work in, which is Kelvin and not per cent. The fixtures in question usually have no RGB channel at all.

What it does

A greenhouse zone reporting 4000 K at 65 % shows both readings with the slider parked on the 4000 quick step. Dragging it to 3000 writes 3000 to the colour-temperature key, and a moment later the footer reads back what the fixture itself reports rather than what was sent.

• Colour temperature is the headline number and dim level is the second one. The slider runs between two ends you set, in Kelvin or mireds, with the ends labelled in that unit and named quick steps — 2700, 3000, 4000, 5000, 6500 — underneath, because specifiers say “4000”, not “47 per cent”.
• Dim level is a percentage on the face and your hardware’s scale on the wire — 0–10 for a 0–10 V driver, 0–254 for DALI, 0–255 or 0–100 for the usual firmware.
• A change writes a device attribute or sends an RPC command, and the attribute is the default. What is being set here is desired state — a photoperiod target, a zone’s circadian setpoint, a segment’s night level. It persists, it survives a reboot, and a rule chain reads it and decides what to send to the hardware. RPC is “do this now, to this one device”, which is what a maintenance override wants and not what a schedule wants.
• The RPC path takes a JS function over the outgoing payload. Casambi, Tuya, DALI gateways, 0–10 V dimmers and Zigbee agree on nothing, and that translation is usually a rule chain in the middle. One function here replaces it: the body receives the value and which control produced it, and returns whatever the vendor wants.
• The footer is a readback, not an echo. It shows what the fixture reports with the age of the reading beside it, and past a window you set it says the reading is stale rather than showing a confident number.
• There is no colour control here, on purpose. A tunable-white fixture has a warm and a cool channel and no RGB channel at all, and ThingsBoard’s own Light control already drives one lamp’s switch, brightness and colour. This card is the tunable-white half, and nothing else.
• Sets colour temperature and level: it does not schedule them, and it keeps no history of who changed what.

Requirements

What must exist before the card can do anything:

• A tunable-white fixture, driver or gateway that accepts a colour temperature and a dim level — either as a shared attribute it reads, or as an RPC method it implements. The card writes those two values; it does not speak DALI, 0–10 V or Zigbee itself.
• On the attribute path, a rule chain that reads the attribute and drives the hardware. What the card writes is desired state, and something has to turn that into whatever the fixture accepts. On the RPC path that translation is the payload function instead, and no rule chain is needed.

How to set up

Four decisions make a working card, and the tables below hold the rest at defaults that already work: pick the target device, keep or rename the three attribute keys, set the two slider ends to what your fixture can genuinely reach, and set the dim scale your driver expects. Nothing else has to be touched to get light on a dashboard.

Data keys

The tunable-white card is a control widget and takes no datasource. Choose a target device in the widget configuration; everything below applies to that one entity.

Attribute	Scope	Operation	Description
colorTemp (configurable name)	Shared or Server	Read + Write	Colour temperature in the unit picked under Colour temperature unit
brightness (configurable name)	Shared or Server	Read + Write	Dim level on the scale picked under Device dim scale
power (configurable name)	Shared or Server	Read + Write	Boolean

Method	Direction	Parameters	Sent when
setColorTemp (configurable name)	One-way, or two-way with Wait for the device to answer	The colour temperature, shaped by Payload function if one is written	The slider is released, or a quick step is tapped
setBrightness (configurable name)	The same	The dim level on the device scale	The dim slider is released
setPower (configurable name)	The same	A boolean	The toggle is pressed

A control whose key or method is left empty is drawn greyed out and cannot be pressed. When every control that is shown has no key or method, the card replaces itself with No attribute keys bound — or No RPC methods set on the RPC path — and the chip reads NOT SET, so a half-configured card never looks like a working one. A control the fixture has not reported yet still works; the footer simply has nothing to read back until it does.

Command

Setting	Default	Effect
Action	Write a device attribute	Attribute write or RPC. The dialog shows one path at a time
Power method, Dim level method, Colour temperature method	setPower, setBrightness, setColorTemp	RPC handler names the device implements
Payload function	empty	Shapes the outgoing payload for a gateway. Left blank, the widget sends a boolean for power and a number on the device dim scale for level and colour temperature
Wait for the device to answer	Off	Sends a two-way command and waits for the response
RPC timeout (ms)	5000	How long to wait before the command counts as failed
Queue the command for an offline device	Off	Holds the command until the device reconnects
Retries	0	Used only for a queued command
Hold continuous input for (ms)	350	Stops a held arrow key writing once per press. A drag already writes once, on release

Attributes

Setting	Default	Effect
Power key, Dim level key, Colour temperature key	power, brightness, colorTemp	The attributes this card writes and subscribes to
Attribute scope to write	Shared	Shared is the scope a device can read; server keeps the value on the platform for a rule chain
Read the card’s state from	Attribute	Attributes close the loop with no further configuration; telemetry suits a fixture that reports its real level as a time series

Values

Setting	Default	Effect
Show the power toggle, Show colour temperature, Show the dim level	All on	Each takes its own keys and methods out of the dialog with it
Colour temperature unit	Kelvin	Kelvin or mireds. The slider ends and the quick steps are read in this unit
Slider left end, Slider right end	2700, 6500	The limits your fixture supports
Device dim scale	100	The scale the driver expects — 0–10, 0–100, 0–254 or 0–255

How to customize

• To change what the quick steps offer — set Named quick steps to your own comma-separated list. Anything outside the two ends is dropped rather than drawn unreachable, so a street segment capped at 4000 K keeps only the steps it can reach.
• To say when a reading has gone quiet — set Stale after (minutes, 0 = off).
• To label the panel — set Title and Subtitle. Left empty, the subtitle names the write target, the write path and the dim scale, because on an asset the blast radius is otherwise invisible.
• To match your dashboard’s palette — set Accent color (on state), and Keyboard focus outline color for the Tab-key outline.
• To keep the controls a fixed size — turn off Auto-scale controls to widget size.

Tips

• Leave the write path on attribute unless a gateway is doing the translating. The pair the card writes is desired state, so it survives a reboot and a rule chain can read it and decide what the hardware actually receives — which is the same seam the payload function fills on the RPC path, one layer further out.

• Set the two slider ends to what the fixture can genuinely reach before anything else. Every quick step is filtered against them, so a segment capped at 4000 K stops offering 5000 and 6500 on its own, and nobody has to remember which zone takes which.

If what you need is one lamp’s switch, brightness and colour rather than colour temperature, that is a different card:

${item-link:6d0720c0-919e-11f1-9a63-ef2cf49c242b}