HP Sand Filter

• Display the current filtration mode with the active mode button highlighted.
• Switch the filtration mode by clicking a mode button directly on the widget.
• Show or hide individual mode buttons and configure their appearance.
• Indicate running and stopped states with configurable colors.
• Indicate warning and critical states with configurable alarm colors.
• Animate a blinking effect when the filter is in warning or critical state.
• Trigger separate dashboard actions when the widget is clicked in its warning or critical state.
• Trigger a general dashboard action when the widget symbol is clicked in any state.
• Receive state data from device attributes, time series, alarm status, or dashboard state.

1. Open the dashboard and switch to edit mode.
2. Click Add widget at the top, or the Add new widget icon in the center of the screen.
3. Open the High-performance SCADA fluid system widget bundle.
4. Select HP Sand filter.
5. Configure the widget settings, then click Add.

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. The HP Sand filter widget has a pre-selected symbol from the High-performance 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.

Behavior parameters define what the widget displays and how it responds to user interaction, driven by real-time data from the connected device.

Parameter	Default	Description
Running	Use attribute 'running'	Whether the sand filter is currently running. See Data source configuration.
Filtration mode	Use attribute 'filtrationMode'	The current operational mode of the filter. The matching mode button is highlighted on the widget face. See Data source configuration.
Filtration mode update state	Set 'filtrationMode' attribute to: value	Action triggered when the operator clicks a mode button on the widget face to switch the filtration mode. See Update action configuration.

Warning state

Parameter	Default	Description
Warning	Use alarm status	Whether the filter is in warning state. See Data source configuration.
Warning click	Do nothing	Action triggered when the user clicks the widget symbol while it is in warning state. See Click action configuration.

Critical state

Parameter	Default	Description
Critical	Use alarm status	Whether the filter is in critical state. See Data source configuration.
Critical click	Do nothing	Action triggered when the user clicks the widget symbol while it is in critical state. See Click action configuration.

Parameter	Default	Description
Warning/Critical state animation	False	Whether to enable blinking animation when the filter is in warning or critical state. See Data source configuration.
On click	Do nothing	Action triggered when the user clicks the widget symbol in any non-alarm state. See Click action configuration.

Applies to Warning click, Critical click, and On click. Select one action type from the list below.

• Do nothing

  The symbol is clickable but performs no action. Use while testing styles or as a placeholder.

• Navigate to new dashboard state

  Switches to a different view within the same dashboard, like opening a filter details screen.

  Parameter	Description
  Target dashboard state	The state to open (required).
  Open right dashboard layout (mobile view)	Opens a side panel instead of replacing the view (mobile only).
  Set entity from widget	Passes the current entity to the target state.
  State entity parameter name	The key the entity is passed under.
  Dashboard state display option	Normal (same view), In separate dialog (popup), or In popover (inline overlay).

• Update current dashboard state

  Updates the context of the current view, like switching the selected device, without navigating away.

  Parameter	Description
  Target dashboard state	The state to switch to (optional).
  Open right dashboard layout (mobile view)	Opens a side panel on mobile.
  Set entity from widget	Passes the current entity to the updated state.
  State entity parameter name	The key the entity is passed under.

• Navigate to other dashboard

  Opens a completely different dashboard, like jumping from this system view to a global alarms view.

  Parameter	Description
  Target dashboard	The dashboard to open (required).
  Target dashboard state	The specific view to open within that dashboard.
  Open in a new browser tab	Opens the dashboard without leaving the current page.
  Set entity from widget	Passes the current entity to the other dashboard.
  State entity parameter name	The key the entity is passed under.

• Custom action

  Runs custom JavaScript on click to implement any behavior not covered by the built-in options. Use it to make HTTP requests, open custom dialogs, call other widget APIs, or interact with external services. The function receives: $event, widgetContext, entityId, entityName, additionalParams, entityLabel.

• Custom action (with HTML template)

  Same as Custom action, but also renders a custom HTML panel or dialog when the symbol is clicked. The function receives an additional htmlTemplate parameter: $event, widgetContext, entityId, entityName, htmlTemplate, additionalParams, entityLabel.

  Parameter	Description
  Resources	External scripts and styles loaded before the action runs.
  CSS	Styling for the HTML template.
  HTML	Layout of the rendered dialog or panel.
  JS	Action logic.

• Mobile action

  Triggers a native device feature inside a ThingsBoard mobile app, like the camera or QR scanner.

  Parameter	Description
  Mobile action type	Take picture from gallery, Take photo, Open map directions, Open map location, Scan QR Code, Make phone call, Get phone location, Take screenshot, or Device provision.

• Open URL

  Opens a website or external link when clicked.

  Parameter	Description
  URL	The address to open (required).
  Open in a new browser tab	Keeps the current dashboard open while opening the link.

Applies to Filtration mode update state. This action is triggered each time the operator clicks one of the mode buttons on the widget face to switch the filtration mode. The value written is the identifier of the selected mode. Select one action type from the list below.

• Execute RPC

  Sends the selected filtration mode to the device as an RPC command.

  Parameter	Description
  Method	RPC method to call, like setFiltrationMode.
  Parameters	Value — sends the mode identifier directly; Function — sends a transformed value computed by your f(value) function; None — sends no parameter.
  RPC request timeout (ms)	How long to wait for a device response before timing out (Advanced settings).
  RPC request persistent	Stores and retries the command until the device comes online (Advanced settings).

• Set attribute

  Writes the selected filtration mode to a device attribute.

  Parameter	Description
  Attribute scope	Where to write: Server, Shared, or Client.
  Attribute key	Attribute name to write to, like filtrationMode.
  Value	Value — writes the mode identifier directly; Function — writes a transformed value computed by your f(value) function.

• Add time series

  Writes the selected filtration mode as a new time series data point on the device.

  Parameter	Description
  Time series key	The telemetry key to write, like filtrationMode.
  Value	Value — writes the mode identifier directly; Function — writes a transformed value computed by your f(value) function.

Applies to Running, Filtration mode, Warning, Critical, and Warning/Critical state animation. Click the edit icon next to a parameter to open its configuration dialog. When Action is set to Do nothing, the Value options depend on which parameter you are configuring:

Parameter	Value
Running	True or False
Filtration mode	The mode identifier matching one of the enabled mode buttons
Warning	True or False
Critical	True or False
Warning/Critical state animation	True or False

For all other actions, the configuration dialog works the same way regardless of which parameter you are editing:

• Execute RPC

  Read the parameter value from an RPC response.

  Parameter	Description
  Method	RPC method to call, like getState or getFiltrationMode.
  Action result converter	None — parameter is activated when the result matches the value you specify; Function — parameter is activated when your f(data) returns true.
  ’[parameter]’ when result is	The value or condition that activates this parameter.
  RPC request timeout (ms)	How long to wait for a device response before timing out (Advanced settings).
  RPC request persistent	Stores and retries the command until the device comes online (Advanced settings).

• Get attribute

  Read the parameter value 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 running or filtrationMode.
  Action result converter	None — parameter is activated when the attribute equals the value you specify; Function — parameter is activated when your f(data) returns true.
  ’[parameter]’ when result is	The value or condition that activates this parameter.

• Get time series

  Read the parameter value from the latest telemetry reading.

  Parameter	Description
  Time series key	Telemetry key to monitor, like filtrationMode or filterRunning.
  Action result converter	None — parameter is activated when the telemetry value equals what you specify; Function — parameter is activated when your f(data) returns true.
  ’[parameter]’ when result is	The value or condition that activates this parameter.

• Get alarm status

  Activate the parameter when a specific alarm is active on the device.

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

• Get dashboard state id

  Activate the parameter based on which dashboard state is currently open.

  Parameter	Description
  Action result converter	None — parameter is activated when the state name matches the text you enter; Function — parameter is activated when your f(data) returns true.
  ’[parameter]’ when result is	The state name or condition that activates this parameter.

• Get dashboard state object

  Activate the parameter using the full dashboard state context; use this when you need to evaluate multiple state parameters at once.

  Parameter	Description
  Parse value function	A f(data) function that receives the current dashboard state object. Use data.id to read the active state name, or data.params to inspect state parameters.
  ’[parameter]’ when result is	The expected type and value that activates the parameter. Choose String, Integer, Double, Boolean (then select True or False), or JSON.

The Appearance section controls the widget title, which mode buttons are shown, their colors, and the visual style of the active mode indicator.

Setting	Default	Description
Title	HP Sand filter	Widget title displayed in the header. Supports entityName and entityLabel variables.
Card icon	—	Icon shown in the widget header. Configure its size and color.
Filter	On	Whether to show the Filter mode button on the widget face.
Waste	On	Whether to show the Waste mode button on the widget face.
Backwash	On	Whether to show the Backwash mode button on the widget face.
Recirculate	On	Whether to show the Recirculate mode button on the widget face.
Rinse	On	Whether to show the Rinse mode button on the widget face.
Closed	On	Whether to show the Closed mode button on the widget face.
Running color	White	Filter body color when in the running state.
Stopped color	Gray	Filter body color when stopped (not running).
Warning color	Orange	Filter color when in warning state.
Critical color	Red	Filter color when in critical state.
Mode box background — Active	Dark gray	Background color of the currently active mode button.
Mode box background — Default	White	Background color of inactive mode buttons.
Border color — Active	Dark gray	Border color of the currently active mode button.
Border color — Default	Transparent	Border color of inactive mode buttons.
Label color — Active	Dark	Text color of the label inside the active mode button.
Label color — Default	Transparent	Text color of the labels inside inactive mode buttons.

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.

No mode button is highlighted as active

Cause	Solution
Filtration mode action is Do nothing and no value is set	Open the Filtration mode edit dialog and configure it to read from the device attribute or time series key that holds the current mode.
Device is sending a value that does not match any mode identifier	Confirm the device sends a value that matches one of the enabled mode button identifiers.

Clicking a mode button does not update the filter mode

Cause	Solution
Filtration mode update state is not configured	Open the Filtration mode update state edit dialog and select Execute RPC, Set attribute, or Add time series.
Target device is not connected	Confirm that the selected device is online and able to receive commands.

Warning or critical color does not appear

Cause	Solution
Warning or Critical action is Do nothing and value is False	Configure the state parameter to read from an alarm status or a device attribute.
Alarm is not active on the device	Confirm that the device has an active alarm of the expected severity.

Warning click or Critical click does nothing

Cause	Solution
The filter is not currently in the expected alarm state	The Warning click handler only fires when the Warning state is active; Critical click only fires when the Critical state is active. Verify the alarm is active on the device.
Action is set to Do nothing	Open the Warning click or Critical click edit dialog and configure the desired navigation or action.

This widget is used in the following ready-made solution template built on the High-performance SCADA fluid system bundle:

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