State Chart

The State chart widget displays how an entity’s state changes over time as a timeline of colored segments. It is ideal for tracking discrete state transitions such as online/offline, active/inactive, or open/closed — making device availability, process transitions, and system activity easy to monitor at a glance.

• Visualizes state transitions as colored timeline segments showing exactly when and how a state changed.
• Works with any telemetry data type: string, integer, double, boolean, or JSON.
• Multiple series: monitor state history for several devices or parameters on one chart.
• Customizable state mapping: assign specific labels and colors to each state value.
• Comparison mode: overlay the same state series from a previous time period for pattern analysis.
• Configurable fill style (solid or gradient) for the area beneath the state line.

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 Charts.
3. Select the State chart widget.
4. Configure the datasource, series, states, and appearance, then click Add.

All settings in this section use Basic mode — a quick-start configuration covering the essentials. For finer widget controls like custom tooltip functions and advanced axis formatting, switch to the Advanced tab.

The Basic tab groups settings into: Time window, Datasource, Series, States, Y axes, Appearance, Chart, X axis, Legend, Tooltip, Animation, and Card appearance.

Define the time interval to display, like Last 24 hours or Current day. Learn more in the Time window guide.

Select the source of state data:

• Device — a specific device; shows the state history of this device over the configured time range.
• Entity alias — a set of entities matched by an entity alias; use this to display state timelines for multiple devices on the same chart.

The widget supports two display modes: Series and Comparison.

Each data key is rendered as an independent state timeline. Add a key for each state parameter to display, like connected or doorState. Each series updates dynamically as new telemetry arrives.

The telemetry key can contain any supported data type:

• String — like "online", "offline", or "maintenance".
• Integer — like 0, 1, 2 representing different states.
• Double — like 1.0, 2.5 for numeric state indicators.
• Boolean — like true = active, false = inactive.
• JSON — like {"state": "running"}; the widget extracts and displays the nested value.

Click the settings icon on a series row to open the Data key configuration dialog with General and Advanced tabs.

General tab:

Setting	Description
Key	Telemetry or attribute key name.
Label	Legend label for this series.
Decimals	Decimal places for displayed values.
Color	Series color used for the state line and fill.
Use data post-processing function	Optional JavaScript transform applied to the raw value before display. Signature: f(value, latestData).

Advanced tab — Legend:

Setting	Description
Show in legend	Include this series in the chart legend.
Hidden by default	Series is rendered but hidden in the legend until toggled by the user.

Advanced tab — Y axis: Select which Y axis this series is plotted against.

Advanced tab — Fill: Shade the area beneath the state line. Options: None, Opacity (solid fill with transparency), Gradient (set start and end opacity values).

Advanced tab — Tooltip value format function: Optional JavaScript function f(value, latestData) to format the value shown in the hover tooltip for this series.

Advanced tab — Comparison settings: Enable Show historical data for comparison to plot a comparison series from a previous time period alongside this series. Configure Comparison key label (auto or custom) and Comparison data color.

In Comparison mode, the widget overlays the same data keys from a previous time period on top of the current data — for example, today vs. yesterday or this week vs. last week. Each period is rendered as a separate state timeline, making it easy to spot recurring patterns or behavioral changes.

Switch to the Comparison tab in the Series section to enable this mode. Each comparison entry has an interval dropdown, an X axis button, and a list of data keys (Show, Key, Label, Color).

Comparison interval options:

Option	Description
Previous interval (default)	Shifts the time window back by one full interval length.
Day ago	Compares with the same period from 24 hours earlier.
Week ago	Compares with the same period from 7 days earlier.
Month ago	Compares with the same period from one month earlier.
Year ago	Compares with the same period from one year earlier.
Custom interval	Enter a custom offset in milliseconds.

Comparison X axis settings — click the X axis button to configure how the comparison time axis is displayed:

Setting	Description
Show	Display the comparison X axis on the chart.
Label	Text label for the comparison axis.
Position	Top or Bottom.
Tick labels	Show date/time labels on ticks. Configure font and color.
Show ticks	Render tick marks on the axis.
Show line	Render the axis baseline.
Show split lines	Render vertical grid lines for each tick.

The States section maps each possible telemetry value to a human-readable label displayed on the Y axis. Click Add state to add a new row.

Field	Description
Label	The state label shown on the Y axis, like Online, Offline, or Maintenance.
Ticks value	The numeric position of this state on the Y axis, like 0 for inactive or 1 for active.
Source	Constant — the state matches a single exact value. Range — the state matches any value within a defined range.
Value type	Data type of the incoming telemetry value: String, Integer, Double, Boolean, or JSON.
Value / Range	The exact value (Constant) or the min/max range (Range) that activates this state.

Configure one or more Y axes to control vertical scaling and labeling. Each series can be assigned to a different axis via its Y axis field in the series settings. Click Add Y axis to add a new axis.

Each axis row shows the following columns:

Column	Description
Id	Unique identifier used to assign series to this axis.
Show	Toggle axis visibility on the chart.
Label	Text label shown next to the axis.
Position	Left or Right.
Min / Max	Fixed scale bounds. Set explicitly to match the range of your ticks values — for example, 0 to 1 for a two-state boolean.
Units	Unit suffix for axis tick labels.
Decimals	Decimal places for tick label values.

Click the settings icon on an axis row to open the Y axis settings dialog:

Setting	Description
Label	Text label with configurable font and color.
Tick labels	Show value labels on each tick. Configure font and color.
Show ticks	Render tick marks on the axis line.
Show line	Render the axis baseline.
Show split lines	Render horizontal grid lines across the chart for each tick.
Ticks interval	Interval between ticks. Auto derives it from the data range.
Split number	Suggested number of tick intervals. Auto lets the chart decide.

Controls the chart title displayed in the widget header.

Setting	Description
Title	Text shown in the widget header. Configure font, size, weight, and color. Toggle to hide the title entirely.
Card icon	Optional icon displayed next to the title.

Controls interactive behavior and chart area layout.

Setting	Description
Data zoom	Enable horizontal zoom for inspecting narrow time ranges without changing the dashboard time window.
Grid	Adjust padding inside the chart area.
Stack mode	Accumulate multiple series on the same axis, useful for showing overlapping state histories.

Configure the horizontal time axis. Use the Show toggle to hide the axis entirely.

Setting	Description
Label	Text label displayed along the axis. Configure font and color.
Position	Bottom or Top.
Tick labels	Show date/time labels on each tick. Configure date format, font, and color.
Show ticks	Render tick marks on the axis. Configure color.
Show line	Render the axis baseline. Configure color.
Show split lines	Render vertical grid lines across the chart for each tick.

Use the master toggle to show or hide the legend entirely.

Setting	Description
Position	Legend placement: Top, Bottom, Left, or Right.
Show values	Statistics displayed per series: Min, Max, Average, Total, Latest.
Label	Font and color for series name labels.
Value	Font and color for statistic values.
Column title	Font and color for the column header row (visible when Show values is enabled).
Sort datakeys in legend	Sort series entries alphabetically.

Use the master toggle to show or hide the tooltip entirely.

Setting	Description
Trigger	Point — hover over a data point; Axis — hover anywhere shows values for all series at that timestamp.
Date	Toggle to show the timestamp. Select the date format and configure font and color.
Show date time interval	Display the time interval range in the tooltip header.
Hide zero values	Suppress series entries with a value of zero from the tooltip.
Label	Font and color for series name labels in the tooltip.
Value	Font and color for value text in the tooltip.
Background color	Tooltip background fill color.
Background blur	Blur radius (px) applied to the tooltip background.

Use the master toggle to enable or disable chart animation. When enabled:

Setting	Description
Animation threshold	If the number of data points exceeds this value (default 2000), animation is disabled to maintain performance.
Animation duration	Duration of the initial load animation in milliseconds (default 500 ms).
Animation easing	Easing function for the initial animation, like cubicOut.
Animation delay	Delay before the initial animation starts, in milliseconds.
Update animation duration	Duration of the animation when data updates arrive (default 300 ms).
Update animation easing	Easing function for update animations.
Update animation delay	Delay before update animations start, in milliseconds.

Setting	Description
Background	Solid color or image background for the card.
Show card buttons	Enable Fullscreen and Data export toolbar buttons.
Card border radius	Corner rounding in pixels.
Card padding	Spacing between content and card border.

The State chart supports the Widget header button action — a button placed in the widget header that triggers a configured action when clicked.

Goal: Display a timeline showing when a Smart Device was connected and when it lost connection over the last day, using a boolean connected telemetry key.

Prerequisites: A device named Smart Device that sends a connected key with boolean values (true / false).

Step 1. Add the widget. Open your dashboard in edit mode, click Add widget, select the Charts bundle, then choose State chart.

Step 2. Configure the time window. Set Period to last 1 day. Leave Aggregation set to None.

Step 3. Configure the datasource. Set Datasource type to Device, then select Smart Device.

Step 4. Add a series. In the Series section, add one data key:

Key	Label	Y axis	Color	Decimals
connected	Device state	default	#2196F3	0

Open the series advanced settings and set Fill to Gradient, with start opacity 80 and end opacity 40.

Step 5. Configure states. In the States section, add two states:

Label	Ticks value	Source	Value type	Value
Inactive	0	Constant	Boolean	False
Active	1	Constant	Boolean	True

Step 6. Configure Y axes. Set the default axis:

ID	Label	Position	Min	Max	Decimals
default	Device state	Left	0	1	0

Step 7. Configure appearance. Disable the Title display. In the Legend section, disable the legend.

Step 8. Save. Click Add, resize and reposition as needed, then click Save on the dashboard toolbar.

Result: The chart shows a timeline of blue segments representing periods when the device was active (connected = true). Gaps in the segments indicate inactive periods. The Y axis labels show Inactive and Active instead of raw 0/1 values.

Widget shows no data

Cause	Solution
Wrong data key name	Confirm the key name matches the telemetry key sent by the device. Key names are case-sensitive.
Incorrect datasource or entity alias	Verify the correct Device or Entity alias is selected. Open Entity aliases to confirm the alias resolves to results.
Device not sending data	Open Devices → Latest telemetry and check for recent values. If empty, verify the device transport configuration and access token.
No telemetry in the selected time window	Extend the time range to confirm data exists.
Rule chain misconfiguration	Check that the Rule Chain has a Save time series node routing device telemetry to the database.
Datasource updated after import	After importing a widget, update the datasource to point to your device and update the data key name to match your device’s actual telemetry.

State labels do not appear on the Y axis

Cause	Solution
States not configured	Open the States section and verify that each expected state value has an entry with the correct Value type and Value.
Y axis Min/Max not set	Set Min and Max explicitly to cover the full range of your ticks values — for example, 0 to 1 for a boolean key.
Value type mismatch	Ensure the Value type in the States section matches the actual data type of the telemetry key (Boolean, String, Integer, etc.).

Chart shows a flat line instead of state segments

Cause	Solution
Aggregation enabled	Set Aggregation to None in the time window to show individual state transitions instead of averages.
Ticks values not distinct	Ensure each state has a unique Ticks value so the Y axis can separate them visually.