Support

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

Contact

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

API documentation

Everything below is for developers connecting their own sensors to Hearth.

Sending sensor readings to Hearth

Room sensors let Hearth aim for the temperature where you are, not just where the thermostat is. To use sensors of your own, or a bridge you run (a script, Home Assistant, a small computer next to your sensors' hub), send their readings to your home with its sensor key.

1. Get your home's key

In Hearth, the home's admin opens Settings, then Admin, then Sensor key, and taps Create key. Hearth shows it once; keep it somewhere safe. Creating a new key stops the old one working. 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.

{
  "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: 1 to 64 letters, digits, `-` or `_`. Hearth tells you when a source sends nothing for 10 minutes. Default: `api`.
`name`	Optional. How alerts name the source, such as "the garage hub" (up to 40 characters; set when the source's first sensor is added).
`sensors[].id`	Required. Each sensor's own id, the same every time: 1 to 64 letters, digits, `-` or `_`.
`sensors[].name`	Optional. The name of the sensor's room, up to 40 characters. Send a different one any time to rename it; its history stays.
`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. Default: now. A post no newer than the source's last post is ignored.

Include every measure a sensor has (humidity, battery) in its first post; measures added later aren't picked up. Send at most 10 sensors per post; a home holds at most 10 sensors. A post past either limit gets 400 and none of it is kept.

Hearth answers 204 when it read the post (readings it can't use, such as older ones, are skipped), 400 with the reason as text, 401 for a key it doesn't know, and 405 for anything but POST.

3. Turn the room on

The first time Hearth hears from a sensor that reports a temperature, it adds a room for it, switched off, so nothing about how your home is run changes yet. In Settings, then Admin, then Rooms, turn on the rooms you want Hearth to follow. A sensor that reports only humidity isn't added.

Example

curl -X POST "$HEARTH_URL" \
  -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. SenML can't carry names, so a new sensor's room is named from its id.