Skip to content

About

Repository for the Homematic IP integration for the Homey smart home platform

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Homematic IP for Homey

⚠️ 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 the homematicip project). It can break if eQ-3 changes the cloud, and it is not endorsed by eQ-3.

How it connects

  1. Lookup — lookup.homematic.com resolves which REST + WebSocket host serves your access point (keyed by the access point's SGTIN).
  2. 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.
  3. State — getCurrentState returns all devices and groups.
  4. Realtime — a WebSocket pushes device/group change events.
  5. Control — thermostats are driven by setting the target temperature on their HEATING group.

Connection & rate limits

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 state event.
  • A full getCurrentState is 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.

Pairing

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.

Supported devices

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.

Not supported

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).

Example: BWTH + FSM16 infrared heating

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.

Project layout

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.

Develop

npm install
homey app run      # run on a connected Homey in dev mode
homey app validate # validate the manifest

Adding more device types

The 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.

About

Repository for the Homematic IP integration for the Homey smart home platform

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages