142 lines
6.3 KiB
Markdown
142 lines
6.3 KiB
Markdown
|
# Platform wiki home — `Home.md` template
|
||
|
|
|
||
|
|
The landing page for the EVOLV Gitea wiki. Same visual-first rules as `WIKI_TEMPLATE.md`: diagrams lead, tables annotate, ≤ 60 words per paragraph.
|
||
|
|
|
||
|
|
`Home.md` answers three questions for a first-time visitor:
|
||
|
|
|
||
|
|
1. **What is this platform?** One paragraph.
|
||
|
|
2. **What nodes exist and how do they relate?** One platform-wide Mermaid graph + a navigation table.
|
||
|
|
3. **Where do I find the conventions?** A pointer table to the rule files in `.claude/`.
|
||
|
|
|
||
|
|
Plus a live refactor-status table so a returning visitor knows what changed since they last looked.
|
||
|
|
|
||
|
|
## Template — copy the block below as the seed for `Home.md`
|
||
|
|
|
||
|
|
```
|
||
|
|
<!-- BEGIN TEMPLATE — Home.md -->
|
||
|
|
|
||
|
|
# EVOLV — Wastewater treatment plant automation
|
||
|
|
|
||
|
|
> **Reflects code as of `<git short hash>` · regenerated `<YYYY-MM-DD>` via `npm run wiki:home`**
|
||
|
|
|
||
|
|
EVOLV is a Node-RED node library for wastewater plant automation, developed by the R&D team at Waterschap Brabantse Delta. Nodes follow the ISA-88 (S88) batch control standard. The library exposes 11 active nodes spanning four S88 levels: from Process Cell down to Control Module, plus one utility node for dashboard integration.
|
||
|
|
|
||
|
|
## Platform overview
|
||
|
|
|
||
|
|
~~~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
|
||
|
|
end
|
||
|
|
subgraph EM["Equipment"]
|
||
|
|
rm[rotatingMachine]:::equip
|
||
|
|
v[valve]:::equip
|
||
|
|
diff[diffuser]:::equip
|
||
|
|
end
|
||
|
|
subgraph CM["Control Module"]
|
||
|
|
meas[measurement]:::ctrl
|
||
|
|
end
|
||
|
|
subgraph UT["Utility"]
|
||
|
|
dash[dashboardAPI]:::neutral
|
||
|
|
end
|
||
|
|
ps --> mgc
|
||
|
|
ps --> vgc
|
||
|
|
mgc --> rm
|
||
|
|
vgc --> v
|
||
|
|
reactor --> diff
|
||
|
|
meas -.data.-> rm
|
||
|
|
meas -.data.-> v
|
||
|
|
meas -.data.-> reactor
|
||
|
|
meas -.data.-> settler
|
||
|
|
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 neutral fill:#dddddd,color:#000
|
||
|
|
~~~
|
||
|
|
|
||
|
|
S88 colours: Process Cell `#0c99d9`, Unit `#50a8d9`, Equipment `#86bbdd`, Control Module `#a9daee`. Solid arrow = parent/child relationship. Dashed arrow = data flow (`measurement` feeds many node types).
|
||
|
|
|
||
|
|
## Live nodes
|
||
|
|
|
||
|
|
| S88 | Node | One-liner | Wiki |
|
||
|
|
|---|---|---|---|
|
||
|
|
| 🟦 Process Cell | **pumpingStation** | Manages a wet-well basin, hands demand to one or more group controllers. | [→](pumpingStation) |
|
||
|
|
| 🔷 Unit | **machineGroupControl** | Load-sharing across a group of rotatingMachines. | [→](machineGroupControl) |
|
||
|
|
| 🔷 Unit | **valveGroupControl** | Coordinated valve control across a group of valves. | [→](valveGroupControl) |
|
||
|
|
| 🔷 Unit | **reactor** | Bioreactor — couples diffuser + measurements + kinetics. | [→](reactor) |
|
||
|
|
| 🔷 Unit | **settler** | Settler / clarifier modelling. | [→](settler) |
|
||
|
|
| 🔷 Unit | **monster** | Composite-sample sensor surrogate. | [→](monster) |
|
||
|
|
| 🟦 Equipment | **rotatingMachine** | Single pump / compressor — curves, state machine, prediction. | [→](rotatingMachine) |
|
||
|
|
| 🟦 Equipment | **valve** | Single valve actuator with FSM. | [→](valve) |
|
||
|
|
| 🟦 Equipment | **diffuser** | Aeration diffuser, gas-side modelling. | [→](diffuser) |
|
||
|
|
| 🔹 Control Module | **measurement** | Sensor signal-conditioning, scaling, calibration. | [→](measurement) |
|
||
|
|
| ⚪ Utility | **dashboardAPI** | Bridge between FlowFuse dashboard widgets and EVOLV. | [→](dashboardAPI) |
|
||
|
|
|
||
|
|
## Standards & conventions
|
||
|
|
|
||
|
|
| Document | What it covers | Where |
|
||
|
|
|---|---|---|
|
||
|
|
| Node architecture (3-tier) | entry → nodeClass → specificClass | `.claude/rules/node-architecture.md` |
|
||
|
|
| Flow layout (Node-RED tabs) | Tab boundaries, lanes, S88 colours, link channels | `.claude/rules/node-red-flow-layout.md` |
|
||
|
|
| Topic naming (`set.` / `cmd.` / `evt.`) | Canonical input + output topics | `.claude/refactor/CONTRACTS.md` §1 |
|
||
|
|
| Wiki page shape | Per-node page template | `.claude/refactor/WIKI_TEMPLATE.md` |
|
||
|
|
| Wiki home shape | This page's template | `.claude/refactor/WIKI_HOME_TEMPLATE.md` |
|
||
|
|
| generalFunctions stability rules | What's safe to change | `.claude/rules/general-functions.md` |
|
||
|
|
|
||
|
|
## Refactor status
|
||
|
|
|
||
|
|
| Tier | What | Status |
|
||
|
|
|---|---|---|
|
||
|
|
| 1 | Add infra in generalFunctions (additive only) | ✅ done |
|
||
|
|
| 2 | Pilot: pumpingStation | ✅ done |
|
||
|
|
| 3 | Convert measurement, MGC, rotatingMachine | ✅ done |
|
||
|
|
| 4 | Convert valve, VGC, reactor, settler, monster, diffuser | ✅ done |
|
||
|
|
| 4* | dashboardAPI | ⏸️ out of scope (no `generalFunctions` dep) |
|
||
|
|
| 5 | Canonical topic names + alias deprecation | 🟡 partial |
|
||
|
|
| 6 | development → main promotion | ⏳ pending Docker E2E |
|
||
|
|
| 7 | Wiki refactor (this work) | 🟡 in progress |
|
||
|
|
|
||
|
|
## Archive
|
||
|
|
|
||
|
|
Pre-refactor pages live under `Archive/`. See [Archive index](Archive).
|
||
|
|
|
||
|
|
<!-- END TEMPLATE -->
|
||
|
|
```
|
||
|
|
|
||
|
|
## Notes for the maintainer
|
||
|
|
|
||
|
|
- `npm run wiki:home` (not yet built) re-renders the platform Mermaid block if any node's `softwareType` registration changes. Until then, the diagram is hand-maintained.
|
||
|
|
- Refactor-status rows flip as tiers land. Anyone landing a tier updates the table in the same PR.
|
||
|
|
- The "Live nodes" table is hand-maintained but small — bulk changes happen only when a node is added or retired.
|
||
|
|
- The Mermaid graph above mirrors what's in `.claude/rules/node-red-flow-layout.md` §10.1 (lane convention). If the rule changes, mirror it here.
|
||
|
|
|
||
|
|
## Archive index — `Archive.md` template
|
||
|
|
|
||
|
|
A separate page that lists every archived page with its archival date and the era it describes.
|
||
|
|
|
||
|
|
```
|
||
|
|
<!-- BEGIN TEMPLATE — Archive.md -->
|
||
|
|
|
||
|
|
# Archive — pre-refactor wiki pages
|
||
|
|
|
||
|
|
Pages kept for historical reference. **Do not update them.** Corrections go on the current page; if you find a meaningful inaccuracy in the archived page, leave it and add a note to the *current* page explaining what changed.
|
||
|
|
|
||
|
|
| Page | Era | Archived on |
|
||
|
|
|---|---|---|
|
||
|
|
| [pumpingStation (pre-refactor)](Archive/pumpingStation-pre-refactor) | Pre-Tier-2 (May 2026) | 2026-05-11 |
|
||
|
|
| [rotatingMachine (pre-refactor)](Archive/rotatingMachine-pre-refactor) | Pre-Tier-3 (May 2026) | 2026-05-11 |
|
||
|
|
| ... | ... | ... |
|
||
|
|
|
||
|
|
Each archived page carries the standard banner at its top (see `WIKI_TEMPLATE.md` → Archive banner).
|
||
|
|
|
||
|
|
<!-- END TEMPLATE -->
|
||
|
|
```
|