Document all-site device dashboard, diagnostic registers, and Chep alarm strings

ATOM-DEVICES-GUIDE.md

@@ -0,0 +1,91 @@
+# Atom production — all-site device dashboard
+
+Verified October 21, 2026. Production host: https://www.atomhmi.com. Dashboard: https://www.atomhmi.com/site_atom/page_devices. This is separate from the Shop development site at dev.atomhmi.com/site_atom; see SHOP-BUILD.md for that environment. No Shop or atGVL_alarmManager changes were made.
+
+## Published dashboard
+
+The existing Devices page was expanded from 26 to all 38 non-Global devices found across the 33 accessible sites. Atom has Global scope only; the other 32 sites have hardware-device entries. Global is a site-wide configuration scope, not an extra physical device, so it is not repeated as a hardware row.
+
+The page now has three native roots: heading, coverage/freshness explanation, and All Sites Devices table. Route devices and page title Devices are preserved. Site and device names/IDs are separate searchable columns. Default columns: Site, Device, Telemetry, Uptime, Last Update, CPU Temp, HMI Version, Link. Column visibility retains optional CPU/memory/disk/network/firmware/Node/voltage/throttling fields, Update HMI and Reboot. Maintenance actions are hidden initially. No runtime update/reboot/restart commands were pressed.
+
+Telemetry means uptime-data freshness, not an independent connectivity probe: Recent is a valid uptime timestamp no more than 120 seconds old; Stale is older; No data means missing uptime or an invalid timestamp. Missing values render an em dash instead of a fabricated zero or null.null.null.null. Uptime uses seconds converted to days/hours/minutes. Last Update displays age in s/m/h/d. CPU temperature is °C; other units retain the established register definitions. The display uses native Advanced Text Display expressions with explicit null handling, not custom component setup code.
+
+Original 26 rows retain their device-specific site-page destinations. New rows link to their site's observed root. Site link buttons read Open site and have normal line height and padding. Numeric display fields are read-only. Update HMI and Reboot retain their exact device-scoped command targets, but were not operationally tested.
+
+Fresh runtime verification showed 38 rows and no duplicate DOM IDs or captured browser errors. Search by Chep HighPlains returned its one device with live HMI version 1010, uptime and CPU temperature; search grain returned Lazy B Grain Handling. Cleared search restores all 38. After polling settled, a dated snapshot showed 27 Recent, 1 Stale and 10 No data; these are transient observations, not permanent device classifications. Initial page load can briefly show No data while register requests populate.
+
+## Diagnostic-register additions
+
+Audited rpi_ registers on all 38 devices. Twenty-nine devices already had the standard 29-register set; those definitions were not edited. Nine devices had 239 missing entries total. Created only those missing entries:
+
+| Site | Device | Added |
+| --- | --- | --- |
+| Chep HighPlains | main | 29 |
+| Demo Site | demo | 29 |
+| Demo Site | main | 29 |
+| Demo Site | unknown | 7 |
+| Milferd Unruh | barn | 29 |
+| Rosebud Feeders | mill | 29 |
+| R Reimer Farms | water | 29 |
+| Swalwell Church | controller | 29 |
+| Westland | test_trailer | 29 |
+
+The user explicitly approved creating Terminal connections on the eight devices lacking them. Created slave ID terminal, description Terminal, type Terminal, configuration {}. Demo unknown already had Terminal. These are the existing device agent's native Terminal sources; no credentials or SSH destinations were added.
+
+The portable standard definitions are in terminal-register-templates.json. They were captured from APYD Strathmore Main's actual edit dialogs and checked against persisted native import previews. Add siteId and deviceId for the intended target before importing. Terminal command text is address.formula, not address.command; the register key is id, not _id. Never copy an unverified payload directly into production.
+
+The 29 IDs are rpi_atom_hmi_update, rpi_atom_hmi_version, rpi_cpu_clock, rpi_cpu_temp, rpi_cpu_usage, rpi_disk_available, rpi_disk_percentage, rpi_disk_usage, rpi_firmware_version, rpi_ip_loc_addr_1..4, rpi_ip_tun_addr_1..4, rpi_memory_available, rpi_memory_usage, rpi_model, rpi_node_version, rpi_reboot, rpi_restart_service, rpi_service_uptime, rpi_throttled, rpi_throttling_occurred, rpi_under_voltage, rpi_under_voltage_occurred and rpi_uptime.
+
+rpi_uptime reads /proc/uptime in seconds. rpi_service_uptime reads service age in seconds. HMI version is the repository commit count; firmware version is a timestamp, not a semantic version. CPU clock is MHz; CPU/disk usage are percent. Memory/disk figures retain the source commands' decimal MB / 1M block conventions. Network octets are displayed together. Pi-specific firmware/throttling commands depend on vcgencmd; availability on non-Pi hardware is not established. A configured definition does not establish a working reading.
+
+All new entries are enabled. rpi_atom_hmi_update, rpi_reboot and rpi_restart_service have updateType DISABLED, meaning no automatic command polling; this is distinct from enabled=false. No command values were written. Other entries retain the source template's ON_CHANGE or CONTINUOUS recording type. New polling intervals were capped at 600 seconds because the current create form rejects intervals above ten minutes; existing definitions were preserved. The manifest records the actual new intervals.
+
+## Safe native import and verification
+
+Use Manage Registers → Import → select Device and Terminal → Advanced. Explicitly turn Delete Unused OFF; it defaults ON. Validate first and inspect the Confirm Import JSON: only the intended missing IDs may appear in insert; update and delete must be empty. Native validation sorts entries, so compare per ID rather than array order. Submit only after checking the exact source, command, recording type and enabled flag.
+
+The initial Chep/partial Demo entries used individual Create Register forms; remaining batches used the supported native Advanced import. Each committed batch showed Import Successful. Reload Manage Registers before readback; returning to Edit can retain the old table. A read-only audit with JSON [] and Delete Unused OFF exposes the current Terminal entries in unchanged. Do not submit this audit. On all nine affected devices, freshly verified all 29 IDs and compared every new definition to its intended template (normalizing CRLF/LF only): all 239 matched. Existing entries stayed in unchanged with no updates/deletions.
+
+Chep HighPlains, Milferd, Rosebud and R Reimer returned live diagnostics during verification. Demo's three devices, Swalwell and Test Trailer had no diagnostic values in their fresh verification snapshots. That observation does not prove they are powered off or identify the cause; agent/connection/platform investigation remains separate work. Existing K2 Mill, KAV Well Test, LPOP, Simon and Westland Trailer 1 also showed No data in the settled dashboard snapshot. Gladacres showed Stale.
+
+## Local evidence
+
+Original page Copy: /tmp/atom-devices-before.json. Final table draft: /tmp/atom-devices-draft.json. Initial full device/register inventory: /tmp/atom-all-register-audit.json. Created-entry ledger: /tmp/atom-created-diagnostics.json. Eight source ledger: /tmp/atom-created-terminal-sources.json. Fresh definition/readback audit: /tmp/atom-final-register-audit.json. Native import previews: /tmp/atom-import-*.json. Screenshots: /tmp/atom-devices-dashboard.jpg and /tmp/atom-devices-proof.jpg. These are local evidence paths, not remotely synchronized artifacts. Raw live readings/network addresses and browser credentials were not committed.
+
+## Site/device inventory
+
+| Site | Site ID | Device ID — description |
+| --- | --- | --- |
+| APYD Strathmore | `agra_risk` | `main` — Main |
+| Arco Poultry | `arco_poultry` | `barn_controller` — Barn Controller |
+| Aspen Acres | `aspen_acres` | `main` — Main HMI |
+| Atom | `atom` | Global scope only; no hardware device |
+| Bruce Farms | `bruce_farms` | `water` — Water |
+| Calhoun Cattle Co Ltd | `ccc` | `feed` — Feed - Raspberry pi |
+| Chep | `chep` | `main` — Main PC |
+| Chep HighPlains | `chep_hp` | `main` — Main |
+| Darryl Reimer | `darryl_reimer` | `barn` — Barn |
+| Demo Site | `demo` | `demo` — Demo; `main` — Main DEMO; `unknown` — Unknown |
+| Dusty Road Farms | `dusty_road_farms` | `barn` — Barn Controller |
+| Gladacres | `gladacres` | `barn` — Barn |
+| Highland Milling | `highland` | `plant` — Plant |
+| Highway 21 Feeders | `highway_21` | `water` — Water |
+| KAV Main - Mill | `kav` | `mill` — Mill |
+| KAV East - Mill | `kav_east_mill` | `mill` — Mill |
+| KAV East - Water | `kav_east_water` | `water` — Water System |
+| KAV Main - Water | `kav_water` | `water` — Water System; `well_test` — Well Test |
+| K1 - Water | `korova_1_water` | `k1_water` — K1 Water PC |
+| K2 - Mill | `korova_2_mill` | `k2_mill` — K2 Mill |
+| K2 - Water | `korova_2_water` | `k2_water` — K2 Water PC |
+| Lazy B Farm & Ranch | `lazy_b` | `grain` — Grain Handling; `water` — Water System |
+| Lone Pine | `lone_pine` | `recycling` — Recycling; `sawdust_dryer` — Sawdust Dryer |
+| LPOP | `lpop` | `lpop` — LPOP Raspberry |
+| Milferd Unruh | `milferd_unruh` | `barn` — Barn |
+| Rimrock - Mill | `rimrock_mill` | `mill` — Mill |
+| Rimrock - Water | `rimrock_water` | `water` — Rimrock Water |
+| Rosebud Feeders | `rosebud_feeders` | `mill` — Mill |
+| R Reimer Farms | `rrf` | `water` — Water |
+| Simon Loewen | `simon_loewen` | `main` — Main |
+| Swalwell Church | `swalwell_church` | `controller` — Controller |
+| Sweet Grass | `sweetgrass` | `main` — Main PC |
+| Westland | `westland` | `test_trailer` — Test Trailer; `trailer_1` — Trailer 1 |