48f790d123
Some checks failed
CI / lint-and-test (push) Has been cancelled
Move content to correct locations: - AGENTS.md → .agents/AGENTS.md (with orchestrator reference update) - third_party/docs/ (8 reference docs) → wiki/concepts/ - manuals/ (12 Node-RED docs) → wiki/manuals/ Delete 23 unreferenced one-off scripts from scripts/ (keeping 5 active). Delete stale Dockerfile.e2e, docker-compose.e2e.yml, test/e2e/. Remove empty third_party/ directory. Root is now: README, CLAUDE.md, LICENSE, package.json, Makefile, Dockerfile, docker-compose.yml, docker/, scripts/ (5), nodes/, wiki/, plus dotfiles (.agents, .claude, .gitea). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
122 lines
4.2 KiB
Markdown
122 lines
4.2 KiB
Markdown
# 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)
|
|
```js
|
|
{ topic: "PS West Level", payload: 2.34, timestamp: Date.now() }
|
|
```
|
|
|
|
### Object with x/y mapping
|
|
```js
|
|
{ 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.
|
|
|
|
```js
|
|
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:
|
|
```js
|
|
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
|