Process / State Timeline Chart

Who it’s for

Process engineers, plant operators, and maintenance teams use this widget when a single current value isn’t enough — they need to see when a machine or process was in each state and how long it stayed there. They ask questions like “how long was line 3 in a fault state this shift?” while reviewing a shift report, or “what does today’s uptime and downtime timeline look like?” while investigating a stoppage.

What it does

A conveyor line reporting running from 06:00 to 07:42, then fault for 12 minutes, then running again appears as three colored segments on the conveyor’s row. Hovering the fault segment shows its exact start, end, and 12-minute duration, and the legend shows the total fault time accumulated across the whole shift.

• Gantt mode draws one row per status, so every state change on that row is visible at a glance.
• Stacked mode merges every segment onto a single row, for a compact strip rather than a full breakdown.
• Hovering any segment shows the status name, its exact start and end time, and its duration.
• The legend totals each status’s accumulated time over the visible window.
• Colors are consistent: assign your own per status, or let the widget generate one automatically so nothing renders as plain gray.
• Every rendered segment — status, start, end, duration — can be exported as CSV for a shift report or an audit trail.
• Shows the history of one status key; it does not compute uptime percentages or compare several devices side by side.

Requirements

The timeline renders with the ECharts library, loaded from a CDN resource rather than bundled with the widget. If the library isn’t loaded, the widget shows a message telling you so instead of failing silently. Add the ECharts CDN resource under the widget’s Resources tab before using it on a dashboard.

How to set up

Data keys

Key	Role	Type	Description
Status key (user-configured)	Status value	Timeseries	String, number, or boolean representing a discrete state (e.g. running, idle, fault) rather than a continuous measurement

Set this data key’s timewindow aggregation to None. Any other aggregation (Average, Min, Max, etc.) collapses the raw sequence of states into numbers that no longer represent discrete statuses, and the widget renders nothing.

Process statuses

Setting	Default	Effect
Label (under Process statuses colors)	Empty — raw value shown as-is	Renames a raw telemetry value everywhere it appears: the row name, the legend, the tooltip, and the CSV export

See “How status values become labels” below for the full mapping example and two alternative ways to get readable status names.

How to customize

Layout and timing

• To switch between one row per status and a single merged timeline — change Display mode (General) between Gantt and Stacked.
• To change how times are shown in the axis and tooltip — set Time format (General).
• To make bars thicker or thinner — adjust Bar height ratio (General, 0.1–1.0).
• To hide the legend — turn off Show legend (General).

Colors and text

• To color specific statuses (e.g. red for “fault”, green for “running”) — add entries under Process statuses colors (Chart colors), matching the status name in your telemetry; matching is case-insensitive.
• To restyle axis labels — use Y-axis style and X-axis style (font, color, and, for the y-axis, label rotation).
• To restyle the tooltip — use Tooltip & legend style (separate font controls for the status name and the time/duration line, plus text color).

How status values become labels

Raw telemetry doesn’t have to be readable on its own. The widget interprets it in one of three ways.

The recommended way is a direct mapping under Widget settings → Chart colors → Process statuses colors. Enter the raw value the device sends, a label to show instead, and a color. A device reporting 3 and 4 for two of its states can map them to readable names:

Raw value	Label	Chart display
3	Rolling	Rolling
4	Cooling	Cooling
Heating	(empty)	Heating

Leaving Label empty, as with Heating above, shows the raw value as-is — useful when the telemetry is already readable.

If your telemetry key already sends readable strings like "Heating" or "Cooling", no mapping is needed at all; the widget shows them directly.

A third option is to convert the values before they reach the widget, using the data key’s own Post-processing function in ThingsBoard — for example, if (value === 0) return 'Idle';. This keeps the mapping with the data key rather than the widget, which is useful when several widgets read the same key.

Tips

• Keep Process statuses colors entries matched to your exact telemetry values (or their labels) — an unmatched status still renders, but with an auto-generated color instead of the one you picked.
• If the chart appears empty, check the datasource’s aggregation first — it is the most common cause, and it must be set to None.