Dog tracking collar simulator: a HEART-embedded system you can run and watch#

A demonstration only. It simulates a dog, its owner, a tracking collar and its HEART. There is no collar and no dog. Every position is in metres east and north of a made-up home origin: there is no latitude or longitude anywhere in it, and it never names a real place.

One Python file, dogCollarSimulator.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 dog's day: sleep at night, rest and play in the garden, walks with the owner, now and then a slip through the gate and a wander alone, and a collar whose battery, GNSS, uplink, temperature and accelerometer sometimes fail.

It teaches one lesson above all: where the dog is, is the most private thing the collar knows. The position reveals where the owner lives and walks, and where the dog is right now. So it is private, and the dog leaving its safe zone is a private event for the owner, never an alert and never sent to HEART Hub. Only the collar's health (status and fault codes) goes there.

It also shows one change that runs at once and two that wait for a person: lost mode (more frequent reporting, nothing the dog feels) runs at once with the owner key; the LED and the buzzer act on a living animal, so they wait for the owner's proof of presence, and the buzzer has a welfare guard.

The case study behind it, step by step for a real product, is guides/Dog-Tracking-Collar.md.

On a real device: Dog Tracking Collar, 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 dogCollarSimulator.py --scenario all --clock 09:00

It starts at once and prints three things:

  HEART Hub: register this simulated dog collar
    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=8e2b4f1c07a9d356
    3. Enter the claim code  R3K8M-7XQBA-2PTVW-HN6DZ
    4. Watch it at https://heartcortex.ai/device/8e2b4f1c07a9d356  (private to you until you share it)

11:07:44 HEART API on http://127.0.0.1:43281/heart/v1/pulse  (owner key for private views: ...)
11:07:44 09:00 dog rest · collar on · resting · in safe zone · GNSS off · uplink home base · lost mode off ·
         battery 15.5 % (~279 h) · 29.2 Cel · HEART healthy

Every 15 seconds it prints one line: the simulated time of day, what the dog is doing, what the collar measures, and the HEART's status. When something goes wrong, the HEART says so. When the dog leaves the safe zone, the collar's own firmware tells the owner's app, privately; the HEART has nothing to say about it:

11:08:06 PRIVATE  zone.left: The dog has left the safe zone alone, 93 m from home. Turn on lost mode to follow it
         every 30 s. (waiting for the uplink, then to the owner's app only; never to HEART Hub)
11:08:16 HEART error    performance.too-hot: The collar is too hot. The collar is 46.1 Cel, above 45 Cel: too hot
         for its battery. The collar has warned the owner privately about the dog.
11:08:20 HEART resolved   performance.too-hot: the collar is too hot

Stop it with Ctrl-C. The device ID, claim code and key are kept in dog-collar-monitor.json (readable only by you), so the same simulated collar 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. Sharing it shares the collar's health, never where the dog is.
5. Silence. Stop the simulator, or wait for the staged uplink loss: 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. When it reports again, you get one more.

Until you register it, the site stores nothing: the simulator's reports are answered "not registered yet" and dropped. 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 position, a distance, the track, a safe-zone event, the activity, lost mode or a reading. A "the dog has left the safe zone" message is not a fault code, so it cannot reach the site at all.

Your own monitor site. If you would rather keep even the collar's health on your own machine, run your own HEART Hub server (ownMonitorServer/README.md) and point the simulator at it:

node ownMonitorServer/server.mjs &
python3 dogCollarSimulator/dogCollarSimulator.py --monitor-url http://127.0.0.1:8787 --scenario all --speed 5

3. The staged faults#

With --scenario, each event starts at a set time, lasts a while, and is then put right by the owner, so you can watch an alert open, escalate and resolve. Times are in simulated seconds: at --speed 1 they are real seconds. While a staged scenario that moves the dog is chosen, the random walks and wanders are off, so the staged ones are easy to follow.

If the collar had no fix and no uplink at once, away from home, or a battery at 3 %, it would raise system.main-function-lost (critical): the owner could not be told where the dog is. The staged events do not overlap that way, but the rule is there.

Without --scenario, life goes on at its own pace: sleep from 22:00 to 06:30, walks every 3 to 7 hours by day (20 to 45 minutes), play in the garden, a poor sky under trees now and then on a walk, an uplink loss every 1 to 4 days, and a wander every 3 to 10 days.

The "may have slipped off" check uses 3 minutes so that the demo is short. A real collar would wait much longer (about 30 minutes), and on a hot day, when a collar on the grass is as warm as one on a dog, it cannot tell at all. That is why it is a warning that says "HEART cannot be sure", not a certainty.

4. Options#

5. The local HEART API#

The simulator also serves the HEART API on your own computer, as a real collar's HEART would (see the case study, Step 1, for where that runs):

curl http://127.0.0.1:43281/.well-known/heart-card.json         # the Card: what it is (no capabilities in public)
curl http://127.0.0.1:43281/heart/v1/pulse                       # public health
curl http://127.0.0.1:43281/heart/v1/arrhythmias                 # public alerts: codes only
curl http://127.0.0.1:43281/heart/v1/properties                  # public values: the battery only
KEY=...   # the owner key it printed
A="Authorization: Bearer $KEY"
curl -H "$A" http://127.0.0.1:43281/heart/v1/properties          # all values: position, activity, lost mode, readings
curl -H "$A" http://127.0.0.1:43281/heart/v1/arrhythmias         # alerts with explanations
curl -H "$A" http://127.0.0.1:43281/heart/v1/rhythm              # the private events: zone.left, zone.returned, heat.risk
curl -H "$A" http://127.0.0.1:43281/heart/v1/track               # the private track: every GNSS fix
curl -H "$A" http://127.0.0.1:43281/heart/v1/actions             # every change you made (heart.action)
curl http://127.0.0.1:43281/heart/v1/lifecycle                   # running (public); with the key, what it allows

The privacy of every value:

Your own changes. Lost mode is not physical, so with the owner key it runs at once. The LED and the buzzer are physical, so they wait for you:

curl -H "$A" -X POST -d '{"arguments":{"on":true}}' http://127.0.0.1:43281/heart/v1/capabilities/collar.lost_mode/invoke
         # 200, succeeded: GNSS and reports every 30 s. The result shows the cost, for example
         # "batteryHoursLeft": 279.5 before, 3.3 after (at 15 % charge), and the new average current
curl -H "$A" -X POST -d '{"arguments":{"mode":"blink"}}' http://127.0.0.1:43281/heart/v1/capabilities/collar.led/invoke
         # 202, awaiting-approval; the console shows a 6-character code
curl -H "$A" -X POST -d '{"decision":"approve"}' http://127.0.0.1:43281/heart/v1/actions/<ID>/decision
         # 403 presence-required: the key alone cannot approve it
touch button.press        # in the simulator's working directory: the owner confirmed. It runs.
curl -H "$A" -X POST -d '{"arguments":{"volume":40,"durationSec":3}}' http://127.0.0.1:43281/heart/v1/capabilities/collar.buzzer/invoke
         # 202, waits for the button the same way
curl -H "$A" -X POST -d '{"arguments":{"volume":80,"durationSec":3}}' http://127.0.0.1:43281/heart/v1/capabilities/collar.buzzer/invoke
         # 409 guard-failed: above the safe 50 % for a dog's ears

About button.press. In a real collar the proof of presence is the owner confirming the change on their phone with a passkey (WebAuthn, over the exact Action digest), because nobody presses a button on a dog's neck. This simulator does not check a passkey: it checks for a file in its working directory, and records the decision honestly as presenceMethod: device-button. An approval sent over the network with only the key is refused with 403 presence-required; one with any presence object is refused with 403 presence-invalid, because the simulator cannot verify a passkey.

The buzzer's guard is in the collar, not in HEART: never louder than 50 %, never longer than 5 s, never sooner than 60 s after the last time (409 guard-failed, checked when you ask and again after you confirm). Outside the hardware's range (0 to 100 %, 1 to 30 s) it is 422 out-of-range. A waiting change expires after 10 minutes. Any other change (the safe zone, GNSS, the uplink, a property) gets 403 capability-not-allowed: those are set in the owner's app, not through HEART.

Every message it serves is a valid HEART message: test_e2e.py checks each one against the official schemas.

Sleep until a stated time#

The collar can go into deep sleep and wake at a time you choose, to save its battery (module lifecycle, API Standard 13.2 rule 3). It can also restart.

curl -H "$A" -X POST -d '{"durationSec":600}' http://127.0.0.1:43281/heart/v1/lifecycle/sleep
         # 202: the Action, running, with nextReachableAt: when the collar answers again
curl -H "$A" -X POST -d '{"wakeAt":"2026-11-13T06:30:00Z"}' http://127.0.0.1:43281/heart/v1/lifecycle/sleep
         # the same, until a stated time (UTC)
curl http://127.0.0.1:43281/heart/v1/pulse
         # asleep: "connection refused". The collar answers nothing at all
touch button.press        # wakes it early, as the collar's button would
curl -H "$A" http://127.0.0.1:43281/heart/v1/actions/<ID>
         # awake: succeeded, with wokeBy timer or button
curl -H "$A" -X POST http://127.0.0.1:43281/heart/v1/lifecycle/restart
         # a graceful restart: away for about 3 s, then back

What sleeping means. Half a second after the reply, the simulator closes its HTTP port, so every call is refused. The collar stops its work: no GNSS, no safe-zone check, no reports to the owner's app, no heat warning, no HEART noticing, nothing to HEART Hub. Only its clock runs, and the battery drains at the tiny sleep current. The dog's day goes on. It wakes by its timer or by its button: those are its wakeSources. wake is not offered (501): a collar in deep sleep cannot hear a request to wake.

Time. durationSec counts simulated seconds, like the staged events: at --speed 5, durationSec: 600 is 2 real minutes. wakeAt and nextReachableAt are real UTC times, like every time in a HEART message. nextReachableAt is the wake time plus 3 seconds to start again.

Safety: when it will not sleep. The collar's safety job is to tell the owner where the dog is, and to warn of a hot dog. Asleep, it can do neither, and it will not notice the dog leaving. So it refuses to sleep with 409 conflict while any of these is true:

GET /heart/v1/lifecycle with the key lists sleep in allowed only when none of these holds. A real collar should also wake on movement (the accelerometer's wake-up line) so that a dog that leaves while it sleeps is noticed. The standard has no wake source for that yet, so this simulator does not claim one: sleep it only when the dog is safely at home. HEART Hub cannot tell sleep from a dead collar: a sleep longer than three Pulse intervals (90 s) shows a Flatline there, and you get its email.

Refusals (rule 3):

Sleep and restart are risk write, not physical, and you are a human with the owner key, so they run at once (Section 6.3). The Action is not cancellable: the collar cannot be reached to cancel it. A change waiting for your button is cancelled when the collar goes to sleep. The LED goes dark while it sleeps and comes back as it was.

6. How the code is built#

Dog  ──►  Collar  ──(reads)──►  Heart  ──►  local HEART API      (127.0.0.1)
day,       GNSS, uplink,          watches     └►  HEART Hub    (outbound only: status and fault codes)
walks,     accelerometer,         owner ──(key)──► collar.lost_mode           (not physical: at once)
wanders    temperature, battery,  owner ──(passkey; here button.press)──► collar.led, collar.buzzer  (physical)
           safe zone ──► private events for the owner's app (never HEART Hub)

The HEART reaches the collar through three setters only, set_lost_mode, set_led and buzz, and the two physical ones sit behind presence and the collar's guard. HEART never uses the LED or the buzzer by itself, not even to escalate: they act on the dog.

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

For a real collar, the noticing runs on the collar's own microcontroller, with no network, and the HEART API and HEART Hub reporting run where there is power to spare: the home base or the owner's phone app (see Step 1 of the case study). Pick a starting point, then add four things.

Starting points

The four things you add

1. Read the collar. Replace Dog and Collar with reads from your firmware: the fuel gauge, the GNSS receiver's fix and satellite count, the modem's link state, the accelerometer, the temperature sensor. The position stays where it is: the HEART needs only whether there is a fix, never where.

``python class Readings: """CHANGE: fill these from your firmware. Read only, except the three settings behind the gate.""" def refresh(self): f = your_firmware.status() # your code self.battery, self.temp = f.battery_pct, f.temp_c self.gnss_state, self.sats, self.fails = f.gnss.state, f.gnss.satellites, f.gnss.failed_in_a_row self.pos_age = f.seconds_since_last_position # an age, not a position self.link_down, self.home_base = not f.uplink_up, f.home_base_in_range self.accel = f.accel_xyz ``

2. Your rules and thresholds. Edit RULES and EXPLAIN with your own limits (the battery level that is really low, the temperature your cell can stand). Keep the standard fault codes (Part 3). Keep the dog's facts out of them: leaving the safe zone, a hot dog, a dog that is lying still are not collar faults.
3. Your escalation route. Change escalate() to a notification in the owner's app. Do not use the LED or the buzzer for it: they act on the dog.
4. Your privacy table. Go through properties() and give every value its level (Step 3 of the case study). The position, the track, the safe zone and the activity are private; only status, fault codes and the battery are public. Keep the safe zone's centre in the app, or encrypted on the collar, never in a HEART message to anyone but the owner.

Then keep monitor() as it is, store the device ID, claim code and key in the collar's secure storage, and print the claim code and a QR code of https://<your monitor site>/register?id=<ID> on a card in the box. Serve the API over TLS (or keep it on loopback), run the HEART-Rating client (heart-rating/client/heart_rating.py) and Part 9's tests, and claim HEART Basic, Autonomy Level A1.

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 dogCollarSimulator/test_e2e.py

It starts a HEART Hub site on this computer (port 8808), runs the simulator with every staged event at 5x speed from a simulated 09:00 (local API on port 43308), signs in, registers the device through the site's own form, and checks for about four and a half minutes that: every message is valid (private events and Actions included); public views hold only public data and no location at all; lost mode runs at once with the owner key and its Action shows the battery cost; an LED change and a buzz wait, are refused over the network with 403 presence-required, and run after touch button.press; the buzzer guard refuses loud, long or too-soon buzzing; other changes are refused; the wander is a private zone.left event and never an alert; the hot car is both a private warning and the performance.too-hot fault; every staged fault reaches the owner's page with its fault code; no position, coordinate, safe-zone event, activity or lost mode reaches the site; and the page stays private. Before that, on a second simulator (port 43309, no staged events), it checks the lifecycle: the Card, every refusal, a sleep that refuses connections until its stated time and then says succeeded, a sleep woken early by button.press, and a restart. On the main one it checks that the collar will not sleep while lost mode is on or the dog is outside the safe zone.

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