Site
A place with timezone, circuits, witness collectors, and a network namespace (e.g. broadwater-lan).
Reference
Glossary
Exact product wording from the design contract. Prefer these phrases in UI and docs.
Avoid: “offline” for contact lost; “down”; “battery health” for charge; “0%”/“0 min” for missing; “runtime” without “estimate”; control verbs (shut down, restart, switch) as product actions.
Collector / probe
Agent that samples sources and reports heartbeats. Site witness = expected always-on; workstation sleep is ordinary.
Source
USB or network (NUT/SNMP) endpoint identity used to read a UPS. Identity key includes namespace — not host alone.
UPS asset
Monitored UPS entity. Persists across battery cartridge replacements.
reads
Configured relationship: collector reads a UPS via a source (mint / monitored). Not the same as powers.
powers
Configured relationship: UPS powers equipment. Not measured power flow.
checks
Configured connectivity targets a collector probes (gateway, DNS, ingest, etc.).
Battery installation
One installed battery cartridge interval with stable id; replacement creates a new id.
Heartbeat
Collector check-in cadence H. Late after 2H; contact lost after max(5 min, 3H).
Contact lost — cause unknown
Server stopped hearing expected witnesses; no local evidence of cause. Not synonymous with power failure.
UPS communication lost
Collector reports, but its UPS source stopped answering.
Connectivity failure confirmed by local probe
Local probe records show targets failing.
On schedule · Overdue · Stale
Reading age relative to expected interval I (Accepted §18.4). Always show absolute age.
UPS estimate
Runtime predicted by the UPS. Never call it remaining runtime without “estimate”.
Observed on battery
Measured duration between observed transitions.
Received late · replayed
Uploaded history with receipt > 2 min after observation while draining. It restores history at the original observation time. It does not recover an incident or raise a fresh alert.
Incident lifecycle
First evidence · Grace started · Declared · Acknowledged · Recovered · Resolved (recovered + 5 min stable).
Config states
Desired → Pending → Applied | Failed. Local override may differ from desired.
Secret status
Configured · Missing · Rejected — dashboard never handles secret material.
Monitoring-only
No hardware writes: no self-test initiation, shutdown, outlet switch, etc.
Battery Assurance
Evidence and findings about backup capability — separate from live charge/estimate.
Site witness
Always-on collector carrying site expectations.
Asleep (ordinary workstation)
Workstation collector not reporting; no incident; not counted as expected.
Illustrative — validated board/UPS list pending
Label for unvalidated ESP32 capability numbers.
Technical terms
Plain definitions for the words the chapters use. Product phrases above stay the wording for the screen.
UPS
Uninterruptible power supply. Hardware that runs equipment from a battery when utility power fails. MainsKeeper reads it. The UPS asset is the record of that unit. MainsKeeper does not start tests or switch outlets on it.
NUT
Network UPS Tools. On a host collector, the adapter uses NUT to read a network UPS. Operators are not asked to assemble NUT themselves. ESP32 firmware does not run this stack.
USB-HID
The USB power-device class used for a direct UPS read. It is the designed ESP32 path. A successful read on one model is not a claim that every UPS speaks it.
SNMP
Simple Network Management Protocol. A network read protocol. Identity is namespace, protocol, host, and port. The secret stays on the collector. The dashboard shows only Configured, Missing, or Rejected.
WAN
The path between a site and the MainsKeeper server. When it fails, uploads stop and local collection can continue. That is not, by itself, a UPS power failure or a dead collector.
API
Application programming interface: the requests and records between components. CLI examples and JSON in this guide show intent. Endpoint names and transport stay Proposed unless a section says Accepted.
Ingestion
The responsibility that checks a collector’s credential and writes observations at observation time. It can share a process with queries in an MVP. It is not the UPS adapter.
Durable buffer
Local storage for observations the server has not acknowledged. A host buffer should survive a process restart. When it overflows, the oldest span is a gap. ESP32 size figures in the fixture are illustrative.
Schema
The named shape of a record. Example schema ids in this guide end in “illustrative.” They are not a frozen production contract.
Deduplication
Ignoring a repeated observation with the same collector and sequence, so a retry does not write history twice.
Idempotency
Sending the same accepted batch again does not change stored history a second time. Acknowledgement of a prefix is safe to retry.
Acknowledgement cursor
Proposed The contiguous-prefix retirement mechanism itself: once ingestion has durably accepted a collector’s sequence through a cursor, local rows up to that cursor may be retired. This is not an operator acknowledging an incident, and it is not delivery of a notification.
Rollup
An aggregate over raw observations, such as an hourly summary. Unknown time stays unknown. A rollup does not recreate a span the buffer dropped.
Prometheus
A system that scrapes current metrics on an interval. In the standalone path it can read a collector’s current gauges. A scrape does not replay an outage. That deployment path is Proposed.
Grafana
A dashboard commonly used to graph Prometheus metrics. It can show current state. It does not become the incident record or the Battery Assurance record unless you build that yourself outside this design.