Repository navigation
Example Unified Namespace
A Unified Namespace (UNS) is one place, here one MQTT broker, where every system publishes its current data under a structured, agreed topic tree, and every other system subscribes to what it needs instead of building point-to-point links. Copper Canyon Dam is a small but complete example, with a twist: two parties share the broker, and each organises the data its own way.
- The dam's view (the owner, DRWPA): the plant as the operator thinks of it. Site, areas, equipment, following the ISA-95 equipment hierarchy. Published by the dam's control system.
- The vendor's view (the machine builder, Cromley Hydraulics): the turbine as the manufacturer thinks of it. A fleet of assets identified by serial number, each with the same subsystems. Published by the CH monitoring PLC on each turbine.
This page writes out both trees in full. For payload details, rates and commands see Namespace; for why the two views differ, see Customer data vs. machine-builder data.
| Level | Dam's view (customer tree) | Vendor's view (CH tree) |
|---|---|---|
| 1 |
v1.0: version of the namespace |
v1.0: version of the namespace |
| 2 |
DRWPA: the enterprise |
CH: the vendor |
| 3 |
CopperCanyon: the site |
Fleet: everything CH has installed |
| 4 | Area: Reservoir, Plant, Intake, Powerhouse, … |
Customer: DRWPA
|
| 5 | Equipment: Unit1, Gate01, … (where the area has more than one) |
Site: CopperCanyon
|
| 6 | Tag: MW, GatePosition, … |
Asset serial: CH-FR-1987-0042
|
| 7 | Subsystem: Bearings, Cooling, Governor, Turbine, Vibration, Generator, … |
|
| 8–9 | Component and metric: TGB/PadTemp03, HPU/AccumulatorPressure, … |
|
| Identity | The position in the plant: "Unit 1" | The serial number: the machine keeps it when it moves or is renamed |
| Size | 82 values + 1 event topic + 27 commands | 74 values + 8 waveforms + 4 status/event topics, per turbine |
Both trees are generated from one source,
common/namespace.py,
and every topic below exists on the broker (test_docs_name_existing_topics checks the names in
this wiki).
Every value is retained and published every second as {"value", "unit", "timestamp"}.
Cmd/ branches sit next to the values they act on and are never retained; Plant/Events is a
stream of events, not a value. Units 2 and 3 have exactly the same structure as Unit 1.
v1.0/DRWPA/CopperCanyon/
├── Reservoir/
│ ├── Level [m a.s.l.] Reservoir water level
│ ├── Inflow [m³/s] River inflow into the reservoir (estimated)
│ └── Volume [hm³] Stored volume above the dead storage at 380 m a.s.l.
├── River/
│ ├── TailwaterLevel [m a.s.l.] Tailwater level below the powerhouse
│ └── Flow [m³/s] Total release to the river (units + spillway + bottom outlet)
├── Plant/
│ ├── GrossHead [m] Reservoir level - tailwater level
│ ├── TotalMW [MW] Sum of the unit outputs
│ ├── MWSetpoint [MW] Plant MW setpoint from the grid operator (incl. AGC)
│ ├── MWSetpointReachable False when the online units can't make the setpoint
│ ├── AGCEnabled The grid operator's AGC adds small setpoint changes
│ ├── GridFrequency [Hz] Grid frequency at the 150 kV busbar
│ ├── Events (not retained) Plant events: commands accepted/refused, state changes, trips
│ └── Cmd/
│ ├── MWSetpoint [MW] (cmd) Grid operator: plant MW setpoint, split over the units in PLANT mode
│ └── AGC (cmd) Grid operator: AGC on/off (small automatic setpoint changes)
├── Intake/
│ ├── GatePosition [%] Intake (emergency) gate position, 100 = open
│ ├── TrashRackDP [m] Head loss across the trash rack (clogging)
│ ├── RakerRunning Trash rack raker cleaning cycle active
│ └── Cmd/
│ └── GatePosition [%] (cmd) Intake gate position; closing is refused while a unit is not stopped
├── Penstock/
│ ├── Pressure [bar] Penstock pressure at the powerhouse manifold
│ └── Flow [m³/s] Total penstock flow (all three units)
├── Spillway/
│ ├── Gate01/
│ │ ├── Position [%] Spillway radial gate 01 position
│ │ ├── Flow [m³/s] Flow over spillway gate 01
│ │ ├── Mode AUTO (opens near 420 m a.s.l.) or MAN
│ │ └── Cmd/
│ │ ├── Mode (cmd) AUTO or MAN
│ │ └── Position [%] (cmd) Gate position (switches the gate to MAN)
│ └── Gate02/
│ ├── Position [%] Spillway radial gate 02 position
│ ├── Flow [m³/s] Flow over spillway gate 02
│ ├── Mode AUTO (opens near 420 m a.s.l.) or MAN
│ └── Cmd/
│ ├── Mode (cmd) AUTO or MAN
│ └── Position [%] (cmd) Gate position (switches the gate to MAN)
├── BottomOutlet/
│ ├── ValvePosition [%] Fixed-cone valve position
│ ├── Flow [m³/s] Bottom outlet flow
│ ├── Mode AUTO (keeps the minimum river flow) or MAN
│ └── Cmd/
│ ├── Mode (cmd) AUTO or MAN
│ └── Position [%] (cmd) Valve position (switches the outlet to MAN)
└── Powerhouse/
├── Unit1/
│ ├── State Unit state: Stopped, Starting, SpeedNoLoad, Synchronising, Generating, Stopping, Tripped
│ ├── BreakerClosed Generator breaker closed
│ ├── ControlMode PLANT (plant controller) or LOCAL (own MW setpoint)
│ ├── MWSetpoint [MW] Unit MW setpoint (from the plant controller or local)
│ ├── MW [MW] Active power
│ ├── MVAr [MVAr] Reactive power
│ ├── GatePosition [%] Wicket gate position
│ ├── GateSetpoint [%] Governor gate setpoint
│ ├── Speed [rpm] Shaft speed
│ ├── Flow [m³/s] Turbine flow
│ ├── NetHead [m] Net head at the unit (gross head - penstock losses)
│ ├── InletValveOpen Butterfly inlet valve fully open
│ ├── ActiveAlarms Unit controller alarms and trip causes (list of codes)
│ ├── ThrustBearingTemp [°C] Thrust bearing pad 1 temperature (customer RTD element)
│ ├── UpperGuideBearingTemp [°C] Upper guide bearing pad 1 temperature (customer RTD element)
│ ├── LowerGuideBearingTemp [°C] Lower guide bearing pad 1 temperature (customer RTD element)
│ ├── TurbineGuideBearingTemp [°C] Turbine guide bearing pad 1 temperature (customer RTD element)
│ ├── CoolingWaterFlow [L/s] Total unit cooling water flow
│ ├── GovernorOilPressure [bar] Governor HPU accumulator pressure
│ └── Cmd/
│ ├── Start (cmd) Start sequence to Generating (permissives checked)
│ ├── Stop (cmd) Normal shutdown: unload, open breaker, close gates, brakes
│ ├── EmergencyStop (cmd) Emergency stop (latched, needs Reset at standstill)
│ ├── Reset (cmd) Reset a trip once the unit is at standstill and no cause is active
│ ├── ControlMode (cmd) PLANT or LOCAL
│ └── MWSetpoint [MW] (cmd) Local MW setpoint (switches the unit to LOCAL)
├── Unit2/ same structure as Unit1
└── Unit3/ same structure as Unit1
What stands out:
- Organised for running the plant. The operator looks for "the reservoir" or "Unit 1", not for a serial number, so the tree follows the plant layout.
- Only what the dam's own control system knows. One temperature per bearing (pad 1, wired to the unit protection), one cooling flow, one oil pressure. Nothing about vibration, the other bearing pads or the HPU's pumps: that is the machine builder's monitoring.
-
Commands live in the same tree, under
Cmd/beside the values they change. The result shows up on the value topics, so a client never needs a reply channel.
Every process value is retained and published every second as
{"value", "unit", "timestamp", "quality", "seq"}. Waveforms are raw sample blocks (not retained),
_meta/ describes the asset, Events/ carries the PLC alarms. Only the first turbine is written
out; the other two have the same structure.
v1.0/CH/Fleet/
└── DRWPA/ customer (one branch per customer that shares data with CH)
└── CopperCanyon/ site
├── CH-FR-1987-0042/ turbine serial (Unit1 in the customer's naming)
│ ├── _meta/
│ │ ├── Nameplate digital nameplate (JSON): serial, model, ratings, customer unit name
│ │ └── Status ONLINE / OFFLINE (last will)
│ ├── Context/
│ │ ├── MW [MW] Active power (copied from the customer tree)
│ │ ├── MVAr [MVAr] Reactive power (copied from the customer tree)
│ │ ├── GatePosition_pct [%] Wicket gate position (copied)
│ │ ├── NetHead_m [m] Net head (copied)
│ │ ├── Speed_rpm [rpm] Shaft speed (copied)
│ │ ├── UnitState Customer unit state (copied)
│ │ └── TailwaterLevel_m [m a.s.l.] Tailwater level (copied)
│ ├── Bearings/
│ │ ├── Thrust/
│ │ │ ├── PadTemp01 [°C] Thrust bearing pad 1 temperature
│ │ │ ├── PadTemp02 [°C] Thrust bearing pad 2 temperature
│ │ │ ├── PadTemp03 [°C] Thrust bearing pad 3 temperature
│ │ │ ├── PadTemp04 [°C] Thrust bearing pad 4 temperature
│ │ │ ├── PadTemp05 [°C] Thrust bearing pad 5 temperature
│ │ │ ├── PadTemp06 [°C] Thrust bearing pad 6 temperature
│ │ │ ├── OilBathTemp [°C] Thrust bearing oil bath temperature
│ │ │ ├── OilLevel [%] Thrust bearing oil level
│ │ │ └── HPLiftPressure [bar] High-pressure oil lift (jacking) pressure
│ │ ├── UGB/
│ │ │ ├── PadTemp01 [°C] UGB pad 1 temperature
│ │ │ ├── PadTemp02 [°C] UGB pad 2 temperature
│ │ │ ├── PadTemp03 [°C] UGB pad 3 temperature
│ │ │ ├── PadTemp04 [°C] UGB pad 4 temperature
│ │ │ ├── OilTemp [°C] UGB oil temperature
│ │ │ └── OilLevel [%] UGB oil level
│ │ ├── LGB/
│ │ │ ├── PadTemp01 [°C] LGB pad 1 temperature
│ │ │ ├── PadTemp02 [°C] LGB pad 2 temperature
│ │ │ ├── PadTemp03 [°C] LGB pad 3 temperature
│ │ │ ├── PadTemp04 [°C] LGB pad 4 temperature
│ │ │ ├── OilTemp [°C] LGB oil temperature
│ │ │ └── OilLevel [%] LGB oil level
│ │ └── TGB/
│ │ ├── PadTemp01 [°C] TGB pad 1 temperature
│ │ ├── PadTemp02 [°C] TGB pad 2 temperature
│ │ ├── PadTemp03 [°C] TGB pad 3 temperature
│ │ ├── PadTemp04 [°C] TGB pad 4 temperature
│ │ ├── OilTemp [°C] TGB oil temperature
│ │ └── OilLevel [%] TGB oil level
│ ├── Cooling/
│ │ ├── WaterInletTemp [°C] Cooling water inlet temperature (seasonal)
│ │ ├── WaterFlow_TB [L/s] Cooling water flow, turbine bearing circuit
│ │ ├── WaterFlow_GB [L/s] Cooling water flow, generator bearing circuit
│ │ ├── WaterFlow_AirCoolers [L/s] Cooling water flow, generator air coolers
│ │ └── OilCoolerOutletTemp [°C] Cooling water outlet temperature, oil coolers
│ ├── Governor/
│ │ └── HPU/
│ │ ├── AccumulatorPressure [bar] Accumulator pressure
│ │ ├── SumpLevel [%] HPU sump oil level
│ │ ├── OilTemp [°C] HPU oil temperature
│ │ ├── Pump1Running Pump 1 (lead) running
│ │ ├── Pump2Running Pump 2 (lag) running
│ │ ├── PumpStartsPerHour [1/h] Pump starts in the last hour (both pumps)
│ │ ├── FilterDP [bar] Pressure filter differential pressure
│ │ ├── ServoPositionA [%] Servomotor A position
│ │ ├── ServoPositionB [%] Servomotor B position
│ │ └── GateSetpoint [%] Governor gate setpoint (from the customer's governor)
│ ├── Turbine/
│ │ ├── SpiralCasePressure [bar] Spiral case pressure
│ │ ├── HeadcoverPressure [bar] Headcover pressure (behind the runner crown)
│ │ ├── DraftTubePressure [bar] Draft tube cone pressure, 1 s mean (gauge)
│ │ ├── ShaftSealWaterFlow [L/min] Shaft seal water flow
│ │ ├── HeadcoverSumpPumpStarts Headcover sump pump starts (counter)
│ │ ├── ShearPinStatus Wicket gate shear pins: OK or BROKEN
│ │ └── WicketGateBreakawayAlarm A wicket gate lags its servo ring (breakaway link)
│ ├── Vibration/
│ │ ├── UGB/
│ │ │ ├── ShaftX/
│ │ │ │ ├── Overall_um_pp [µm] UGB shaft displacement X, overall peak-to-peak
│ │ │ │ └── Waveform [µm] (not retained) UGB shaft displacement X: 1000 S/s × 4.0 s
│ │ │ └── ShaftY/
│ │ │ ├── Overall_um_pp [µm] UGB shaft displacement Y, overall peak-to-peak
│ │ │ └── Waveform [µm] (not retained) UGB shaft displacement Y: 1000 S/s × 4.0 s
│ │ ├── LGB/
│ │ │ ├── ShaftX/
│ │ │ │ ├── Overall_um_pp [µm] LGB shaft displacement X, overall peak-to-peak
│ │ │ │ └── Waveform [µm] (not retained) LGB shaft displacement X: 1000 S/s × 4.0 s
│ │ │ └── ShaftY/
│ │ │ ├── Overall_um_pp [µm] LGB shaft displacement Y, overall peak-to-peak
│ │ │ └── Waveform [µm] (not retained) LGB shaft displacement Y: 1000 S/s × 4.0 s
│ │ ├── TGB/
│ │ │ ├── ShaftX/
│ │ │ │ ├── Overall_um_pp [µm] TGB shaft displacement X, overall peak-to-peak
│ │ │ │ └── Waveform [µm] (not retained) TGB shaft displacement X: 1000 S/s × 4.0 s
│ │ │ └── ShaftY/
│ │ │ ├── Overall_um_pp [µm] TGB shaft displacement Y, overall peak-to-peak
│ │ │ └── Waveform [µm] (not retained) TGB shaft displacement Y: 1000 S/s × 4.0 s
│ │ ├── Headcover/
│ │ │ ├── Vel_mm_s_rms [mm/s] Headcover vibration velocity, RMS 2-1000 Hz
│ │ │ └── Accel/
│ │ │ └── Waveform [m/s²] (not retained) Headcover accelerometer (cavitation): 10000 S/s × 0.5 s
│ │ └── DraftTube/
│ │ └── Pressure/
│ │ └── Waveform [bar] (not retained) Draft tube cone pressure (gauge): 100 S/s × 10.0 s
│ ├── Generator/
│ │ ├── AirGapMin_mm [mm] Minimum air gap (rotor to stator)
│ │ ├── StatorTemp01 [°C] Stator winding RTD 1
│ │ ├── StatorTemp02 [°C] Stator winding RTD 2
│ │ ├── StatorTemp03 [°C] Stator winding RTD 3
│ │ ├── StatorTemp04 [°C] Stator winding RTD 4
│ │ ├── StatorTemp05 [°C] Stator winding RTD 5
│ │ └── StatorTemp06 [°C] Stator winding RTD 6
│ ├── Counters/
│ │ ├── Starts Unit starts since commissioning
│ │ ├── RunHours [h] Generating hours since commissioning
│ │ ├── EmergencyStops Emergency stops (trips) since commissioning
│ │ └── LoadRejections Breaker openings under load
│ └── Events/
│ ├── Alarm (not retained) PLC alarm events
│ └── ActiveAlarms Active PLC alarm ids
├── CH-FR-1987-0043/ same structure (Unit2)
└── CH-FR-1989-0051/ same structure (Unit3)
What stands out:
-
Organised for a fleet. CH builds the same turbine for many customers. Under
Fleet/every installed machine has the same subtree, so one analytics model or dashboard works on all of them. The customer and site levels exist so CH can tell installations apart and filter by contract. - The serial is the identity. "Unit1" appears only in the nameplate. If the dam renumbers its units, or the turbine is refurbished and moved, the history stays with the serial.
- Much richer machine data: every bearing pad, oil levels, cooling per circuit, the HPU, vibration overall values and raw waveforms, generator temperatures, counters. This is what condition monitoring and an RCA need.
-
Data quality is part of the payload.
qualitysays whether a value can be trusted,seqlets a subscriber detect lost messages,_meta/Status(with an MQTT last will) says whether the PLC is online.
The trees describe the same three turbines, so they overlap in two ways:
| Link | Direction | Example |
|---|---|---|
| Context | The CH PLC copies the operating point from the customer tree (subscribe only, it never writes there) |
Powerhouse/Unit1/MW → CH-FR-1987-0042/Context/MW, also MVAr, gate, net head, speed, state, tailwater |
| Dual-element sensors | One physical sensor, two elements: A wired to the dam's protection, B to the CH PLC |
Powerhouse/Unit1/TurbineGuideBearingTemp (A) and Bearings/TGB/PadTemp01 (B); the same for the other bearings and the governor oil pressure |
| Unit ↔ serial | Only in the CH nameplate |
CH-FR-1987-0042/_meta/Nameplate → "unitTag": "Unit1"
|
Everything else exists in only one tree. That is the lesson of the RCA demo: the overheating TGB pad 3 was visible only in the CH tree, while the control room's screens, built on the customer tree, showed nothing wrong.
- The faults the instructor injects. The scenarios live only in the simulators. No topic carries the ground truth, so the screens and tools see what a real system would see.
- Analytics results. No health scores, spectra or predictions: that is what the edge and IIoT vendors add in the next step (see Edge vendor brief).
- Security and device management. Anonymous, no TLS, no ACLs: out of scope for the demo, not a recommendation.
mosquitto_sub -h localhost -p 1884 -t 'v1.0/DRWPA/CopperCanyon/Powerhouse/Unit1/#' -v # the dam's view of Unit 1
mosquitto_sub -h localhost -p 1884 -t 'v1.0/CH/Fleet/+/+/CH-FR-1987-0042/Bearings/#' -v # the vendor's view of the same turbine
mosquitto_sub -h localhost -p 1884 -t 'v1.0/CH/Fleet/+/+/+/Bearings/TGB/PadTemp03' -v # one metric across the fleetOr open MQTT Explorer (see Node-RED and MQTT Explorer) and fold out both trees side by side.
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