Operational question
Which utility or generator path is feeding each stream, which breakers are closed/open/tripped, and what downstream equipment is affected?
Product requirements · electrical one-line simulator
EPMS Telemetry Dashboard
A testable contract for the source-transfer, breaker, power-flow, telemetry and export behavior in EPMS_Telemetry.html. The page is a simulated teaching cockpit. It is not a live EPMS, protection relay, switching authority or approved operating procedure.
01 Purpose & problem
An electrical operator needs a fast read of source availability, transfer state, breaker position, energized paths, load and alarm count without reconstructing topology from a raw point list. A reviewer also needs to know which numbers are engine-bound and which are illustrative simulator values.
Trust question
Can the displayed voltage, current, power and site aggregate be reproduced from declared formulas and sources, with simulation clearly separated from metered telemetry?
02 Users & personas
| Persona | Goal | Primary read | Success condition |
|---|---|---|---|
| Facilities operator | Triage a source loss or breaker trip. | Status strip → one-line → event log. | Names active source, affected stream and breaker state within one scan. |
| Electrical engineer | Review topology, ratings and calculated current. | Source/MV/RMU/TX/LVSB/ATS/UPS/PDU branches and telemetry labels. | Can identify voltage basis, power factor and capacity gaps. |
| Commissioning engineer | Exercise transfer and breaker-state sequences. | Utility/tie controls, breaker gestures, generator state and alarms. | Every action has a deterministic expected state and visible feedback. |
| Design reviewer | Reconcile EPMS totals with the conventional facility basis. | Facility/IT/PUE strip and representative rack-row scope. | Mismatch is visible rather than hidden by display rounding. |
| Educator / learner | Understand a three-stream protected electrical one-line. | Legend, labels, manual formulas and exports. | Can distinguish a simulated state from an approved switching instruction. |
03 Scope & non-goals
In scope
- Utility A/B, MV tie, A/B/C streams and generator transfer simulation.
- MV/RMU/transformer/LVSB/ATSDB/UPS/PDU/rack and mechanical-load topology.
- Open, closed and trip breaker presentation.
- Voltage/current/kW labels, site roll-up, alarm count and timestamps.
- Zoom, pan, fit, reset and PDF/CSV/JSON report actions.
Non-goals
- No field meters, IEC 61850, Modbus, SCADA historian or relay connection.
- No remote switching, lockout/tagout, synchronization or protection study.
- No validated short-circuit, arc-flash, coordination or load-flow result.
- No claim that the ten visible racks represent the full 1.85 MW IT estate.
- No procurement, safety or operations authorization.
04 Functional requirements
Every visible control, status family and diagram family is mapped below. Generated equipment instances are covered by their stable ID ranges.
| ID | Visible element / requirement | Acceptance |
|---|---|---|
| FR-01 | Show an engine-bound top strip for Facility Load, IT Load and PUE. | epms-fac, epms-it and epms-pue read CONV_CALC.snapshot when available. |
| FR-02 | Show Utility, UPS A/B, generator, trip, data-quality and scenario labels. | Labels remain visible above the one-line and say Simulated rather than Live. |
| FR-03 | Show a five-state line legend: energized, standby, open, alarm/trip and maintenance bypass. | Each state has text plus line sample; meaning is not color-only. |
| FR-04 | Provide Back, Portfolio, PRD and Manual navigation. | All links are keyboard reachable and resolve without changing simulator state. |
| FR-05 | Provide 50%, 75%, 120% and Fit zoom controls. | Each control updates the transform and zoomIndicator. |
| FR-06 | Allow wheel zoom bounded from 15% to 200% and mouse drag pan. | Pointer-centred zoom and pan preserve the selected breaker state. |
| FR-07 | Provide Reset View. | Reset invokes fit-to-screen and records the action in the local log. |
| FR-08 | Provide Export PDF Report, Export CSV Data and Export JSON. | Each action emits current source, generator, breaker and summary state and logs completion. |
| FR-09 | Allow Utility A and Utility B source toggles. | btn-u-a/btn-u-b state, flow and ATS response agree. |
| FR-10 | Allow the MV bus-coupler toggle. | btn-tie and br_mv_tie change together. |
| FR-11 | Show GEN A/B/C status indicators. | Indicators change from standby to running during the associated ATS sequence; they are not presented as manual start controls. |
| FR-12 | Render Utility A/B, streams A/B/C and the A–B MV tie. | Source reachability follows SIM.sources, breaker state and ring/tie logic. |
| FR-13 | Render MV, RMU and transformer groups. | MV_A/B, RMU_A/B/C and TX_A/B/C retain tags, voltage levels and transformer nameplates. |
| FR-14 | Render LVSB, generator and ATS distribution groups. | LVSB_A/B/C, GEN_A/B/C, ATSDB_IT_* and ATSDB_M_* remain connected. |
| FR-15 | Render UPS IT A/B/C and UPS mechanical A/B. | Incoming and downstream paths remain distinct; status labels do not imply metered load. |
| FR-16 | Render ATS panel ties, CDP and mechanical branches. | ATS_PNL1/2, CDP, CH-1…4 and AHU-1/2 appear at stable locations. |
| FR-17 | Render ten DAHU branches. | DAHU_A_0…4 and DAHU_B_0…4 each have breaker, path and telemetry. |
| FR-18 | Render ten representative rack paths. | Each RACK_0…9 has main/catcher PDU, rack ATS and final protected branch. |
| FR-19 | Initialize every wire breaker to closed unless its model declares open. | Generator incomers, tie and catcher-panel alternatives start open; all other modeled defaults match WIRES. |
| FR-20 | Support breaker closed/open/trip simulation. | Click toggles open/closed, Alt sets open and Shift sets trip; state is visible in symbol and alarm count. |
| FR-21 | Run ATS transfer logic for streams A, B and C. | Utility loss opens utility breaker, starts the generator and closes generator breaker after the declared simulated delay; restoration reverses the sequence. |
| FR-22 | Animate only energized paths and preserve source identity. | Flow class is derived from reachable source; final rack leg uses the protected downstream color. |
| FR-23 | Show voltage, current and power on every wire not marked noTele. | tele-<wire-id> labels update to zero when de-energized and calculated/assigned values when energized. |
| FR-24 | Show bottom System, Total Load, Power Factor, Frequency, Breakers, Alarms and timestamp. | Seven groups update without shifting layout; units remain visible. |
| FR-25 | Count closed and total breakers. | val-breakers equals a direct roll-up of SIM.breakers. |
| FR-26 | Count tripped breakers as active alarms. | val-alarms and its fault presentation agree with the number of trip states. |
| FR-27 | Show utility-online or generator-mode system state. | Loss of both utility booleans changes val-system to GEN MODE with warning semantics. |
| FR-28 | Maintain a newest-first local event log. | Source, tie, view and export actions prepend readable entries. |
| FR-29 | Keep simulator scope explicit in reports. | Exported data carries a timestamp and current modeled state; product copy never calls it field telemetry. |
| FR-30 | Preserve the public site shell on documentation pages and the existing cockpit gate/state. | Docs remain public; adding links changes no cockpit control or script. |
05 Data model & telemetry points
Rows enumerate every displayed point family. Wildcards identify generated instances and are the canonical point namespace, not an omission of individual equipment.
| Signal | Symbol / ID | Unit | Nominal / semantics | Source binding |
|---|---|---|---|---|
| Facility load | epms-fac | MW | 2.68; engine-bound aggregate. | CONV_CALC.snapshot.site.facility_kw / 1000. |
| IT load | epms-it | MW | 1.85; engine-bound protected IT aggregate. | snapshot.site.it_kw / 1000. |
| PUE | epms-pue | ratio | 1.45; facility/IT basis. | snapshot.site.pue. |
| Utility summary | top-strip Utility | state | OK presentation; green normal. | Static label; not bound to SIM.sources. |
| UPS summary | top-strip UPS A/B | state | Online presentation. | Static label; not a live UPS register. |
| Generator / trip summary | top-strip Gen / Trips | state / count | Standby / 0 presentation. | Static top strip; dynamic equivalents exist below. |
| Data quality / scenario | top-strip Data / Scenario | quality / mode | GOOD / Simulated. | Static provenance declaration. |
| Utility source availability | SIM.sources.A/B, btn-u-a/b | boolean | Active or off. | User toggle in local simulator. |
| Generator running | SIM.genRunning.A/B/C, btn-gen-a/b/c | boolean | Standby or running. | runATSLogic(). |
| Breaker state | SIM.breakers[br_*] | enum | closed / open / trip; trip is fault-red. | WIRES[].br plus user gesture/ATS. |
| Line energized state | flow-w_* | state | Energized by A/B/C utility or generator; de-energized is muted. | calcPowerFlow() graph traversal. |
| MV feeders | tele-w_mv_a/b, tele-w_rmu_a/b, tele-w_mv_tie | V / A / kW | 20,000 V; illustrative power assignment. | WIRES voltage + calcPowerFlow(). |
| Ring / transformer feeders | tele-w_ring_ac/bc, tele-w_tx_a/b/c | V / A / kW | 20 kV upstream; current from assigned kW/PF. | WIRES and 3-phase current formula. |
| LVSB / generator feeders | tele-w_lvsb_*, tele-w_gen_* | V / A / kW | 400 V; utility or generator source path. | WIRES, breaker state and source reachability. |
| IT distribution feeders | tele-w_db_a/b/c, tele-w_ups_a/b/c | V / A / kW | 400 V; assigned 1,000/300 kW based on destination type. | calcPowerFlow() destination-name mapping. |
| Mechanical distribution | tele-w_db_m_*, tele-w_ups_m_*_in, tele-w_ats* | V / A / kW | 400 V; illustrative feeder values. | WIRES and destination-name mapping. |
| Chiller/AHU branches | tele-w_ch1…4, tele-w_ahu1/2 | V / A / kW | 400 V; energized state and assigned load. | WIRES. |
| DAHU branches | tele-w_dahu_a_0…4, tele-w_dahu_b_0…4 | V / A / kW | 400 V; 30 kW assignment per destination rule. | Generated WIRES loops. |
| Rack PDU incoming | w_ups_pdu_m_0…9, w_ups_pdu_c_0…9 | state | No telemetry label; topology/energization only. | WIRES[].noTele=true. |
| Rack ATS feeders | tele-w_pdu_ats_m_0…9, tele-w_pdu_ats_c_0…9 | V / A / kW | 230 V; 60 kW assignment because destination contains PDU upstream only; branch mapping is illustrative. | Generated WIRES. |
| Final rack branch | tele-w_ats_rack_0…9 | V / A / kW | 230 V; 6 kW per representative rack. | calcPowerFlow() rack destination rule. |
| CDP feeder | tele-w_cdp | V / A / kW | 230 V; controls load presentation. | WIRES. |
| Total load | val-total-load | kW | 2,400–2,499 while either utility is on; illustrative jitter. | updateStatusBar() with Math.random(). |
| Power factor | val-pf | ratio | 0.92–0.95 jitter. | updateStatusBar(). |
| Frequency | val-freq | Hz | Approximately 49.95–50.05, shown to 0.1 Hz. | updateStatusBar(). |
| Breaker roll-up | val-breakers | closed / total | Direct state count. | SIM.breakers. |
| Alarm roll-up | val-alarms | count | Number of breakers in trip. | SIM.breakers filter. |
| System mode | val-system | state | ONLINE if either utility boolean is true; otherwise GEN MODE. | updateStatusBar(). |
| Last update | val-timestamp | local time | Browser time, 1 s cadence. | Date().toLocaleTimeString(). |
06 Formulas & derivations
Facility_kW = IT_kW × PUE = 1,850 × 1.45 = 2,682.5 kWNonIT_kW = Facility_kW − IT_kW = 832.5 kWSource:
CONV_CALC.snapshot.site and the Conventional manual. These values drive the top strip, not the jittered bottom Total Load.I_3φ = P_kW × 1,000 / (√3 × V_LL × PF)Example: 2,400 kW at 20,000 V and PF 0.90 → 76.98 A → 76 A after floor()The cockpit applies this three-phase formula to every displayed wire, including 230 V rack branches. The latter is an acknowledged modeling shortcut; a single-phase branch would use
I=P/V/PF.closedBreakers = count(SIM.breakers[state = closed])activeAlarms = count(SIM.breakers[state = trip])These roll-ups are deterministic for a given interaction sequence.
TotalLoad_kW = utilityAvailable ? 2,400 + floor(random × 100) : 0PF = round2(0.92 + random × 0.03)f_Hz = round1(50.0 + (random − 0.5) × 0.1)These are simulator display functions, not engineering calculations or meter models. The manual marks them as illustrative until replaced by one reconciled scenario source.
07 UX & interaction specification
| Interaction | Required behavior | Accessibility / failure behavior |
|---|---|---|
| Source / tie selection | State, LED, ATS sequence, flow and log update together. | Controls require button semantics and an accessible pressed/state label; color alone is insufficient. |
| Breaker selection | Click toggles; Alt opens; Shift trips. | Hidden modifier gestures must be documented in-context before production use; focus/keyboard parity is required. |
| Zoom / pan / fit | Viewport remains bounded and fit excludes the fixed sidebar/topbar. | Buttons expose names; reduced motion disables flow animation without hiding energized state. |
| Export | PDF preview and CSV/JSON downloads reflect current simulator state. | Popup/download failure returns visible feedback; exports state that data is simulated. |
| Alarm presentation | A trip changes symbol, count and fault state. | Text and symbol supplement red; unexpected open and trip must remain distinct. |
| Mobile | Toolbar scrolls internally and the document does not overflow horizontally. | Core status and doc links remain reachable at 360 px; desktop diagram scope is disclosed. |
| Reports / log | New actions appear newest first with timestamps where applicable. | No report or log is described as a persistent historian. |
08 Acceptance criteria
| ID | Given / when / then | Evidence |
|---|---|---|
| AC-01 | Given CONV_CALC.snapshot, when the page loads, then top-strip values are 2.68 MW, 1.85 MW and 1.45. | DOM assertion against engine output. |
| AC-02 | Given Utility A on, when it is toggled off, then its button and reachable flow become off and an event is logged. | Puppeteer interaction. |
| AC-03 | Given both utilities unavailable, when ATS delays settle, then system mode is GEN MODE and required generator paths close. | Fake-clock state sequence. |
| AC-04 | Given utility restoration, then generator breaker opens before utility breaker closes for that stream. | Fake-clock state sequence. |
| AC-05 | Given an open MV tie, when Tie is selected, then br_mv_tie closes and the control reads active. | State/DOM assertion. |
| AC-06 | Given any breaker, when Shift-clicked, then its state is trip and alarm count increases by one. | Pointer modifier E2E. |
| AC-07 | Given a tripped breaker, when returned to closed/open, then alarm count decreases and symbol leaves trip state. | DOM/state assertion. |
| AC-08 | Given an energized modeled wire, then its flow class is present and its telemetry label is non-zero. | DOM class/text assertion. |
| AC-09 | Given a de-energized wire, then its label reads 0V 0A 0kW. | DOM assertion. |
| AC-10 | Given each zoom preset and Fit, then the indicator and transform change without losing breaker state. | Interaction plus state snapshot. |
| AC-11 | Given a drag and wheel input, then pan/scale stay finite and scale remains 0.15–2.0. | Transform parse assertion. |
| AC-12 | Given each export action, then a report/download is created with current sources, generators and breakers. | Popup/download capture. |
| AC-13 | Given the default simulator, then breaker roll-up equals the model count and alarm count is zero. | Direct JavaScript/DOM comparison. |
| AC-14 | Given 360 px width, then page scroll width does not exceed viewport width and PRD/Manual links remain reachable. | Responsive render measurement. |
| AC-15 | Given reduced-motion preference, then energized state remains legible without animated dash flow. | Computed-style screenshot. |
| AC-16 | Given PRD and Manual pages, then neither is access-gated and both load shared shell/RZExplain scripts. | Static contract and browser load. |
| AC-17 | Given cockpit link injection, then the diff contains exactly two added anchor lines and no deleted cockpit line. | git diff --unified=0. |
| AC-18 | Given the full interaction journey, then no uncaught console error occurs. | Captured console/page error stream. |
09 Non-functional requirements
Performance
- Initial interactive state within 2.5 s on a mid-tier mobile CPU when served locally.
- The 500 ms power-flow and 1 s status intervals must not overlap or grow DOM nodes except bounded log entries.
- Pan/zoom should sustain 30 fps on the full SVG.
Accessibility
- WCAG 2.2 AA contrast and 44 px mobile targets.
- Every click control needs keyboard parity, name, role and state.
- Line/breaker meaning must combine text, geometry and color.
Resilience
- If
CONV_CALCis unavailable, show an explicit unavailable quality state rather than silently trusting fallback numerals. - Blocked popup/download returns actionable feedback.
- No external service is required for the simulator core.
Compatibility
- Current Chromium, Firefox and Safari desktop; current mobile Safari/Chrome for navigation and overview.
- SVG geometry and exports remain standards-based.
- No access-gate is added to docs.
10 Provenance & sources
| Source | Governs | Binding / use |
|---|---|---|
EPMS_Telemetry.html | Visible topology, controls, state machine, telemetry assignment and exports. | Primary implementation source. |
js/conv-engine.js | 1,850 kW IT, 2,682.5 kW facility and PUE 1.45 shared basis. | Top status strip through CONV_CALC.snapshot. |
| EPMS Technical Manual | Electrical formulas, transfer sequence, point interpretation and worked examples. | Human-readable methodology. |
| IEC 60364 | Low-voltage installation principles and conductor/protection context. | Design reference only; simulator is not a compliance calculation. |
| IEC 60909 | Short-circuit current calculation framework. | Future study boundary; no fault level is currently calculated. |
| IEC 61850 / IEC 60870-5-104 | Substation communication and telemetry concepts. | Future integration context; no live protocol client exists. |
| IEEE C37.2 | Device function numbering for protection/control nomenclature. | Recommended detail for future breaker inspector. |
| NFPA 70E / IEEE 1584 | Electrical safety and arc-flash study context. | Explicit non-goal until project-specific study data exists. |
| Conventional review docs 00, 02, 09 and 12 | Cross-page reconciliation, EPMS gaps, engineering basis and acceptance criteria. | Risk and target-state source. |
11 Open questions & risks
| Risk / open question | Current evidence | Required resolution |
|---|---|---|
| Site total is internally inconsistent. | Top strip is 2.6825 MW from CONV_CALC; bottom Total Load jitters at 2.4–2.499 MW. | Bind both to one scenario with an explicit metering tolerance, or label bottom value as a separate sample meter. |
| Ten visible racks do not reconcile to 1.85 MW IT. | Ten × 6 kW = 60 kW; the page does not label the row as representative. | Declare representative scope or render aggregate PDU rows whose sum matches IT. |
| Wire kW is destination-name based. | Values 2,400/1,000/300/60/30/6 kW are assignments, not a conserved load-flow model. | Replace with a topology-aware allocation that balances at each bus. |
| 230 V rack current uses the three-phase formula. | One formula is applied to all wires. | Declare phase model per branch and use single- or three-phase calculation accordingly. |
| Source colors conflict with alarm semantics. | Stream A is fault-red and stream C is purple even when normal. | Move source identity to labels/markers; reserve red for trip and avoid purple as primary operational chrome. |
| Top status fields can become stale. | Utility/UPS/Gen/Trips/Data are static while lower simulator state changes. | Bind to the same state object and expose timestamp/quality per point. |
| Breaker gestures are undiscoverable and lack confirmation. | Alt/Shift behavior exists only in code; any diagram click changes state. | Add explicit training controls, keyboard semantics and confirmation for destructive/safety-like actions. |
| ATS timing is illustrative. | 1 s restoration and 2 s generator start are browser timers, not equipment curves/interlocks. | Label simulated timing and model sync/check permissives before any operational claim. |
| Generator/capacity duty is not reconciled. | Three 2.5 MW sets are shown without required-running/N+1 or fuel coupling. | Derive duty and autonomy from facility load and documented generator curve. |
| Data quality says GOOD without point freshness. | No acquisition timestamp, stale threshold or bad-quality state per wire. | Adopt RZTelemetryQuality or equivalent point-level quality contract. |
| Export omits simulation provenance. | Files contain current values but not a formal data-mode field. | Add schema/version/data-mode and units without changing existing behavior until separately approved. |