machineGroupControl/examples/README.md

# machineGroupControl - Example Flows

Import-ready Node-RED examples for `machineGroupControl` (MGC). MGC is not a standalone node — it needs at least one `rotatingMachine` child to dispatch demand to. Both flows below ship three child pumps.

## Files

| File | Tier | What it shows |
|---|---|---|
| `01-Basic.json` | 1 | One MGC + three `rotatingMachine` pumps driven by inject buttons. Setup once-fires `virtualControl` + `cmd.startup` on all three pumps; mode / scaling / demand are then driven by buttons. |
| `02-Dashboard.json` | 2 | Same command surface driven by a FlowFuse Dashboard 2.0 page — mode + scaling buttons, demand slider, live status rows, three trend charts, and a raw-output table. |

## Prerequisites

- Node-RED with the EVOLV package installed (`machineGroupControl` and `rotatingMachine` registered).
- For `02-Dashboard.json`: `@flowfuse/node-red-dashboard` (Dashboard 2.0).

## Load a flow

```bash
curl -X POST -H 'Content-Type: application/json' \
  --data @nodes/machineGroupControl/examples/01-Basic.json \
  http://localhost:1880/flows
```

Or in the editor: Menu → Import → drag the file → Import.

## Canonical command surface

| Topic | Aliases | Payload | What it does |
|---|---|---|---|
| `set.mode` | `setMode` | `"optimalControl"`, `"priorityControl"`, `"prioritypercentagecontrol"`, `"maintenance"` | Switch dispatch strategy |
| `set.scaling` | `setScaling` | `"normalized"`, `"absolute"` | Interpret demand as 0–100 % vs m³/h |
| `set.demand` | `Qd` | number | Operator demand setpoint |
| `child.register` | `registerChild` | child node id (string) | Manually register a child (Port 2 wiring does this automatically) |

## 01-Basic — what to try

1. Deploy. After ~1.5 s the Setup group auto-fires, putting all three pumps in `virtualControl` mode + sending `cmd.startup` to each.
2. Click `set.demand = 50 %` — MGC's `optimalControl` picks the best pump combination by BEP-gravitation and dispatches `flowmovement` to the selected pumps.
3. Click `set.demand = 100 %` — MGC switches to a higher combination, possibly engaging an extra pump.
4. Switch mode to `priorityControl` and try the same demands — pumps now run equal-flow by priority order.
5. Switch scaling to `absolute` — set.demand is now interpreted as m³/h (capped at the group min / max).
6. `set.demand = 0` — MGC calls `turnOffAllMachines`, all pumps shut down.

## 02-Dashboard — what to try

1. Deploy → open `http://localhost:1880/dashboard/mgc-basic`.
2. The dashboard auto-initialises the pumps; the `Initialize pumps` button on the page re-runs the setup manually.
3. Drag the **Demand** slider — MGC dispatches and the Flow / Power / BEP charts react.
4. Switch modes and scalings via the buttons; the Mode / Scaling rows in the Status panel reflect the change.
5. Inspect the **Raw output** table for the full Port 0 surface (every field MGC emits, including `flowCapacityMax`, `machineCountActive`, `absDistFromPeak`, `relDistFromPeak`).