Weheat smart home integration, free and open source
Unofficial connector: Weheat heat pumps, temperatures, state, COP, power, energy, flow.
Published by LM1LC3N7
- Devices
- Version 0.1.1
- Requires Gladys >=5.1.0
- ★ 0
This integration reads your Weheat heat pumps (Blackbird, Sparrow, Flint) through the official Weheat API, read only: nothing is ever commanded.
Unofficial connector, not affiliated with Weheat. Never tested with a real account or heat pump yet: it follows the manufacturer's official library (
weheat, MIT) and the Weheat integration of Home Assistant. Your feedback is welcome on the Gladys forum. Weheat, Blackbird, Sparrow and Flint are trademarks of their owner.
What you get
One device per active heat pump of the account, with:
| Feature | Unit | Note |
|---|---|---|
| State | text | heating, hot water, standby, defrosting, cooling… |
| Water in (return), water out (flow), heating water in | °C | |
| Outside temperature | °C | measured at the air inlet of the heat pump |
| Room temperature (thermostat) | °C | only with an OpenTherm thermostat |
| Hot water tank, top and bottom | °C | only with a tank |
| Electrical power | W | |
| Heat output power (W) | plain sensor | negative while cooling or defrosting |
| COP (coefficient of performance) | plain sensor | from the latest log, as Weheat computes it |
| Heating water flow, hot water flow | m³/h | estimated from the pump control |
| Electricity used, outdoor unit and indoor unit (kWh total) | plain sensor | totals since commissioning |
| Heat produced (kWh total) | plain sensor | can go down (cooling, defrosting) |
The energy totals are plain sensors, not energy indexes: Gladys does not count them in its consumption tracking nor prices them. Heat is not electricity, and the electricity total is a sum computed by the Weheat server that we could not check on a real account. An electricity index may come once a user confirms it only goes up.
The badge of each device turns "unreachable" when Weheat reports the heat pump offline, when it could not be read, or when the integration is stopped.
Before you start: the client ID
The Weheat API needs a client ID (and a client secret) given by Weheat, as for the Home Assistant integration (whose documentation points to the knowledge base of Weheat support; otherwise, ask Weheat support for them). Weheat also registers a redirect address for that client: where the browser goes back to after the sign-in. Use a client Weheat gives you, under its terms of use.
- If Weheat registered the address of your Gladys, signing in takes one click.
- Otherwise (for example a client meant for another application), the sign-in ends with a copy and paste of an address (see below).
Signing in
- In Integrations → Weheat → Configuration, enter the client ID and the client secret, then save.
- Click Connect: the Weheat sign-in page opens. Sign in with the e-mail and the password of your Weheat account. Your password is typed on the Weheat page only: the integration never sees it.
- Weheat sends you back to Gladys: the integration reads your heat pumps. Add them from the Discovery tab.
With another redirect address
- Enter the address Weheat registered in Redirect address (https, or http on localhost only) and save.
- Click Connect and sign in on the Weheat page.
- At the end, the browser stops on that address (the page may show an error,
that is expected). Copy the whole address from the address bar: it
holds
code=andstate=. - Paste it into the Finish the sign-in action, within 15 minutes. It
must hold
state=and start with the redirect address: another address is refused (the sign-in then stays usable).
A sign-in serves once; after a restart of the integration, click Connect again. If Weheat is slow to answer (over 3.5 seconds on the return to Gladys, 10 seconds for "Finish the sign-in"), the integration says "Weheat is slow to answer: click Connect again": start the sign-in again.
What the integration keeps
- The client secret is kept by Gladys in its database, like every configuration value: never shown again, sent only to Weheat.
- The Weheat tokens (access and renewal) are kept in clear in the file
/data/weheat-state.jsonof the integration's volume, readable by its container only (mode 0600), and sent only to Weheat. The same file keeps the pauses, the stops and the list of heat pumps. No password is ever written there.
Refresh pace
- The latest log of each heat pump is read every 2 minutes by default, and at least 2 minutes per heat pump (as Home Assistant): 4 minutes with two heat pumps.
- The energy totals are read every 30 minutes, the list of heat pumps every 6 hours (and on request from Discovery).
- The token is renewed by a timer shortly before its end, never twice within a minute.
- After a restart, the first read waits for the end of the interval since the last read and for the end of a running pause (both kept in /data).
Errors and stops
| Situation | What the integration does |
|---|---|
| Weheat asks to slow down (HTTP 429) | pause of 1 minute to 6 hours (as Weheat says), kept across a restart, for every request |
| Weheat unavailable (5xx error) | pause of 5 minutes to 1 hour, kept across a restart |
| Network down, unexpected answer | new try after the interval, then 5, 15, 30 minutes, kept across a restart |
| One heat pump, the energy totals or the list failing | the rest goes on; new try at the next round (30 minutes for the energy and the list) |
| Renewal refused by Weheat | "session ended" stop, kept: click Connect |
| Access refused even with a new token | stop kept: check the account, then Connect or "Test Weheat" |
The integration never signs in by itself and never retries a refusal: only a click does. The Test Weheat button reads the heat pumps at once (at most once every 30 seconds).
Troubleshooting
- "Enter the client ID": the client ID is missing.
- Weheat refused the sign-in (
invalid_client): wrong client ID or secret. - Weheat refused the sign-in (
invalid_grant) or a redirect error on the Weheat page: the redirect address does not match the one registered for this client, or the pasted address is older than 15 minutes. - No heat pump: only the heat pumps "active" at Weheat are read.
Limits
- Read only: no setpoint, no mode.
- The values come from the Weheat cloud (latest known log), not from the heat pump locally.
- Never tested with a real account: the field names and computations follow
the
weheatlibrary 2026.9.3.
Configuration settings
These are the settings Weheat asks for in its configuration screen in Gladys.
| Setting | Type | Required | Description |
|---|---|---|---|
| Weheat heat pumps in Gladys | section | No | Unofficial connector, not affiliated with Weheat. It reads your Weheat heat pumps (Blackbird, Sparrow, Flint) through the official Weheat API, read only: one device per heat pump with its state, water, outside and room temperatures, COP, electrical and heat output power, energy totals and water flow. It signs in with OAuth like the Weheat integration of Home Assistant: your password is typed on the Weheat page only. Never tested yet with a real account or heat pump. Weheat, Blackbird, Sparrow and Flint are trademarks of their owner. |
| Signing in | section | No | 1. Enter the client ID and the client secret Weheat gives for its API (see the guide), and save. 2. Click Connect: the Weheat page opens, sign in there. 3. Weheat sends you back to Gladys and the integration reads your heat pumps. If the redirect address Weheat registered for your client is not this Gladys, write it in "Redirect address": at the end of the sign-in, copy the whole address the browser shows (it holds code= and state=) and paste it into "Finish the sign-in" below, within 15 minutes. The tokens are kept in clear in the /data volume of the integration (readable by its container only), sent only to Weheat; the client secret is kept by Gladys in its database, never shown again, sent only to Weheat. |
| Client ID | string | Yes | Given by Weheat for its third-party API. |
| Client secret | secret | No | Given by Weheat with the client ID. Kept by Gladys in its database, never shown again, sent only to Weheat. |
| Redirect address (optional) | string | No | Empty: Weheat sends you back to this Gladys. Otherwise the address Weheat registered for your client (https, or http on localhost only): finish the sign-in by pasting the address the browser ended on. |
| Weheat account | oauth2 | No | Opens the Weheat sign-in page (save the client ID first). |
| Refresh interval (minutes) | number | No | At least 2 minutes per heat pump, as Home Assistant. The energy totals are read every 30 minutes. |
| Language of the names and texts | select | No |
How to install Weheat in Gladys
- In Gladys, open Integrations: Weheat appears in the catalog, next to the native integrations, with a community badge.
- Click Install. Gladys pulls the Docker image (
ghcr.io/lm1lc3n7/gladys-weheat:0.1.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/LM1LC3N7/gladys-weheat.
Weheat 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
Weheat 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