EVOLV/wiki/Home.md

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.

Platform overview

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
    end
    subgraph EM["Equipment"]
        rm[rotatingMachine]:::equip
        v[valve]:::equip
        diff[diffuser]:::equip
    end
    subgraph CM["Control Module"]
        meas["measurement<br/><i>registers with any process node</i>"]:::ctrl
    end
    subgraph UT["Utility"]
        dash["dashboardAPI<br/><i>any node → Grafana dashboard</i>"]:::util
    end

    ps -->|owns| mgc
    ps -.->|direct child, no group| rm
    mgc -->|load-shares| rm
    vgc -->|positions| v
    settler -->|return pump| rm

    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

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.

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 →
🔷 Unit	machineGroupControl	Load-sharing across a group of rotatingMachine children.	Home →
🔷 Unit	valveGroupControl	Coordinated position control across a group of valve children; can register pump/PS/MGC nodes as flow sources.	Home →
🔷 Unit	reactor	Bioreactor — ASM kinetics (CSTR/PFR engines); pairs with diffuser + downstream settler.	Home →
🔷 Unit	settler	Secondary clarifier; subscribes to upstream reactor stateChange, drives a return-pump.	Home →
🔷 Unit	monster	Composite-sample sensor surrogate / proportional sampling program.	Home →
🟦 Equipment	rotatingMachine	Single pump / compressor — characteristic curves, prediction, FSM.	Home →
🟦 Equipment	valve	Single valve actuator with FSM (shared with rotatingMachine state model).	Home →
🟦 Equipment	diffuser	Aeration diffuser; gas-side modelling, OTR emission to reactor.	Home →
🔹 Control Module	measurement	Sensor signal-conditioning, scaling, smoothing, outlier detection, analog/digital/MQTT.	Home →
⚪ Utility	dashboardAPI	Receives child.register for any process node → provisions Grafana dashboard via HTTP.	Home →
—	generalFunctions	Shared library — BaseDomain, BaseNodeAdapter, ChildRouter, commandRegistry, UnitPolicy, MeasurementContainer, statusBadge, HealthStatus, logger, configManager. Not a Node-RED node.	Home →

Start here

You want to…	Read
Stand up a local dev environment + run an example flow	Getting-Started
Understand the codebase layout, BaseDomain/adapter pattern, output ports	Architecture
See typical plant configurations and how nodes wire together	Topology-Patterns
Know what topic names to use, units, S88 colours	Topic-Conventions
Understand what Port 0 / Port 1 / Port 2 carry, InfluxDB layout	Telemetry
Decode S88 / EVOLV jargon	Glossary

Domain concepts

Evergreen technical references (not affected by refactors):

Page	Topic
ASM models	Activated Sludge Models — biological process kinetics
PID control theory	Loop tuning, anti-windup, controller forms
Pump affinity laws	Speed/flow/head/power scaling
Settling models	Takács / Vesilind / discrete settling
Signal processing — sensors	Smoothing, outlier rejection
InfluxDB schema design	Cardinality, tags vs fields
Wastewater compliance NL	Dutch regulatory context
OT security — IEC 62443	OT cybersecurity baseline

Operations findings

Algorithm-level proofs and behavioural notes that are still valid:

Page	Topic
BEP gravitation proof	Best-efficiency-point convergence
Curve non-convexity	When pump curves break local optima
NCog behaviour	NCog control metric notes
Pump switching stability	Hysteresis design for multi-pump groups

Project status

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

823 platform tests pass · 0 failures · 12 submodules + parent on development.

Archive

Pre-refactor planning pages have been moved to the Archive. The current Home and supporting pages are the canonical references.