Setpoint control

Setpoint control

A round dial for setting one numeric value on a device — target humidity, temperature, fan speed, brightness, valve position. Drag the knob, scroll the wheel or use the arrow keys, and the widget sends the value you settle on to the device. It ships configured as a humidity control and can be pointed at any numeric setpoint.

Features

• Writes either a one-way RPC command or a device attribute, in shared or server scope
• Three payload shapes for RPC: a named object, the bare number, or whatever your own function returns
• Optional queueing for an offline device, with retries, so a command survives a device being away
• One command per gesture — a drag across thirty values sends one command, not thirty
• Reads the current value back from the device when the card loads, with optional polling
• Optional on / off switch that locks the dial while the device is off
• Range, step, decimals, units, scale and colours are all configurable
• Read-only mode for a dial that displays but never sends

Target device

This is a control widget, so it takes no data keys. Choose a Target device in the widget configuration — everything the widget reads and writes goes to that one device.

Attributes

Used when What a change does is set to Write an attribute. Names and scope are configurable; these are the defaults.

Attribute	Type	Scope	What it holds
humidityLevel	number	Shared	The setpoint. Written when you move the dial, read back when the card loads
enabled	boolean	Shared	Whether the device is on. Written by the switch, read back when the card loads

Use Shared scope for anything the device itself has to act on — that is the scope a device subscribes to. Use Server scope when only the platform reads the value, for example when a rule chain rather than the device acts on the change.

RPC methods

Used when What a change does is set to Send a one-way RPC command — the shipped default. Method names are configurable; these are the defaults.

Method	Type	Parameters	When it is sent
setHumidityLevel	one-way	the setpoint	When you move the dial and settle
setState	one-way	true / false	When you use the switch
getHumidityLevel	two-way	none	Once, when the card loads

What the device receives controls the shape of the setpoint parameter:

Option	Sent
An object	{"value": 71} — the parameter name is configurable
The number alone	71, for firmware that expects a scalar
A function of yours	whatever the function returns

The function is given value, the number being sent, and ctx, the widget context. If it returns nothing or throws, the change counts as failed: nothing is sent and the reason is reported. The switch always sends a plain boolean and never goes through the function.

getHumidityLevel is expected to answer with the value under the configured parameter name, falling back to value and then result. Leave the read method empty for firmware that has none — the dial then opens at the lowest value.

Note that a one-way command nobody answers is not an error. If the device has no matching RPC handler, the dial will appear to accept changes and nothing will happen; switch to Write an attribute if your device works through shared attributes.

Ways to change the value

• Drag anywhere on the ring. The knob face is not draggable, so a stray tap in the middle of the card cannot throw the setpoint across the range.
• Scroll the wheel over the dial. It works immediately, with no click first, and takes the scroll event — so a dashboard that scrolls will not scroll while the cursor is over the knob.
• Keyboard, once the dial has focus: arrow keys move one step, Page Up and Page Down ten, Home and End jump to the ends.

All three cross many values on the way. Wait before sending (ms) means the device hears only the value you settled on.

Configuration

Command

Setting	Default	What it does
What a change does	Send a one-way RPC command	RPC command, or attribute write
RPC method	setHumidityLevel	Handler the device implements
RPC method that reads the current value	getHumidityLevel	Two-way call on load; empty to skip
What the device receives	An object	Payload shape — object, bare number, or your function
Parameter name	value	Field the value is sent under, and read back from
Payload function(value)	return { value: value };	Used only for the custom payload shape
Attribute key	humidityLevel	Attribute written and read in attribute mode
Attribute scope	Shared	Shared or server
Request timeout (ms)	5000	100 ms to two minutes
Queue the command for an offline device	off	Platform holds the command until the device connects
Retries	0	Up to ten; applies only to a queued command
Wait before sending (ms)	350	Delay after the last movement before sending. 0 sends every step
Re-read the device every (s)	0	0 reads once on load. Polling pauses while the dial is moving
Read only	off	Shows the value and refuses every gesture

Switch

Setting	Default	What it does
Show the on / off switch	on	While the device is off, the dial is locked
RPC method that switches the device	setState	Receives true or false
Attribute holding the on / off state	enabled	Written as a boolean

If the device has never reported its on / off state, the switch starts on and the dial stays usable, rather than locking a widget that may be perfectly healthy. Once the device reports, the switch follows it.

Range

Setting	Default	What it does
Lowest value	0	Start of the scale
Highest value	100	End of the scale
Step between values	1	Also how far one wheel notch or arrow key moves. 0 allows any value
Decimal places	0	Applied to the value and the scale
Units	%	Sits next to the value, smaller. Empty leaves a bare number
Show the scale	on	The numbers and ticks around the outside
Number of scale labels	5	Between 2 and 13
Repeat the units on the scale	off	0% 25% 50% instead of 0 25 50; crowds the ring

Appearance

Setting	Default	What it colours
Caption under the value	Humidity level	Empty leaves the value on its own
Arc and switch	#303F9F	The filled arc and the switch when on
Value	#212121	The number in the middle
Caption, scale and track	#9E9E9E	Caption, scale numbers, unfilled arc, dashed ring
Knob face	#FFFFFF	The disc behind the value
Knob glow	#F1F3F9	Soft tint at the foot of the knob. Match the face for a flat disc

The shipped palette suits a white dashboard. For a dark card: arc #6EE7A0, value #FFFFFF, muted rgba(255, 255, 255, 0.55), knob face #132A2E, glow rgba(46, 160, 108, 0.85), plus a dark background in the widget’s own Appearance tab.

Widget title, background, padding and drop shadow come from that Appearance tab rather than from these settings. With the title hidden there and the switch hidden here, the header row collapses and the dial takes the space back.

What the dial shows while a change is in flight

The dial moves to the value you chose as soon as the gesture settles, not once the device confirms — so the number on screen can be ahead of the device for as long as the request takes. A failed write is reported rather than silently dropped.