Repository navigation
Development
Developer knowledge (how each part works, why, and the gotchas) lives in CLAUDE.md. Plans and work in progress are in ROADMAP.md: propose an idea there, or claim an item before you start, so people and agents working in parallel don't collide.
| Path | What |
|---|---|
common/ |
Shared by every image: namespace.py (both topic trees, the single source of truth), turbine.py (turbine design data), mqttio.py, httpd.py, store.py
|
damsim/ |
Dam simulator: model.py (physics, plant controller, dam scenarios), main.py (MQTT, hardwired polling, HTTP) |
chplc/ |
CH PLC simulator: model.py (thermal, HPU, vibration, waveforms, PLC alarms, machine-fault scenarios), main.py (one PLC per turbine, MQTT, HTTP) |
scada/ |
Dam SCADA server and pages (web/index.html hub, web/scada.html) |
instructor/ |
Instructor station |
chviewer/ |
CH asset viewer |
tools/ |
offline_sim.py (both models coupled, faster than real time), inventory.py (generates inventory/), publish_wiki.py
|
inventory/ |
Generated interface inventory |
tests/ |
The test suite |
wiki/ |
The source of this wiki |
nodered_data/flows.json |
The Node-RED flows |
mqtt_explorer_data/settings.json |
The seeded MQTT Explorer connection |
mosquitto/config/ |
Broker configuration |
After any code or web change: docker compose up -d --build (files are copied into the images).
tools/offline_sim.py couples the dam model and the three CH turbine models directly, without
broker or HTTP, and runs about 100× faster than real time:
docker run --rm -v "$PWD":/w -w /w python:3.12-slim python tools/offline_sim.py \
--minutes 30 --every 60 --scenario tgb_bearing_degradation:Unit1@60 \
--cols Unit1:Bearings/TGB/PadTemp03,Powerhouse/Unit1/TurbineGuideBearingTemp-
--scenario id[:unit]@secondsstarts a dam or CH scenario; -
--cmd <command path>=<value>@secondssends a command, e.g.--cmd Plant/Cmd/MWSetpoint=80@600; -
--colstakes customer paths, or<unit>:<CH path>for a CH tag; -
--seed 7makes a run repeatable.
The model will keep growing, and the systems around it must keep agreeing. The tests guard stable interfaces and consistent behaviour: no topic goes missing or changes without anyone noticing.
docker compose run --rm tests # everything (builds the test image once)
docker compose run --rm tests python -m pytest -m "not e2e" # without the end-to-end part
docker compose run --rm tests python tools/inventory.py # after an intended interface changeThe test container mounts the working tree, so nothing needs a rebuild after a code change, and it doesn't touch the running stack.
| File | What it checks |
|---|---|
tests/test_inventory.py |
The committed interface inventory still matches the code, and the interface version was raised with it |
tests/test_contracts.py |
Every topic a component, page, flow or wiki page names exists in the namespace; hidden faults never reach MQTT |
tests/test_behaviour.py |
Both models coupled offline, faster than real time: steady state without alarms, start/stop, the plant controller, a signature for every instructor scenario |
tests/test_e2e.py |
The real programs with an embedded Mosquitto: every topic of the inventory is published, commands round-trip, waveform blocks have the right shape, the last will works |
When a test fails: an inventory diff means an interface changed; if you meant it, regenerate
the inventory and commit it with the change, and name every added, renamed or removed topic in the
PR. A new instructor scenario needs its expected signature in tests/test_behaviour.py.
The same tests run on GitHub for every pull request and every push to main.
The wiki's source is the wiki/
folder in the repository, reviewed in pull requests like code. Don't edit pages on GitHub: the next
publish overwrites them. Screenshots live in wiki/images/, so image links work in the repo and in
the wiki alike.
Publishing is automatic: when a change to wiki/ is merged into main, a GitHub Action
(.github/workflows/wiki.yml) runs tools/publish_wiki.py. By hand, from an up-to-date main:
python tools/publish_wiki.py --dry-run # show what would change
python tools/publish_wiki.py # copy wiki/ (pages and images) to the wiki repo, commit, pushPages link to each other by page name ([Architecture](Architecture)), and to repository files by
full GitHub URL.
Start
Understand
- Copper Canyon Dam
- Architecture
- Customer data vs. machine-builder data
- Example Unified Namespace
- Failure modes
- RCA demo walkthrough
- RCA with Claude: a guide for engineers
Use
- Dam SCADA
- CH asset viewer
- Instructor station
- Node-RED and MQTT Explorer
- Namespace
- Interface reference
- Configuration
For vendors
Contribute