HomeKit Active Hub Monitoring

Avaliable on DockerHub

This project aims to provide monitoring and optionally restart of your HomeKit Hubs - Apple TV, HomePod (mini, OG).
Monitoring is done by configuring an advanced automation in HomeKit which will report the state to the Docker container. In case the currently active Hub crashes/hangs or otherwise stops running this automation the container will notify you about the issue and optionally (if you have your Hubs plugged into smart outlets) restart the last known active HomeKit hub.

Supported notification methods

E-mail
Telegram

Supported smart outlets

IKEA Tradfri Wireless Outlet + IKEA Tradfri Hub

Requirements

Docker host running on amd64, armv7 or arm64 - Raspberry Pi or any modern Intel/AMD powered computer or VM
(Optional) IKEA Tradfri Wireless Outlets + IKEA Tradfri Hub

Usage

Command Line:

docker run --name homekit-monitord -e IKEA_USER=ikea_hub_user -e IKEA_HUB_ADDR=ikea_hub_ip -e IKEA_TOKEN=ikea_hub_token -e HOMEKIT_HUBS="10.10.10.20:200 10.10.10.30:200 10.10.10.40:200" -e NOTIFY_EMAIL="me@example.com" -e EMAIL_SENDER="bot@example.com" -e EMAIL_SERVER="smtp.gmail.com" -e EMAIL_PORT="587" -e EMAIL_PASSWORD="secret" -e RESTART_HUB=1 -e TELEGRAM_TOKEN=secret -e TELEGRAM_CHATID=chatid -d -p 8080:80 clickbg/homekit-monitord:latest

Using Docker Compose (recommended):

version: '3.6'
services:

  homekit-monitord:
    container_name: homekit-monitord
    restart: always
    image: clickbg/homekit-monitord:latest
    ports:
      - "8080:80"
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=Bulgaria/Sofia
      - RESTART_HUB=0
      - NOTIFY_EMAIL=me@example.com
      - EMAIL_SENDER=bot@example.com
      - EMAIL_PASSWORD=secret
      - EMAIL_SERVER=smtp.gmail.com
      - EMAIL_PORT=587
      - TELEGRAM_TOKEN=secret
      - TELEGRAM_CHATID=chatid
    healthcheck:
      test: curl --fail http://localhost/nginx_status || exit 1
      interval: 10s
      retries: 5
      start_period: 5s
      timeout: 10s

Parameters

Required parameters
-p 8080:80 - On which port should the container listen for Hub connections

Optional parameters
-e PUID=1000 - uid for the nginx process, leave at 1000 if unsure
-e PGID=1000 - guid for the nginx process, leave at 1000 if unsure
-e TZ=Bulgaria/Sofia - Timezone

Zigbee2MQTT Smart Outlets (read below for detailed instructions):
-e RESTART_HUB=1 - Binary value 1/0, dictates whether or not the container will try to restart the Hubs
-e HOMEKIT_HUBS=10.10.10.20:0xb4e3f9fffe22f3d2 10.10.10.30:0xb4e3f9fffe66f3d9 - List of the HomeKit Hubs in the format IP:IEEE_Address
-e MQTT_ADDR=mqtt://10.1.1.1/zigbee2mqtt - Support for SSL and auth avaliable as well, format is: mqtt(s)://[username[:password]@]host[:port]/topic

IKEA Smart Outlets configuration (read below for detailed instructions):
-e RESTART_HUB=1 - Binary value 1/0, dictates whether or not the container will try to restart the Hubs
-e HOMEKIT_HUBS=10.10.10.20:65609 10.10.10.30:65610 - List of the HomeKit Hubs in the format IP:IKEA_TRADFRI_ID
-e IKEA_USER=ikea_hub_user - IKEA hub user
-e IKEA_HUB_ADDR=ikea_hub_ip - IKEA hub IP
-e IKEA_TOKEN=ikea_hub_token - IKEA hub token

E-mail notifications (the container doesn't ship with e-mail server so please use your own or Gmail):
-e NOTIFY_EMAIL=me@example.com - The e-mail address of the person who will receive alerts
-e EMAIL_SENDER=bot@example.com - The username of the e-mail from which the alerts will be sent
-e EMAIL_PASSWORD=secret - The password of the e-mail from which the alerts will be sent
-e EMAIL_SERVER=smtp.gmail.com - The e-mail server from which the alerts will be sent
-e EMAIL_PORT=587 - The e-mail server port - common options 25, 465, 487

Telegram notifications (you can use both e-mail and Telegram, read below for detailed instructions):
-e TELEGRAM_TOKEN=secret - Telegram token
-e TELEGRAM_CHATID=chatid - Telegram chatid

Installation

Configuring advanced automation in HomeKit

Open the Home app
Click on + sign
Select Add New Automation
Select A Time Of Day Occurs
Set any date (we will change that later)
Select People Off and click Next
Scroll to the bottom of the page and click Convert To Shortcut
Click Add action and select URL
Click on the URL action and input your Docker container IP followed by /active-hub-report-health/ Example: http://10.10.200.200:8080/active-hub-report-health/
Click Add action and select Get Contents Of URL
Make sure the Get Contents Of URL action uses the URL variable Result:
Click Next and set a Name for the automation

Next we need to schedule this automation to run every 5 minutes. Unfortunately that is not possible in the Home app, so we are going to use a 3rd party app. You can do that with either Controller for HomeKit (the free version supports that), Home+ (paid), Eve for HomeKit (also free)

Open your app of choice and find the automation that we just defined in Home - Automations in Controller, Automation > Timers in Eve
Click on it and set Repeat to 5 minutes

Controller

Eve

Zigbee2MQTT Smart Outlet setup

Zigbee2MQTT like IKEA Tradfri can be controlled outside of HomeKit and has open, well documented format.

Getting access
If you are using Eclipse Mosquitto check out your mosquitto.conf for user/password/port/encryption.
Apart from that the configuration format is: mqtt(s)://[username[:password]@]host[:port]/topic.
The default topic for Zigbee2MQTT is zigbee2mqtt:
Example:
MQTT_ADDR=mqtt://10.1.1.1/zigbee2mqtt

Getting the Zigbee2MQTT ID of your outlets

Navigate to Zigbee2MQTT Web UI
Find the outlet and click on it
Copy the IEEE Address

IKEA Tradfri Smart Outlet setup

IKEA Tradfri smart outlet is ideal for us since it can be controlled outside of HomeKit and doesn't require internet.
If you want me to add support for other smart outlet please get in touch.

Getting access token
In the container there is a helper script which you can use to register and discover devices on your IKEA Tradfri Hub:

Enter the container
docker exec -it homekit-monitord /bin/bash
Run the interactive script, be prepared to enter the IKEA Hub IP and Registration Code (Found on the bottom of the Hub)
root@588e501a6cf1:/# /usr/local/bin/setup_tradfri.sh setup
Hub Security Code (Bottom of the device): CODE_FROM_THE_BOTTOM_OF_THE_HUB
Choose access username: CHOOSE_COOL_USER_NAME
Hub IP Address: ikea_hub_ip

Output:
Username: test2
Token: TOKEN
1.17.0033
Discover the smart outlet/s ID:
root@588e501a6cf1:/# /usr/local/bin/setup_tradfri.sh discover
Hub IP Address: ikea_hub_ip
Hub Username: ikea_hub_user
Hub Token: ikea_hub_token

Output:

{
"9001": "Office HomePod Outlet",
"9003": 65609,
"9002": 1649486154,
"9020": 1649832083,
"9054": 0,
"9019": 1,
"3": { "0": "IKEA of Sweden",
"1": "TRADFRI control outlet",
"2": "",
"3": "2.3.089",
"6": 1,
"7": 4353,
"8": 0
},

The ID is stored in property 9003, in our case the ID is 65609.
Now we can setup our container to restart this HomePod by entering the following properties in compose:
- RESTART_HUB=1
- HOMEKIT_HUBS=10.10.10.20:65609 10.10.10.30:65610
- IKEA_USER=ikea_hub_user
- IKEA_HUB_ADDR=ikea_hub_ip
- IKEA_TOKEN=ikea_hub_token