Viessmann API binding for 3.3.x [3.3.0;3.4.0)

Add-on Marketplace Bundles
, , ,
1

Screenshot from 2022-09-19 12-44-16

This binding integrates Viessmann heating devices using the Viessmann API.
It provides information similar to what you can get through the ViCare mobile app.

Please note this binding is unofficial and not endorsed by Viessmann in any way.

This binding has been developed against 3.3.0 stable release and is not
supported for 3.4.0.

Requirements

This binding requires OpenHAB 3.3.
Users of OpenHAB 3.4 please use the 3.4 version of this binding

Supported Devices

Currently this binding has only been tested with Vitodens 100-W in a fairly
basic configuration, however it should support other Viessmann devices.

Supported Features

Below is an incomplete summary of the main features supported - depending on your boiler model and/or heating
configuration some or all of these may or may not be present:

  • Read and write of active heating circuit operating mode.
  • Temperature sensors
  • Temperature setpoints (read/write)
  • Supply temperature max/min limit (read/write)
  • Burner status
  • Burner modulation
  • Burner statistics (hours and starts)
  • Circulation pump status
  • Frost protection status
  • Basic text properties: device serial number etc.
  • DHW, Heating and Total consumption statistics
  • Program mode temperature settings
  • DHW Heating status
  • DHW Hot water storage temperature
  • DHW Primary and Circulation Pump Status
  • DHW target temperature (read/write)
  • DHW One time charge mode (read/write)
  • Holiday program settings (read-only)
  • Holiday-at-home program settings (read-only)
  • Heating curve settings
  • Heating circuit names
  • Heating circuit operating mode (read/write)
  • Heating circuit supply temperature
  • Extended heating mode
  • Solar production statistics
  • Solar collector temperature
  • Solar circuit pump status
  • Heat pump compressor status
  • Heat pump compressor statistics
  • Heat pump primary and secondary supply temperature sensors

Configuring

In order to use the binding, you will need to have a Viessmann API account and
configure it with the redirect URL for your OpenHAB installation and then authorise
the binding. Follow the instructions in openhab at http://<Your OpenHAB>/vicare/setup

Create an instance of the Viessmann API Bridge thing, and configure it with your Client ID
which you should obtain from the Viessmann Developer portal. The developer portal should be
configured with the redirect URI shown on the setup page. Then you should be able to
authorise the Viessmann binding by clicking on the Authorise button on the setup page.

After authorising the binding, then it should automatically discover any heating devices you have
and they will appear in your Inbox.

Changelog

3.3.6

  • Fix #29 VicareDiscoveryService fails if some properties are null
  • Fix #25 README + setup instructions are misleading
  • Fix #24 Support for heat pump features
  • Fix #23 Create equipment from Thing fails with “Bad Request”
  • Fix #21 Support setting for DHW target temperature heating.dhw.temperature.main
  • Fix #9 Add response capture for installations and gateways
  • Support additional features.
    Note: Some of the channel names with string values may have changed slightly -
    heating_circuits_operating_modes_active, device_serial may now have _value suffixes.
    Please check your Items for missing channel links and relink if upgrading from a previous version.
  • Support for dynamic channel types - channel labels should now clearly identify which heating
    circuit they are associated with, and max/min values should be exposed for controllable values.

3.3.5

  • Fix #19 Using openhab in Docker prevents authentication - Illegal key size - CRYPTO_POLICY ==> limited
  • Fix #18 Binding makes excessive calls during power outage
  • Fix #17 Text features missing from boiler channels
  • Additional device properties available on Thing

3.3.4

  • Add read/write support for heating.circuits.N.temperature.levels
  • Add write support for operating program temperature setpoints
  • Fix #16 Cannot start binding from new install - token store not initialized

3.3.3

  • Stored tokens are now encrypted
  • Support for read and write of heating.circuits.N.operating.modes.active
  • Channels are now sorted
  • Fix #5 The binding should automatically discover devices after OAuth access token is granted the first time.
  • Fix #7 If binding throws unhandled exception, things are no longer updated

3.3.2

Polling interval is now configurable.

Read-only support for additional features:

  • Burner status
  • DHW Heating status
  • DHW Hot water storage temperature
  • DHW Primary and Circulation Pump Status
  • Holiday Program settings
  • Heating curve settings

Note that the names of some channels may have changed slightly in order to
distinguish between “active” and “status”. Status channels are now of String type
and not Switch - you may need to either change your linked item type accordingly or
apply a transformation to the value.

Fix #2 If more than one boiler is configured, the binding doesn’t work correctly

3.3.1

This is the initial release

Resources

Github source code
Github Release binary

5 Likes
2

I get the following error for the authorising:
{"error":"Client not registered."}

After filling the client ID manually in the url, I get this error:
Received error from server: invalid-token-request

I think your correct URL is:
http://192.168.101.120:8080/vicare/authCode
Ther is a Space missing after that.
Currently you write:
.....vicare/authCodeOnce this is done, then.....

3

Sounds like either:

  • you don’t have a clientId from Viessmann - you need to go to https://developer.viessmann.com and sign up for their API, once you’ve done that the clientId is shown in the Developer Portal Dashboard

viessman-config
viessman-config616×651 24.5 KB

You also need to configure it with the redirect Uri to your own OpenHAB install as shown

Then you should be able to go to /vicare/setup on your OpenHAB install and authorise it.

Edit: Ah ok I see you’ve done this

Yes, you are right, there is a typo in the URL, on the setup page. It will be fixed in the next release

1 Like
4

I cannot find your bridge 

I just copied the binding in the addon folder 
 any other steps necessary to see your bridge?

5

You should be able to add the bridge as soon as the binding is installed - just go to Settings->Things, click ‘+’ → Select Viessman API Binding → Viessman API Bridge

1 Like
6

Works for the first step :slightly_smiling_face:
But for me the binding doesn’t supply all the information I like to have.
I’m looking for these items :innocent:

image
image906×736 54.9 KB

7

I’ve created a github issue Support additional features on Viessmann API Binding · Issue #1 · rtuck99/openhab-binding · GitHub

It’ll take a little while to decode all that :slight_smile:

I think you should have quite a few of those supported already though, this is what my heating system shows:

image
image807×917 165 KB

image
image814×980 219 KB

image
image809×745 162 KB

image
image777×572 47.1 KB

1 Like
8

I will continue my testing on friday :grinning:
If I remember, my item list was not so long :thinking:

9

I’ve updated the github issue, there is a link to a spreadsheet on it with a breakdown of what features correspond to what.

There are some features that are advanced features and only available in Viessmann’s paid-for API. If there’s demand for it, I might consider supporting if people are willing to send sample API responses to develop against.

The other ones, some I can support fairly easily but others I will need to see what the API is returning. I will see if I can get you a debug version of the addon that will record what comes back from the API so I can support them.

There is one of the values “Externe Betriebsartenumschaltung” that I really have no idea what it is “External operating mode switchover”? Do you have a better translation? I can’t find anything that looks like a likely candidate in Viessmann’s API documentation.

1 Like
10

“Externe Betriebsartenumschaltung” means an external “switch” for changing the operation mode.
The API ist an internal switch :wink: - so not really necessary

11

Additional features requested should now be supported in 3.3.2

1 Like
12

looks good :+1:

when I create items in vscode from the vscode extension for openhab (create items from channel), all items are undefined
image

13

Hi,

thanks for integrating the Viessmann API. I have been waiting for years to integrate my Viessmann Heating to OpenHab.

I installed you binding (version 3.3.2) and created the bridge. I have added the correct client ID. But it remains in state unknown (no log message why). Once I add the Heating Device I get the following NullPointerException:

‘com.qubular.openhab.binding.vicare.internal.VicareDeviceThingHandler@5a9d76’: null
java.lang.NullPointerException: null
at com.qubular.openhab.binding.vicare.internal.VicareUtil.decodeThingUniqueId(VicareUtil.java:25) ~[?:?]
at com.qubular.openhab.binding.vicare.internal.VicareDeviceThingHandler.initialize(VicareDeviceThingHandler.java:62) ~[?:?]
at jdk.internal.reflect.GeneratedMethodAccessor107.invoke(Unknown Source) ~[?:?]
at jdk.internal.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43) ~[?:?]
at java.lang.reflect.Method.invoke(Method.java:566) ~[?:?]
at org.openhab.core.internal.common.AbstractInvocationHandler.invokeDirect(AbstractInvocationHandler.java:154) [bundleFile:?]
at org.openhab.core.internal.common.Invocation.call(Invocation.java:52) [bundleFile:?]
at java.util.concurrent.FutureTask.run(FutureTask.java:264) [?:?]
at java.util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1128) [?:?]
at java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:628) [?:?]
at java.lang.Thread.run(Thread.java:834) [?:?]

Any advice?

Thanks a lot!
Björn

14

Hi there,

It sounds like it can’t find a property defined on the Device Thing. There should be a property

image
image757×465 38.9 KB

deviceUniqueId that is automatically populated on the Thing when it is created in the Inbox.

If you are creating it via a text file, it won’t work, as the info in this needs to be obtained from the API.

15

I’m not familiar with the VSCode extension. Where does it get the information for the channel definitions from?

16

I dont know 
 I just use it :see_no_evil:
In the UI I can see the correct definition 
 ok, thats more nice to have :grinning:

In current version I’m missing the channel for the normal mode “DWH” or “DHWandHeating”.
Can you mark which channel are writeable?
I test to set the eco od comfort mode but without success 


The channels for:
heating_dhw_pumps_primary_active and heating_dhw_pumps_circulation_active give an UNDEV back.

17

Currently there’s no write support for any of the channels, although I am planning it. I’ve raised an enhancement for operating.modes.active property which is what selects between DHW, heating and DHW+heating

The heating_dhw_pumps_primary and heating_dhw_pumps_circulation features don’t have an “active” property for some reason, only “status”. Hence they are UNDEF. TBH I am not entirely sure what the distinction is between “active” and “status” properties, I haven’t figured out why sometimes one is used and not the other. But some things have both, and sometimes the status is something other than “on” or “off”, like “connected” or “error”.

I will have a bit of a look at VSCode, although I don’t think I’m doing anything unusual, so it should just work?

1 Like
18

sounds good :slight_smile:
So like I wrot, the vscode method for creating items is mor “nice to have”.

Suggestion from my side:
Make the differnt modes and pump for dhw circulation writeable.

My plan is to change between these modes in depend of outside temp and if someone is present in the house or all outside.

Like:
Outside > 10 degree, no one present – change mode to reduced
Outside > 19 degree, change mode to dhw only
Outside < 11 degree, no one present, change mode to eco
No-one present, stop dhw circulation

And so on. Today I do this manually 
 but this is not smart :stuck_out_tongue_winking_eye:

1 Like
19

Hi,

thanks for the quick reply. I do not see any things properties.

  1. I go to + and add the Viessmann API Bridge. I enter my client ID and hit create thing.
  2. The Viessmann Bridge is in the status UNKNOWN without any hint in the logfiles.
  3. There is no Heating Device in the inbox.
  4. I hit + and add a heating device. This one has no properties but is empty.

Any suggestions what I do wrong?

Thanks a lot!!

Björn

20

Hi Bjorn,

It’s possible the discovery service didn’t successfully discover the heating device the first time; it doesn’t poll very

frequently for new devices. Remove your manually added heating device, and suspend and restart the bridge, that should
trigger the discovery again.

If that doesn’t work, then you can try editing your userdata/etc/log4j2.xml and insert

into it, restart OpenHAB and check the openhab.log output - send it to me if nothing obvious jumps out