⚠️ Alpha — use at your own risk. This is an early, largely untested release. It may be unstable, may stop working without notice, and could interact unexpectedly with your devices. It is provided as-is, with no warranty and no support — there is no guarantee of fixes, updates, or responses to issues. If that's not acceptable for your setup, don't install it.
A Homey app that connects to the Homematic IP Cloud — the same backend the official Homematic IP smartphone app uses — through a Cloud Access Point (HmIP-HAP). It provides two device types (thermostat and metered switch) and covers the full path: registration, state, realtime updates over WebSocket, and control.
⚠️ Homematic IP has no official public API. This app uses the well-known, community-reverse-engineered protocol (as implemented by thehomematicipproject). It can break if eQ-3 changes the cloud, and it is not endorsed by eQ-3.
- Lookup —
lookup.homematic.comresolves which REST + WebSocket host serves your access point (keyed by the access point's SGTIN). - Registration (during pairing) — the app requests a connection, you press
the blue button on the access point, and the app exchanges that for a
long-lived
authToken+clientId, stored in Homey app settings. - State —
getCurrentStatereturns all devices and groups. - Realtime — a WebSocket pushes device/group change events.
- Control — thermostats are driven by setting the target temperature on
their
HEATINGgroup.
The Homematic IP cloud rate-limits clients, so the app is deliberately conservative — one shared connection per access point, used by all of its devices, and push-first:
- The WebSocket is the primary source. It pushes both state changes and
periodic measurement updates, which are applied to the cached state directly,
with no cloud call, and broadcast to every device via a
stateevent. - A full
getCurrentStateis fetched only when needed: once on connect, as a catch-up after a reconnect, and a slow 15-minute backstop poll (POLL_INTERVAL_MS). Any forced fetch is throttled to at most one per 10s (MIN_REFRESH_INTERVAL_MS). - On HTTP 429 (rate limited) the client backs off for the server's
Retry-After, or 5 minutes, instead of retrying. - The WebSocket reconnects with exponential backoff (15s → 5 min cap), so a temporary cloud block never becomes a tight retry loop.
In steady state this means near-zero polling — essentially just the occasional backstop fetch plus your own control commands.
If eQ-3 temporarily blocks your account for "unusual requests", stop/disable the app, wait until the official Homematic IP app works again, then re-enable it.
Add a Homematic IP Thermostat device. The pairing screen is a two-field form:
- Access Point SGTIN — printed on the sticker on the back of your Cloud
Access Point (HmIP-HAP), e.g.
3014F721A000…. - System PIN — required only if you set an authorization PIN in the Homematic IP app (leave empty otherwise).
Tap Log In, then press the blue button on the access point within ~60 seconds. The app registers itself as a client of the access point (the same way the official phone app does — no username/password account exists), stores the resulting token, and lists the thermostats on your account.
Pairing a second device type (or re-pairing) reuses the stored registration, so the button press is only needed once. Each registration appears as a client named "Homey (Homematic IP app)" in the Homematic IP app; you can remove stale ones there.
The app provides two drivers. Devices are matched structurally (by the channels they expose), not against a fixed model list, so models beyond the ones named below should also work — though only HmIP-BWTH and HmIP-FSM16 have actually been tested.
Thermostat — any device with a setPointTemperature channel in a HEATING
group: radiator valves (e.g. HmIP-eTRV) and wall thermostats (e.g. HmIP-WTH,
HmIP-BWTH, HmIP-STHD). Capabilities: measured temperature, target temperature
(control via the HEATING group), humidity (when the device reports it), and a
low-battery alarm (battery-powered models only — mains models show no battery).
Switch (metered) — switch-measuring actuators such as HmIP-FSM16,
HmIP-FSM, or metered plugs (HmIP-PSM): anything reporting both on/off and power.
Exposed read-only: onoff shows whether the load (e.g. an infrared panel) is
currently powered, measure_power the live draw, meter_power the cumulative
energy. Switching is intentionally not settable, because in a heating setup the
Homematic HEATING group controls the actuator from the thermostat's setpoint.
There are no drivers (yet) for other Homematic IP device classes — door/window
contacts, motion/presence and weather sensors, dimmers, blinds/shutters,
non-metered switches, sirens, and buttons/remotes. Those won't appear during
pairing. The cloud client in lib/homematicip.js is generic, so adding a driver
for another class is the main work needed to extend coverage (see below).
A common layout is one HmIP-BWTH wall thermostat plus one HmIP-FSM16 per room, both members of that room's HEATING group, with the FSM16 powering an infrared panel. Pair each BWTH as a Thermostat (set the target temperature, read the room temperature/humidity) and optionally each FSM16 as a Switch (metered) to watch the panel's power. The thermostat's setpoint regulates the panel automatically via the group.
| Path | Purpose |
|---|---|
lib/homematicip.js |
Cloud client: lookup, registration, state, control, WebSocket |
app.js |
Shares one client per access point; restores tokens on boot |
drivers/thermostat/driver.js |
Pairing (login_credentials register + structural thermostat discovery) |
drivers/thermostat/device.js |
State sync, realtime updates, setpoint control |
drivers/switch/driver.js |
Metered-switch discovery; reuses a registered access point |
drivers/switch/device.js |
Read-only on/off + power + energy monitoring |
Pairing uses Homey's built-in login_credentials template (SGTIN as username,
PIN as password) — see each driver's onPair login handler — rather than a
custom HTML view.
npm install
homey app run # run on a connected Homey in dev mode
homey app validate # validate the manifestThe client is generic and the auth/transport layer is shared across drivers. To
add another device type, create a driver that filters getCurrentState for the
channels you care about and (for controllable devices) calls the relevant
control method — e.g. client.setSwitchState(deviceId, on) for a switchable
plug, or add a method to lib/homematicip.js for other endpoints.