openhab-addons/bundles/org.openhab.binding.viessmann

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