Repository navigation
Interface reference
Every name one part of Copper Canyon exposes to another is listed in the interface inventory,
the inventory/
folder in the repository. It is generated from the code and checked by the tests, so you can trust
it.
| File | Contains |
|---|---|
topics.csv |
Start here. One row per concrete topic, both trees: tree, topic, unit, type, retained, publisher, subscribers, description |
customer.json |
The customer tree: every measured tag with unit, type, range, decimals |
ch.json |
The CH tree per asset: process tags, waveform channels, events, nameplate, status, context mapping |
commands.json |
Every Cmd topic, its payload type and range |
hardwired.json |
The dual-element sensors: customer tag ↔ CH element |
scenarios.json |
Instructor scenarios of both simulators (instructor only) |
api.json |
The HTTP routes and response shapes of every service |
interface.json |
The interface version and a fingerprint of the files above |
Who owns which name, and how a change is made, is in
inventory/README.md.
The single source of truth for both topic trees is
common/namespace.py.
Stability: a rename or removal breaks external clients (edge devices, Node-RED, MQTT Explorer bookmarks, dashboards), so it is always mentioned in the pull request that makes it.
Another project (a course lab, a vendor demo, an analytics stack) can run Copper Canyon unchanged and add its own containers around it. The inventory is the contract between the two.
-
Pin a commit. Build the images from that commit; do not copy the source. Your own compose
file decides which services run. The minimum plant is
mosquitto,dam-simandch-plc-sim; adddam-scadafor the operator's screen. -
Record the interface version you built against:
versionininterface.json. -
Use only what the inventory lists:
- data: the topics in
topics.csv, with the payloads described incustomer.jsonandch.json; - commands: the topics in
commands.json; - faults: the scenario routes of
dam-simandch-plc-siminapi.json(list, start, stop, ground truth) and the scenario ids inscenarios.json. These two services are not exposed on the host, so reach them on the compose network; - settings: the environment variables on the Configuration page.
- data: the topics in
-
To take in a newer Copper Canyon, move the pin and compare
interface.json:- same version: nothing you read has changed;
- second number up: there is something new to use, nothing to fix;
- first number up: read the pull request that raised it, it names every rename and removal.
What your project needs changed inside Copper Canyon comes here as a pull request, so every user gets it and the inventory stays the one place where the interface is written down.
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