Homey Pro bridge smart home integration, free and open source

The devices of your Homey Pro in Gladys: lights, plugs, shutters, thermostats, sensors…

• Published by LM1LC3N7
• Devices
• Version 0.1.3
• Requires Gladys >=5.1.0
• ★ 0

View on GitHubAll integrations

This integration connects Gladys to your Homey Pro and offers every Homey device in the Discovery tab of Gladys: lights, plugs, shutters, thermostats, locks, buttons, sensors, meters. Once a device is added, its states follow Homey live, and Gladys controls it through Homey, which keeps its Zigbee, Z-Wave, Matter, Wi-Fi and app devices. Move to Gladys at your own pace, room after room, or use both side by side. Everything stays on your local network. Unofficial, not affiliated with Athom.

Development version (0.1). Written from the Homey Web API documentation and tested against a simulated Homey Pro, not yet on a real one. Your feedback is welcome on the GitHub repository.

Which Homey

Homey	Works?
Homey Pro (Early 2023)	Yes: it has the local API and the API keys this integration uses.
Homey Pro mini	Probably: same Homey Pro software, with API keys. Not tested yet.
Homey Self-Hosted Server	Probably, if it offers the API keys. Not tested yet.
Homey Pro (Early 2019) and older	No: they have neither API keys nor local API (an MQTT bridge app is the way there).
Homey Cloud (Homey Bridge)	No: it runs in Athom's cloud, there is no API on your local network.

What you get

Homey capability	In Gladys
onoff, dim	a light (light devices, or a plug used for a lamp), else a switch
light_hue + light_saturation, light_temperature, light_mode	colour (RGB) and colour temperature, the one Homey shows
windowcoverings_state (up / stop / down), windowcoverings_set	a shutter (or a curtain): open, close, stop, position
target_temperature, thermostat_mode (auto, heat, cool, off)	a thermostat: setpoint and mode
locked	a lock
button	a button: every press is an event for your scenes, pushable
measure_temperature, _humidity, _pressure, _luminance, _co2, _pm25, _noise	the sensor of the right category
measure_power, meter_power, measure_voltage, measure_current	power and energy (on the switch of a plug), voltage, current
meter_gas, meter_water	a volume in m³
measure_battery, alarm_battery	the battery level, battery low
alarm_motion, alarm_contact, alarm_water, alarm_smoke, alarm_co, alarm_tamper	motion, opening, leak, smoke, CO and tamper sensors

Each Homey device makes one Gladys device, named after the device and its zone ("Lamp (Living room)"); its Homey id, zone, class and driver are kept in its parameters. The sub-capabilities of a device ("onoff.2", a second outlet; "measure_temperature.outside") become features of their own, named with their Homey title. Devices with none of these capabilities (speakers, for now) are left out.

Requirements

• A Homey Pro (Early 2023), see above, on the same local network as Gladys.
• An API key of that Homey.

Installation

1. Open the Homey web app (https://my.homey.app), Settings → API Keys → New API Key. Give it a name ("Gladys") and these permissions:

   • View devices and Control devices (required);
   • View zones (the room in the device names);
   • View System (the live updates: without it, Gladys reads the devices every 10 seconds).

   Homey shows the key once: copy it.

2. In Gladys, open the integration, Configuration:

   • Homey API key: paste it.
   • Address of Homey: leave it empty, Gladys finds your Homey on the local network. Or type its IP address, like 192.168.1.20. Not a .local name: the integration runs in its own container and cannot resolve them.

3. Click Test the connection: the Homey version, its address, the number of devices and zones, the devices offered and whether the live updates work show up.

4. Open the Discovery tab and add the devices you want. Their values are sent as soon as they are added.

Options

• Minimum interval between two readings of a sensor: 10 seconds by default (0 to 300). A plug that reports its power every second is sent to Gladys at this pace. Switches, lights, buttons, motion and opening sensors are never delayed.
• Allow unlocking from Gladys (off by default): without it, Gladys can lock a lock through its "Locked" feature (the locked capability), never unlock it. The switch, brightness, cover or button of a lock (class lock, or a device with the locked capability) need this option both ways.
• Allow garage door and gate control (off by default): without it, the switch, brightness, cover and button of the devices of class garagedoor, or with the garagedoor_closed capability, are refused.
• Allow valve and sprinkler control (off by default): the same for the classes watervalve, sprinkler and faucet (opening and cutting).
• Allow alarm and siren control (off by default): the same for the classes homealarm, smokealarm and siren, or the devices with the homealarm_state capability (arming, disarming, silencing).

The classes are the Homey ones (or the virtual class chosen in the Homey app); watervalve, sprinkler and siren exist since Homey 12.0. Limit: a valve, a siren or a gate relay filed under another class (socket, relay, other, sensor) is protected only when it has one of the capabilities above; otherwise it is driven like a plug. Give it the right virtual class in Homey.

These commands still show as controllable in Gladys (the features are frozen when the device is created): the integration refuses them, with a message naming the option, while the option is off, devices added earlier included. Once allowed, each such command first reads the device again from Homey and is refused when Homey does not answer, says the device is unavailable, or the state is unknown (a capability Homey cannot read back, getable false, is therefore refused even with the option). A command that could not leave within 3.5 s is refused without sending anything; a command of several requests (colour, colour temperature) goes to the end once its first request left.

Good to know

• Homey stays in charge of the devices: Gladys sends its commands to Homey, which drives them. Keep Homey running.
• Live updates: the changes reach Gladys within a second. The whole list is read again every 5 minutes. When the live updates are refused or lost, the devices are read every 10 seconds meanwhile, and Gladys tries the live updates again in the background.
• Buttons: the buttons Homey exposes as a capability (Homey's virtual buttons, the buttons of some apps) send every press to your scenes, and Gladys can press them. Most remotes (IKEA, Hue, Aqara…) only exist as Flow triggers in Homey, which the Web API does not show: make a Homey Flow that presses a virtual button, and use that button in Gladys.
• Colours: a bulb in colour mode shows its colour, in white mode its colour temperature (the Homey light_mode); Gladys switches the mode when it sets one or the other.
• Door contacts: Homey says "contact alarm" for an open door, Gladys 0 for open and 1 for closed; the integration converts.
• Transport badge: a device turns "unreachable" when Homey is, or when Homey marks it unavailable (with Homey's reason); an orange dot means the live updates are off and the state is read every 10 seconds.
• Devices added, renamed or moved in Homey show up in Discovery within seconds (at the latest at the next full read). The Scan button reads them at once.
• A new IP address (DHCP): when Homey stops answering, Gladys looks for it on the network by its id and keeps its new address.

Troubleshooting

Status message	What to do
Homey refused the API key	Create a new key (Settings → API Keys) and paste it.
The API key lacks a permission	Create a key with View devices, Control devices, View zones and View System.
Homey refused the live updates	Give the key the View System permission (create a new key). Meanwhile Gladys reads every 10 seconds.
No Homey Pro found on the network	Type the IP address of Homey in the configuration.
Several Homeys found	Type the address of yours in the configuration.
No Homey Pro answers at this address	Check the IP address. A Homey Pro (Early 2019) or a Homey Cloud cannot be used.
Homey is unreachable: connection refused	Check the address, seen from the Gladys machine (not localhost), and that Homey is on.

The logs of the integration (Gladys, integration page) give the details.

Privacy

Everything stays on your local network: the integration only talks to your Homey, over its local API. The API key is stored as a secret by Gladys and never written to the logs. Homey is a trademark of Athom B.V.; this integration is not affiliated with Athom.

Configuration settings

These are the settings Homey Pro bridge asks for in its configuration screen in Gladys.

Setting	Type	Required	Description
Your Homey Pro devices in Gladys	section	No	Every device of your Homey Pro (2023 or later) is offered in the Discovery tab: lights with their colour, plugs and switches with their consumption, shutters, thermostats, locks, buttons, motion, door, leak and smoke sensors, temperature, humidity and air quality, meters. The states follow Homey live and Gladys controls the devices through Homey, which keeps its Zigbee, Z-Wave, Matter and app devices: migrate at your pace, or use both side by side. Everything stays on your local network. Homey Pro (Early 2019) and older and Homey Cloud have no local API: they cannot be used. Unofficial, not affiliated with Athom.
Homey API key	secret	Yes	Create it in the Homey web app (my.homey.app): Settings → API Keys → New API Key, with the permissions View devices, Control devices, View zones and View System. Homey shows it once: paste it here.
Address of Homey	string	No	Leave empty: Gladys looks for your Homey on the local network. Otherwise its IP address, like 192.168.1.20 (http://192.168.1.20).
Minimum interval between two readings of a sensor (s)	number	No	Some devices report every second (power meters): Gladys keeps the last reading at this pace. Switches, lights, buttons, motion and opening sensors are never delayed.
Allow unlocking from Gladys	boolean	No	Off by default: Gladys can lock a lock (its Locked feature), never unlock it; the switch, brightness, cover and button of a lock (class lock, or a device with a Locked capability) are refused both ways. On, Gladys can UNLOCK, from the dashboard, scenes and voice assistants.
Allow garage door and gate control from Gladys	boolean	No	Off by default: the switch, brightness, cover and button of the Homey devices of class garagedoor, or with a garagedoor_closed capability (a gate relay too), are refused. A gate relay filed under another class without that capability is not protected. On, Gladys can open and close them.
Allow valve and sprinkler control from Gladys	boolean	No	Off by default: the switch, brightness, cover and button of the Homey devices of class watervalve, sprinkler (Homey 12.0 or later) or faucet are refused (opening and cutting). A valve filed under another class (socket, relay, other) is not protected. On, Gladys can open and close them.
Allow alarm and siren control from Gladys	boolean	No	Off by default: the switch, brightness, cover and button of the Homey devices of class homealarm, smokealarm or siren (Homey 12.0 or later), or with a homealarm_state capability, are refused (arming, disarming, silencing). A siren filed under another class (socket, relay, other, sensor) is not protected. On, Gladys can switch them.

How to install Homey Pro bridge in Gladys

1. In Gladys, open Integrations: Homey Pro bridge appears in the catalog, next to the native integrations, with a community badge.
2. Click Install. Gladys pulls the Docker image (ghcr.io/lm1lc3n7/gladys-homey:0.1.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/LM1LC3N7/gladys-homey.

Homey Pro bridge 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

Homey Pro bridge 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 LM1LC3N7, not by the Gladys core team.

• Browse all integrations, native and community
• Build and publish your own external integration
• Source code on GitHub — source of this documentation

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 🙂