EVOLV/wiki/Getting-Started.md

# Getting Started

![code-ref](https://img.shields.io/badge/code--ref-9ab9f6b-blue)
![platform-tests](https://img.shields.io/badge/platform_tests-823%2F823-brightgreen)

> [!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

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

If you forgot the recurse flag:

```bash
git submodule update --init --recursive
```

There are 12 submodules &mdash; `generalFunctions` plus 11 active nodes. Each lives under `nodes/<name>/`.

---

## Step 2 &mdash; Verify the platform builds

```bash
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 &mdash; Pick a run mode

### Option A &mdash; Docker (recommended)

```bash
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:

```bash
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 &mdash; Local Node-RED

If you already have Node-RED installed:

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

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

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

Then start Node-RED:

```bash
node-red
```

---

## Step 4 &mdash; Run your first flow

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

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

In the Node-RED editor:

1. Menu &rarr; Import &rarr; pick the file &rarr; Import.
2. Click Deploy.
3. Open http://localhost:1880/dashboard.
4. Click the startup button.
5. Watch the state machine progress: `idle` &rarr; `starting` &rarr; `warmingup` &rarr; `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 &mdash; What to read next

```mermaid
flowchart LR
    start["You are here"]
    arch["Architecture &mdash; 3-tier code"]
    topo["Topology Patterns &mdash; plant configs"]
    node["Pick a node &mdash; per-repo wiki"]
    conv["Topic Conventions &mdash; naming + units"]
    tele["Telemetry &mdash; 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](Architecture) | Internalise the three-tier (entry &rarr; nodeClass &rarr; specificClass) pattern |
| [Topology Patterns](Topology-Patterns) | See typical plant configs end-to-end with verified edges |
| Pick a node | Most mature is [pumpingStation](https://gitea.wbd-rd.nl/RnD/pumpingStation/wiki/Home) (refactor pilot) |
| [Topic Conventions](Topic-Conventions) | Reference for naming when you wire your own flows |
| [Telemetry](Telemetry) | If you are plumbing InfluxDB or Grafana |

---

## Quick command reference

```bash
# 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 &mdash; 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](Home) | Top-level navigation |
| [Architecture](Architecture) | How a node is built |
| [Topology Patterns](Topology-Patterns) | Plant configurations |
| [Glossary](Glossary) | Decode S88 / EVOLV jargon |