Skip to main content

HomeKit Controller smart home integration, free and open source

HomeKit Controller integration for Gladys Assistant

Pair and control your HomeKit Wi-Fi/Ethernet accessories from Gladys, no Apple hub needed.

View on GitHubAll external integrations

This integration turns Gladys into a HomeKit controller: it pairs directly with your Wi-Fi / Ethernet HomeKit accessories and controls them locally, without an iPhone, Apple TV or HomePod, and without any cloud.

Before you start​

  • A HomeKit accessory accepts only one controller at a time. If it is already in Apple's Home app (or in Home Assistant…), remove it there first. Otherwise, factory-reset the accessory.
  • Have the 8-digit setup code (123-45-678) at hand: it is printed on the accessory, its box or its manual.
  • The accessory must be on the same local network as Gladys.
  • Only IP accessories (Wi-Fi, Ethernet) are supported. Bluetooth and Thread accessories are not.
  • Gladys 5.1.0 or later is required.

Pair an accessory​

  1. Open the Configuration tab of the integration.
  2. Click Search for accessories. The list shows, for each accessory: its name, type, HomeKit ID, IP address and status (ready to pair, paired elsewhere, paired with Gladys).
  3. Click Pair an accessory and fill in:
    • Accessory: the name, ID or IP address shown by the search. If the search does not find it, type its address as IP:port (for example 192.168.1.20:51826);
    • Setup code: the 8 digits, with or without dashes.
  4. Pairing takes a few seconds (up to a minute on small modules). Then open the Discovery tab: the accessory's devices are ready to be added.

A HomeKit bridge gives one Gladys device per bridged accessory.

Supported devices​

HomeKit serviceIn Gladys
LightbulbOn/off, brightness, color, color temperature
Switch, outlet, valveOn/off
FanOn/off, speed
ThermostatTemperature, target temperature, humidity
Window covering, window, doorPosition, open / stop / close
LockLocked / unlocked
SensorsTemperature, humidity, illuminance, motion,
occupancy, contact, leak, smoke, CO, CO2,
PM2.5 / PM10 particles
BatteryLevel, low battery

Programmable buttons and doorbells are not devices: their presses trigger scenes (see below).

Other services (cameras, televisions…) are ignored for now.

Settings​

  • Refresh interval: HomeKit pushes changes in real time. Gladys also re-reads the whole accessory at this interval, as a safety net (60 s by default).
  • Search duration: how long the network is listened to during a search (10 s by default).

Actions​

  • Search for accessories: lists the HomeKit accessories on the network.
  • Pair an accessory: see above.
  • Identify a device: the accessory signals itself (blinks, beeps…), handy to spot it.
  • Unpair an accessory: removes the pairing from the accessory and from Gladys. For a bridge, all its devices are affected. Then delete the devices in Gladys.

Scenes​

Triggers ("When…"):

  • HomeKit button pressed: a button or a doorbell was pressed. Optional filters: the device, the press type (single, double, long) and the button number (for a remote with several buttons). Variables: accessory, button, button number, press, doorbell.
  • HomeKit accessory offline / back: an accessory became unreachable, or came back. Optional filters: the device and the status. For a bridge, each bridged device sends its own event.

To pick a button in the "Device" filter, the accessory must have created a device in Gladys (for example through its battery). Otherwise, leave the filter empty.

Actions ("Then…"):

  • Identify a HomeKit device: the accessory signals itself.
  • Re-read a HomeKit device: reads all its values right away (handy before a condition).

Dashboard widget​

The HomeKit accessories widget shows how many accessories are online and offline, the list of accessories (unreachable ones first) and, when one is offline, a Reconnect button.

Troubleshooting​

  • The accessory is not found by the search: check that it is powered on and on the same network (same VLAN) as Gladys. Try a longer search duration, or pair it with IP:port.
  • "paired elsewhere": remove it from the Home app or factory-reset it.
  • Unreachable accessory: the Configuration screen shows which accessories are offline. The integration retries on its own and finds the accessory again if its IP address changed. To avoid it, give the accessory a fixed IP address (DHCP reservation).
  • Pairings are stored in the integration's /data volume: they are kept across updates.
  • For details, check the integration logs (LOG_LEVEL=debug).

Configuration settings​

These are the settings HomeKit Controller asks for in its configuration screen in Gladys.

SettingTypeRequiredDescription
Getting startedsectionNo1. Remove the accessory from Apple Home (a HomeKit accessory accepts only one controller). 2. Click "Search for accessories" below. 3. Click "Pair an accessory" with its name and the 8-digit setup code printed on it. 4. Add its devices from the Discovery tab.
Refresh interval (s)numberNoHomeKit pushes changes in real time; this full refresh is only a safety net.
Search duration (s)numberNoHow long Gladys listens for HomeKit accessories on the network.

How to install HomeKit Controller in Gladys​

  1. In Gladys, open Integrations: HomeKit Controller appears in the catalog, next to the native integrations, with a community badge.
  2. Click Install. Gladys pulls the Docker image (ghcr.io/prohand/gladys-homekitcontroller:1.0.3), starts it in a sandbox isolated from the core, and generates the integration's interface (devices, discovery and configuration).
  3. Open the Configuration screen of the integration, fill in the settings, and save.
  4. You can also install it directly from its repository URL: https://github.com/prohand/gladys-homekitcontroller.

HomeKit Controller requires Gladys >=5.1.0. The catalog inside Gladys refreshes every hour, so a new version becomes available at most one hour after its release.

Not running Gladys yet? It is free and open source: follow the installation guide to get started.

About external integrations​

HomeKit Controller is an external integration: a community integration packaged as a Docker container and published on GitHub, that Gladys installs in one click and runs in a sandbox isolated from its core. It is published and maintained by prohand, not by the Gladys core team.

Subscribe to the Gladys Assistant newsletter

A few emails per month about new releases and project news. Sent by Pierre-Gilles Leymarie, founder of the project. Unsubscribe anytime 🙂
Last updated on