Knob Control

The Knob control widget provides a rotary dial for setting a numeric value on a HMI Device — a temperature setpoint, a motor speed, a dimmer level, or any other adjustable parameter. Turning the dial sends the selected value straight to the target HMI Device.

The widget follows four functional principles:

1. Initial value — on dashboard load, the widget reads the HMI Device’s current value and moves the dial to that position.
2. Value change — when the user turns the dial or types a number, the new value is sent to the HMI Device immediately.
3. Fallback — until the Initial value action delivers a value, the dial shows the configured Fallback initial value. Once the action delivers a value, that value replaces it.
4. Range clamping — the configured minimum and maximum bound the dial, so the operator cannot send a value outside the allowed range.

• Select a target HMI Device and the widget is ready to send values — no further setup required.
• Configurable range, decimal precision, and fallback value.
• Targets a single HMI Device directly, or an entity resolved at runtime through an entity alias.

1. Open the dashboard in edit mode. Click Add widget in the top toolbar, or click the Add new widget icon in the center of an empty dashboard.
2. In the widget bundle selection dialog, find and click Control widgets.
3. Select the Knob control widget.
4. Configure the target HMI Device and appearance, then click Add.

Select the datasource the widget reads from and writes to:

• Device — a specific HMI Device; values are always sent to this HMI Device.
• Entity alias — an entity matched by an entity alias; use this when the target HMI Device is selected dynamically at runtime, for example from a dashboard state parameter.

The Behavior section defines where the dial reads its value from and where it sends the value to. Click the pencil icon on either row to select the action type and its settings. Once configured, each row shows a summary such as Use time series 'temperature' or Set 'temperature' attribute to: value.

Determines the dial’s starting position when the dashboard loads. Selecting an Action reveals the fields that action requires.

Action	Description	Additional settings
Do nothing	No data is queried.	—
Get attribute	Reads an attribute value from the entity.	Attribute scope, Attribute key
Get time series	Reads the latest value of a time series key.	Time series key
Get alarm status	Derives the value from active alarms.	Alarm severity, Alarm types
Get dashboard state id	Reads the current dashboard state ID.	Result type
Get dashboard state object	Reads the full dashboard state as JSON.	Result type

Use Action result converter to transform the value before it reaches the dial. Leave it empty when no transformation is needed.

Since the dial holds a number, use Get time series in practice. If the value read is not a number, use Action result converter to return one.

Defines the action executed when the dial value changes.

Action	Description	Additional settings
Set attribute	Stores the new value in a HMI Device attribute.	Attribute scope (Shared), Attribute key, Value
Add time series	Records the new value as time series data.	Time series key, Value

Value offers two modes: Value sends the number selected on the dial as is, while Function transforms it before sending.

Controls the dial’s visual style and value range.

Setting	Description
Knob title	Text displayed above the dial, like Temperature controller.
Range	The min and max bounds of the dial. Values outside this range cannot be selected.
Value	The unit shown next to the value and the number of decimals displayed. Unit °C with 0 decimals renders as 4 °C.
Fallback initial value	The value shown while the widget is first rendered. As soon as the Initial value action delivers a value, that value replaces it — including an empty one, which the dial does not fall back from. Point Initial value at a key that is guaranteed to hold a value.
”No data to display” alternative message	Text shown in place of the dial when no data is available. Defaults to No data.

Controls how the widget card itself is displayed — title, colors, padding, and borders.

The Knob control supports the Widget header button action — adds a button to the widget header that triggers a configured action when clicked.

Scenario: A refrigeration controller (SN-001) runs at a target temperature between -10 °C and 20 °C. The controller reports the setpoint currently in effect as temperature time series data, and receives a new setpoint through the temperature shared attribute.

Goal: Give the operator a dial that shows the current target temperature and sets a new one as a whole number.

Prerequisite: On the SN-001 HMI Device, open the Latest telemetry tab and confirm that the temperature time series holds a value. Without one, the dial renders empty.

Step 1. Add the widget. Open the dashboard in edit mode, click Add widget, select Control widgets, then choose Knob control.

Step 2. Configure the datasource. Set the target to Device, then select SN-001.

Step 3. Configure Initial value. In Behavior, click the pencil icon on Initial value and set the dial to read the current target temperature on load:

• Action: Get time series
• Time series key: temperature
• Action result converter: leave empty

Step 4. Configure On value change. Click the pencil icon on On value change and set the dial to store the new value in a shared attribute:

• Action: Set attribute
• Attribute scope: Shared
• Attribute key: temperature
• Value: Value

Step 5. Configure the dial. In Appearance, set the following:

• Knob title: Temperature
• Range: min -10, max 20
• Value: unit °C, 0 decimals
• Fallback initial value: 0

Step 6. Save. Click Add, resize the widget, then click Save on the dashboard toolbar.

Result: On load, the widget reads the latest temperature time series value and shows it on the dial. Each turn of the dial stores the selected value in the temperature shared attribute, and SN-001 applies it as the new target temperature. When the controller reports the applied value back as time series data, the dial position updates to match.

The dial renders empty even though Fallback initial value is set

Fallback initial value is not a substitute used when the Initial value action fails. It only fills the dial while the widget is first rendered, and whatever the Initial value action delivers replaces it — including an empty value. So a dial that stays empty means Initial value is reading an empty value.

Cause	Solution
The key holds no value	Confirm that the attribute or time series key set in Initial value actually holds a value. Key names are case-sensitive.
Scope mismatch	Confirm that Attribute scope matches where the value is stored. A value stored in Shared cannot be read from Server.
Value is not a number	A value stored as a string does not render on the dial. Store it as a number, or return one from Action result converter.
Wrong target HMI Device	Confirm that the HMI Device selected in Datasource is the one you intend to control.

Turning the dial has no effect on the HMI Device

Cause	Solution
HMI Device offline	The value is stored, so the HMI Device applies it once it reconnects. Check the connection status.
On value change not configured	Confirm an action type is selected. Without one, the dial moves but no value is stored.
Attribute key or scope mismatch	Confirm that Attribute key and Attribute scope in On value change match the ones Initial value reads from. Key names are case-sensitive.
Wrong target HMI Device	Check the target in Datasource. If an entity alias is used, confirm which entity it resolves to in the current dashboard state.

The HMI Device receives a different number than the one selected

Cause	Solution
Wrong decimal precision	Adjust decimals. A dial with 0 decimals sends 4, not 4.0.
Range wider than the actual limits	Narrow Range min and max to the HMI Device’s real operating limits so out-of-range values cannot be selected.