EVOLV/wiki/Getting-Started.md

Getting Started

Note

Clone the repo with --recurse-submodules, install dependencies, then either spin up the Docker stack (recommended) or symlink into a local Node-RED. Import an example flow, deploy, watch the state machine run. Total time is around ten minutes.

---

Prerequisites

Tool	Required version	Why
Node.js	18 LTS or newer	Node-RED 4 requires 18+
npm	9 or newer	Bundled with Node.js
git	2.35 or newer	Submodule support
Docker + compose v2	Optional	Local Node-RED + InfluxDB stack
WSL2 (Windows)	Optional	Recommended for native Docker performance

---

Step 1 — Clone and install

git clone --recurse-submodules https://gitea.wbd-rd.nl/RnD/EVOLV.git
cd EVOLV
npm install

If you forgot the recurse flag:

git submodule update --init --recursive

There are 12 submodules — generalFunctions plus 11 active nodes. Each lives under nodes/<name>/.

---

Step 2 — Verify the platform builds

npm run test:platform

Expect: 823 / 0 (823 passing, 0 failing) across all 12 submodules. Around three minutes on a workstation; reactor's mathjs initialisation dominates.

Tip

A failure here usually means a submodule isn't on its development tip or npm install didn't complete. Run git submodule update --init --recursive and try again.

---

Step 3 — Pick a run mode

Option A — Docker (recommended)

docker compose up -d

Brings up Node-RED + InfluxDB pre-loaded with EVOLV nodes.

Service	URL
Node-RED editor	http://localhost:1880
FlowFuse dashboard	http://localhost:1880/dashboard
InfluxDB UI	http://localhost:8086

Watch logs:

docker compose logs -f nodered

Warning

WSL2 users: use the native Ubuntu docker, not docker.exe from Windows Docker Desktop. The compose v2 plugin lives at ~/.docker/cli-plugins/docker-compose.

Option B — Local Node-RED

If you already have Node-RED installed:

# from EVOLV/
ln -s "$PWD" ~/.node-red/nodes/EVOLV
node-red

Or via ~/.node-red/settings.js:

module.exports = {
  nodesDir: ['/path/to/EVOLV/nodes'],
};

Then start Node-RED:

node-red

---

Step 4 — Run your first flow

Every node ships example flows under nodes/<name>/examples/. The recommended start is the rotatingMachine "Basic Manual Control" example.

cp nodes/rotatingMachine/examples/01-Basic-Manual-Control.json ~/.node-red/

In the Node-RED editor:

1. Menu → Import → pick the file → Import.
2. Click Deploy.
3. Open http://localhost:1880/dashboard.
4. Click the startup button.
5. Watch the state machine progress: idle → starting → warmingup → operational.
6. Drag the demand slider. Flow + power predictions update in real time.

Tip

Inject pressure for meaningful predictions. Without pressure data, fDimension=0 produces unrealistic flow/power values. The example flow injects a simulated pressure profile.

---

Step 5 — What to read next

flowchart LR
    start["You are here"]
    arch["Architecture — 3-tier code"]
    topo["Topology Patterns — plant configs"]
    node["Pick a node — per-repo wiki"]
    conv["Topic Conventions — naming + units"]
    tele["Telemetry — Port 0/1/2 + InfluxDB"]

    start --> arch
    start --> topo
    arch --> node
    topo --> node
    node --> conv
    node --> tele

    class start neutral
    class arch,topo,conv,tele step
    class node domain

    classDef neutral fill:#dddddd
    classDef step fill:#a9daee,color:#000
    classDef domain fill:#50a8d9,color:#000

Path	Why
Architecture	Internalise the three-tier (entry → nodeClass → specificClass) pattern
Topology Patterns	See typical plant configs end-to-end with verified edges
Pick a node	Most mature is pumpingStation (refactor pilot)
Topic Conventions	Reference for naming when you wire your own flows
Telemetry	If you are plumbing InfluxDB or Grafana

---

Quick command reference

# All tests
npm run test:platform

# 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

# Fetch 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

Page	Why
Home	Top-level navigation
Architecture	How a node is built
Topology Patterns	Plant configurations
Glossary	Decode S88 / EVOLV jargon