openHAB

# Viessmann Binding

This binding connects Viessmann devices via the new Viessmann API. It provides features similar to the ViCare App.

# Important Notes

You must register your ViCare account at the Viessmann developer portal (opens new window) and create a Client ID.

  • name – e.g., openhab
  • Google reCAPTCHA – off
  • Redirect URI – http://localhost:8080/viessmann/authcode/ (*)

(*) If your openHAB system runs on a different port than 8080, adjust the Redirect URI.

Hint: You can add multiple Redirect URIs on the Viessmann developer portal by clicking the plus sign.

# Supported Things

  • account – Connects to the Viessmann API to link the gateway thing; discovers gateways and devices.
  • gateway – Connects to the account thing (Discovery).
  • device – Represents individual devices (Discovery). Connected via gateway or bridge
  • bridge – (deprecated) Connects directly to the Viessmann API and links the first installed gateway.

# Thing Hierarchy

Account Thing
   │
   └── Gateway Thing (discovered via Account)
          │
          └── Device Things (discovered via Gateway)


Bridge Thing (connects directly to API) (deprecated)
   │
   └── Device Things (discovered via Bridge)

# Binding Configuration

# Account Thing

Parameter Required Default Description
apiKey Yes – Client ID from the Viessmann developer portal
user Yes – E-Mail registered for the ViCare App
password Yes – Password registered for the ViCare App
apiCallLimit No 1450 Limit for API calls (*)
bufferApiCommands No 450 Buffer for commands (*)
pollingInterval No 0 Interval in seconds to query available devices (**)
pollingIntervalErrors No 60 Interval in minutes to query errors
disablePolling No OFF Disables automatic polling

# Bridge Thing (deprecated)

Parameter Required Default Description
apiKey Yes – Client ID from the Viessmann developer portal
user Yes – E-Mail registered for the ViCare App
password Yes – Password registered for the ViCare App
installationId No – Optional, will be discovered
gatewaySerial No – Optional, will be discovered
apiCallLimit No 1450 Limit for API calls (*)
bufferApiCommands No 450 Buffer for commands (*)
pollingInterval No 0 Interval in seconds to query available devices (**)
pollingIntervalErrors No 60 Interval in minutes to query errors
disablePolling No OFF Disables automatic polling

# Gateway Thing

Parameter Required Default Description
installationId No – Optional, will be discovered
gatewaySerial No – Optional, will be discovered
pollingIntervalErrors No 60 Interval in minutes to query errors
disablePolling No OFF Disables automatic polling

(*) Used to calculate refresh time in seconds
(**) If set to 0, interval is calculated automatically by the binding.

# Channels

# Account

Channel Type RO/RW Description
count-api-calls Number RO Number of API calls today

# Bridge (deprecated)

Channel Type RO/RW Description
count-api-calls Number RO Number of API calls today
error-is-active Switch RO Indicates active error
last-error-message String RO Last error message from installation
run-query-once Switch W Run device query once
run-error-query-once Switch W Run error query once

# Gateway

Channel Type RO/RW Description
error-is-active Switch RO Indicates active error
last-error-message String RO Last error message from installation
run-query-once Switch W Run device query once
run-error-query-once Switch W Run error query once

# Device

Channels are generated automatically for available features.

# Examples: Thing Definitions in openHAB

# Account Thing

Thing viessmann:account:myaccount "Viessmann Account" @ "Home" [
    apiKey="YOUR_CLIENT_ID",
    user="YOUR_EMAIL",
    password="YOUR_PASSWORD"
]

# Bridge Thing (deprecated)

Thing viessmann:bridge:mybridge "Viessmann Bridge" @ "Home" [
    apiKey="YOUR_CLIENT_ID",
    user="YOUR_EMAIL",
    password="YOUR_PASSWORD"
]

# Gateway Thing

Thing viessmann:gateway:mygateway "Viessmann Gateway" @ "Home" [
    installationId="YOUR_INSTALLATION_ID",
    gatewaySerial="YOUR_GATEWAY_SERIAL"
]

# Device Thing

Thing viessmann:device:heating "Heating Device" @ "Home" [
    deviceId="YOUR_DEVICE_ID"
]

# Breaking Changes

# Version 5.1.0

  • Added new account and gateway things for gateway selection.
    Existing device things can be switched manually to the new gateway as bridge.
    After that, the bridge thing can be removed.
  • Reorganization of channel-types: Starting the binding takes about 3 minutes
    and results in the following warnings, which will not occur on the next restart:
[WARN ] [.core.thing.internal.ThingManagerImpl] - Failed to normalize configuration for thing 'viessmann:device:abcdefg:xxxxxxxxx:0': 
{thing/channel=Type description viessmann:type-string for viessmann:device:abcdefg:xxxxxxxxx:0:heating-circuits-0-operating-programs-active not found, 
although we checked the presence before.}
Caught a mistake or want to contribute to the documentation? Edit this page on GitHub (opens new window)

← VigiCrues →