Horizontal Ball Valve

This widget belongs to the Traditional SCADA fluid system bundle — a collection of pipe segments, fittings, valves, pumps, and gauges designed for building fluid system diagrams on ThingsBoard dashboards. It connects to a device and reflects the real-time valve state through open/close animation and configurable state colors.

• Visualize the open or closed state of a valve in real time.
• Animate the valve symbol between open and closed positions using configurable rotation angles.
• Send open or close commands to the device when the user clicks the valve symbol.
• Apply custom colors for the open and closed states independently.
• Receive state data from device attributes, time series, alarm status, or dashboard state.

The widget connects to a single data source: either a Device or an Entity alias that resolves to a device. This device provides the telemetry or attribute values used to drive the widget’s visual state.

The SCADA symbol defines the visual shape of the widget. Each valve widget has a pre-selected symbol from the Traditional SCADA fluid system bundle. To use a different symbol, click Browse SCADA symbol from gallery and choose one from the library, or upload your own.

The widget has three behavior parameters: one that reads the current valve state from the device, and two that define the commands sent to the device when the user opens or closes the valve.

Parameter	Default	Description
Opened	Use attribute 'open'	Whether the valve is currently open. True = open state (symbol rotates to the opened angle and shows the opened color); False = closed state.
Open	Set 'open' attribute to: true	Command sent to the device when the user clicks the valve to open it.
Close	Set 'open' attribute to: false	Command sent to the device when the user clicks the valve to close it.

To configure the Opened parameter, click its edit icon. This parameter reads the current valve state from the connected device.

When Action is Do nothing, set the Value directly:

Value	Effect
True	Widget always shows the valve as open.
False	Widget always shows the valve as closed.

For all other actions, the widget reads the valve state dynamically from the device:

• Execute RPC — Read the state from an RPC response.

  Parameter	Description
  Method	RPC method to call, like getState or getValveStatus.
  ‘Opened’ when result is	The value that activates the open state.

• Get attribute — Read the state from a device attribute.

  Parameter	Description
  Attribute scope	Where the attribute is stored: Any, Client, Server, or Shared.
  Attribute key	Attribute name to read, like open or valveOpen.
  ‘Opened’ when result is	The attribute value that activates the open state.

• Get time series — Read the state from the latest telemetry value.

  Parameter	Description
  Time series key	Telemetry key to monitor, like open or state.
  ‘Opened’ when result is	The telemetry value that activates the open state.

• Get alarm status — Activate the open state when a specific alarm is active on the device.

  Parameter	Description
  Alarm severity	Severity levels that trigger the state: Critical, Major, Minor, Warning, or Indeterminate.
  Alarm types	Any alarm, or a specific alarm type.

• Get dashboard state id — Activate the state based on which dashboard state is currently open.

  Parameter	Description
  ’Opened’ when result is	The dashboard state name that activates the open state.

• Get dashboard state object — Activate the state using the full dashboard state context.

  Parameter	Description
  Parse value function	A f(data) function that returns true when the valve should show as open.

The Open and Close parameters define the command sent to the device when the user clicks the valve symbol. Click each parameter’s edit icon to configure the action.

• Execute RPC — Send an RPC command to the device.

  Parameter	Description
  Method	RPC method to call, like setState.
  Parameters	Command value: true for Open, false for Close.

• Set attribute — Write a value to a device attribute.

  Parameter	Description
  Attribute scope	Where the attribute is stored: Shared, Client, or Server.
  Attribute key	Attribute name to write, like open.
  Value	Attribute value: true for Open, false for Close.

• Add time series — Write a value to a time series key.

  Parameter	Description
  Time series key	Time series key to write, like state.
  Value	Time series value: true for Open, false for Close.

The Appearance section controls the widget title, valve state colors, and the rotation angle of the symbol in each state.

Setting	Default	Description
Title	Widget name	Widget title displayed in the header. Supports entityName and entityLabel variables.
Card icon	—	Icon shown in the widget header. Configure its size and color.
Opened color	Green	Color of the valve symbol when in the open state.
Closed color	Gray	Color of the valve symbol when in the closed state.
Opened rotation angle	0	Rotation angle (degrees) of the symbol when the valve is open.
Closed rotation angle	90	Rotation angle (degrees) of the symbol when the valve is closed.

The Card appearance section controls the widget container style.

Setting	Default	Description
Background	Transparent	Card background color.
Show card buttons	Fullscreen	Buttons shown on the card when hovered.
Card border radius	0px	Rounding of card corners.
Card padding	12px	Inner spacing between the card edge and widget content.

Widget shows no state change or shows the wrong state

Cause	Solution
Opened action is set to Do nothing	Open the Opened edit dialog, set the correct Action, and specify the attribute or time-series key.
Attribute or telemetry key mismatch	Verify that the key name in the Opened configuration matches exactly what the device reports.
Target device is not connected	Confirm that the selected device is online and actively sending data.

Clicking the valve does not send a command to the device

Cause	Solution
Open or Close action is not configured	Open the Open or Close edit dialog and set the action type (Execute RPC, Set attribute, or Add time series).
Attribute key or RPC method is incorrect	Verify the key name or method name matches what the device expects.
Target device is not connected	Confirm that the selected device is online.

These widgets are used in the following ready-made solution templates built on the Traditional SCADA fluid system bundle:

• SCADA Swimming pool — a complete swimming pool monitoring dashboard built with pipe, pump, valve, and gauge widgets from the Traditional SCADA fluid system bundle.