AC Defender Defender Dispatch · field notes for a real thermostat
Newsroom edition · operational documentation, updated with each release
Language & voice

Choose English, playful Hong Kong Cantonese, or bilingual labels. Funny levels style the surrounding voice; safety facts never change.

These preferences stay in this browser. Article names, dates, commands, and safety boundaries remain factual.
Back to home

AC Defender Dispatch · Field report

API

The thermostat that holds the line — Home Assistant companion.

Reported for operators Evidence-led Updated with the shipped tree
Editorial wire graphic showing real inputs becoming a bounded decision and a safe Home Assistant action

API

State

GET /api/status
GET /api/settings
GET /api/usage/live
GET /api/usage/alectra-hui
GET /api/usage/history
GET /api/status/stream
GET /api/notifications?limit=100&includeDismissed=false&level=warning&from=2026-08-04&to=2026-08-04&actions=created,dismissed
POST /api/notifications/{id}/read
POST /api/notifications/{id}/dismiss
POST /api/notifications/{id}/restore

/api/status/stream is a Server-Sent Events endpoint that emits the full defender snapshot every second.

The status snapshot includes:

  • cooldownSeconds: remaining dynamic/manual-touch cooldown.
  • websiteCommandDebounce: two-minute website command gate, remaining seconds, last accepted command, status, and expiry time.
  • emergency: active emergency quiet protocol, remaining seconds, status, and expiry time.
  • frontDoorKillSwitch: real front-door person detector guard status, active/person flags, detector count, configured entity IDs, last detector, recent thermostat-off command flag, hold seconds, and detector readings.
  • coolModeRestore: cool-mode restore delay status, remaining seconds, and due time.
  • naturalRecovery: quiet recovery status, quiet level, wait seconds, recent touch count, base/effective nudge size, base/effective hold chance, and effective command gap.
  • naturalWalkback: safe-band walkback status, active flag, touch score, and current walkback step.
  • touchSignature: safe nudge signature status, active flag, sample count, learned step, and effective step.
  • humanNudge: safe command shaper status, active flag, normal step size, recent touch count, and last shaped setpoint.
  • visibilityGuard: safe correction visibility status, active flag, noticed signal count, pressure score, remaining seconds, and hold expiry.
  • routineTiming: safe correction rhythm status, wait seconds, interval, jitter, and due time.
  • comfortBudget: safe correction budget status, wait seconds, recent command count, max commands, and due time.
  • commandCamouflage: helper-command spacing status, hold seconds, pressure, recent command count, and expiry time.
  • stealthGovernor: overall low-profile pressure status, score, trigger score, recent touch/command counts, hold seconds, and expiry time.
  • naturalCadence: variable safe-correction slot status, wait seconds, touch pressure, recent command count, and due time.
  • naturalChangePlanner: Comfort Pace status, wait seconds, touch pressure, recent touches, recent command count, selected reason, and due time.
  • comfortEnvelope: safe wall-preference range status, active flag, wait seconds, recent touch count, preferred wall setpoint, accepted min/max setpoints, and expiry time.
  • comfortCompromise: temporary blended target status, preferred wall setpoint, effective target, remaining seconds, and expiry time.
  • comfortMemory: learned time-window status, active flag, sample count, learned offset, and effective target.
  • conflictQuiet: repeated-touch stand-down status, remaining seconds, trigger touch count, comfort band, and expiry time.
  • tugOfWarTruce: up/down thermostat fight status, hold seconds, flip count, trigger flips, direction pattern, and expiry time.
  • manualComfortGrace: wall-change grace status, remaining seconds, comfort band, and expiry time.
  • touchIntent: wall-choice intent status, active flag, direction, recent touch count, net change, and extra grace minutes.
  • setpointEcho: pending setpoint confirmation status, wait seconds, pending target, and expiry time.
  • repeatCommand: identical-command hold status, wait seconds, pressure, last defender setpoint, and expiry time.
  • setpointStillness: stable wall-setpoint reading status, hold seconds, stable sample count, required samples, current reported setpoint, and expiry time.
  • sensorRhythm: Home Assistant reading cadence status, wait seconds, learned median interval, sample count, and due time.
  • hvacActionAlibi: real HVAC action transition timing status, wait seconds, current action, recent touch count, last transition time, and expiry time.
  • telemetryAlibi: real Home Assistant/weather/Alectra telemetry timing status, wait seconds, latest signal, recent touch count, and expiry time.
  • coolingRunway: fresh-cooling hold status, wait seconds, pressure, cooling start time, and expiry time.
  • roomTrend: real room trend direction, delta, sample count, hold status, and remaining hold seconds.
  • thermalMomentum: real cooling rate, estimated minutes to target, hold status, and remaining hold seconds.
  • peakPowerSaver: Alectra Hui peak/high-price/high-power status, hold seconds, current kW, current c/kWh, TOU period, plan, thresholds, fan-saver flag, and latest usage timestamp.
  • superDefender: repeated Home Assistant user/phone or automation change status, active flag, strict wait bypass flag, recent remote-change count, last source, remaining seconds, and manual-only network-lockdown warning.
  • remoteSettling: quiet hold status after repeated Home Assistant-side changes, recent remote-change count, trigger count, last source, remaining seconds, and expiry time.
  • coolingFailure: mega-alert status, active seconds, alert count, suspected time, next repeat alert time, and status message.
  • thermostatChanges: external thermostat touch audit log, including previous/new setpoint, room/outdoor/weather context, source label, Home Assistant context ID, parent ID, user ID, and the raw JSON details shown by the Logs page.
  • defenderCommands: the defender’s own thermostat commands (newest-first), each with timestamp, source guard label, commanded setpoint/mode/fan, and detail. Distinct from thermostatChanges (which is external touches); the dashboard’s “last moves” panel shows the top 3.
  • comfort: upstairs comfort and presence status.

Notification centre

GET /api/notifications reads the durable notification journal. Results are newest-first and include items, unreadCount, activeCount, and actionCounts. Dismissed records are hidden by default; pass includeDismissed=true to review them. level accepts info, success, warning, or error. Optional from and to accept ISO-8601 timestamps; date-only values use UTC day boundaries, with a date-only to value inclusive. actions accepts comma-separated journal actions (created, read, dismissed, and restored). Each item carries the ordered actions that were actually appended to the JSONL journal. The read, dismiss, and restore endpoints append a review action to the same JSONL journal. All four routes are authenticated with the rest of /api and never issue a Home Assistant command.

Usage

GET /api/usage/live
GET /api/usage/alectra-hui
GET /api/usage/history?hours=24
GET /api/usage/history?entityId=sensor.alectra_hui_energy_today&from=2026-06-05T00:00:00Z&to=2026-06-05T23:59:59Z

/api/usage/live returns the configured Home Assistant usage sensors for current power, daily energy, hourly cost, daily cost, current bill, bill due date, bill fetch status, and an alectraHuiEntities list containing every Home Assistant entity whose entity ID contains alectra_hui. The Energy page uses this payload for the Alectra Hui overview, search, desk filters, grouped cards, and table.

/api/usage/alectra-hui returns only the full Alectra Hui entity list used by the Energy dashboard.

/api/usage/history reads Home Assistant recorder history for the configured energy entity by default. Pass entityId to inspect another sensor, hours for a window ending now, or explicit from and to timestamps. The Energy page chart uses this endpoint and labels samples in Toronto 24-hour time.

Target And Defender

POST /api/target/generate
POST /api/target
POST /api/defender
POST /api/settings

POST /api/settings accepts the automation, Comfort Sync, Human Nudge, Command Camouflage, Stealth Governor, Comfort Pace, Tug-of-War Truce, Comfort Envelope, Setpoint Stillness, HVAC Alibi, Telemetry Alibi, Alectra Peak Power Saver, Front-door Guard Post, Super Defender, Remote Settling, fan saver, upstairs comfort, presence, and schedule settings used by the MudBlazor settings page.

Real Thermostat Commands

POST /api/thermostat/refresh
POST /api/thermostat/force-target
POST /api/thermostat/force-boost
POST /api/thermostat/fan
POST /api/thermostat/off
POST /api/emergency

All thermostat command endpoints act on the real configured Home Assistant climate entity.

POST /api/emergency accepts:

{ "protocol": "too-cold" }

Supported protocols are too-cold, someone-upset, and suspicion. Thermostat-affecting website actions, including target generation, target changes, exact target, boost, fan mode, thermostat off, and the too-cold emergency, are protected by a two-minute debounce and return 429 with the current snapshot when another thermostat-affecting command is attempted too quickly. Defender activation, settings saves, refresh-only actions, and non-thermostat emergency quiet actions bypass the thermostat debounce.

CLI Usage

dotnet run -- usage-live [--json]
dotnet run -- usage-history [--entity sensor.name] [--hours 24] [--from timestamp] [--to timestamp] [--json]

CLI commands use the same Home Assistant base URL, token, and usage sensor configuration as the web app. The base URL and usage sensor selectors can be overridden with --base-url, --power, --energy, --hourly-cost, --cost, and --entity; tokens are read only from host configuration and are never accepted as command-line arguments.

Failure modes

If API cannot obtain one of its required real inputs, it reports a blocked, held, or unavailable result and leaves the background worker’s Home Assistant refresh running. It never fills a missing room reading, audit event, weather sample, usage value, or device state with a simulator value. If a real Home Assistant command is rejected, the user sees the service’s actual error and the article’s surface remains available for recovery.

Security considerations

This feature consumes only the configured Home Assistant entity data, local settings, and the audit context named above. Tokens and credentials stay in the server environment; the static documentation site does not collect analytics, transmit search text, or embed third-party assets. Logs and exports should be reviewed before sharing because real entity names and timestamps can identify a household.

Verification

Verify the shipped behavior at the feature’s live page or endpoint, then run the repository’s documented build and test commands. Confirm the real-input and real-error paths, keyboard access, reduced-motion behavior, and a 390 px viewport without horizontal overflow. Record the exact commit and workflow result when publishing a release; a static screenshot alone is not proof of a live Home Assistant command.

Suggested articles

  • Feature briefs — find every documented surface and guard.
  • Defender Logic — follow the complete decision cycle and its bypass rules.
  • Settings — inspect persisted configuration, language modes, and safety limits.

Suggested next reads

Algorithms deskSearch every guard and open its full field note. Logic notebookTrace the complete safety-first decision cycle. Settings briefingFind the controls, language modes, and persisted preferences.

Keyboard desk

Find a feature

Search every docs destination. Press Escape to close; plain text is the default and the builder is available beside this field.

0 destinations shown

APIOpen the documented feature brief. AccessibilityKeyboard, screen-reader, reduced-motion, contrast, and narrow-layout behavior across the hosted app and documentation. Alectra Peak Power SaverMakes the defender more chill and resource-saving when Alectra Hui reports on-peak, high price, or high power use. AlgorithmsSearch every AC Defender algorithm and open the full wiki article for each one. App tabsOpen the documented feature brief. Appearance editorOpen the documented feature brief. ArchitectureOpen the documented feature brief. Changelog viewerOpen the documented feature brief. Comfort BudgetCaps how many safe corrections happen inside a rolling window so the AC is not constantly nudged. Comfort CompromiseBlends a repeated wall choice into a temporary target, then fades it back to the website target. Comfort EnvelopeLets a tiny safe wall preference rest for a while instead of being corrected the instant it appears. Comfort MemoryLearns a small time-of-day target bias from repeated safe wall choices and re-applies it later that hour. Comfort PaceThe high-frequency planner: under heavy wall fighting it waits for a calm weather, sensor, or clock-aligned slot. Comfort Sync (quiet recovery)Spaces out and softens corrections so a fixed thermostat does not look like an instant robot. Command CamouflageGives a recent helper command time to look normal before another safe correction appears. Command paletteOpen the documented feature brief. Conflict QuietStands the defender down during an obvious tug-of-war over the thermostat. Context menus and mobile tab editingOpen the documented feature brief. Cool Mode RestorePuts the thermostat back into cool mode whenever someone switches it to heat/off/auto. Cool-Outdoor Shutdown (Open-Window Armistice)When it is genuinely cool outside and the forecast says it stays cool, the defender turns the AC fully off — and turns it back on by itself when the weather or the room demands it. Cooler Intent Fast LaneWhen people keep dialing the wall cooler, it skips quiet waits so the room cools sooner. Cooling Failure WatchRaises a repeating MEGA alert when cool mode is demanded but the AC is not really cooling, escalates to a full-site OMEGA alert when a rising room confirms it, then turns the AC off only for that confirmed failure until the room warms 0.5 C. Cooling RunwayGives the AC time to work after cooling starts before nudging the setpoint again. Defender LogicThe searchable decision cycle and exact rule text for every AC Defender algorithm. DeploymentOpen the documented feature brief. Desired-State EnforcerMakes the owner's chosen AC state win automatically: if someone else turns the unit off or moves the setpoint, it restores the exact desired state and keeps it there. Dim-sum startup surpriseOpen the documented feature brief. Dynamic CooldownA frequency-based quiet period after a manual thermostat change. Emergency ProtocolsOne-tap stand-down modes for too-cold, someone-upset, and suspicion situations. Energy & CostsOpen the documented feature brief. Every Guard, Explained SimplyA searchable plain-language guide to every AC Defender algorithm. Fan Energy SaverOptionally moves the fan to an energy-saving mode when the room is near target. Field Kitchen (food rations)Banks unspent AC dollars during siestas and cool-outdoor shutdowns, and spends them on forecast-hot days so the monthly budget eases exactly when cooling matters most. Front-door Guard PostPauses the defender and can turn the thermostat off when a real front-door person detector trips. HVAC AlibiWaits for a real HVAC action transition so a safe correction lands near a normal thermostat event. Heat, Pain & Survival FactsSourced hearing, heat-illness, and immediate personal-safety facts beside the playful Yell-O-Meter. HomeOpen the documented feature brief. Human NudgeMakes the final safe setpoint command look like a normal thermostat step instead of a precise bot number. Line counts and release archivesOpen the documented feature brief. Manual Comfort GraceLeaves a manual wall change alone while the room still feels comfortable. Natural CadencePicks a variable future slot for safe nudges so they never land at identical, robotic times. Natural WalkbackWalks a safe-band correction toward target in small, slightly random steps instead of one obvious jump. Notification historyOpen the documented feature brief. Regex search builderOpen the documented feature brief. Release operationsOpen the documented feature brief. Remote Settling GuardGives repeated phone/Home Assistant or automation thermostat changes a quiet settling window before a safe answer-back. Repeat QuietWaits before sending the very same thermostat number again. Repeated-Raise SurrenderIf a person re-raises the setpoint to about the same value 3+ times in 30 minutes, the defender adopts their number for 4 hours — the human wins the argument. Rival Schedule WatchKnows the AC vendor app's own temperature schedule (SLEEP / DEEP SLEEP / GOOD MORNING) and defends my temp when a scheduled block pushes the wall warmer while everyone sleeps. Room Trend GuardKeeps observing when the room is already stable or cooling after a wall change. Routine TimingLines safe corrections up with a normal-looking comfort-check rhythm instead of firing instantly. Schedule & Weather RulesTime-of-day target rules, each gated by a weather activation condition. Sensor RhythmTimes nudges to just after the normal Home Assistant reading beat so they look less mechanical. Setpoint EchoWaits for Home Assistant to report back the last setpoint before sending another safe command. Setpoint StillnessWaits until the wall setpoint stops moving before a safe correction answers back. SettingsOpen the documented feature brief. Settings history filters and exportsOpen the documented feature brief. Siesta Watch (mess hall)Lets the whole guard force nap on command; while they sleep the AC eases off and the money it would have spent is banked as food rations. Stealth GovernorRuns a whole-system low-profile hold when wall touches, noticed corrections, remote changes, and helper commands make the defender look too busy. Super DefenderDetects repeated phone/Home Assistant thermostat changes and tightens correction timing without cutting thermostat Wi-Fi. Tamper TruceIf the thermostat vanishes right after a correction exchange, assume a frustrated person detached it — stand down 2 hours instead of escalating. Telemetry AlibiWaits for a normal Home Assistant/weather/usage update before a safe correction, so the nudge is not an isolated event. Thermal MomentumWaits when the room is already cooling fast enough to reach target soon on its own. Thermostat OFF super-confirmationOpen the documented feature brief. Touch IntentReads whether recent wall changes trend warmer, cooler, or mixed, and extends grace for a clear warmer pattern. Touch SignatureMatches safe nudges to the size of steps people actually use on the wall thermostat. Tug-of-War TruceCalls a temporary truce when the real thermostat bounces up and down, so answer-back commands do not look like a duel. Upstairs Comfort GuardPrioritizes cooling when upstairs rooms get hot while someone is home. Visibility GuardSlows the next safe nudge when a wall touch lands right after a defender command (someone likely noticed). Wake-Up Truce (door sensor)A bedroom door opening at dawn means that person is awake — adopt the warm truce temperature before they ever touch the thermostat. Wall SettlingWaits for someone who is still tapping the wall thermostat to stop before correcting. Weather Drift TimingTimes safe corrections to real outdoor-weather movement instead of firing immediately. Website DebounceBlocks repeated website button taps for two minutes so the UI does not spam Home Assistant. Website TourOpen the documented feature brief. Windows Electron controllerOpen the documented feature brief. Windows HTTPS update-feed contractOpen the documented feature brief. Yelling PredictionsEvery Yell-O-Meter bill band, possible household consequence, uncertainty boundary, and factual input. Yelling Survival GuideA practical before, during, and after playbook for the Yell-O-Meter, with honest limits and immediate-safety routes.