Homematic IP smart home integration, free and open source
Homematic IP through the cloud: heating, contacts, sensors, plugs, shutters, alarm.
Published by guim31
- Devices
- Version 1.0.1
- Requires Gladys >=5.1.0
- ★ 0
Brings your Homematic IP devices (eQ-3) into Gladys through the Homematic IP cloud, the way the official app reaches them: radiator and wall thermostats, heating rooms, window and door contacts, motion, presence, smoke and water sensors, plugs and switch actuators with their power, dimmers, shutters and blinds, wall switches and remote controls, weather sensors, and the alarm system.
Developed without the hardware: feedback welcome. This integration was built from the public protocol and recorded answers of the Homematic IP cloud, without an access point at hand. If something is wrong or missing, please open an issue: github.com/guim31/gladys-homematicip/issues. Not affiliated with eQ-3 AG: Homematic IP is a trademark of eQ-3.
Requirements
- A Homematic IP access point (HmIP-HAP, or the HmIP-DRAP wired access point) set up in the Homematic IP app, with its devices already paired.
- Its SGTIN: the 24-character code printed under the access point and on
the sticker that came with it (for example
3014-F711-A000-0000-0000-0000). - Internet access for Gladys: everything goes through the Homematic IP cloud.
- Gladys 5.1 or later.
The Home Control Unit (HCU) with its local "Connect API" is not supported: this integration talks to the cloud of the access point.
Configuration
Open the Configuration tab of the integration.
- Access point SGTIN: type the code printed under the access point (dashes and spaces are allowed), then save.
- Access point PIN: only if you protected your access point with a PIN in the app. It is used during the pairing only.
- Language of the device names: the language of the feature names of the devices you add (Temperature, Set point, Opening...). French by default.
- Alarm control: what Gladys may do with the alarm system (see below).
Pairing
- Click Start pairing. Gladys asks the cloud for access, as a new client called "Gladys".
- Press the blue button on top of the access point.
- Click I pressed the button. Gladys receives its token, reads your home and lists the devices in the Discovery tab.
- Add the devices you want from the Discovery tab.
The token is stored in the integration's private volume (/data), never in
the logs. "Gladys" then appears among the clients of the Homematic IP app:
removing it there revokes the access, and the status of the integration says
to pair again.
Read the home again reads every device and room at once and tells how many were found (useful after adding a device in the app).
Alarm control
Reading the alarm is always possible. Changing it is your choice, in Alarm control:
- Read only (default): Gladys shows the alarm mode and the alarm, nothing more;
- Arm only: Gladys may arm the alarm (perimeter or full protection), never disarm it;
- Arm and disarm: Gladys may also disarm it.
The alarm mode is never a switch a voice assistant could flip by mistake: it changes from its selector on the device, or from the scene action Set the Homematic IP alarm, within what this setting allows.
Devices
Three kinds of devices appear in the Discovery tab.
Homematic IP devices
One Gladys device per Homematic IP device, named as in the app. Its features depend on what the device has, whatever its model:
| Feature | Devices | Values |
|---|---|---|
| Temperature | thermostats, climate and weather sensors, STE2 (×2) | °C |
| Humidity | wall thermostats, climate and weather sensors | % |
| CO2 | CO2 sensors | ppm |
| Illuminance | motion, presence, light and weather sensors | lux |
| Wind speed | weather sensors | km/h |
| Rain | weather sensors pro/plus, rain sensor | yes / no |
| Opening | window and door contacts, window handles, contact inputs | open / closed (tilted is open) |
| Motion | motion detectors | yes / no |
| Presence | presence detectors | yes / no |
| Smoke | smoke detectors (smoke seen by this one) | yes / no |
| Water leak / Water level | water sensors | yes / no |
| Heating | radiator thermostats (valve open) | idle / heating |
| Switch | plugs, switch actuators, flush-mount switches | on / off, controllable |
| Power / Energy | measuring plugs and actuators | W / kWh |
| Light / Brightness | dimmers | on / off, %, controllable |
| Position / Open/close | shutters, blinds, sun shading | 0 % closed to 100 % open |
| Button | wall switches, remote controls, key inputs | short press, long press |
| Low battery / Tamper | battery devices, devices with a tamper switch | yes / no |
A device with several channels (a 4-way actuator, a 6-key wall switch) has one feature per channel, named after the channel label of the app or its number. The access point itself, and devices this version does not know (door locks, sirens, floor heating actuators...), do not appear.
Buttons: each press is a new value of the Button feature (short press, long press, release), usable in the "device state" trigger of the Gladys scenes. The cloud only reports the presses of the devices that send them.
Heating rooms
One device per heating room of the app, named Heating followed by the room:
- Temperature and Humidity of the room (wall thermostat, or the radiator thermostat);
- Set point: the target temperature, by half degrees, within the limits of the room;
- Mode: Automatic (weekly programme), Manual or Eco;
- Boost: the valves fully open for the boost time set in the app;
- Window: open as soon as a contact or the thermostat sees it open;
- Heating: whether a valve of the room is open.
Home (eco mode and alarm)
One Homematic IP device for the whole home:
- Eco mode (absence): on, every room is at its eco temperature until you switch it off (an eco mode or a vacation started from the app shows here too);
- Alarm mode: Disarmed, Perimeter protection or Full protection, changed within what Alarm control allows;
- Alarm: on while the alarm is going off.
Widget
The Homematic IP heating widget shows the whole house at a glance: the Outside temperature the cloud knows for your home, how many rooms are Heating, then each room with its temperature, its set point and what it is doing (window, boost, eco). Its button starts the Eco mode of the whole home (with a confirmation) or, when it runs, offers End eco mode. In its settings, choose the rooms to show (all of them when none is chosen).
Scene trigger
Homematic IP alarm triggered: the armed alarm system went off. Filter on the sensor (any when empty) and on the cause: Intrusion, Smoke, Water, Sabotage, Other. The scene receives the sensor name and the cause as variables. An alarm already going off when Gladys starts does not fire it.
Everything else (a window opened, a key pressed, the temperature of a room) is a device feature: use the "device state" trigger of Gladys.
Scene actions
- Start the Homematic IP eco mode: every room at its eco temperature, for a number of hours, or until ended (0).
- Start the Homematic IP vacation mode: every room at one temperature (5 to 30 °C) for a number of days, then back to the programme.
- End the Homematic IP eco or vacation mode: back to the normal programme.
- Set the Homematic IP alarm: disarmed, perimeter or full protection, within what Alarm control allows. It tells the scene whether the mode was applied, and which sensors blocked it (an open window, for example).
Scene examples
- When the last person leaves home (Gladys presence): Start the Homematic IP eco mode, then Set the Homematic IP alarm to full protection; if the mode was not applied, send yourself a message with the blocking sensors.
- When the Homematic IP alarm triggered with the cause Intrusion: turn on every light and send a message naming the sensor.
- When the Opening of the bathroom window goes to open: switch the Boost of the room off.
Refresh and cloud limits
The cloud pushes every change as it happens (a live connection, like the app): states usually show within a second or two. On top of that, Gladys reads the whole home when it starts, when the live connection comes back, and every 30 minutes (every 5 minutes while the live connection is down). Gladys never polls these devices itself.
The Homematic IP cloud throttles busy clients and publishes no quota: the integration sends at most 10 requests at once, then one every 8 seconds, the pace of the reference client Home Assistant uses. A scene switching many devices at once may see the last commands refused ("Too many Homematic IP commands in a row"): spread them, or use a group of the app.
Troubleshooting
- "This is not an SGTIN": the code has 24 characters, digits and letters A to F. Copy it from under the access point.
- "The Homematic IP cloud refused the request": check the SGTIN and, if your access point has a PIN, the Access point PIN field.
- "The access point has not confirmed yet": press the blue button of the access point, then click I pressed the button again soon after.
- "The Homematic IP cloud refuses the access of Gladys": Gladys was removed from the clients in the app. Start the pairing again.
- "The access point is not connected": the cloud still answers, but with the last values. Check the power and the network cable of the access point.
- A key press does not show: some devices only act on their direct links and send nothing to the cloud; check in the app that the key is not only linked to an actuator.
- Details are in the integration logs; set
LOG_LEVEL=debugfor more.
Limits
- Cloud only: no local access point API (the HCU is not supported), so no Internet means no control.
- Not mapped in this version: door locks, sirens, floor heating actuators, energy sensor interfaces (HmIP-ESI), RGB lights, garage door modules, slats of the blinds, heating profiles.
- Cooling is not handled.
- The alarm trigger fires on the alarm the cloud reports for the whole home; the smoke detectors still have their own Smoke feature.
- Feature names are set when a device is added: change the language before adding the devices.
- The token is lost with the
/datavolume: pair again then.
Support
Developed without the hardware: feedback welcome. Questions, bugs and missing devices: github.com/guim31/gladys-homematicip/issues. This project is not affiliated with eQ-3 AG.
Configuration settings
These are the settings Homematic IP asks for in its configuration screen in Gladys.
| Setting | Type | Required | Description |
|---|---|---|---|
| Connect your access point | section | No | Gladys reaches your Homematic IP access point (HmIP-HAP) through the Homematic IP cloud, like the app. 1. Type its SGTIN (printed under the access point) and save. 2. Click "Start pairing". 3. Press the blue button on top of the access point, then click "I pressed the button". 4. Add the devices from the Discovery tab. |
| Access point SGTIN | string | Yes | 24 characters printed under the access point and on its sticker, dashes allowed. |
| Access point PIN | secret | No | Only if you set a PIN in the Homematic IP app. Used for the pairing only. |
| Language of the device names | select | No | Names given to the features of new devices (Temperature, Set point, Opening...). |
| Alarm control | select | No | What Gladys may do with the Homematic IP alarm system. Reading it is always possible. |
How to install Homematic IP in Gladys
- In Gladys, open Integrations: Homematic IP appears in the catalog, next to the native integrations, with a community badge.
- Click Install. Gladys pulls the Docker image (
ghcr.io/guim31/gladys-homematicip:1.0.1), starts it in a sandbox isolated from the core, and generates the integration's interface (devices, discovery and configuration). - Open the Configuration screen of the integration, fill in the settings, and save.
- You can also install it directly from its repository URL: https://github.com/guim31/gladys-homematicip.
Homematic IP 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
Homematic IP 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.
- Browse all external integrations
- Discover the native integrations built into Gladys
- Build and publish your own external integration
- Source code on GitHub — source of this documentation