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 aggregate rack-group scope. | Top, bottom and terminal roll-ups reconcile without hiding aggregation. |
| 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 aggregate rack groups are ten physical cabinets, feeders or protection zones.
- 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 a complete CONV_CALC v2.0.0 snapshot: 43.50 MW facility, 30.00 MW current IT and PUE 1.45. |
| FR-01A | Reject missing, legacy, requested-version-mismatched or same-version-incomplete authority. | All engine-owned fields, status chips, drawer values and controls become unavailable/inert without leaking plausible retired values. |
| 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 aggregate rack-group paths. | Each RACK_0…9 has main/catcher PDU, rack ATS, 3,000 kW and 200-position disclosure. |
| 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 | 43.50; engine-bound campus aggregate. | CONV_CALC.snapshot.site.facility_load_kw / 1000. |
| IT load | epms-it | MW | 30.00; engine-bound protected IT aggregate. | snapshot.site.it_load_kw / 1000. |
| PUE | epms-pue | ratio | 1.45; facility/IT basis. | snapshot.site.pue. |
| Utility summary | top-strip Utility | state | Available source count. | SIM.sources via updateEpmsStatusStrip(). |
| UPS summary | top-strip UPS A/B | state | Governed module/system basis. | snapshot.electrical; not a live UPS register. |
| Generator / trip summary | top-strip Gen / Trips | state / count | Running generator count / open breaker count. | Bound to SIM state. |
| Data quality / scenario | top-strip Data / Scenario | quality / mode | GOOD / Simulated under current authority. | Validated snapshot.meta; unavailable on missing provenance. |
| 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; engine-derived share of 30,000 kW IT. | EPMS_LADDER plus calcPowerFlow(). |
| 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; derived share of governed non-IT load. | EPMS_LADDER.dahuKw. |
| 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 | Intermediate topology allocation derived from the governed IT load. | EPMS_LADDER and generated WIRES. |
| Final rack group | tele-w_ats_rack_0…9 | aggregate kW / count | 3,000 kW and 200 installed positions per group; no invented physical V/A. | site.it_load_kw / 10 and campus.racks_total / 10. |
| CDP feeder | tele-w_cdp | V / A / kW | 230 V; controls load presentation. | WIRES. |
| Total load | val-total-load | kW | 43,500 while a utility source is available; 0 in the modeled dark-site state. | snapshot.electrical.epms_total_kw. |
| Power factor | val-pf | ratio | UNAVAILABLE. | No governed point; no fallback or random value. |
| Frequency | val-freq | Hz | UNAVAILABLE. | No governed point; no fallback or random value. |
| 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 = 30,000 × 1.45 = 43,500 kWNonIT_kW = Facility_kW − IT_kW = 13,500 kWSource: complete
CONV_CALC v2.0.0 snapshot. Current load is four halls × 7,500 kW; 40,000 kW is planning/design capacity only.I_3φ = P_kW × 1,000 / (√3 × V_LL × PF)Example: 43,500 kW at 20,000 V and PF 0.90 → 1,395.30 A → 1,395 A after floor()Intermediate wire labels use the declared three-phase assumption. Final rack groups are aggregate roll-ups and intentionally suppress physical V/A.
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 ? electrical.epms_total_kw : 0PF = UNAVAILABLEf_Hz = UNAVAILABLEThe total shares the governed scenario source; unpublished points remain neutral rather than receiving plausible defaults.
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 complete CONV_CALC v2.0.0 authority, when the page loads, then top-strip values are 43.50 MW, 30.00 MW and 1.45. | DOM assertion against engine output. |
| AC-01A | Given missing, legacy or same-version-incomplete authority, then all governed values and the shared basis drawer remain unavailable and no retired current value appears. | Hostile-fixture browser assertions. |
| 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 | CONV_CALC v2.0.0: four halls, 30,000 kW current IT, 43,500 kW facility, PUE 1.45 and 2,000 installed rack positions. | Top status strip through a schema-complete snapshot; 40 MW IT remains planning/design capacity. |
| 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 aggregate is a modeled authority, not a field meter. | Top and bottom both bind to 43.50 MW from CONV_CALC v2.0.0. | Add physical meter identity, timestamp and tolerance before any live-operations claim. |
| Ten terminal symbols are aggregate rack groups. | Ten × 3,000 kW = 30 MW and ten × 200 positions = 2,000 positions. | Keep the aggregate label explicit; do not present a group as one cabinet or feeder. |
| Intermediate wire kW is topology-class allocation. | Values derive from site IT/non-IT totals and drawn branch counts, not a solved network. | Replace with a bus-conserving load-flow/allocation model if detailed feeder design is required. |
| Rack-group V/A is not governed. | Final group labels show only aggregate kW and rack count. | Publish branch phase/voltage/conductor topology before exposing physical current. |
| 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. |
| Point-level freshness is absent. | Top source/gen/trip state is bound, while quality remains snapshot-level. | Expose acquisition timestamp, stale threshold and 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 cannot establish capacity for the governed 43.50 MW facility load. | Keep adequacy unavailable until fleet quantity, derating, dispatch, N+1 and the 15,503 L/h fuel basis are governed together. |
| Data quality is snapshot-level. | The shared telemetry banner and metadata validate authority, but individual wires have no sample age. | Adopt point-level freshness and bad-quality state before a live integration. |
| 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. |