Process / State Timeline Chart

Process / State Timeline Chart

Description:

Displays process, machine, or device status history as a Gantt-style timeline or a single merged bar, showing when each state was active, how long it lasted, and how states transitioned over time. Supports per-status colors, custom time formats, and CSV export — ideal for equipment run/idle/fault tracking and process audit trails.

---

Who it’s for

Built for process engineers, plant operators, and maintenance teams who need to see when a machine or process was in each state, not just its current value — answering questions like “how long was line 3 in fault state this shift?”, “show me a Gantt chart of my device’s status history”, or “what does my equipment’s uptime/downtime timeline look like today?”

What it does

The widget reads a single time-series telemetry key whose values represent discrete states (e.g. running, idle, fault, or any string/number/boolean value) and renders it as an interactive ECharts timeline with two display modes:

• Gantt mode — one row per unique status value across the selected data key; every time the value changes, a new colored segment is drawn on the corresponding row, from when that status started to when it ended (or to “now” for the currently active status).
• Stacked mode — all status segments drawn on a single merged row, useful when you just want one compact timeline strip rather than a full per-status breakdown. Hovering any segment shows the status name, its exact start/end time, and duration. The legend lists each status with its total accumulated duration over the visible window. Colors are configurable per status name (case-insensitive match); any status without an explicit color gets a consistent auto-generated color so nothing renders as a default gray block. The widget also exposes a CSV/data export of every rendered segment (status, start, end, duration).

How Telemetry Values are Interpreted & Mapped

The widget dynamically processes telemetry values (string, boolean, or numeric) and renders them across the chart, legend, tooltips, and data exports.

You can configure value interpretation in two ways.

1. Direct Mapping via Widget Settings (Recommended)

Under Widget Settings → Chart colors → Process statuses colors, you can map raw telemetry values directly to human-readable labels and assign custom colors:

• Value: Enter the raw telemetry value received from the device (e.g., 3, true, or "0").
• Label: Enter the custom display name (e.g., Rolling, Active, Idle).
• Status color: Select the custom color for this status bar.

Note: If a Label is provided, the widget automatically translates all occurrences of that raw value into the configured label across the Gantt Y-axis, legend, tooltips, and exported files. If left empty, the raw value is displayed as-is.

Mapping Example

Raw Telemetry (Value)	Configured Label	Chart Display Name
3	Rolling	Rolling
4	Cooling	Cooling
Heating	(empty)	Heating

2. Default String Values & Data Key Post-Processing

• String Telemetry: If your telemetry key already contains human-readable string values (e.g., "Heating", "Cooling"), the widget displays them as-is without requiring extra configuration.
• Data Key Post-processing Function: Alternatively, you can use the Data Key’s native Post-processing function in ThingsBoard to map raw codes prior to widget rendering (e.g., if (value === 0) return 'Idle';).

---

If the ECharts library isn’t loaded, the widget shows a clear inline message rather than failing silently, telling you to add the CDN resource under the widget’s Resources tab.

How to set up

1. Add the widget to a dashboard and assign it a single time-series data key whose values represent a status/state (string, number, or boolean all work).
2. Drop it in — it works with defaults immediately: Gantt-style rows, default color-coded statuses, standard date/time formatting in tooltips and axis labels.
3. Resize as needed; the chart reflows to fit the widget’s width and height, and respects the dashboard’s time window.

⚠️ Important — timewindow aggregation must be set to “None.” In the dashboard’s timepicker, leave the aggregation function as None for this data key. The widget needs the raw, unaggregated sequence of status values with their exact timestamps to build the timeline — if any other aggregation (Average, Min, Max, etc.) is applied, the underlying values are collapsed into numbers that no longer represent discrete statuses, and the widget will display nothing.

How to customize

• To switch between one-row-per-status and a single merged timeline — change Display mode (General group) between “Gantt” and “Stacked.”
• To change how times are displayed in the axis and tooltip — set Time format (General group).
• To make bars thicker or thinner — adjust Bar height ratio (General group, 0.1–1.0).
• To hide the legend — turn off Show legend (General group).
• To assign specific colors to specific statuses (e.g. red for “fault”, green for “running”) — add entries under Process statuses colors (Chart colors group), matching the exact status names in your telemetry (matching is case-insensitive).
• To restyle axis labels — use the Y-axis style and X-axis style groups (font, color, and for the y-axis, label rotation angle).
• To restyle the tooltip — use Tooltip & legend style (separate font controls for the status name vs. the time/duration line, plus text color).