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.

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.3.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 Discover tab: the accessory's devices are ready to be added with Add to Gladys.

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
Energy metering (Eve)Power (W), energy (kWh), voltage, current
FanOn/off, speed
ThermostatTemperature, target temperature, humidity, mode, operating state
Heater cooler (air conditioner)On/off, mode, target temperature, temperature
Window covering, window, doorPosition, open / stop / close
LockLocked / unlocked
SensorsTemperature, humidity, illuminance, motion,
occupancy, contact, leak, smoke, CO, CO2,
PM2.5 / PM10 particles, VOC, NO2, ozone, SO2
BatteryLevel, low battery
Button, doorbellPress

A button gives a "Button" feature whose value changes on each press: 1 single, 2 double, 6 long. A doorbell gives a "Doorbell" feature (1 on each ring). Use them with the usual device state trigger, or with the HomeKit button pressed trigger (see below).

Air conditioner: the mode is 0 auto, 1 cooling, 2 heating (HomeKit has no dry or fan-only mode). The target temperature follows the mode: heating threshold in heating mode, cooling threshold otherwise.

After an update of the integration, a device already created may gain new features: the Discover tab then offers to update it.

Other services (cameras, televisions…) are ignored for now. On each connection, the logs list the unsupported services of each accessory (HomeKit service(s) not supported: …) and the vendor-specific characteristics (vendor characteristic(s) not supported: …): add these lines to a support request.

Energy metering: HomeKit has no standard power characteristic. The integration reads the Eve ones (Eve accessories, many Homebridge plugins). A plug that only shows its consumption in its own app (Aqara…) only gives on/off.

Only what the bridge publishes over HomeKit is visible: a device a hub only shares over Matter does not show up here. This is the case of the infrared air conditioners of Aqara hubs (M2, M3): add them with the Gladys Matter integration.

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 (in a scene, Add trigger → Integrations):

  • 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, first create its device in Gladys (Discover tab). Otherwise, leave the filter empty.

Actions (in a scene, New action → Integrations):

  • 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 integration's Configuration tab 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's Logs tab (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 Discover 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.4.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.3.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 🙂