Light control

Light control

Controls one light from one card: a switch, a brightness slider and a colour picker. It reads the light’s current state, level and colour from that device’s attributes and writes changes back to the same attributes, or sends them as one-way RPC commands.

Features

• Switch, slider and colour, each of which can be hidden — a card can be a plain dimmer, a plain switch, or all three
• Writes either one-way RPC commands or device attributes
• Three payload shapes for RPC: a named object, the bare value, or whatever your own function returns
• One command per gesture: dragging the slider across thirty levels sends one command, not thirty
• Optional queueing for an offline device, with retries
• Reads the light back when the card loads, with optional polling
• Slider locked while the light is off, so a level cannot be set on a dark lamp
• Accent colour follows the ThingsBoard theme unless you override it

Target device

This is a control widget: it takes no data keys. Choose a Target device in the widget configuration. Everything the widget reads and writes goes to that one device, so add one card per light.

Attributes

The widget reads these on load and writes to the very same keys — one attribute per thing, in one scope, in both directions. Names and scope are configurable; the table shows the defaults.

Attribute scope offers Shared — the scope a device subscribes to — and Server, which keeps the value on the platform for a rule chain to act on. Client scope is deliberately not offered: only the device itself can write there, so a widget that wrote to it would always fail.

color is written in whichever shape How the colour is sent selects: "#FF5722", {"r":255,"g":87,"b":34} or "255,87,34". All four read formats are accepted regardless.

RPC methods

Used when What a change does is set to Send a one-way RPC command, which is the default. Method names are configurable; the table shows the defaults.

What the device receives shapes the parameters of all three:

The function receives one argument, value — the level as a number, the switch as a boolean, the colour as a string or object. Its type tells you which command is being built:

if (typeof value === 'boolean') { return { on: value }; }
if (typeof value === 'string')  { return { rgb: value }; }
return { level: value, fade: 500 };

If the function returns nothing or throws, the change counts as failed: nothing is sent, and the device name turns red until a later change succeeds. A function that will not compile is caught when the card loads rather than on first use.

A one-way command that nobody answers is not an error, so a device with no matching RPC handler will appear to accept changes and do nothing. If your lights work through shared attributes, switch What a change does over.

Reading the light back

Once, when the card loads. Set Re-read the device every to a few seconds if a scene, a rule chain or a wall switch can move the same light; it is 0 by default, because polling a lamp that nothing else touches wastes both ends. Polling pauses while the slider is being dragged so it cannot fight the person using it.

Configuration

Every explanation sits behind the question mark beside its field. Fields that cannot apply are hidden: choose Write an attribute and the RPC method names, payload shape, timeout, queueing and retries all disappear; choose RPC and the attribute scope goes instead.

Command

Attributes

Values

Colour

Appearance

The card draws no title of its own — only the device name. The widget’s own Appearance tab still controls the title, background, padding and drop shadow; the title and the shadow ship off.

What the card shows while a change is in flight

The switch, slider and swatch move to the value you chose as soon as the gesture settles, not once the device confirms — so the card can be ahead of the light for as long as the request takes. A failed change is reported and turns the device name red rather than being dropped silently.

If the device has never reported its on/off state, the switch starts on and the slider stays usable. Treating an unknown state as off would lock a card that may be perfectly healthy, which reads as a broken widget.