EVOLV/wiki/manuals/node-red/flowfuse-ui-chart-manual.md

FlowFuse ui-chart Manual (EVOLV Reference)

Source: https://dashboard.flowfuse.com/nodes/widgets/ui-chart.html

Chart Types

Type	X-Axis Options	Notes
Line	timescale, linear, categorical	Interpolation: linear, step, bezier, cubic, cubic-mono
Bar	categorical	Grouped (side-by-side) or stacked
Scatter	timescale, linear, categorical	Configurable point shape & radius
Pie / Doughnut	radial	Nested series for multi-layer
Histogram	auto-binned	Numerical bins or categorical counting

Properties

Property	Type	Dynamic	Notes
group	ref	No	Parent ui-group
width	int	No	Columns
height	int	No	Row units
label	string	No	Chart title
chartType	string	No	"line", "bar", "scatter", "pie", "histogram"
showLegend	bool	No	Show series legend
action	string	Yes	"append" or "replace"
pointShape	string	No	Point marker shape (scatter/line)
xAxisLimit	int	No	Max data points to keep
textColor	color	No	Override text color
gridColor	color	No	Override grid lines
xAxisType	string	No	"time", "linear", "category"

Series Configuration

Source	How It Works
msg.topic	Default — each unique topic creates a series
key	Uses a named property from data object
JSON	Array of keys for multi-series from single msg
(blank)	Auto-generates timestamp for x

Input Format

Simple (recommended for EVOLV)

{ topic: "PS West Level", payload: 2.34, timestamp: Date.now() }

Object with x/y mapping

{ payload: { time: 1700000000000, value: 2.34 } }
// Configure x → "time", y → "value"

Nested access

X/Y keys support dot notation: "nested.value" → payload.nested.value

Dynamic Properties

Property	Path	Notes
Action	msg.action	"append" or "replace"
Chart Options	msg.ui_update.chartOptions	eCharts config merge
CSS Class	msg.class	Add custom class

eCharts Customization (msg.ui_update.chartOptions)

Deep-merges with existing config. Accumulates across messages.

msg.ui_update = {
  chartOptions: {
    yAxis: { position: "right", name: "Level (m)" },
    grid: { top: 60, right: 40 },
    title: { text: "Basin Levels", textStyle: { fontSize: 14 } }
  }
};

Series colors — must provide all series configs together:

msg.ui_update = {
  chartOptions: {
    series: [
      { name: "PS West", type: "line", lineStyle: { color: "#2196f3" }, itemStyle: { color: "#2196f3" } },
      { name: "PS North", type: "line", lineStyle: { color: "#ff9800" }, itemStyle: { color: "#ff9800" } }
    ]
  }
};

Data Actions

Action	How	Effect
Append	msg.action = "append" (default)	Add points to existing data
Replace	msg.action = "replace"	Clear then add
Clear	msg.payload = []	Remove all data

Time Formatting Tokens

{HH}:{mm}:{ss} → 12:00:00 {yyyy}-{M}-{d} → 2020-1-1 Tokens: {yyyy}, {MM}, {dd}, {HH}, {H}, {hh}, {h}, {mm}, {m}, {ss}, {s}, {eeee} (day name)

EVOLV Key Rules

1. Send minimal { topic, payload, timestamp } — chart auto-uses topic for series.
2. Set category: "topic", categoryType: "msg" in node config — blank category causes editor validation errors.
3. For timeseries: leave x-key blank → auto-timestamp. Supply ms timestamps if custom.
4. For multi-station overlay charts: each station sends with a different msg.topic.
5. Use msg.action = "append" (default) for streaming data; "replace" for snapshot updates.
6. Keep one topic per chart for simple KPIs; use multi-topic for comparison views.
7. Prefer explicit output-slot routing: node.send([msgForChart, msgForText, ...]); return null;

Common Failure Modes

• Payload is not numeric (string/object without y-key config)
• Function node returns to wrong output index
• Topic churn creates unexpected series fragmentation
• Chart has stale data policy mismatch (append vs replace)
• Blank category field causes red node on deploy