Number stepper

Who it’s for

The Number stepper widget is for operators and technicians who change one number on a device from a ThingsBoard dashboard: a target temperature, a fan speed, a dosing rate, a pressure limit or a batch count. They want to nudge the value up or down a step at a time, see at once where it sits in its range, and know that the device got it. The question they would type is “how do I set a value on my device from my dashboard?”

What it does

A thermostat holds a target of 21.5 °C in its shared attribute setpoint. An operator clicks plus three times. The card shows 23.0 straight away, waits until the clicks stop, writes setpoint = 23 once, and shows Saved when the write lands.

• Changes the value with big minus and plus buttons. Hold a button and the value keeps moving until you let go.
• Takes a typed value: click the number, enter a new one, and press Enter. Escape cancels. A typed value is rounded to the step and kept inside the range.
• Sends a run of clicks as one command, so the device sees 23.0 instead of 22.0, 22.5 and 23.0 in turn.
• Keeps the new number on screen while it is sent. It goes back to the device’s value only when the send fails, and a message says why.
• Sends the value as an attribute or as a one-way RPC command, with the payload shaped as an object, the bare value, or whatever your own function returns.
• Shows where the value sits on a bar between the lowest and the highest value, and scales the whole card to fit its size.
• Changes one number. It is not a dial, a slider or a schedule.

How to set up

Data keys

The Number stepper widget has no data keys. Like other control widgets, it works on the Target device picked in the widget’s data settings, and the keys it writes and reads are named in the settings below.

• The value — Attribute or Timeseries, read. The number the card opens on. Until a value arrives the card shows a dash and No data, and the first click starts from the lowest value.
• active — the server attribute ThingsBoard keeps for every device, read only when Lock when offline is on. Without it the widget treats the device as online.

Value

• Send the value as — Write an attribute by default. Send a one-way RPC command reaches the device directly; an attribute is picked up the next time the device looks and survives a reboot.
• Attribute — setpoint by default. Written with the new value and read back as the current one, so the widget works on any device without extra setup.
• Attribute scope — Shared - the device reads it by default; Server - only the platform sees it keeps the value inside ThingsBoard.
• RPC method — setValue by default. Receives the new value.
• Read the value from — empty by default. The telemetry or attribute key the device reports its value in. When it is empty, the widget uses RPC method that reads the value, or else the last value it sent.
• RPC method that reads the value — empty by default. Called once when the card loads, as a two-way command.
• What the device receives — An object - { “value”: 21.5 } by default. The value alone - 21.5 sends a bare number. Whatever a function of yours returns hands the payload to Payload function(value).
• Parameter name — value by default. The field name in the object, and the field the read method is expected to answer with.
• Payload function(value) — return { value: value }; by default. Receives value, the number being sent, and ctx, the widget context, and returns the command parameters. When it returns nothing or throws, nothing is sent and the card says why.
• Request timeout (ms) — 5000 by default.
• Queue the command for an offline device — off by default. The platform holds the command until the device connects, instead of failing straight away.

Range

• Lowest value and Highest value — 5 and 35 by default. The buttons stop at both ends, and a typed value is kept between them.
• Step — 0.5 by default. How far one click moves the value. Values are rounded to steps counted from the lowest value.
• Decimals — 1 by default.

Behavior

• Wait before sending (ms) — 600 by default. How long the widget waits after the last click before it sends. The number on screen changes at once either way. 0 sends every step.
• Lock when offline — off by default. When on, the card shows Offline and disables the buttons while the device’s active attribute is false.

How to customize

• To show a different unit — edit Units, °C by default. Empty leaves a bare number.
• To hide the bar — turn off Show the range bar, on by default. The buttons and the number stay.
• To keep the sizes fixed — turn off Scale to fit the card, on by default. With it on, a wide card puts the bar beside the buttons.
• To rename the card — change the widget title.

Tips

• Use Whatever a function of yours returns for a device that expects its own shape, for example return { temp: Math.round(value * 10) }; for a controller that takes tenths of a degree.
• Leave Read the value from empty while you wire a device up. The widget then reads back what it sent, so the buttons already work, and you can point it at the real telemetry key later.
• Set Step and Decimals together: a step of 0.5 needs 1 decimal, and a step of 5 needs 0.
• Turn on Queue the command for an offline device for devices that sleep, such as battery-powered controllers that wake every few minutes.