nx_hvac_efficiency.nx
buildroot/runtime/nx_hvac_efficiency.nx
about
nx_hvac_efficiency.nx -- INDEPENDENT HVAC efficiency verdict from
out-of-band sensor readings (the thermostat cannot fake this).
Operator ask (2026-06-23): "get our hvac efficiency s class measured in
our iot so that when we use our therm we can measure independently how
effective the systems are working." Architecture (operator-chosen): broad
/ multi-system; the independent runtime + power signal comes from a
whole-panel CT monitor (Emporia Vue / Sense class), so on/off is the
HVAC circuit drawing current -- NOT the thermostat's self-report.
THE EXCEED: a vendor thermostat reports comfort + schedule ("at setpoint,
all good"). A CT monitor reports energy. NEITHER emits a physics-grounded
verdict on whether the equipment is actually working well. This organ does,
from signals the thermostat does not control:
- SHORT_CYCLING -> oversizing (cycles/hr too high; high humidity,
wear, "feels hot at 72") -- the vendor hides this
- DEGRADED_CAPACITY -> it runs but barely moves temp (fouled coil, low
charge, dirty filter) -- the vendor says "heating..."
- POOR_TRACKING -> overshoots the setpoint (bad control loop)
= a verdict a happy thermostat would never give you.
This is the R1 CORE: it needs only ONE independent indoor temp sensor +
the runtime flag, so it works for ANY system type (forced-air, heat pump,
mini-split, window) before any per-vendor power math (R3/R4 COP) lands.
NO-FLOAT: everything is integer (milli-degC, seconds, permille, x10 rates)
per the ecosystem integer-only doctrine. No syscalls -> deterministic +
hard-gateable with a canned trace.
NEVER-BRICK (CLAUDE.md #26): efficiency MEASUREMENT is read-only by
construction -- this organ reads samples and emits a verdict; it writes
nothing to any device, thermostat, or firmware. There is no firmware path
here to prove safe because none exists. (Any future active-recovery TEST
that commands a setpoint is a SEPARATE organ that must restore the prior
setpoint + fail-safe; it is deliberately NOT in this read-only core.)
genealogy_id: project-iot-discovery-pairing-revival-2026-06-22 (R-HVAC.1)
+ project-ac-footprint-and-hvac-refurb (short-cycle/oversize)
license_tier: ORIGINAL
dependencies 0 imports · 4 importers
imports: none
imported by: nx_ac_sensor_verify.nxnx_hvac_efficiency_test.nxnx_maint_asset.nxnx_maint_unify.nx
structs
| 89 | struct HvacThresh |
| 96 | struct HvacEff |
consts
| 66 | const NX_HVAC_MODE_HEAT: i64 = 1 |
| 67 | const NX_HVAC_MODE_COOL: i64 = -1 |
| 70 | const NX_HVAC_INSUFFICIENT_DATA: i64 = 0 // < 2 samples or zero-length window |
| 71 | const NX_HVAC_EFFICIENT: i64 = 1 // ran, moved temp well, low cycling, tracked |
| 72 | const NX_HVAC_SHORT_CYCLING: i64 = 2 // cycles/hr over ceiling -> oversizing |
| 73 | const NX_HVAC_DEGRADED_CAPACITY: i64 = 3 // ran but response rate under floor |
| 74 | const NX_HVAC_POOR_TRACKING: i64 = 4 // overshot setpoint past tolerance |
| 75 | const NX_HVAC_IDLE: i64 = 5 // never ran in window (valid, not a fault) |
| 76 | const NX_HVAC_BAD_ARG: i64 = 6 // invalid mode / args |
| 77 | const NX_HVAC_N: i64 = 7 |
functions
| 79 | func nx_hvac_verdict_is_valid(v: i64) -> i64 called by 1: main |
| 109 | func nx_hvac_abs(x: i64) -> i64 called by 1: nx_hvac_analyze_core |
| 119 | func nx_hvac_analyze_core(t_sec: *i64, indoor_mC: *i64, outdoor_mC: *i64, on: *i64, |
| 223 | func nx_hvac_analyze(t_sec: *i64, indoor_mC: *i64, outdoor_mC: *i64, on: *i64, |