refactor: regenerate Home.md with 14-section visual-first template

2026-05-11 18:30:14 +00:00
parent f8c9ad74fa
commit 7f72a0490e
1 changed files with 348 additions and 0 deletions
--- a/Home.md
+++ b/Home.md
@@ -0,0 +1,348 @@
+# rotatingMachine
+
+> **Reflects code as of `afc304b` · regenerated `2026-05-11` via `npm run wiki:all`**
+> If this banner is stale, the page may be out of date. Treat as informative, not authoritative.
+
+## 1. What this node is
+
+**rotatingMachine** models a single pump, compressor, or blower. It loads a supplier characteristic curve, takes upstream + downstream pressure measurements (or simulated values), predicts the resulting flow + power, drives a startup/shutdown state machine, and assesses prediction drift against measured flow / power. Used as a child of `machineGroupControl` when grouped, or directly under a `pumpingStation`.
+
+## 2. Position in the platform
+
+```mermaid
+flowchart LR
+    parent[machineGroupControl /<br/>pumpingStation]:::unit -->|flowmovement<br/>execsequence| rm[rotatingMachine<br/>Equipment]:::equip
+    m_up[measurement<br/>pressure upstream]:::ctrl -.data.-> rm
+    m_dn[measurement<br/>pressure downstream]:::ctrl -.data.-> rm
+    sim[dashboard-sim<br/>virtual pressure children]:::ctrl -.data.-> rm
+    rm -->|child.register| parent
+    rm -.->|flow.predicted.*<br/>power.predicted.atequipment| parent
+    classDef unit fill:#50a8d9,color:#000
+    classDef equip fill:#86bbdd,color:#000
+    classDef ctrl fill:#a9daee,color:#000
+```
+
+S88 colours: Unit `#50a8d9`, Equipment `#86bbdd`, Control Module `#a9daee`. Source of truth: `.claude/rules/node-red-flow-layout.md`.
+
+## 3. Capability matrix
+
+| Capability | Status | Notes |
+|---|---|---|
+| Curve-based flow prediction | ✅ | Built from `asset.model` via `curves/curveLoader`. |
+| Curve-based power prediction | ✅ | Reverse curve composed inside `buildPredictors`. |
+| FSM (startup / shutdown / movement) | ✅ | Shared `state/state.js` from generalFunctions. |
+| Interruptible movements | ✅ | `abortMovement` from MGC overrides on new demand. |
+| Drift assessment (flow + power) | ✅ | `DriftAssessor` with EWMA + alignment tolerance. |
+| Virtual pressure children for sim | ✅ | `dashboard-sim-upstream / -downstream`. |
+| Real-pressure child preference | ✅ | `pressureSelector` prefers real over virtual. |
+| Group operating-point prediction | ✅ | `setGroupOperatingPoint` for MGC integration. |
+| `cmd.estop` hard cut | ✅ | Forces `emergencystop` state. |
+| `data.simulate-measurement` injection | ✅ | Pressure / flow / power / temperature. |
+| Auto-recovery from prediction loss | ⚠️ | Reverts to null predictors silently — health falls to `invalid`. |
+| Multi-parent registration | ⚠️ | Accepted but not exercised in production. |
+
+## 4. Code map
+
+```mermaid
+flowchart TB
+    subgraph nodeRED["nodeClass.js — adapter (BaseNodeAdapter)"]
+        nc["buildDomainConfig()<br/>static DomainClass, commands"]
+    end
+    subgraph domain["specificClass.js — orchestrator (BaseDomain)"]
+        sc["Machine.configure()<br/>_setupCurves / _setupState /<br/>_setupDrift / _setupPressure /<br/>_setupChildren"]
+    end
+    subgraph concerns["src/ concern modules"]
+        curves["curves/<br/>loadModelCurve + normalize"]
+        prediction["prediction/<br/>buildPredictors + math"]
+        drift["drift/<br/>DriftAssessor + healthRefresh"]
+        pressure["pressure/<br/>init + router + selector + virtual"]
+        state["state/<br/>FSM bindings + sequenceController"]
+        measurement["measurement/<br/>handlers + childRegistrar"]
+        flow["flow/<br/>flowController (handleInput)"]
+        display["display/<br/>workingCurves + CoG"]
+        io["io/<br/>output + status"]
+        commands["commands/<br/>topic registry + handlers"]
+    end
+    nc --> sc
+    sc --> curves
+    sc --> prediction
+    sc --> drift
+    sc --> pressure
+    sc --> state
+    sc --> measurement
+    sc --> flow
+    sc --> display
+    sc --> io
+    nc --> commands
+```
+
+| Module | Owns | Read first if you're changing… |
+|---|---|---|
+| `curves/` | Supplier curve loader + normaliser + reverse | Curve fitting, unit mismatches, fallback. |
+| `prediction/` | Per-machine + group predictors, math helpers | Predicted flow / power values. |
+| `drift/` | DriftAssessor (EWMA, alignment), healthRefresh | Prediction quality, flags, confidence. |
+| `pressure/` | init + router + selector + virtual children | Pressure plumbing, sim vs real preference. |
+| `state/` | FSM bindings + setpoint / sequence orchestration | Startup / shutdown sequences. |
+| `measurement/` | Measurement handlers + child registrar | Measured value plumbing per type. |
+| `flow/` | `flowController.handle(source, action, parameter)` | Top-level input dispatch. |
+| `display/` | `showWorkingCurves`, `showCoG` | `query.curves` / `query.cog` outputs. |
+| `io/` | `getOutput`, `getStatusBadge` | Output shape, badge text. |
+| `commands/` | Input-topic registry and handlers | New input topics, payload validation. |
+
+## 5. Topic contract
+
+> **Auto-generated** from `src/commands/index.js`. Do NOT hand-edit between the markers. Re-run `npm run wiki:contract`.
+
+<!-- BEGIN AUTOGEN: topic-contract -->
+
+| Canonical topic | Aliases | Payload | Unit | Effect |
+|---|---|---|---|---|
+| `set.mode` | `setMode` | `string` | — | Switch the machine between auto / manual control modes. |
+| `cmd.startup` | _(none)_ | `any` | — | Initiate the machine startup sequence. |
+| `cmd.shutdown` | _(none)_ | `any` | — | Initiate the machine shutdown sequence. |
+| `cmd.estop` | `emergencystop` | `any` | — | Trigger an emergency stop. |
+| `execSequence` | _(none)_ | `object` | — | Legacy umbrella that demuxes payload.action to startup / shutdown. |
+| `set.setpoint` | `execMovement` | `object` | — | Move the machine to a control-% setpoint via execMovement. |
+| `set.flow-setpoint` | `flowMovement` | `object` | `volumeFlowRate` (default `m3/h`) | Move the machine to a flow setpoint via flowMovement. |
+| `data.simulate-measurement` | `simulateMeasurement` | `object` | — | Inject a simulated sensor reading (pressure/flow/temperature/power). |
+| `query.curves` | `showWorkingCurves` | `any` | — | Return the working curves for the machine on the reply port. |
+| `query.cog` | `CoG` | `any` | — | Return the centre-of-gravity (CoG) point on the reply port. |
+| `child.register` | `registerChild` | `string` | — | Register a child measurement with this machine. |
+
+<!-- END AUTOGEN: topic-contract -->
+
+## 6. Child registration
+
+`measurement` children register through `childRegistrationUtils`; the machine subscribes to the matching `<asset.type>.measured.<positionVsParent>` event.
+
+```mermaid
+flowchart LR
+    subgraph kids["accepted children (softwareType)"]
+        m_pu["measurement<br/>type=pressure<br/>position=upstream"]:::ctrl
+        m_pd["measurement<br/>type=pressure<br/>position=downstream"]:::ctrl
+        m_f["measurement<br/>type=flow"]:::ctrl
+        m_pw["measurement<br/>type=power"]:::ctrl
+        m_t["measurement<br/>type=temperature"]:::ctrl
+    end
+    m_pu -->|pressure.measured.upstream| router[pressureRouter.route]
+    m_pd -->|pressure.measured.downstream| router
+    m_f  -->|flow.measured.<pos>| mh[measurementHandlers]
+    m_pw -->|power.measured.atequipment| mh
+    m_t  -->|temperature.measured.<pos>| mh
+    router --> upd[updatePosition + drift refresh]
+    mh --> upd
+    classDef ctrl fill:#a9daee,color:#000
+```
+
+| softwareType | filter | wired to | side-effect |
+|---|---|---|---|
+| `measurement` | `type=pressure, position=upstream` | `pressureRouter.route('upstream', ...)` | Sets upstream pressure; refresh prediction + drift. |
+| `measurement` | `type=pressure, position=downstream` | `pressureRouter.route('downstream', ...)` | Sets downstream pressure; refresh prediction + drift. |
+| `measurement` | `type=flow, position=*` | `measurementHandlers.updateMeasuredFlow` | Stored; drift assessed against predicted. |
+| `measurement` | `type=power, position=atEquipment` | `measurementHandlers.updateMeasuredPower` | Stored; drift assessed against predicted. |
+| `measurement` | `type=temperature, position=*` | `measurementHandlers.updateMeasuredTemperature` | Stored; used by power correction if relevant. |
+
+Two **virtual children** are auto-registered at startup: `dashboard-sim-upstream` and `dashboard-sim-downstream`. `data.simulate-measurement` payloads land on these. Real pressure children, when registered, are preferred over the virtuals by `pressureSelector`.
+
+## 7. Lifecycle — what one event does
+
+```mermaid
+sequenceDiagram
+    participant parent as MGC / pumpingStation
+    participant rm as rotatingMachine
+    participant fsm as state FSM
+    participant pred as predictors
+    participant out as Port-0 output
+
+    parent->>rm: flowmovement (Q)
+    rm->>rm: flowController.handle('parent', 'flowmovement', Q)
+    rm->>fsm: setpoint(Q) → maybe transitionToState('accelerating')
+    Note over fsm: state.emitter 'positionChange' per tick
+    fsm-->>rm: positionChange → updatePosition()
+    rm->>pred: calcFlowPower(x) → cFlow, cPower
+    rm->>rm: calcEfficiency / cog / distance-BEP
+    rm->>rm: drift refresh on every measured tick
+    rm->>out: msg{topic, payload} (delta-compressed)
+    parent->>rm: execsequence ('startup' | 'shutdown')
+    rm->>fsm: transitionToState('starting' | 'stopping')
+    fsm-->>rm: stateChange → _updateState()
+```
+
+## 8. Data model — `getOutput()`
+
+Composed in `io/output.js → buildOutput(this)`, then delta-compressed.
+
+<!-- BEGIN AUTOGEN: data-model -->
+
+| Key | Type | Unit | Sample |
+|---|---|---|---|
+| `NCog` | number | — | `0` |
+| `NCogPercent` | number | — | `0` |
+| `atmPressure.measured.atequipment.wikigen-rotatingmachine-id` | number | — | `101325` |
+| `cog` | number | — | `0` |
+| `ctrl` | number | — | `0` |
+| `effDistFromPeak` | number | — | `0` |
+| `effRelDistFromPeak` | number | — | `0` |
+| `flow.predicted.max.wikigen-rotatingmachine-id` | number | m3/s | `0` |
+| `flow.predicted.min.wikigen-rotatingmachine-id` | number | m3/s | `0` |
+| `maintenanceTime` | number | — | `0` |
+| `mode` | string | — | `"auto"` |
+| `moveTimeleft` | number | — | `0` |
+| `predictionConfidence` | number | — | `0` |
+| `predictionFlags` | array | — | `[…]` |
+| `predictionPressureSource` | null | — | `null` |
+| `predictionQuality` | string | — | `"invalid"` |
+| `pressureDriftFlags` | array | — | `[…]` |
+| `pressureDriftLevel` | number | — | `0` |
+| `pressureDriftSource` | null | — | `null` |
+| `runtime` | number | — | `0` |
+| `state` | string | — | `"idle"` |
+| `temperature.measured.atequipment.wikigen-rotatingmachine-id` | number | K | `15` |
+
+<!-- END AUTOGEN: data-model -->
+
+**Concrete sample** (live, from a known-good test run — pump warming up with simulated upstream/downstream pressure):
+
+~~~json
+{
+  "state": "warmingup",
+  "flow.predicted.downstream.default":     0.00345,
+  "flow.predicted.atequipment.default":    0.00345,
+  "power.predicted.atequipment.default":   1820,
+  "pressure.measured.upstream.dashboard-sim-upstream":     101325,
+  "pressure.measured.downstream.dashboard-sim-downstream": 145000,
+  "temperature.measured.atequipment.default": 15,
+  "atmPressure.measured.atequipment.default": 101325,
+  "predictionHealth": {
+    "quality": "warming",
+    "confidence": 0.35,
+    "pressureSource": "dashboard-sim",
+    "flags": ["pressure_init_warming"]
+  },
+  "cog": 0.62, "NCog": 0.71,
+  "absDistFromPeak": 0.04, "relDistFromPeak": 0.12
+}
+~~~
+
+Position labels are normalised to lowercase in MeasurementContainer keys (`atequipment`, `downstream`, `upstream`, `max`, `min`). The trailing `<childId>` segment is the registering child's id (or `default` for own predictions / virtuals tagged via `dashboard-sim-*`).
+
+## 9. Configuration — editor form ↔ config keys
+
+```mermaid
+flowchart TB
+    subgraph editor["Node-RED editor form"]
+        f1[Asset model dropdown]
+        f2[Mode current]
+        f3[Position vs parent]
+        f4[State times: starting, warmingup, ...]
+        f5[Movement mode + speed]
+        f6[Position min / max / initial]
+        f7[Allowed sources / actions per mode]
+        f8[Output unit (flow, pressure, power)]
+    end
+    subgraph cfg["Domain config slice"]
+        c1[asset.model]
+        c2[mode.current]
+        c3[functionality.positionVsParent]
+        c4[time.starting / warmingup / stopping / coolingdown]
+        c5[movement.mode / speed / maxSpeed / interval]
+        c6[position.min / max / initial]
+        c7[mode.allowedSources / allowedActions]
+        c8[general.unit / asset.unit]
+    end
+    f1 --> c1
+    f2 --> c2
+    f3 --> c3
+    f4 --> c4
+    f5 --> c5
+    f6 --> c6
+    f7 --> c7
+    f8 --> c8
+```
+
+| Form field | Config key | Default | Range | Where used |
+|---|---|---|---|---|
+| Asset model | `asset.model` | `Unknown` | string (must resolve in curve loader) | `_setupCurves` |
+| Mode | `mode.current` | `auto` | enum (`auto`, `manual`) | `flowController.handle` source check |
+| Position vs parent | `functionality.positionVsParent` | `atEquipment` | enum | child-register payload + event suffix |
+| State time — starting | `time.starting` | `10` (s) | ≥ 0 | FSM timing |
+| State time — warmingup | `time.warmingup` | `5` (s) | ≥ 0 | FSM timing |
+| State time — stopping | `time.stopping` | `5` (s) | ≥ 0 | FSM timing |
+| State time — coolingdown | `time.coolingdown` | `10` (s) | ≥ 0 | FSM timing |
+| Movement mode | `movement.mode` | `dynspeed` | enum (`staticspeed`, `dynspeed`) | position trajectory |
+| Movement speed | `movement.speed` | `1` | ≤ `maxSpeed` | trajectory rate |
+| Position min/max | `position.min` / `position.max` | `0` / `100` | numeric | setpoint clamp |
+| Output unit (flow) | `general.unit` | `l/s` | unit string | unit policy `output.flow` |
+
+## 10. State chart
+
+The FSM is the canonical state set declared in `generalFunctions/src/state/stateConfig.json`. `emergencystop` is reachable from *every* state. Allowed transitions per `stateConfig.allowedTransitions`.
+
+```mermaid
+stateDiagram-v2
+    [*] --> idle
+    idle --> starting: execsequence(startup)
+    idle --> off: off
+    idle --> maintenance: maintenance
+    starting --> warmingup: timer
+    warmingup --> operational: timer
+    operational --> accelerating: flowmovement / setpoint up
+    operational --> decelerating: flowmovement / setpoint down
+    accelerating --> operational: target reached
+    decelerating --> operational: target reached
+    operational --> stopping: execsequence(shutdown)
+    stopping --> coolingdown: timer
+    stopping --> idle: timer
+    coolingdown --> idle: timer
+    coolingdown --> off: off
+    off --> idle: execsequence(startup)
+    off --> maintenance: maintenance
+    maintenance --> idle: maintenance done
+    maintenance --> off: off
+
+    note right of operational
+        any state -> emergencystop
+        via cmd.estop
+    end note
+```
+
+`accelerating` / `decelerating` are abortable on new demand via `abortMovement(reason)`; the controller does **not** auto-transition back to `operational` after an abort (see `state.js` comment "Abort path"). `warmingup` and `coolingdown` are **protected** — abort signals are dropped for safety. `activeStates = { operational, starting, warmingup, accelerating, decelerating }` is the set MGC treats as "machine alive".
+
+## 11. Examples
+
+| Tier | File | What it shows | Status |
+|---|---|---|---|
+| Basic | `examples/01 - Basic Manual Control.json` | Inject + dashboard, simulated pressure, manual startup/shutdown | ✅ validated |
+| Integration | `examples/02 - Integration with Machine Group.json` | rotatingMachine wired under MGC | ⏳ pending validation |
+| Dashboard | `examples/03 - Dashboard Visualization.json` | FlowFuse charts: flow / power / pressure trends | ✅ in repo |
+| Legacy | `examples/basic.flow.json` / `integration.flow.json` / `edge.flow.json` | Pre-refactor flows | ⚠️ kept until new Tier 2 is validated |
+
+Screenshots will land under `wiki/_partial-screenshots/rotatingMachine/` once captured from the live demo.
+
+## 12. Debug recipes
+
+| Symptom | First thing to check | Where to look |
+|---|---|---|
+| `state` stuck on `idle`, no startup | Source not in `mode.allowedSources[currentMode]`. Check `flowController` warn log. | `_setupState` + `isValidSourceForMode`. |
+| `flow.predicted.*` is 0 or `NaN` | Pressure not initialised — `predictionHealth.flags` will say `pressure_init_warming`. Inject pressure via `data.simulate-measurement` or wire real measurement children. | `getMeasuredPressure` + `pressureSelector`. |
+| `predictionHealth.quality='invalid'` | Curve normalisation failed at startup — null predictors installed. Check container log for `Curve normalization failed for model …`. | `_setupCurves`. |
+| Drift `level=3` after startup | Less than 10 paired samples (`minSamplesForLongTerm`) — wait a few ticks before judging. | `driftProfiles.minSamplesForLongTerm`. |
+| `cmd.estop` doesn't recover | After `emergencystop`, only `idle` / `off` / `maintenance` are allowed. Send `cmd.shutdown` then `cmd.startup`, or reset via maintenance. | `stateConfig.allowedTransitions.emergencystop`. |
+| Position bounces around target | Movement mode `dynspeed` ease-in/out may overshoot at high speed; try `staticspeed`. | `movement.mode`. |
+
+> Never ship `enableLog: 'debug'` in a demo — fills the container log within seconds and obscures real errors.
+
+## 13. When you would NOT use this node
+
+- Use rotatingMachine for a **single** pump / compressor / blower. For groups of 2+ with load sharing, wire `machineGroupControl` as the parent.
+- Don't use rotatingMachine to model a **passive non-return valve** — use `valve` (no curve, no FSM-driven motor).
+- Don't use rotatingMachine without a **curve model** — flow / power predictions degrade to zero and drift is meaningless.
+
+## 14. Known limitations / current issues
+
+| # | Issue | Tracked in |
+|---|---|---|
+| 1 | Drift confidence drops to 0 when pressure source is missing > 30 s — health flips to `invalid` silently. | `pressure/pressureInitialization.js`. |
+| 2 | Multi-parent registration accepted by `childRegistrationUtils` but ordering of teardown is not test-covered. | Open question — `OPEN_QUESTIONS.md`. |
+| 3 | `data.simulate-measurement` does not unset previous values on missing keys — stale sim data can persist after toggling off. | `measurementHandlers.updateSimulatedMeasurement`. |
+| 4 | `execSequence` legacy umbrella topic kept alive in registry; planned removal in Phase 7. | `commands/index.js` `_legacy: true`. |