wiki: master EVOLV wiki refactor — 7 new pages + corrected Home
Complete redesign of the platform-level wiki. Previous Home.md had a broken Mermaid diagram (showed pumpingStation → valveGroupControl as a parent/child edge, which isn't in any configure() declaration). Audit of all 12 specificClass.js configure() calls drives the new ground-truth hierarchy. New pages: - Home.md (rewritten — accurate mermaid, full node + concept index) - Architecture.md (3-tier code structure, generalFunctions API surface, child-registration sequence) - Topology-Patterns.md (5 verified plant configurations + worked example) - Topic-Conventions.md (set./cmd./evt./data./child. + unit policy + S88 palette + measurement key shape + status badge + HealthStatus) - Telemetry.md (Port 0/1/2 contracts + InfluxDB line-protocol layout + FlowFuse charts + Grafana provisioning) - Getting-Started.md (clone, install, Docker vs local, first example) - Glossary.md (S88, EVOLV runtime, WWTP, pumps, control, project terms) - _Sidebar.md (gitea wiki navigation) Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
znetsixe
172
wiki/Getting-Started.md
Normal file
172
wiki/Getting-Started.md
Normal file
@@ -0,0 +1,172 @@
|
||||
# Getting Started
|
||||
|
||||
> **Reflects code as of `9ab9f6b` · regenerated `2026-05-11`**
|
||||
|
||||
How to clone, install, and run EVOLV locally; how to deploy the example flows; and where to go next.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
| Tool | Version | Why |
|
||||
|---|---|---|
|
||||
| Node.js | ≥ 18 LTS | Node-RED 4 requires 18+ |
|
||||
| npm | ≥ 9 | Comes with Node.js |
|
||||
| git | ≥ 2.35 | Submodule support |
|
||||
| Docker + compose v2 | optional | For the local Node-RED + InfluxDB stack |
|
||||
| WSL2 (on Windows) | optional | Recommended for native docker performance |
|
||||
|
||||
## Clone and install
|
||||
|
||||
```bash
|
||||
git clone --recurse-submodules https://gitea.wbd-rd.nl/RnD/EVOLV.git
|
||||
cd EVOLV
|
||||
npm install
|
||||
```
|
||||
|
||||
If you cloned without `--recurse-submodules`, run:
|
||||
|
||||
```bash
|
||||
git submodule update --init --recursive
|
||||
```
|
||||
|
||||
There are 12 submodules — one per node (`generalFunctions` plus 11 active nodes). Each lives under `nodes/<name>/`.
|
||||
|
||||
## Verify the platform builds
|
||||
|
||||
```bash
|
||||
npm run test:platform # expect 823 / 0
|
||||
```
|
||||
|
||||
This runs the full unit test suite across all 12 submodules. ~3 minutes on a workstation (reactor's mathjs initialisation dominates).
|
||||
|
||||
## Option A — Run via Docker (recommended)
|
||||
|
||||
The repo ships a `docker-compose.yml` that brings up Node-RED + InfluxDB pre-loaded with the EVOLV nodes:
|
||||
|
||||
```bash
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
When healthy:
|
||||
|
||||
| Service | URL |
|
||||
|---|---|
|
||||
| Node-RED editor | http://localhost:1880 |
|
||||
| FlowFuse dashboard (if widgets installed) | http://localhost:1880/dashboard |
|
||||
| InfluxDB UI | http://localhost:8086 |
|
||||
|
||||
Watch the container logs while you click around:
|
||||
|
||||
```bash
|
||||
docker compose logs -f nodered
|
||||
```
|
||||
|
||||
**WSL2 note:** use the native `docker` from Ubuntu, not `docker.exe` from Windows Docker Desktop. systemd `docker.service` should be enabled and your user in the `docker` group. Compose v2 plugin lives at `~/.docker/cli-plugins/docker-compose`.
|
||||
|
||||
## Option B — Run via local Node-RED
|
||||
|
||||
If you already have Node-RED installed in `~/.node-red`:
|
||||
|
||||
```bash
|
||||
# in EVOLV/
|
||||
ln -s "$PWD" ~/.node-red/nodes/EVOLV
|
||||
```
|
||||
|
||||
Or add to your `~/.node-red/settings.js`:
|
||||
|
||||
```js
|
||||
module.exports = {
|
||||
// ...
|
||||
nodesDir: ['/path/to/EVOLV/nodes'],
|
||||
}
|
||||
```
|
||||
|
||||
Then start Node-RED:
|
||||
|
||||
```bash
|
||||
node-red
|
||||
```
|
||||
|
||||
## Your first flow
|
||||
|
||||
Each node ships with example flows under `nodes/<name>/examples/`. The recommended starting point is **rotatingMachine — Basic Manual Control**:
|
||||
|
||||
```bash
|
||||
# Copy the example into your Node-RED user dir
|
||||
cp nodes/rotatingMachine/examples/01-Basic-Manual-Control.json ~/.node-red/
|
||||
```
|
||||
|
||||
In the editor:
|
||||
|
||||
1. Menu → **Import** → select the file → **Import**.
|
||||
2. Hit **Deploy**.
|
||||
3. Open the dashboard at http://localhost:1880/dashboard.
|
||||
4. Click the **startup** button. Watch the state machine progress: `idle → starting → warmingup → operational`.
|
||||
5. Drag the demand slider. The flow + power predictions update in real time.
|
||||
|
||||
## What to read next
|
||||
|
||||
```mermaid
|
||||
flowchart TB
|
||||
start[You are here]:::neutral
|
||||
arch[Architecture<br/>3-tier code structure]:::tier1
|
||||
topo[Topology-Patterns<br/>typical plant configs]:::tier1
|
||||
conv[Topic-Conventions<br/>naming + units]:::tier1
|
||||
tele[Telemetry<br/>Port 0/1/2 + InfluxDB]:::tier1
|
||||
node[Pick a node's wiki<br/>per-repo Home.md]:::tier3
|
||||
|
||||
start --> arch
|
||||
start --> topo
|
||||
arch --> node
|
||||
topo --> node
|
||||
node --> conv
|
||||
node --> tele
|
||||
|
||||
classDef neutral fill:#dddddd
|
||||
classDef tier1 fill:#a9daee,color:#000
|
||||
classDef tier3 fill:#50a8d9,color:#000
|
||||
```
|
||||
|
||||
| Path | Why |
|
||||
|---|---|
|
||||
| [Architecture](Architecture) | Internalise the 3-tier (entry → nodeClass → specificClass) pattern. |
|
||||
| [Topology-Patterns](Topology-Patterns) | See typical plant configs end-to-end with verified edges. |
|
||||
| Pick a node | The most mature is [pumpingStation](https://gitea.wbd-rd.nl/RnD/pumpingStation/wiki/Home) (refactor pilot). |
|
||||
| [Topic-Conventions](Topic-Conventions) | Reference for naming when you start wiring your own flows. |
|
||||
| [Telemetry](Telemetry) | If you're plumbing InfluxDB or Grafana. |
|
||||
|
||||
## Quick command reference
|
||||
|
||||
```bash
|
||||
# run all tests
|
||||
npm run test:platform
|
||||
|
||||
# run one node's tests
|
||||
cd nodes/rotatingMachine && node --test test/basic/*.test.js
|
||||
|
||||
# regenerate a node's wiki AUTOGEN blocks
|
||||
cd nodes/rotatingMachine && npm run wiki:all
|
||||
|
||||
# rebuild docker stack
|
||||
docker compose build && docker compose up -d
|
||||
|
||||
# update all submodules to their development tips
|
||||
git submodule update --remote --recursive
|
||||
|
||||
# pack EVOLV as an npm tarball
|
||||
npm pack
|
||||
```
|
||||
|
||||
## Where to ask for 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. |
|
||||
| Gitea repo issues per submodule | File a bug against a specific node. |
|
||||
| R&D team Slack / Teams | Anything urgent or strategic. |
|
||||
|
||||
## Related pages
|
||||
|
||||
- [Home](Home) — top-level navigation
|
||||
- [Architecture](Architecture) — how a node is built
|
||||
- [Topology-Patterns](Topology-Patterns) — plant configurations
|
||||
Reference in New Issue
Block a user