Setpoint control

Who it’s for

Dashboard authors who need one numeric setpoint on one device ask “how do I let someone set a target value — a temperature, a humidity level, a fan speed — with a dial instead of a text box?” A single round dial that drags, scrolls and reads the device’s own value back answers that directly, without wiring a slider and a label together by hand.

What it does

Out of the box the control is a 0–100% humidity dial: drag it, scroll over it, or move it with the arrow keys, and it sends setHumidityLevel once you settle. Point it at any numeric setpoint — temperature, fan speed, valve position — by changing the range, the method names and the caption.

• Drag, scroll, or use the keyboard — the knob face itself is not draggable, so a stray tap in the middle of the card can’t throw the setpoint across the range; scrolling works with no click first; arrow keys move one step, Page Up and Page Down move ten, Home and End jump to the ends
• One command per gesture — dragging or scrolling across many values sends the value you settle on, not every value crossed on the way
• Reads the setpoint back from the device, so the dial opens on the value the device is actually holding rather than at zero, with optional polling if something else can move the same value
• An optional switch locks the dial while the device is off, so a setpoint can’t be set on a device that isn’t running
• Read-only mode for a dial that only displays a value and never sends one
• Writes either a one-way RPC command or a device attribute; it does not wait for a device reply, so what actually happened is best confirmed with a feedback key elsewhere or a separate alarm

How to set up

Data keys

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

Reading and writing don’t follow What a change does quite the same way: in RPC mode, the on/off switch is never read back from the device — there is no RPC call for it — so the switch always starts on and only changes when someone uses it here. Only attribute mode reads the switch’s real state.

What the device receives picks the RPC parameter shape for the setpoint (not the switch, which always sends a plain boolean). The function receives value and ctx, the widget context, and returns the object to send:

return { target: value, mode: 'auto' };

If it returns nothing or throws, the change counts as failed: nothing is sent and the reason is reported.

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

Delivery

Range

How to customize

Switch

• To hide the on/off switch — turn off Show the on/off switch; the dial stays usable at all times.
• To change which method or attribute the switch uses — set RPC method that switches the device or Attribute holding the on/off state, whichever applies to your What a change does setting.

Scale & precision

• To change how many decimal places show — set Decimal places; it affects the number in the middle and every scale label.
• To add or remove the unit shown beside the value — edit Units; empty leaves a bare number.
• To hide the ring of numbers around the dial — turn off Show the scale.
• To change how many labels the scale shows — set Number of scale labels, from 2 to 13.
• To repeat the unit on every scale label — turn on Repeat the units on the scale; it crowds the ring, which is why it’s off by default.

Appearance

• To change the caption under the value — edit Caption under the value; empty leaves the value on its own.
• To recolor the arc and the switch — set Arc and switch.
• To recolor the number in the middle — set Value.
• To recolor the caption, the scale, and the unfilled track — set Caption, scale and track.
• To recolor the knob — set Knob face and Knob glow; match them for a flat disc instead of a soft radial tint.

The widget’s own Appearance tab still controls the title, background, padding and drop shadow — this widget embeds the title panel into its own header, so hiding the title there collapses the header row and the dial takes the space back.

How the dial behaves 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 dropped silently.

If the device has never reported its on/off state and the switch is shown, the switch starts on and the dial stays usable — locking a dial that may be perfectly healthy would read as a broken widget. In RPC mode this is permanent: nothing here ever reads the switch state back from the device, so it always starts on and only reflects what’s clicked here, not what the device is actually doing.

Tips

• If your device answers RPC method that reads the current value with the setpoint under a field other than value, set Parameter name to match — the read-back looks there first, then falls back to value, then result.
• Leave RPC method that reads the current value empty for firmware that has no read command; the dial opens at the lowest value instead of guessing.
• If the on/off state needs to be trustworthy on screen, use Write an attribute instead of RPC — it’s the only mode this widget reads the switch back in.
• A device that’s often offline is a better fit for Write an attribute than a queued command — the attribute waits for it, and nothing has to be queued.