Support

Help with Hearth: Room Thermostat, the app for Daikin, Amana and Goodman smart thermostats, and thermostats Home Assistant runs.

Contact

Questions, problems or feedback? Email contact@meethearth.app and we'll get back to you.

Delete your account

In Hearth, open Settings and choose Delete account. A member leaves their home; a home's admin deletes the home, its history and everyone's access with it. See what's deleted.

Hearth Autopilot

Hearth Autopilot is the switch in Settings (anyone in the home can use it; it asks before changing). With it on, Hearth sets the thermostat to reach your rooms' targets and runs your schedule itself. On a Daikin, Amana or Goodman thermostat it turns off the thermostat's own schedule; through Home Assistant, turn the thermostat's own schedule off yourself. With it off, Hearth only watches: your schedule pauses, the Thermostat page mirrors the thermostat, and the thermostat and its own app are in full control.

With Autopilot on, a change made at the thermostat or in its own app is handled as chosen in Manage home, under When the thermostat is changed outside of Hearth: Leave it for a while (the default: Hearth waits before going back to its plan, 2 hours unless set otherwise under How long to leave it, and each further change restarts the wait) or Make it the new target.

Having your system serviced? Switch Autopilot off for the visit, so the thermostat is fully in the technician's hands, and back on once they're done.

Sensors

Room sensors let Hearth aim for the temperature where you are, not just where the thermostat is. A home has up to 10 sensors, from any mix of the sources below.

Govee is built in: Wi-Fi thermometers such as the H5179 and H5103, connected with the account's API key. No hub needed; readings arrive as often as each sensor sends them, every 10 minutes at the Govee Home app's fastest setting.
Ambient Weather is built in: a station's indoor and outdoor sensors, connected with the account's API key. No code needed.
Other sensors (Hearth API): for any sensors Hearth doesn't connect to directly (Home Assistant, ESPHome, SensorPush, a script of your own, another brand's hub), the system you run sends their readings to Hearth with the Hearth API, below.

Each built-in source's page has its setup steps; in Hearth, the home's admin connects it in Settings, then Manage home, then Sensors.

However they arrive, sensors are never added on their own. Each sensor Hearth hears from shows up under its source in Manage home, then Sensors, with Add. Add it, name it for the room it measures, and it gets a room of its own, not controlled by the thermostat yet. Tap the sensor to have the thermostat control its room, mark it as the sensor beside the thermostat (Hearth checks the thermostat's own reading against it, and follows it when the room you're following goes quiet), rename it or remove it. Removing a sensor keeps its history, and you can add it again while it still sends readings.

A sensor its source marks as outdoor (an Ambient Weather station's outdoor sensor, or "kind": "outdoor" below) is added as the home's outdoor sensor instead of a room, shown on History. A home has one; remove it to add another.

Without an outdoor sensor, History's outdoor lines are your thermostat's own outdoor reading, if it reports one, else the weather at the home's location (set in Manage home, under Home location) in the US. Without any of these, History simply has no outdoor lines.

Something not working with a sensor or its source? Email contact@meethearth.app with the source's name and what Manage home shows for it under Sensors.

Hearth API

Everything below is for developers sending readings from sensors Hearth doesn't connect to directly.

1. Get your home's key

In Hearth, the home's admin opens Settings, then Manage home, then Sensors, taps Other sensors (Hearth API) and taps Create key. Hearth shows it once; keep it somewhere safe. Replacing the key stops the old one working, and turning the Hearth API off removes the sensors added from it. Demo homes don't have one.

2. Send readings

Post JSON to:

https://api.meethearth.app/v1/readings

with the header Authorization: Bearer YOUR_KEY. Send each sensor's latest reading about once a minute; more often doesn't help. A room stops using a sensor after 10 minutes without a reading (the admin can change this in Manage home).

{
  "source": "garage-hub",
  "name": "the garage hub",
  "sensors": [
    {"id": "office", "name": "Office", "temperature": 70.7, "unit": "F", "humidity": 45, "battery": "ok"},
    {"id": "nursery", "name": "Nursery", "temperature": 21.5, "time": 1791070000}
  ]
}

Field	Meaning
`source`	Optional. What is sending: any text up to 128 characters, the same every time. Hearth tells you when a source with added sensors sends nothing for 10 minutes. Names of built-in integrations (such as `ambient`) are reserved. Default: `api`.
`name`	Optional. How Hearth names the source, such as "the garage hub" (up to 40 characters).
`sensors[].id`	Required. Each sensor's own id, the same every time: any text up to 128 characters, such as the device id its maker uses.
`sensors[].name`	Optional. Suggested as the sensor's name when it's added (up to 40 characters). After that, the name is the one set in Hearth.
`sensors[].kind`	Optional. `"room"` (the default) or `"outdoor"`: an outdoor sensor is added as the home's outdoor sensor, not a room.
`temperature`	A number. `unit` is `"C"` (the default) or `"F"`.
`humidity`	Relative humidity, 0 to 100.
`battery`	`"ok"`, `"low"`, or a percentage (20 or less is low).
`time`	When it was read: seconds since 1970, or an ISO 8601 time, within the last day and not in the future (10 minutes' leeway for clocks). Default: now. A post no newer than the source's last post is ignored.

Only sensors that report a temperature can be added. Include every measure a sensor has (humidity, battery) before it's added; measures added later aren't picked up. Send at most 10 sensors per post, in at most 64 KB.

3. Add the sensors in Hearth

After the first post, each sensor shows up in Manage home, then Sensors, under Other sensors (Hearth API), with Add. Until a sensor is added, Hearth doesn't keep its readings. A sensor that stops sending drops off the list after a day.

Responses

Status	Meaning
`204`	Read. Every sensor in the post is added, or there was nothing to keep (a reading no newer than the source's last is skipped).
`200`	Read, but some sensors aren't added yet. The body names them: `{"not_added": ["garage-hub:nursery"]}`, each as `source:sensor` (escaped as in SenML below). The added ones' readings were kept.
`422`	None of the sensors in the post are added yet, so nothing was kept. The body says which ones to add in Hearth.
`400`	The post can't be read, or a reading's time is outside the last day (or more than 10 minutes ahead); the body says why as text.
`401`	The key isn't one Hearth knows.
`403`	The key belongs to a demo home, which can't take readings.
`405`	Anything but POST.
`413`	The post is over 64 KB.
`429`	Too many posts: a home may send 12 at once, then 6 a minute. Wait the seconds the `Retry-After` header gives.

Every 2xx, 400 and 422 answer carries a Hearth-Home header: the home's id, the same whatever its key. A new key for the same home answers with the same id.

Example

curl -X POST "https://api.meethearth.app/v1/readings" \
  -H "Authorization: Bearer $HEARTH_KEY" \
  -H "Content-Type: application/json" \
  -d '{"sensors": [{"id": "office", "name": "Office", "temperature": 21.4}]}'

SenML

If your bridge already produces SenML (RFC 8428, a standard JSON format for sensor readings), it can post that instead of the JSON above: same address, same key. Most bridges should use the JSON above. A SenML post is an array of records, each named source:sensor.measure. This sends the same reading as the office example, from the source garage-hub:

[
  {"bn": "garage-hub:", "bt": 1791070000, "n": "office.temperature", "u": "Cel", "v": 21.4},
  {"n": "office.humidity", "u": "%RH", "v": 45},
  {"n": "office.battery", "u": "%EL", "v": 80}
]

The measures are temperature (unit Cel, °C only), humidity (%RH) and battery (%EL, a percentage). Records with other units or names are ignored. A pack holds at most 100 records, each read within the last day (10 minutes' leeway ahead). SenML can't carry names, so a new sensor is suggested a name made from its id. Because : and . separate the parts of a name, write them inside an id as %3A and %2E (and % as %25); Hearth reads them back as sent.