Registry / web-framework / node-red-contrib-ui-state-trail

node-red-contrib-ui-state-trail

library1.0.2jsnpmunverified

node-red-contrib-ui-state-trail is a Node-RED dashboard UI node that renders a Gantt-type chart to visualize the historical changes of a state over a configurable time period. It is designed for displaying single-line state timelines, such as the operational status (on/off, running/stopped) of a device or process. The current stable version is 1.0.2. As a Node-RED contrib node, it typically receives updates on an as-needed basis rather than a strict release cadence, focusing on stability and new features. Key differentiators include its ability to accept both simple and timestamped historical data, customizable legend display (showing all states, current states, or latest state), state aggregation for performance, and optional persistent data storage when Node-RED's context storage is properly configured. It supports string, number, and boolean state types, which are treated distinctly.

web-framework data observability

npm install node-red-contrib-ui-state-trail

github ↗package ↗

INSTALL

IMPORT

SIG · NODE-RED-CONTRIB-U

node-red-contrib-ui-state-trail

web-frameworkjavascriptv1.0.2

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

msg.payload (simple state)

✓ msg.payload = true; // or 'running', 1

✗ msg.payload = { value: true };

For current state updates, send the raw state value directly in `msg.payload`. The type (boolean, string, number) must match configured states.

msg.payload (historical state)

✓ msg.payload = { state: 'on', timestamp: Date.now() };

✗ msg.payload = { value: 'on', time: Date.now() };

To input historical data, `msg.payload` must be an object with `state` and `timestamp` (milliseconds since epoch). An array of such objects is also supported.

msg.control (period override)

✓ msg.control = { period: 300000 }; // 5 minutes

✗ msg.control = { period_ms: 300000 };

The chart's display period can be dynamically overridden by sending `msg.control` with a `period` property in milliseconds.

This Node-RED flow demonstrates sending a simple current state, an array of historical states, and a control message to dynamically change the chart's display period for the 'State Trail' UI node. Replace `flow_id` and `dashboard_group` with actual IDs from your Node-RED instance.

[ { "id": "inject_current_state", "type": "inject", "name": "Send 'running'", "topic": "", "payload": "running", "payloadType": "str", "repeat": "5", "crontab": "", "once": false, "onceDelay": 0.1, "x": 160, "y": 100, "wires": [ ["state_trail_node"] ] }, { "id": "inject_historical_data", "type": "inject", "name": "Send Historical Data", "topic": "", "payload": "[ {state: \"stopped\", timestamp: Date.now() - 3600000}, {state: \"running\", timestamp: Date.now() - 1800000}, {state: \"error\", timestamp: Date.now() - 600000} ]", "payloadType": "json_ata", "repeat": "", "crontab": "", "once": true, "onceDelay": 1, "x": 190, "y": 160, "wires": [ ["state_trail_node"] ] }, { "id": "inject_control_period", "type": "inject", "name": "Set Period to 10 min", "topic": "", "payload": "{\"period\":600000}", "payloadType": "json", "repeat": "", "crontab": "", "once": true, "onceDelay": 2, "x": 190, "y": 220, "wires": [ ["state_trail_node"] ] }, { "id": "state_trail_node", "type": "ui_state_trail", "z": "flow_id", // Replace with your flow ID "group": "dashboard_group", // Replace with your dashboard group ID "name": "My State Trail", "label": "Process State", "order": 0, "width": 0, "height": 2, "period": 3600000, // Default to 1 hour "period_unit": "hour", "combine": true, "states": [ { "state": "running", "label": "Running" }, { "state": "stopped", "label": "Stopped" }, { "state": "error", "label": "Error" }, { "state": true, "label": "Active" }, { "state": false, "label": "Inactive" } ], "legend": 0, "ticks": 6, "x": 450, "y": 100, "wires": [] } ]

Debug

Known issues

gotchaPerformance can significantly degrade with long periods and high input rates, especially on lower-end hardware, due to the volume of data needing to be rendered. Use the 'combine similar states' option to mitigate this.

fix

Keep the input rate low for long periods, or configure shorter display periods. Ensure the 'Combine similar states' option is enabled in the node's configuration if individual state instances are not critical for analysis.

affects: >=1.0.0

gotchaChart data will be lost on Node-RED redeploy, restart, or system reboot unless persistent context storage is explicitly configured in Node-RED's `settings.js` file AND the 'Data Storage' option is enabled in the node's configuration.

fix

To retain data, enable 'Data Storage' in the node properties and follow Node-RED documentation to configure a persistent context store (e.g., file-based) in `settings.js`.

affects: >=1.0.0

gotchaBoolean states (`true`, `false`) and string states (`"true"`, `"false"`) are treated as distinct values. Mixing types for what appears to be the 'same' state will result in separate entries on the chart and in the legend.

fix

Ensure consistency in state types. If you intend `true` and `"true"` to represent the same state, standardize on one type or configure both with identical labels.

affects: >=1.0.0

gotchaThe legend and labels configured for the widget will not be visible on the dashboard if the widget's height is set to less than 2 units in the Node-RED Dashboard layout.

fix

Increase the widget height to at least 2 units in the Node-RED Dashboard UI tab to display the label and legend correctly.

affects: >=1.0.0

gotchaWhen feeding an array of historical data (`msg.payload = [...]`), the previous set of data in the chart is cleared and replaced by the new array. This is intentional for batch updates but can be unexpected if continuous appending is desired.

fix

If continuous appending of historical data is needed, send individual historical state messages one by one rather than large arrays, or manage the data set externally before sending the complete array.

affects: >=1.0.0

Errors

Common errors & fixes

Chart data disappears after Node-RED restart or full redeploy.

Persistent context storage is not enabled or configured incorrectly.

fix

Go to Node-RED `settings.js`, configure a persistent context storage (e.g., `localfilesystem`), and ensure the 'Data Storage' checkbox is selected in the State Trail node's properties.

Chart performance is slow, or the dashboard becomes unresponsive when viewing the State Trail.

Too much data is being fed to the node over a long configured period, overwhelming rendering capabilities.

fix

Reduce the `Period` setting in the node's configuration, lower the frequency of input messages, or ensure the 'Combine similar states' option is checked to reduce data points.

The chart legend or node label is not displayed on the Node-RED dashboard.

The UI widget's height is set too low in the dashboard layout.

fix

Edit the Node-RED Dashboard layout, find the State Trail node, and increase its 'Height' property to at least 2 units.

States like 'true' and "true" are shown as different entries on the chart or in the legend.

The node differentiates between data types (boolean, string, number).

fix

Standardize the data type for your states (e.g., always send `true` boolean or always send `"true"` string) or configure both `true` and `"true"` as distinct states with appropriate labels in the node's configuration.

Upgrade

Version history

1.0.2latest on npm

Audit

Dependencies

node-redrequiredRequired for the Node-RED runtime environment.

node-red-dashboardrequiredProvides the dashboard framework for the UI widget.

Agent activity

15 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/hotNipi/node-red-contrib-ui-state-trail ↗

packagehttps://www.npmjs.com/package/node-red-contrib-ui-state-trail ↗