feat: Add methods do distinguish between e3 and legacy devices

[CFenner]

related to this:

November 2022

Important adjustment in IoT features: Split heating circuits and domestic hot water

In our API we have coupled heating circuits (HC) and domestic hot water (DHW) support closely together to keep the backwards compatibility between Legacy devices and devices based on our Viessmann One Base control platform, also called E3. Viessmann One Base provides the HCs and DHW as independent systems with a chance to access HC- and DHW-features as independent features.

What is being adjusted?

The planned adjustments brings the following changes to our IoT features:

adjust heating.circuits.N.operating.modes.* by removing existent DHW dependencies
remove heating.circuits.N.operating.modes.dhw* operating modes
adjust heating.circuits.N.operating.modes.active to only show the following states for the “value” property: auto, heating, cooling, heatingCooling or testMode
The DHW operating can in future be requested through the following new features:

introduce heating.dhw.operating.modes.off >> Shows whether the DHW is off
adjust heating.dhw.operating.modes.active >> Shows the current DHW operating mode with the possible states for the “value” property: balanced, comfort, eco, off
This change only affects our Viessmann One Base (E3) control platform (wifi integrated devices). For legacy devices, i.e. using a Vitoconnect, there are no changes. However, this also means, depending on the device, requesting and changing the DHW operating mode differs.

How to find out which device (legacy / One Base) is used?

To find which device you have, you can use the following request to check the devices of your installation: curl -X GET https://api.viessmann.com/iot/v1/equipment/installations/{{installationID}}/gateways/{{gatewaySerial}}/devices/

In the response, you find the list of devices, containing information about the type of device:

{
   "data": [
       {
           "gatewaySerial": {{gatewaySerial}},
           "id": {{deviceId}},
           "boilerSerial": {{boilerSerial}},
           "boilerSerialEditor": "DeviceCommunication",
           "bmuSerial": null,
           "bmuSerialEditor": null,
           "createdAt": "2020-11-16T07:06:56.267Z",
           "editedAt": "2022-10-27T11:16:06.670Z",
           "modelId": "E3_Vitodens_300_0421",
           "status": "Online",
           "deviceType": "heating",
           "roles": [
               "capability:backup;0002_HMU_VD3",
               "type:E3",
               "type:boiler",
               "type:product;Vitodens_300"
           ]
       },
   ]
}

The “roles” parameter lists the different types the device is assigned to. Here, you will find either the type:E3 or type:legacy. This information then tells you how to check the DHW operating modes.

When will this change take effect?

The adjustments will go live in January 2023 (exact date will be added as soon as possible). From this date, you can only request the DHW operating mode for E3 using the described new way.