Viessmann ViCare smart home integration, free and open source
Viessmann boilers and heat pumps through ViCare: heating, hot water and sensors.
Published by bertrandda
- Devices
- Version 1.1.0
- Requires Gladys >=5.1.0
- ★ 0
This integration connects Viessmann boilers (gas, oil) and heat pumps linked to the ViCare app to Gladys, through the Viessmann cloud: heating, domestic hot water, temperatures and consumption.
Requirements
- A Viessmann appliance visible in the ViCare app (Vitoconnect gateway or built-in gateway).
- Your ViCare account (e-mail address and password).
- Gladys 5.1 or later, with Internet access.
1. Create a client on the Viessmann developer portal
The ViCare API needs a free, personal "client", created once:
- Open the Viessmann developer portal and sign in with your ViCare credentials.
- Create a new client (Clients menu).
- Give it a name (for example "Gladys") and set its redirect URI to the
address shown in the Configuration screen of the integration, under the
Connect button:
https://my.gladysassistant.com/redirect/oauth. It must match character for character. Leave the other options to their defaults. - Save, then copy the Client ID. No secret is needed.
The free plan ("Basic") is enough: it allows 1450 API calls a day.
2. Configure the integration in Gladys
- In the Configuration tab of the integration, paste the client ID and save the configuration.
- Only then, in the ViCare account block, click Connect, sign in with your ViCare account and accept the access. Connect uses the saved client ID, not the one being typed: clicking it before saving fails.
- The status turns to "Connected". The Test the connection button lists the installations, gateways and appliances found.
- In the Discovery tab, add the devices and put each heating circuit in its room.
Devices
For each boiler or heat pump, the integration offers up to three kinds of devices. Only the features your model actually reports are created.
One thermostat per heating circuit
| Feature | Description |
|---|---|
| Target temperature | Temperature of the program currently running (normal, reduced, comfort...). Changing it changes that program, like the ViCare app does. |
| Mode | Off, heating, cooling or auto (see the table below). |
| Operating state | Idle, heating or cooling, from the burner or compressor. |
| Room temperature | When a room sensor is wired to the circuit. |
| Supply temperature | Temperature of the water sent into the circuit. |
Domestic hot water (water heater)
| Feature | Description |
|---|---|
| Hot water target temperature | Requested hot water temperature. |
| Hot water mode | On recent (E3) appliances and heat pumps (see the table below). |
| One-time charge | Heat the tank once, right now. |
| Hot water heating | The tank is being heated. |
| Hot water tank temperature | Temperature measured in the tank. |
Heat generator (boiler or heat pump)
Read-only sensors: outside, boiler, supply and return temperatures (primary and secondary circuits on heat pumps), burner and compressor (running, number of starts, operating hours), today's gas consumption (m³ or kWh depending on the model) and power consumption (kWh).
Mode mapping
Heating circuit mode:
| ViCare mode | Gladys mode |
|---|---|
standby, dhw (hot water only) | Off |
heating, dhwAndHeating, forcedNormal, forcedReduced | Heating |
cooling | Cooling |
heatingCooling, dhwAndHeatingCooling | Auto |
Turning a circuit off from Gladys picks dhw when the appliance supports
it: heating stops but hot water keeps being produced. Hot water has its own
controls, on the water heater device.
Hot water mode:
| ViCare mode | Gladys mode |
|---|---|
off | Off |
eco, efficient, efficientWithMinComfort | Eco |
balanced | Auto |
comfort | Manual |
Eco gathers the economy modes of ViCare (eco, efficient,
efficientWithMinComfort, named "Eco" or "Efficient" in the app depending on
the model). Gladys has no "Comfort" mode for water heaters: ViCare comfort
shows as Manual.
A mode your appliance does not offer is refused, with a message listing the accepted modes.
Heating schedule widget
On a dashboard, add the Heating schedule widget of the integration and choose a heating circuit. It shows:
- the program the circuit runs now, and its setpoint, live;
- the ViCare weekly schedule, one row a day, and the program that runs outside the slots (usually reduced);
- the heating curve: slope and shift.
The widget costs no API call: it uses the values of the regular refresh.
The schedule is read-only: change it in the ViCare app. The Heating curve button opens a form to change the slope and the shift (Gladys 5.2 or later; on Gladys 5.1 the button says so). The curve sets the supply temperature from the outside temperature:
- too cold when it freezes outside, fine in mid-season: raise the slope;
- too cold (or too warm) whatever the weather: raise (or lower) the shift.
Change it in small steps (0.1 for the slope, 1 for the shift) and wait a few days between two changes: a building reacts slowly. The room and outside temperatures kept in the Gladys history help judging the result.
Gladys 5.2 thermostat (schedule and widget)
Gladys 5.2 can program a heating circuit with its own weekly schedule and show it in its thermostat widget:
- In Integrations → Thermostat, create an external thermostat.
- Setpoint: the Target temperature of the circuit. Mode: its Mode. State: its Operating state. Temperature: its Room temperature when the circuit has a room sensor, otherwise any room sensor.
- Attach a schedule if Gladys should program the circuit.
Good to know:
- The setpoint Gladys writes changes the temperature of the program the circuit runs in ViCare (normal, reduced, comfort). If the ViCare schedule keeps switching between normal and reduced, the setpoints of Gladys land in both programs. To let the Gladys schedule rule, set the ViCare schedule of the circuit to a single "normal" slot over the whole day in the ViCare app. To keep the ViCare schedule, do not attach a Gladys schedule.
- Stopping the thermostat sets the circuit to hot water only: hot water keeps being produced. Gladys then also writes its frost protection setpoint, and writes the right setpoint back when the thermostat starts again.
- Each value Gladys writes is one API call (an unchanged value is not sent again).
Refresh and quota
- The integration reads every value of a gateway in a single call. The default interval (120 s) uses about 720 of the 1450 daily calls. With several gateways, the interval is multiplied by their number to stay within the quota.
- After a command, the new value shows up right away, and the appliance is read again about fifteen seconds later to confirm it.
- When the quota is exhausted, the integration pauses until it renews. The Configuration screen shows when it resumes (UTC). Raise the refresh interval if it happens.
Known limitations
- Thermostat presets (comfort, eco, away) are not offered: Gladys only has them since 5.2, and the integration still supports Gladys 5.1.
- When the circuit runs a program without an adjustable temperature (standby, frost protection), the target temperature is not shown and cannot be changed.
- Not supported yet: burner modulation (Gladys has no matching category), solar thermal, photovoltaics and batteries, ventilation, Zigbee thermostats and sensors, the temperature of each program, and changing the schedules (shown read-only in the widget).
- The clock of the boiler cannot be set from Gladys: the ViCare API has no command for it. Set it from the boiler menu.
- Control only goes through the Viessmann cloud: an Internet connection is required.
Troubleshooting
- "Enter the client ID…", or Connect fails: paste the Client ID of the developer portal and save the configuration before clicking Connect.
- Redirect error while connecting: the redirect URI of the client on the portal must be exactly the one shown under the Connect button.
- "The ViCare authorization expired or was revoked": click Connect again. Changing the client ID also requires connecting again.
- "ViCare API daily quota reached": wait for the time shown and raise the refresh interval.
- A gateway is offline: its devices keep their last values, the others keep being updated.
- The integration logs detail every error. They never contain your tokens.
Configuration settings
These are the settings Viessmann ViCare asks for in its configuration screen in Gladys.
| Setting | Type | Required | Description |
|---|---|---|---|
| Before you start | section | No | 1. Sign in to the Viessmann developer portal with your ViCare account and create a client whose redirect URI is the address shown under the Connect button below. 2. Paste its client ID in the field below. 3. Save the configuration. 4. Only then, click Connect and sign in with your ViCare account. The Documentation link details every step. |
| Client ID | string | Yes | Client ID of the application created on the Viessmann developer portal. |
| ViCare account | oauth2 | No | Save the configuration with the client ID before clicking Connect: Connect uses the saved client ID, not the one being typed. |
| Refresh interval (s) | number | No | Seconds between two readings of a gateway. The free ViCare plan allows 1450 calls a day: 120 s uses about half of it, and the interval is multiplied by the number of gateways. |
How to install Viessmann ViCare in Gladys
- In Gladys, open Integrations: Viessmann ViCare appears in the catalog, next to the native integrations, with a community badge.
- Click Install. Gladys pulls the Docker image (
ghcr.io/bertrandda/gladys-viessmann:1.1.0), 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/bertrandda/gladys-viessmann.
Viessmann ViCare 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
Viessmann ViCare 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 bertrandda, 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