# Quick start **Pick what you want to do. Each path takes 5 to 20 minutes and needs nothing you do not already have.** | I want to... | Path | Time | |---|---|---| | See HEART working, with no code and no hardware | [Path 1: watch the live demos](#path-1-watch-the-live-demos) | 5 minutes | | Give my own program a HEART and watch it from anywhere | [Path 2: a HEART in Python, on HEART Hub](#path-2-a-heart-in-python-on-heart-monitor) | 15 minutes | | Put a HEART into a real product | [Path 3: choose a template](#path-3-choose-a-template-for-your-product) | 20 minutes to choose | | Know which parts of the standard I must read | [Path 4: pick a reading track](#path-4-pick-a-reading-track) | 5 minutes | | Try a HEART inside Docker | [Path 5: Docker with a HEART](#path-5-docker-with-a-heart) | 20 minutes | --- ## What HEART is, in one minute A **HEART** is a small, standard part that lives inside a product. It knows whether the product is doing its main job. When the job stops, it notices with no network and no AI, raises an alert with a standard **fault code**, and tells a person. - **Its API** is the same on every product: a public **Card** (who it is), a **Pulse** (how it is now) and **alerts** (what is wrong). - **HEART Hub** at heartcortex.ai lets the owner watch it from anywhere, on a private page. - **An AI model is optional.** It may explain and propose, but only a person, or rules the owner set, can approve a change. A Command Center can take the AI away at any time. --- ## Path 1: watch the live demos 1. Open [the live demos](/monitor/demos). Nine simulated products run there: a pacemaker, a thermostat, a dog collar, an EV charger, a greenhouse and more. 2. Pick one. Its page shows its Pulse, its alerts and what its HEART noticed, as it happens. 3. Watch a fault being staged, noticed and resolved. Each demo says which faults it stages, and when. 4. **Look inside** a demo to see the HEART's own replies: its Card, its Pulse and its alerts, exactly as the standard defines them. Every demo is also one Python file you can download and run on your own computer: see [Demo simulators](/docs#simulators). --- ## Path 2: a HEART in Python, on HEART Hub You need Python 3.8 or later, and an email address. **1. Get the template.** Download [the Python template](/downloads/heart-python.zip) and unzip it. It is one file, `heart.py`. **2. Make it yours.** Open `heart.py` and change the four lines marked `CHANGE`: ```python SYSTEM_ID = "org.example.my-product" # a reverse-DNS name under a domain you own NAME = "My Product" VERSION = "0.1.0" INSTANCE = "unit-1" # must not identify a person ``` Then write `check_main_function()`: return `(True, "")` while your program does its main job, and `(False, "what is wrong, in plain words")` when it does not. Leave it as it is for now to try the demo. **3. Turn reporting on.** Set `MONITOR = True`. Reporting is off by default, because watching is the owner's choice. **4. Run it.** ```sh python3 heart.py ``` At first start it makes a **device ID** and a **claim code**, and prints them once: ```text HEART Hub: register this device at https://heartcortex.ai/register?id=3f9c0a71b2d4e865 with claim code K7Q2M-... ``` It keeps them in `heart-monitor.json`. Keep that file, and keep it private. **5. Register it.** Open the address it printed. Sign in with your email address (a 6-digit code is emailed to you), enter the claim code, give the device a name, and press **Register**. The [HEART Hub owner's manual](HEART-Monitor-Owner-Manual.md) shows every step with screenshots. **6. Watch it.** Its page shows **Healthy** within 30 seconds. **7. Break it.** Create a file named `fault.flag` next to `heart.py`. Within 30 seconds the page shows **Failing**, with the alert `system.main-function-lost` explained in plain words. Delete the file, and the alert is resolved. **8. Silence it.** Stop the program. After three missed reports (at least 90 seconds) the page shows **Not heard from**, and HEART Hub emails you once. **Next:** [the Templates manual](/heart-templates/README.md) explains every option of the template. To ask the owner before a change, see `ask_owner()` in [the owner's manual](HEART-Monitor-Owner-Manual.md#9-approvals-a-device-asks-you-first). --- ## Path 3: choose a template for your product 1. Read [Choosing a template](/heart-templates/README.md#7-choosing-a-template): 17 templates, from Python and Go to C on bare metal, three assembly languages, WebAssembly and the ESP32. - **Server templates** are for anything with an operating system. - **Device templates** are for microcontrollers. 2. For a microcontroller with sensors and a button, start from the [ESP32 Full starter](/heart-templates/templates/esp32-full/README.md). It serves a signal table, explains alerts with a cloud model through a gateway, and carries out a physical command only after a press of the button on the device. 3. For a product that must approve changes, act on its own or use an AI brain, build on [HEART Core](/heart-core-rs/README.md), the reference runtime in Rust, and its daemon `heartd` ([configuration](/heart-core-rs/docs/CONFIGURATION.md)). 4. See a whole product worked through in [the product guides](/docs#guides), such as the [thermostat](/guides/Thermostat.md) or the [EV charger](/guides/EV-Charger.md). 5. Measure how closely your product follows the standard with [HEART-Rating](/heart-rating/README.md), a score from 0 to 10. --- ## Path 4: pick a reading track You do not have to read the whole standard. [Start here](/start) asks four questions and gives you one of three tracks: | Track | For | Reading | |---|---|---| | [1: Basic](/spec/HEART-Track-1-Basic.md) | Products that watch themselves and tell a person | About 1 hour 45 minutes | | [2: Intermediate](/spec/HEART-Track-2-Intermediate.md) | Products people log in to, change, update and approve | 1 hour 30 minutes to 2 hours more | | [3: Advanced](/spec/HEART-Track-3-Advanced.md) | Products that act on their own, use an AI brain, run fleets, or move | 1 hour 20 minutes to 4 hours more | Each track lists the exact sections to read, in order, and where to stop. --- ## Path 5: Docker with a HEART Docker Engine was given a HEART in two ways: rebuilt from source with the HEART inside its daemon, and as a sidecar beside the unchanged daemon. Both notice a restart loop, an out-of-memory kill and a failing health check within about 3 seconds. - [Docker with a HEART](/experimentalDocker/README.md): what it adds, and how to run it. - [Replicate it](/experimentalDocker/REPLICATE.md): every step, with the exact versions and commands. - [Screenshots of a live run](/experimentalDocker/screenshots/README.md): Docker on heartcortex.ai, with Claude recommending more CPU and the owner changing it from the site. --- ## Where next - [All documentation](/docs) - [The standard](/spec) - [Downloads](/downloads)