wiki: crisp overhaul — no decoration emoji, all 9 master pages refactored
Source-tree mirror of EVOLV.wiki.git refactor (27a42ee on wiki.git): - 7 master pages rewritten with clean design (Home, Architecture, Topology-Patterns, Topic-Conventions, Telemetry, Getting-Started, Glossary). Tables and Mermaid for visuals, gitea alert callouts for warnings, shields badges for metadata only. No emoji as decoration. - Archive.md becomes a removal-changelog pointing readers to git history and to the successor pages. - _Sidebar.md updated to navigate the new flat-name layout. - Concept / finding / manual pages: uniform mini-header (badges + "reference page" callout) added without rewriting domain content. - Every internal link now uses the flat naming that resolves on the live gitea wiki (Concept-ASM-Models, Finding-BEP-..., etc.). On wiki.git: 29 Archive-* pages hard-deleted (the git history preserves them; Archive.md documents the removal). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
znetsixe
222
wiki/Home.md
222
wiki/Home.md
@@ -1,34 +1,41 @@
|
||||
# EVOLV — Wastewater Treatment Plant Automation
|
||||
|
||||
> **Reflects code as of `9ab9f6b` · regenerated `2026-05-11`**
|
||||
> Source of truth: `nodes/<name>/src/specificClass.js` `configure()` declarations. Edges below were verified against `router.onRegister(...)` calls and emitter subscriptions.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
EVOLV is a Node-RED node library for wastewater plant automation, developed by Waterschap Brabantse Delta's R&D team. Nodes follow ISA-88 (S88). The library exposes **11 active nodes** across four S88 levels plus **1 utility node** for Grafana dashboard provisioning, all built on a shared `generalFunctions` library.
|
||||
> [!NOTE]
|
||||
> EVOLV is a Node-RED node library for wastewater plant automation, built by Waterschap Brabantse Delta R&D. It exposes 11 active nodes across four ISA-88 (S88) levels plus one Grafana-provisioning utility, all on a shared `generalFunctions` library. Every node follows the same three-tier code shape: entry registers the node type; `nodeClass` (extends `BaseNodeAdapter`) bridges to the Node-RED runtime; `specificClass` (extends `BaseDomain`) holds pure-JS domain logic. Source of truth for everything claimed on this page: each node's `src/specificClass.js` `configure()` plus `.claude/refactor/CONTRACTS.md`.
|
||||
|
||||
---
|
||||
|
||||
## Platform overview
|
||||
|
||||
Every solid arrow is a real `router.onRegister(<softwareType>, …)` call in the parent's `configure()`. Dashed arrows are emitter subscriptions (no child-register handshake). Thick `==>` arrows are Unit-to-Unit `stateChange` subscriptions. Verified node by node against current source.
|
||||
|
||||
```mermaid
|
||||
flowchart TB
|
||||
subgraph PC["Process Cell"]
|
||||
ps[pumpingStation]:::pc
|
||||
end
|
||||
subgraph UN["Unit"]
|
||||
mgc[machineGroupControl]:::unit
|
||||
vgc[valveGroupControl]:::unit
|
||||
reactor[reactor]:::unit
|
||||
settler[settler]:::unit
|
||||
monster[monster]:::unit
|
||||
mgc[machineGroupControl]
|
||||
vgc[valveGroupControl]
|
||||
reactor[reactor]
|
||||
settler[settler]
|
||||
monster[monster]
|
||||
end
|
||||
subgraph EM["Equipment"]
|
||||
rm[rotatingMachine]:::equip
|
||||
v[valve]:::equip
|
||||
diff[diffuser]:::equip
|
||||
subgraph EM["Equipment Module"]
|
||||
rm[rotatingMachine]
|
||||
v[valve]
|
||||
diff[diffuser]
|
||||
end
|
||||
subgraph CM["Control Module"]
|
||||
meas["measurement<br/><i>registers with any process node</i>"]:::ctrl
|
||||
meas["measurement — registers with any process node"]
|
||||
end
|
||||
subgraph UT["Utility"]
|
||||
dash["dashboardAPI<br/><i>any node → Grafana dashboard</i>"]:::util
|
||||
dash["dashboardAPI — any node → Grafana"]
|
||||
end
|
||||
|
||||
ps -->|owns| mgc
|
||||
@@ -40,86 +47,149 @@ flowchart TB
|
||||
reactor ==stateChange==> settler
|
||||
diff -. OTR data .-> reactor
|
||||
|
||||
classDef pc fill:#0c99d9,color:#fff
|
||||
classDef unit fill:#50a8d9,color:#000
|
||||
classDef equip fill:#86bbdd,color:#000
|
||||
classDef ctrl fill:#a9daee,color:#000
|
||||
classDef util fill:#dddddd,color:#000
|
||||
class ps pc
|
||||
class mgc,vgc,reactor,settler,monster unit
|
||||
class rm,v,diff equip
|
||||
class meas ctrl
|
||||
class dash util
|
||||
|
||||
classDef pc fill:#0c99d9,color:#fff,stroke:#075a82,stroke-width:2px
|
||||
classDef unit fill:#50a8d9,color:#000,stroke:#2c7ba8,stroke-width:2px
|
||||
classDef equip fill:#86bbdd,color:#000,stroke:#5a90b2,stroke-width:2px
|
||||
classDef ctrl fill:#a9daee,color:#000,stroke:#76b7d4,stroke-width:2px
|
||||
classDef util fill:#dddddd,color:#000,stroke:#a8a8a8,stroke-width:2px
|
||||
```
|
||||
|
||||
**Edges in this diagram are ground-truth** — every solid arrow is a `router.onRegister(softwareType, …)` declaration in the parent's `configure()`. Dashed arrows are emitter subscriptions (not child registrations). For full data-flow including `measurement` fan-out to every process node and `valveGroupControl`'s flow-source registrations, see **[Topology-Patterns](Topology-Patterns)**.
|
||||
### Edge legend
|
||||
|
||||
| Arrow | Meaning | Implementation |
|
||||
|---|---|---|
|
||||
| `A --> B` (solid) | A owns B as an S88 child via `child.register` | `router.onRegister('<swType>', ...)` |
|
||||
| `A -.-> B` (dashed) | A subscribes to B's emitter events; no handshake | `B.emitter.on('<event>', ...)` |
|
||||
| `A ==> B` (thick) | Unit-to-Unit `stateChange` subscription | `settler._connectReactor` pattern |
|
||||
|
||||
### S88 colours
|
||||
|
||||
| Hex | Level | Used by |
|
||||
|:---|:---|:---|
|
||||
| `#0f52a5` | Area | Reserved — no node yet |
|
||||
| `#0c99d9` | Process Cell | pumpingStation |
|
||||
| `#50a8d9` | Unit | MGC, VGC, reactor, settler, monster |
|
||||
| `#86bbdd` | Equipment Module | rotatingMachine, valve, diffuser |
|
||||
| `#a9daee` | Control Module | measurement |
|
||||
| `#dddddd` | Utility / neutral | dashboardAPI, helper functions |
|
||||
|
||||
Source: `.claude/rules/node-red-flow-layout.md` §14.
|
||||
|
||||
For the full data-flow map — every `measurement -> parent` edge, VGC's flow-source registrations, dashboardAPI's provisioning calls, and the worked plant example — see [Topology Patterns](Topology-Patterns).
|
||||
|
||||
---
|
||||
|
||||
## Live nodes
|
||||
|
||||
| S88 level | Node | One-liner | Per-node wiki |
|
||||
|---|---|---|---|
|
||||
| 🟦 Process Cell | **pumpingStation** | Wet-well basin model; dispatches demand to one or more pump groups. | [Home →](https://gitea.wbd-rd.nl/RnD/pumpingStation/wiki/Home) |
|
||||
| 🔷 Unit | **machineGroupControl** | Load-sharing across a group of `rotatingMachine` children. | [Home →](https://gitea.wbd-rd.nl/RnD/machineGroupControl/wiki/Home) |
|
||||
| 🔷 Unit | **valveGroupControl** | Coordinated position control across a group of `valve` children; can register pump/PS/MGC nodes as flow sources. | [Home →](https://gitea.wbd-rd.nl/RnD/valveGroupControl/wiki/Home) |
|
||||
| 🔷 Unit | **reactor** | Bioreactor — ASM kinetics (CSTR/PFR engines); pairs with diffuser + downstream settler. | [Home →](https://gitea.wbd-rd.nl/RnD/reactor/wiki/Home) |
|
||||
| 🔷 Unit | **settler** | Secondary clarifier; subscribes to upstream reactor stateChange, drives a return-pump. | [Home →](https://gitea.wbd-rd.nl/RnD/settler/wiki/Home) |
|
||||
| 🔷 Unit | **monster** | Composite-sample sensor surrogate / proportional sampling program. | [Home →](https://gitea.wbd-rd.nl/RnD/monster/wiki/Home) |
|
||||
| 🟦 Equipment | **rotatingMachine** | Single pump / compressor — characteristic curves, prediction, FSM. | [Home →](https://gitea.wbd-rd.nl/RnD/rotatingMachine/wiki/Home) |
|
||||
| 🟦 Equipment | **valve** | Single valve actuator with FSM (shared with rotatingMachine state model). | [Home →](https://gitea.wbd-rd.nl/RnD/valve/wiki/Home) |
|
||||
| 🟦 Equipment | **diffuser** | Aeration diffuser; gas-side modelling, OTR emission to reactor. | [Home →](https://gitea.wbd-rd.nl/RnD/diffuser/wiki/Home) |
|
||||
| 🔹 Control Module | **measurement** | Sensor signal-conditioning, scaling, smoothing, outlier detection, analog/digital/MQTT. | [Home →](https://gitea.wbd-rd.nl/RnD/measurement/wiki/Home) |
|
||||
| ⚪ Utility | **dashboardAPI** | Receives `child.register` for any process node → provisions Grafana dashboard via HTTP. | [Home →](https://gitea.wbd-rd.nl/RnD/dashboardAPI/wiki/Home) |
|
||||
| — | **generalFunctions** | Shared library — `BaseDomain`, `BaseNodeAdapter`, `ChildRouter`, `commandRegistry`, `UnitPolicy`, `MeasurementContainer`, `statusBadge`, `HealthStatus`, `logger`, `configManager`. **Not a Node-RED node.** | [Home →](https://gitea.wbd-rd.nl/RnD/generalFunctions/wiki/Home) |
|
||||
| S88 level | Node | Role | Per-node wiki |
|
||||
|:---|:---|:---|:---|
|
||||
| Process Cell | pumpingStation | Wet-well basin model; dispatches demand to pump groups. | [Open](https://gitea.wbd-rd.nl/RnD/pumpingStation/wiki/Home) |
|
||||
| Unit | machineGroupControl | Load-sharing across a group of `rotatingMachine` children. | [Open](https://gitea.wbd-rd.nl/RnD/machineGroupControl/wiki/Home) |
|
||||
| Unit | valveGroupControl | Coordinated position control over `valve` children. Registers upstream pumps / PS / MGC as flow sources. | [Open](https://gitea.wbd-rd.nl/RnD/valveGroupControl/wiki/Home) |
|
||||
| Unit | reactor | Bioreactor — ASM kinetics (CSTR / PFR). Pairs with diffuser and downstream settler. | [Open](https://gitea.wbd-rd.nl/RnD/reactor/wiki/Home) |
|
||||
| Unit | settler | Secondary clarifier; subscribes to upstream reactor `stateChange`, drives a return pump. | [Open](https://gitea.wbd-rd.nl/RnD/settler/wiki/Home) |
|
||||
| Unit | monster | Composite-sample sensor surrogate; proportional sampling program. | [Open](https://gitea.wbd-rd.nl/RnD/monster/wiki/Home) |
|
||||
| Equipment | rotatingMachine | Single pump or compressor — characteristic curves, prediction, full FSM. | [Open](https://gitea.wbd-rd.nl/RnD/rotatingMachine/wiki/Home) |
|
||||
| Equipment | valve | Single valve actuator — shared FSM with rotatingMachine. | [Open](https://gitea.wbd-rd.nl/RnD/valve/wiki/Home) |
|
||||
| Equipment | diffuser | Aeration diffuser; gas-side modelling, OTR emission. | [Open](https://gitea.wbd-rd.nl/RnD/diffuser/wiki/Home) |
|
||||
| Control Module | measurement | Sensor signal conditioning — scaling, smoothing, outlier detection; analog / digital / MQTT modes. | [Open](https://gitea.wbd-rd.nl/RnD/measurement/wiki/Home) |
|
||||
| Utility | dashboardAPI | Receives `child.register` from any node; provisions a Grafana dashboard via HTTP. | [Open](https://gitea.wbd-rd.nl/RnD/dashboardAPI/wiki/Home) |
|
||||
| Library | generalFunctions | `BaseDomain`, `BaseNodeAdapter`, `ChildRouter`, commandRegistry, `UnitPolicy`, `MeasurementContainer`, `statusBadge`, `HealthStatus`, `LatestWinsGate`, logger, configManager. Not a Node-RED node. | [Open](https://gitea.wbd-rd.nl/RnD/generalFunctions/wiki/Home) |
|
||||
|
||||
---
|
||||
|
||||
## Start here
|
||||
|
||||
| You want to… | Read |
|
||||
|---|---|
|
||||
| Stand up a local dev environment + run an example flow | [Getting-Started](Getting-Started) |
|
||||
| Understand the codebase layout, BaseDomain/adapter pattern, output ports | [Architecture](Architecture) |
|
||||
| See typical plant configurations and how nodes wire together | [Topology-Patterns](Topology-Patterns) |
|
||||
| Know what topic names to use, units, S88 colours | [Topic-Conventions](Topic-Conventions) |
|
||||
| Understand what Port 0 / Port 1 / Port 2 carry, InfluxDB layout | [Telemetry](Telemetry) |
|
||||
| Decode S88 / EVOLV jargon | [Glossary](Glossary) |
|
||||
| If you want to… | Read |
|
||||
|:---|:---|
|
||||
| Stand up a local dev environment and run an example flow | [Getting Started](Getting-Started) |
|
||||
| Understand the codebase layout, BaseDomain / adapter pattern, output ports | [Architecture](Architecture) |
|
||||
| See typical plant configurations and how nodes wire together | [Topology Patterns](Topology-Patterns) |
|
||||
| Know what topic names to use, units, S88 colours, measurement keys | [Topic Conventions](Topic-Conventions) |
|
||||
| Understand what Port 0 / Port 1 / Port 2 carry, InfluxDB layout, Grafana | [Telemetry](Telemetry) |
|
||||
| Decode S88 / EVOLV / WWTP jargon | [Glossary](Glossary) |
|
||||
|
||||
## Domain concepts
|
||||
---
|
||||
|
||||
Evergreen technical references (not affected by refactors):
|
||||
## Domain concepts (evergreen)
|
||||
|
||||
Domain knowledge that doesn't change when code is refactored.
|
||||
|
||||
| Page | Topic |
|
||||
|---|---|
|
||||
| [ASM models](concepts/asm-models) | Activated Sludge Models — biological process kinetics |
|
||||
| [PID control theory](concepts/pid-control-theory) | Loop tuning, anti-windup, controller forms |
|
||||
| [Pump affinity laws](concepts/pump-affinity-laws) | Speed/flow/head/power scaling |
|
||||
| [Settling models](concepts/settling-models) | Takács / Vesilind / discrete settling |
|
||||
| [Signal processing — sensors](concepts/signal-processing-sensors) | Smoothing, outlier rejection |
|
||||
| [InfluxDB schema design](concepts/influxdb-schema-design) | Cardinality, tags vs fields |
|
||||
| [Wastewater compliance NL](concepts/wastewater-compliance-nl) | Dutch regulatory context |
|
||||
| [OT security — IEC 62443](concepts/ot-security-iec62443) | OT cybersecurity baseline |
|
||||
|:---|:---|
|
||||
| [ASM Models](Concept-ASM-Models) | Activated Sludge Models — biological process kinetics |
|
||||
| [PID Control Theory](Concept-PID-Control-Theory) | Loop tuning, anti-windup, controller forms |
|
||||
| [Pump Affinity Laws](Concept-Pump-Affinity-Laws) | Speed / flow / head / power scaling |
|
||||
| [Settling Models](Concept-Settling-Models) | Takács / Vesilind / discrete settling |
|
||||
| [Signal Processing — Sensors](Concept-Signal-Processing-Sensors) | Smoothing, outlier rejection |
|
||||
| [InfluxDB Schema Design](Concept-InfluxDB-Schema-Design) | Cardinality, tags vs fields |
|
||||
| [Wastewater Compliance NL](Concept-Wastewater-Compliance-NL) | Dutch regulatory context |
|
||||
| [OT Security — IEC 62443](Concept-OT-Security-IEC62443) | OT cybersecurity baseline |
|
||||
|
||||
## Operations findings
|
||||
|
||||
Algorithm-level proofs and behavioural notes that are still valid:
|
||||
## Operations findings (algorithm proofs)
|
||||
|
||||
| Page | Topic |
|
||||
|---|---|
|
||||
| [BEP gravitation proof](findings/bep-gravitation-proof) | Best-efficiency-point convergence |
|
||||
| [Curve non-convexity](findings/curve-non-convexity) | When pump curves break local optima |
|
||||
| [NCog behaviour](findings/ncog-behavior) | NCog control metric notes |
|
||||
| [Pump switching stability](findings/pump-switching-stability) | Hysteresis design for multi-pump groups |
|
||||
|:---|:---|
|
||||
| [BEP Gravitation Proof](Finding-BEP-Gravitation-Proof) | Best-Efficiency-Point convergence |
|
||||
| [Curve Non-Convexity](Finding-Curve-Non-Convexity) | When pump curves break local optima |
|
||||
| [NCog Behaviour](Finding-NCog-Behavior) | NCog control metric notes |
|
||||
| [Pump Switching Stability](Finding-Pump-Switching-Stability) | Hysteresis design for multi-pump groups |
|
||||
|
||||
## Project status
|
||||
## Node-RED / FlowFuse manuals
|
||||
|
||||
| Tier | What | Status |
|
||||
|---|---|---|
|
||||
| 1 | Add infra in `generalFunctions` (additive only) | ✅ done |
|
||||
| 2 | Pilot: pumpingStation end-to-end on new infra | ✅ done |
|
||||
| 3 | Convert measurement, MGC, rotatingMachine | ✅ done |
|
||||
| 4 | Convert valve, VGC, reactor, settler, monster, diffuser, dashboardAPI | ✅ done |
|
||||
| 5 | Canonical topic names + alias deprecation map | ✅ done |
|
||||
| 6 | Promote `development` → `main` | ⏳ pending Docker E2E + human review |
|
||||
| 8.5 | Remove deprecated paths in `generalFunctions` | ✅ done |
|
||||
| 9 | Wiki refactor — visual-first per-node + master pages | ✅ landed 2026-05-11 |
|
||||
| 10 | Test-suite refactor across all nodes | 🟡 in progress |
|
||||
| — | pumpingStation Docker E2E (P2.14) | ⏳ pending |
|
||||
| Page | Topic |
|
||||
|:---|:---|
|
||||
| [Manual Index](Manual-NodeRED-INDEX) | Top of the Node-RED reference set |
|
||||
| [Runtime — Node.js](Manual-NodeRED-Runtime-Node-Js) | `send`, `done`, multi-output arrays |
|
||||
| [Function Node Patterns](Manual-NodeRED-Function-Node-Patterns) | Return / send patterns |
|
||||
| [Messages and Editor Structure](Manual-NodeRED-Messages-And-Editor-Structure) | Msg shape + HTML / editor / runtime split |
|
||||
| [FlowFuse ui-chart](Manual-NodeRED-Flowfuse-Ui-Chart-Manual) | Data contract, runtime controls |
|
||||
| [FlowFuse ui-button](Manual-NodeRED-Flowfuse-Ui-Button-Manual) | Button reference |
|
||||
| [FlowFuse ui-gauge](Manual-NodeRED-Flowfuse-Ui-Gauge-Manual) | Gauge reference |
|
||||
| [FlowFuse ui-text](Manual-NodeRED-Flowfuse-Ui-Text-Manual) | Text reference |
|
||||
| [FlowFuse ui-template](Manual-NodeRED-Flowfuse-Ui-Template-Manual) | Template reference |
|
||||
| [FlowFuse ui-config](Manual-NodeRED-Flowfuse-Ui-Config-Manual) | Config reference |
|
||||
| [Dashboard Layout](Manual-NodeRED-Flowfuse-Dashboard-Layout-Manual) | Compact layout guidance |
|
||||
| [Widgets Catalog](Manual-NodeRED-Flowfuse-Widgets-Catalog) | All widgets at a glance |
|
||||
|
||||
823 platform tests pass · 0 failures · 12 submodules + parent on `development`.
|
||||
---
|
||||
|
||||
## Refactor status
|
||||
|
||||
| Tier | Scope | Status |
|
||||
|:---:|:---|:---|
|
||||
| 1 | Add infra in `generalFunctions` (additive only) | Done |
|
||||
| 2 | Pilot: pumpingStation on new infra | Done |
|
||||
| 3 | Convert measurement, MGC, rotatingMachine | Done |
|
||||
| 4 | Convert valve, VGC, reactor, settler, monster, diffuser, dashboardAPI | Done |
|
||||
| 5 | Canonical topic names + alias deprecation map | Done |
|
||||
| 6 | Promote `development` → `main` | Pending Docker E2E + human review |
|
||||
| 8.5 | Remove deprecated paths in `generalFunctions` | Done |
|
||||
| 9 | Visual-first wiki refactor — per-node + master | Done 2026-05-11 |
|
||||
| 10 | Test-suite refactor across all nodes | In progress |
|
||||
|
||||
> [!IMPORTANT]
|
||||
> Active branch is `development` everywhere — 12 submodules plus parent EVOLV. `main` will receive the merged refactor only after Docker E2E sign-off (pumpingStation P2.14 pending).
|
||||
|
||||
---
|
||||
|
||||
## Archive
|
||||
|
||||
Pre-refactor planning pages have been moved to the [Archive](Archive). The current Home and supporting pages are the canonical references.
|
||||
Pre-refactor wiki content has been removed from the live wiki. The git history of `EVOLV.wiki.git` preserves every prior page if you need to consult it. See [Archive](Archive) for the changelog of what was removed and when.
|
||||
|
||||
---
|
||||
|
||||
## Need help?
|
||||
|
||||
| Channel | Use it for |
|
||||
|:---|:---|
|
||||
| Per-node wiki on Gitea | Operator-level questions for one node |
|
||||
| `.claude/refactor/OPEN_QUESTIONS.md` | Live decisions log — issues being worked on |
|
||||
| Submodule issues on Gitea | File a bug against a specific node |
|
||||
| R&D team Slack / Teams | Anything urgent or strategic |
|
||||
|
||||
Reference in New Issue
Block a user