Skip to main content

Homebridge smart home integration, free and open source

Homebridge integration for Gladys Assistant

Bridge to Homebridge: its accessories (plugs, lights, sensors, blinds…) in Gladys, with control.

View on GitHubAll integrations

This integration connects Gladys to your Homebridge and offers the accessories of all its plugins in the Gladys Discovery tab: lights, switches and plugs, thermostats and air conditioners, blinds and windows, fans, valves, sensors and detectors, locks and garage doors. Once a device is added, its values follow Homebridge live, and Gladys controls it through Homebridge, which keeps its plugins (Hue, Tuya, Shelly, Ring, cloud devices…). Everything stays on your local network. Unofficial, not affiliated with the Homebridge project nor with Apple.

The Gladys core already has a HomeKit integration that works the other way round (Gladys devices in the Apple Home app). This one brings Homebridge accessories into Gladys.

Developed against Homebridge 2.4.0 and Homebridge UI 5.29.0 in Docker, with the virtual accessories of homebridge-dummy, not with real hardware: feedback is welcome on the GitHub repository.

Requirements​

  • Homebridge with its web interface (Homebridge UI, homebridge-config-ui-x 5.x), reachable from the Gladys machine (same network, or a VPN).
  • Homebridge running in insecure mode: in the Homebridge UI, Settings → Homebridge Settings → Homebridge Insecure Mode (on by default with hb-service), then restart Homebridge. It is what the Accessories page of the UI needs too: the UI reads and controls the accessories through the HomeKit protocol of your own bridges, with their PIN. Any program on your network that knows the PIN can then do the same, without a HomeKit pairing.
  • A user of the Homebridge UI for Gladys, without two-factor authentication (a one-time code cannot be typed again by a container). It does not need to be an administrator: create a dedicated user in User Accounts.

Configuration​

Address and user​

  1. In the Homebridge UI, User Accounts → Add: a user gladys, a strong password, not an administrator.
  2. In Gladys, open the integration, Configuration:
    • Address of the Homebridge UI: like http://192.168.1.40:8581. Not a .local name, not localhost: the integration runs in its own container.
    • User name and password of that user. Leave them empty if your UI runs without login (authentication disabled).
  3. Click Test the connection: the Homebridge version, the number of devices offered and the services not imported show up.
  4. Open the Discovery tab and add the devices you want. Their values are sent as soon as they are added.

Choosing what to import​

Gladys offers one device per Homebridge accessory, with the features of all its services (a sensor with temperature, humidity and battery is one device).

  • Only these accessories: names separated by commas, * matches any text (Living*, Garage). Empty: every accessory.
  • Accessories to leave out: never imported (* battery, Test*).

A name matches the accessory name or one of its service names, whatever the case. Only the devices added in Gladys receive values: the others cost nothing.

Locks, garage doors and alarms​

By default, locks, garage doors, motorised doors and alarms (security systems) are read-only in Gladys: you see whether they are locked, open or closed, but Gladys cannot open, unlock or disarm them, neither from a device, nor from a scene, nor from a voice assistant connected to Gladys. Each family has its own switch in the configuration: Allow commands of locks, Allow commands of garage and motorised doors, Allow arming and disarming the alarms. Turn on only what you need, knowing that a mistake in a scene could then open your house.

Options​

  • Minimum interval between two values of a sensor: a sensor that reports every second is sent at this pace (10 seconds by default). Switches, lights, covers and detectors are never delayed.
  • Language of the feature names: the suffixes of the secondary features ("Brightness", "Battery"…). Accessory names are kept as in Homebridge.

What you get​

Devices​

Homebridge (HAP) serviceIn Gladys
Lightbulblight: on/off, brightness, colour, colour temperature (what it offers)
Switch, Outletswitch on/off
Fan, Fanv2, AirPurifier, HumidifierDehumidifierswitch on/off, fan speed (%)
Valve, Faucet, IrrigationSystem, Televisionswitch on/off
Thermostatset point, mode (off, heat, cool, auto), current temperature
HeaterCoolerair conditioner: on/off, mode, set point of the current mode
WindowCovering, Windowshutter: open, close (stop if the accessory can), position
Doorposition and open or closed; commands only when allowed
LockMechanismlock: locked or unlocked; commands only when allowed
GarageDoorOpeneropen or closed; open/close only when allowed
Temperature, humidity, light, CO2, PM2.5, PM10 sensorssensors with their unit
Motion, occupancy, contact, leak, smoke, CO detectorsbinary sensors (a contact is 0 when open, as everywhere in Gladys)
Battery, low battery, tamperingbattery level, low battery and tamper alerts

Other services (cameras, speakers, TV inputs…) are listed by the connection test as "not imported". The scene action below still reaches their characteristics.

Dashboard widget​

The Homebridge widget shows the connection, how values arrive ("Live" via the socket of the UI, or "Polling"), the Homebridge version, the devices offered and added, the services followed, and a Reload button that reads the accessory list again.

Scene triggers​

  • Homebridge button pressed: a programmable switch (StatelessProgrammableSwitch) or a doorbell was pressed. Filters: accessory, press (single, double, long). Variables: accessory, button, press. Needs the live updates: a press is an event, polling cannot see it.
  • Homebridge alarm changed: a security system was armed (home, away, night), disarmed or triggered. Filters: alarm, new state. Variables: accessory, state, previous state.

Scene actions​

  • Arm or disarm a Homebridge alarm: home, away, night or disarm. Needs Allow arming and disarming the alarms. The name is only needed when there are several security systems.
  • Set a Homebridge characteristic: any writable characteristic of any accessory, even one not added to Gladys: the input of a TV (ActiveIdentifier), the swing of a fan (SwingMode), a switch (On, true). The names are those of the HomeKit protocol, as the Homebridge UI shows them in the accessory details. The security switches apply here too.

Scene examples​

  • When the doorbell button is pressed (trigger), take a camera snapshot and send it to your phone.
  • When the Homebridge alarm becomes "triggered", turn on every light and send a message.
  • At 7 a.m. on weekdays, set the living room TV input to 3 with "Set a Homebridge characteristic", and the thermostat set point to 20 °C.

Troubleshooting​

  • "Homebridge does not run in insecure mode": enable Homebridge Insecure Mode in the Homebridge settings and restart Homebridge. A new attempt is made every minute.
  • "Homebridge refused the login": check the user name and password; a user with two-factor authentication cannot be used. After 10 failures in 5 minutes the UI locks the account out for 5 minutes: the integration only tries again every 5 minutes.
  • "Homebridge is unreachable": check the address from the Gladys machine (curl http://<address>:8581/api/auth/settings). A new attempt is made after 5 seconds, then up to every minute.
  • The widget says "Polling": the socket of the UI (/socket.io) does not get through, often because of a reverse proxy without WebSocket support. Values still arrive every 30 seconds, button presses do not.
  • An accessory is missing: run the connection test, it lists the services not imported. Check the names to include and to leave out, and that the accessory shows in the Accessories page of the Homebridge UI.
  • Logs: set LOG_LEVEL=debug to see every value received.

Limits​

  • Developed without real hardware, against homebridge-dummy: feedback welcome.
  • Matter accessories of Homebridge 2 are not imported (the REST API of the UI lists HomeKit accessories only).
  • Reading the list asks every accessory for its values: without the socket, it happens every 30 seconds, which some cloud plugins may not like.
  • Resetting the Homebridge accessory cache (or changing a bridge user name) gives new identifiers: the devices must be added again. Renaming an accessory does not.
  • The names of features are fixed when the device is added in Gladys.
  • The security switches know locks, garage doors, motorised doors and alarms by their HomeKit type: a gate or a strike that a plugin exposes as a plain switch is an ordinary switch. Leave it out (Accessories to leave out hides it from the Discovery tab; the scene action can still reach it by name).

Privacy​

The bridge talks only to your Homebridge UI, on your network. The password is stored by Gladys in its configuration and never written to the logs; the session token lives in memory only. Nothing is sent to the internet.

Configuration settings​

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

SettingTypeRequiredDescription
Your Homebridge accessories in GladyssectionNoGladys reads the accessories of every Homebridge plugin through the Homebridge UI and follows their changes live. Homebridge must run in insecure mode (Homebridge settings), as for the Accessories page of the UI. Create a dedicated user in the UI, without two-factor authentication. The accessories then show up in the Discovery tab: add the ones you want.
Address of the Homebridge UIstringYesIts IP address and port, as seen from the Gladys machine. Not a .local name, not localhost.
User namestringNoA user of the Homebridge UI; it does not need to be an administrator. Empty if the UI runs without login.
PasswordsecretNo
Only these accessoriesstringNoAccessory names, separated by commas; * matches any text. Empty: every accessory.
Accessories to leave outstringNoAccessory names, separated by commas; * matches any text. Never imported.
SecuritysectionNoLocks, garage doors, motorised doors and alarms always show their state. Off, Gladys cannot open, unlock or disarm them, from a device, a scene or a voice assistant.
Allow commands of locksbooleanNo
Allow commands of garage and motorised doorsbooleanNo
Allow arming and disarming the alarmsbooleanNo
Minimum interval between two values of a sensor (s)numberNoA sensor that reports every second is sent to Gladys at this pace. Switches and detectors are never delayed.
Language of the feature namesselectNo

How to install Homebridge in Gladys​

  1. In Gladys, open Integrations: Homebridge appears in the catalog, next to the native integrations, with a community badge.
  2. Click Install. Gladys pulls the Docker image (ghcr.io/guim31/gladys-homebridge:1.0.0), 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/guim31/gladys-homebridge.

Homebridge 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​

Homebridge 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 guim31, 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