Skip to content

Heartbeat Service

Overview

The Heartbeat service listens to a heartbeat sent from a client device in your home, and sends an email alert when the heartbeat has not been received for 15 minutes. Only one email will be sent to inform you of the missing heartbeat -- the next email will be sent when the heartbeat is restored again.

To use the service, the following needs to be done:

  1. Create an account at the Hausnet App Site, and obtain an API key. See the App section for instructions.
  2. If you're setting up a client on a Home Assistant device, follow this procedure.
  3. If you're using the service directly using the API, the API is documented here.

Heartbeat Device

In order to use the service, a representation of the device that will be monitored must be created inside the App system. This device will have a name, which is the identity for the client device.

To create a device:

  1. Click the "Create one now" link on the Heartbeat Dashboard.
  2. Provide the device name.
  3. Click "Submit".

Home Assistant Component

Install

Via the excellent HACS component for Home Assistant, the Heartbeat client can be installed as a custom component. First step is to install HACS itself - follow the instructions here.

After installing HACS, and restarting your Home Assistant, install the Heartbeat component as a custom repository, following these steps:

  1. Click on "HACS" in the Home Assistant sidebar menu
  2. Click on "Integrations"
  3. From the top right "vertical dots" menu, pick "Custom repositories"

  4. Enter this repository URL:

    https://github.com/HausNet/heartbeat-hass

  5. And select "Integration" in the "Category" select list.

  6. Then click "Add", and restart Home Assistant.

Enable the Service

After restart, enable the Heartbeat integration by following the usual route for installing a new component:

  1. Go to "Settings" in the sidebar menu.
  2. Click on the "Add integration" button at bottom right.
  3. Search for "Heartbeat", and click on the integration when it is found.
  4. Enter the API key you obtained when registering at the Apps Site.
  5. Enter the device name of the device you created at the Apps Site.
  6. Click "Submit".

You will be asked again to restart Home Assistant to activate the new configuration. Once that is done, the Home Assistant device will start sending heartbeats to the service, and the service will report missing heartbeats via an email to you.

API

The API is documented with Swagger. The API documentation can be viewed here.

Authentication is required, and is done via an API key in the request headers. The API key is available via the App Site, and needs to be set in the request header like this:

    Authorization: Token 9944b091a9c62bcf9418ad846dd3e4bbdfc6ee4b

In addition to the token, the API requires a device to be defined at the service. This device represents your home automation system at the service, and its name is needed to generate a heartbeat for the actual device.