Smart thermostat simulator: a HEART-embedded system you can run, watch and ask to change things#

A demonstration only. It simulates a house, a smart thermostat, a gas boiler and the thermostat's HEART. It switches no real heating and must never be connected to a boiler or heat pump.

One Python file, thermostatSimulator.py, with only the standard library. Run it, register it on HEART Hub with the code it prints, and watch its health on your own private page while it lives a simulated life: day and night, cold and mild spells, sunshine, windows opened now and then, people coming and going, a boiler that cycles on and off. Faults come and go: strong sun overheating the room, a lost Wi-Fi link, a frozen room sensor, an impossible reading, a boiler that will not light, a boiler that short-cycles, and flat batteries in the wall unit.

Unlike the pacemaker simulator, this HEART also takes changes. The owner can change the setpoint, the night temperature and the mode through the local HEART API. Heating acts on the physical world, so every change waits for a person to press the thermostat's own button. A clearly labelled mock AI suggests ways to save energy, and its suggestions wait for the same yes. They never run on their own.

The case study behind it, step by step for a real product, is guides/Thermostat.md (Guide 5).

On a real device: Thermostat, for real shows the hardware we assume, where the HEART runs, the code to change, how to build and install it, the factory steps and what the owner sees. For illustration only.

1. Download and run#

You need Python 3.8 or newer. Nothing to install.

python3 thermostatSimulator.py --scenario all

It starts at once and prints three things:

  HEART Hub: register this simulated thermostat
    1. Sign in at https://heartcortex.ai/login with your email (a 6-digit code is sent to you).
    2. Open https://heartcortex.ai/register?id=5b1e0c93a7d2f418
    3. Enter the claim code  Q4M7T-ZX2KD-9RBVA-H3NPW
    4. Watch it at https://heartcortex.ai/device/5b1e0c93a7d2f418  (private to you until you share it)

10:50:09 HEART API on http://127.0.0.1:43278/heart/v1/pulse  (owner key for private views: ...)
10:50:24 room  20.3 C · target 20.0 (heat) · CALL · boiler ON  flow 61.8 C starts 1 · outdoor   5.4 C · battery 2.98 V · wifi up · HEART healthy

Every 15 seconds it prints one line of what the simulated thermostat knows. When something goes wrong, its HEART says so:

10:52:21 HEART critical system.main-function-lost: The boiler does not heat when the thermostat calls for heat.
         Called for heat for over 2 minutes, but the burner has not fired (the boiler reports a lockout). The house
         will get cold. Check the boiler's display and gas supply, or call the installer. No fix HEART can make: it
         never resets a boiler.
10:53:42 HEART resolved   system.main-function-lost: the boiler does not heat when the thermostat calls for heat

And when a change is waiting for a yes, the thermostat's "display" shows it with a short code:

10:51:10 THERMOSTAT DISPLAY  Night temperature: 20 to 18 °C at night?  code 01ED72  (press the button within 900 s: touch button.press)

Stop it with Ctrl-C. The device ID, claim code, key and the monitor site's signing key are kept in thermostat-monitor.json (readable only by you), so the same simulated device comes back next time. Delete that file to make a new device.

2. Register it and watch it on HEART Hub#

1. Sign in. Open https://heartcortex.ai/login and enter your email address. A 6-digit code arrives; type it in. There are no passwords.
2. Register. Open the register?id=... link the simulator printed, and enter the claim code. The claim code is the proof that you hold the device: it is shown only on the simulator's console, and the site holds only its hash.
3. Watch. Your device's page, https://heartcortex.ai/device/<ID>, shows its status (healthy, degraded or failing) and its open and recent alerts, each with the plain-language meaning of its fault code. All your devices are at https://heartcortex.ai/devices.
4. Share, if you want. The page is private until you make a share link or make it public.
5. Silence. Stop the simulator: after three missed Pulse intervals (90 seconds) the page shows a Flatline, and you get one email. The site checks for silent devices every 5 minutes, so the email can take a few minutes more. (The staged Wi-Fi loss lasts 200 simulated seconds: at --speed 1 that is long enough for a Flatline, at --speed 5 it is not.)

Until you register it, the site stores nothing. After registering, it can take up to five minutes for the first report to arrive, or less as soon as something changes.

What the site sees. Only the public Pulse and public alerts, and it keeps only the status and timing and each alert's fault code, severity and times. Never a temperature, the boiler's state, the schedule, or whether anyone is home. The one exception is opt-in: see approvals on the site, below.

Approvals on the site (optional, off by default)#

With --monitor-approvals, the HEART also offers a waiting change to its owner on the monitor site, as the Python template's ask_owner() does (HEART Hub, Section 7.1). The site sees only a title and a change in plain words, such as "Night temperature: 21 to 18 °C at night", never the hours of the night schedule or anything about who is home. The owner turns approvals on for the device on its page, presses Approve…, and types the code the site emails them. The device acts only after it has checked the site's Ed25519 signature on the decision with the key it pinned at its first hello, that the digest is the waiting Action's (API Standard 6.3), and that the decision is at most 300 seconds old. It records the approval as presence method remote-site.

Every change on a thermostat is physical, and remote-site proves only that the owner could read their inbox, not that anyone stood in the house. So physical changes are offered on the site only with a second flag, --monitor-approvals-physical (the owner's remoteSitePhysical setting, Part 6 Section 3.2). Without it, the site never sees a thermostat change, and the button is the only way to say yes. Resuming after Stop is never offered on the site.

Note for heartcortex.ai. Approvals need the site to have its signing key. The live heartcortex.ai must be redeployed with SITE_SIGNING_KEY set before approvals work there; until then the owner's page says approvals are not available, and everything else works. The local test site (heart-monitor/test/serve.mjs) has a test key, and test_e2e.py uses it.

3. The staged faults#

With --scenario, each fault starts at a set time, lasts a while, and is then "fixed by the installer", so you can watch an alert open, escalate and resolve. Times are in simulated seconds: at --speed 1 they are real seconds.

Without --scenario, the house still has random weather, sun, open windows and Wi-Fi losses (every 3 to 9 hours), as in life. A long run with no scenario raises only those.

4. Options#

5. The local HEART API#

The simulator serves the HEART API on your own computer, as a real thermostat's hub would:

curl http://127.0.0.1:43278/.well-known/heart-card.json         # the Card: what it is
curl http://127.0.0.1:43278/heart/v1/pulse                       # public health
curl http://127.0.0.1:43278/heart/v1/arrhythmias                 # public alerts: codes only
curl http://127.0.0.1:43278/heart/v1/properties                  # public values: battery status only
curl http://127.0.0.1:43278/heart/v1/tending/autonomy            # max 3, mode suggest; max 2, mode observe after Stop
KEY=...   # the owner key it printed
A="Authorization: Bearer $KEY"
curl -H "$A" http://127.0.0.1:43278/heart/v1/properties          # all values, internal and private
curl -H "$A" http://127.0.0.1:43278/heart/v1/arrhythmias         # alerts with explanations, cause and confidence
curl -H "$A" http://127.0.0.1:43278/heart/v1/actions             # every change asked for, and what became of it
curl -H "$A" http://127.0.0.1:43278/heart/v1/rhythm              # private history: actions, occupancy, windows

Changing things. Every change needs the owner key, and every one acts on the heating, so it is physical:

P=http://127.0.0.1:43278/heart/v1/properties/org.heartaispec.demo.thermostat
curl -X PUT -H "$A" -d '{"value": 21}' $P.setpoint             # 202: an Action waits; the display shows a code
curl -X POST -H "$A" -d '{"decision":"approve"}' http://127.0.0.1:43278/heart/v1/actions/<id>/decision
                                                                 # 403 presence-required: a key is not a person
touch button.press                                               # a press on the thermostat: it runs
curl -X PUT -H "$A" -d '{"value": "eco"}' $P.mode              # heat, eco (setpoint - 3 °C) or off (frost protection only)
curl -X PUT -H "$A" -d '{"value": 18}' $P.night_setpoint       # 23:00 to 06:00; null to turn it off
curl -X POST -H "$A" -d '{"decision":"deny"}' http://127.0.0.1:43278/heart/v1/actions/<id>/decision   # no proof needed
curl -X POST -H "$A" http://127.0.0.1:43278/heart/v1/tending/stop   # Stop: at once; or touch button.hold
curl -X PUT -H "$A" -d '{"max":3}' http://127.0.0.1:43278/heart/v1/tending/autonomy   # resume: waits for the button

Autonomy. A person sets the ceiling max; the current level is the lower of max and the promised level 3, and the mode follows from it: 3 is suggest, 2 or below is observe. Stop sets max to 2, and so does PUT /heart/v1/tending/autonomy with a max of 2 or below, at once. Raising it back to 3 is destructive and waits for the button. The owner's Pulse shows autonomy with max, current, and limitedBy: stopped while max is below 3.

Only one change waits at a time, so one press can never approve the wrong thing. The mock AI (MockAI in the file, plain rules over the private occupancy log, no model and no network) waits until nothing else is waiting, then offers its suggestion as an ai Action with onBehalfOf: owner. Because it is physical and started by an AI, the gate treats it as destructive: it always waits for a person, whatever is configured, and after Stop it does not suggest at all.

Every message it serves is a valid HEART message: test_e2e.py checks each one against the official schemas. Two simplifications: the simulator honours an Idempotency-Key header but does not insist on one, as API Standard 5 requires of a real system; and the API is plain HTTP on loopback only.

6. How the code is built#

House ──► Thermostat (firmware: control loop, limits) ──► Boiler (its own firmware)
             ▲  │ read                                       │ read
   apply()   │  ▼                                             ▼
   (clamps)  └── Heart ◄─── MockAI (suggests only)
                  │  watches, gates changes, tells a person
                  ├─► local HEART API    (127.0.0.1; owner key; button for physical changes)
                  └─► HEART Hub      (outbound only; approvals only with the flags)

HEART is not in the control loop (Part 6, Section 9): the firmware decides each second whether to call for heat. HEART changes only the targets the loop works to, only through Thermostat.apply(), which keeps the firmware's limits, and only after a person's yes.

7. What code to add to make a real product HEART-embedded#

For a real thermostat, HEART runs on the hub: the part with Wi-Fi, beside the boiler-control firmware, never inside it. Pick a starting point, then add four things.

Starting points

The four things you add

1. Read the thermostat. Replace House, Thermostat and Boiler with reads of values your firmware already has: room reading, target, call for heat, the boiler's OpenTherm status (firing, flow temperature, fault flags), battery voltage, Wi-Fi state.

``python class Readings: """CHANGE: fill these from your firmware. Read only.""" def refresh(self): f = your_firmware.status() # your code self.raw, self.reading, self.call = f.room_raw, f.room_filtered, f.call_for_heat self.firing, self.flow, self.lockout = f.ot_flame_on, f.ot_flow_temp, f.ot_fault self.months, self.wifi_up = f.battery_days / 30.44, f.wifi_connected ``

2. Your rules, thresholds and guards. Edit RULES and EXPLAIN with your product's limits, keeping the standard fault codes (Part 3). Keep the guards (guard()) and limits (apply()) in the firmware, where HEART cannot remove them: HEART asks, the firmware decides.
3. Your presence and escalation routes. Wire the "button" to a real press on the wall unit (and show the 6-character code on its display), and Stop to a long press. Change escalate() to notify the owner's app, and to show the problem on the thermostat itself, with no internet needed.
4. Your privacy table. Go through PROPS and give every value its level (Step 3 of the case study). Occupancy, windows and the schedule are private; only status and fault codes are public.

Then keep monitor() as it is, store the device ID, claim code, key and pinned site key in the hub's secure storage, and print the claim code and a QR code of https://<your monitor site>/register?id=<ID> on a label in the box. Serve the API over TLS, run the HEART-Rating client (heart-rating/client/heart_rating.py) and Part 9's tests, and claim what passed. The simulator's Card promises Autonomy Level A1: it demonstrates the A3 gate ("suggests and waits for a yes"), but Part 2 Section 8 says a claim of A3 needs HEART Full, which this one-file simulator does not implement in full. Case study, Step 10.

8. Test it#

From the project's top folder, with Node 20+ and Python 3 with pip install --user "jsonschema[format]>=4.18" referencing:

python3 thermostatSimulator/test_e2e.py

It starts a HEART Hub site on this computer (port 8802), runs the simulator with every staged fault at 5x speed (API on port 43302) with approvals on the site allowed, signs in, registers the device through the site's own form, and checks for five minutes that:

• every message is valid against the official schemas, and public views hold only public data;
• out-of-range setpoints are refused 422, the firmware's limits 403, and a second change too soon 409 guard-failed;
• a setpoint change waits: approving with the key is refused 403 presence-required, it stays waiting with the setpoint unchanged, and runs after touch button.press;
• a waiting change can be denied without the button;
• the mock AI's suggestion is refused with the key, then expires, and nothing changes; its next one runs only after the owner approves it on the site, with an emailed code, and the device checks the signature (remote-site);
• Stop cancels a waiting change at once, and resuming needs the button;
• every staged fault reaches the owner's page with its fault code, no temperature, occupancy or schedule reaches the site, and the page stays private.

Licence: Apache-2.0. Part of HEART, the open standard at heartcortex.ai.