Viessmann Vitotrol for Home Assistant

A Home Assistant custom integration for Viessmann heating systems that use the Vitotrol mobile app. Connects directly to the Viessmann cloud API.

What you get

Platform	Examples	Description
Climate	Heating	HVAC modes (Off / Dry / Auto), ECO and Boost presets, target temperature control
Sensor	75+ sensors	Temperatures, burner hours/starts, operating modes, solar yield, energy counters, and more
Binary sensor	30 sensors	Burner, pumps, frost protection, holiday mode, solar pump, and more
Switch	10 switches	Party mode, energy saving — per heating circuit
Number	30+ controls	Temperature setpoints, heating curve slope/level — per heating circuit
Select	10+ selectors	Operating mode, heating schema, maintenance mode — plus any discovered writable enums

Supports boilers (Vitodens, Vitovalor), heat pumps (VT 200, Vitocal), and solar-equipped systems. Multi-heating-circuit devices (HC1/HC2/HC3) get per-circuit entities automatically.

The integration queries your device for its full attribute catalog (GetTypeInfo) on first setup. Well-known attributes are enabled by default. All other discovered attributes are created as disabled entities — enable them in the HA entity settings if you need them.

Requirements

• A Viessmann heating system with Vitotrol connectivity
• A Viessmann account (the same credentials you use in the Vitotrol mobile app)
• Home Assistant 2024.12 or newer

Installation

HACS (recommended)

1. Open HACS in Home Assistant
2. Search for Viessmann Vitotrol and install it
3. Restart Home Assistant

Manual

1. Download the custom_components/vitotrol folder from this repository
2. Copy it to your Home Assistant config/custom_components/vitotrol directory
3. Restart Home Assistant

Setup

1. Go to Settings > Devices & Services > Add Integration
2. Search for Viessmann Vitotrol
3. Enter your Viessmann account email and password
4. The integration will connect, discover your devices, and create entities automatically

Configuration

After setup, click Configure on the integration card to adjust options:

Scan interval

How often to poll the Viessmann API for new data (default: 300 seconds, range: 60-900 seconds).

The Vitotrol API is slow by nature — each data refresh involves telling the boiler to upload data, waiting for completion, then reading it. Lower intervals mean fresher data but more API calls.

Climate entity

The climate entity maps Viessmann operating modes to Home Assistant:

HA Mode	Vitotrol Mode	Description
Off	Mode 0	System off
Dry	Mode 1	Domestic hot water only (no space heating). Uses HA's "Dry" mode as the closest match for a DHW-only mode.
Auto	Mode 2	Heating + domestic hot water (recommended)

Presets

Preset	Effect
None	Normal operation
ECO	Enables energy saving mode (reduced temperature)
Boost	Enables party mode (temporarily higher temperature)

Presets are mutually exclusive — enabling ECO disables Boost and vice versa.

Diagnostics

The integration supports Home Assistant's diagnostics feature. Go to the integration page and click Download diagnostics to get a JSON file with your device configuration and current data. Sensitive data (username, password) is automatically redacted.

Troubleshooting

"Unable to connect to the Vitotrol service"

• Verify your credentials work in the Vitotrol mobile app
• The Viessmann cloud service may be temporarily unavailable

"No devices found under this account"

• Ensure your Viessmann device is registered and online in the Vitotrol app

Entities show "unavailable"

• The Vitotrol API can be slow (10-15 seconds per refresh cycle). Wait for at least one full poll interval
• Check if your device is connected in the Vitotrol app
• Some attributes may not be supported by your specific boiler model — unsupported attributes are automatically excluded during discovery

Data feels stale

The Vitotrol API uses a request-wait-poll pattern:

1. Tell the device to upload fresh data
2. Wait ~8 seconds for it to respond
3. Poll until the upload is confirmed
4. Read the data

This is inherent to the API design. The default 300-second scan interval balances freshness against API load.

Known limitations

• API speed: The Viessmann cloud API is inherently slow. Data refreshes take 10-15 seconds, writes take 4-10 seconds. This cannot be improved.
• Single session: The integration uses one session per account. Running the Vitotrol mobile app simultaneously may cause session conflicts.
• Cloud dependency: All communication goes through Viessmann's cloud servers. If their service is down, the integration won't work.

Sharing your device attributes

When reporting issues or requesting support for new attributes, enable debug logging to capture your device's full attribute catalog. Add this to your configuration.yaml:

logger:
  logs:
    custom_components.vitotrol: debug

Restart Home Assistant, then go to Settings > System > Logs and search for Attribute catalog. The log entry contains a JSON block with every attribute your device supports — IDs, names, types, units, min/max, read/write flags, and enum values.

Copy the JSON block and paste it into your GitHub issue. This is all we need to add support for new attributes.

Example JSON output

{
  "device_name": "MyBoiler",
  "device_id": 12345,
  "attributes": {
    "51": {
      "name": "HotWaterSetpointTemp",
      "type": "Double",
      "type_value": "1",
      "min": "10",
      "max": "60",
      "unit": "°C",
      "group": "Hot Water",
      "heating_circuit_id": "",
      "factory_default": "",
      "readable": true,
      "writable": true
    },
    "92": {
      "name": "OperatingModeRequested",
      "type": "Enum",
      "type_value": "2",
      "min": "0",
      "max": "4",
      "unit": "",
      "group": "Operating Modes",
      "heating_circuit_id": "0",
      "factory_default": "",
      "readable": true,
      "writable": true,
      "enum_values": {
        "0": "Off",
        "1": "DHW only",
        "2": "Heating + DHW",
        "3": "Cont. reduced",
        "4": "Cont. normal"
      }
    }
  }
}

Discovery script (advanced)

A standalone script is also available for exploring your device without Home Assistant:

pip install -r scripts/requirements.txt
python scripts/discover.py --user YOUR_EMAIL --password YOUR_PASSWORD --values

Removal

1. Go to Settings > Devices & Services
2. Find Viessmann Vitotrol and click the three-dot menu
3. Select Delete
4. All entities and device entries are removed automatically
5. If you installed via HACS, open HACS, find the integration, and click Remove; otherwise, delete the custom_components/vitotrol folder from your HA config directory
6. Restart Home Assistant

Contributing

The easiest way to contribute is sharing your device's attribute catalog (see above). The contributor guide walks through adding attributes — it's a one-line table addition per attribute.

For deeper changes, see the architecture overview and API reference.

Found a bug or have a feature request? Open an issue.

License

MIT License. See LICENSE for details.

This project is not affiliated with or endorsed by Viessmann. All product names, logos, and brands are property of their respective owners.