Usage¶
Quickstart¶
Warning
You need to know your device ID. If you don’t already know it, use device_id to find the device ID of your heating control system. If your device ID is not listed in the devices node within vcontrold_config.yml, you need to add it (or replace the existing) to each command. Otherwise no command will be processed!
Just import the class vcontrold, create an instance and fire get_viessmann_data(). This will return the data as JSON, from all available commands.
>>> from vcontrold import vcontrold
>>> vcd = vcontrold.vcontrold(host="127.0.0.1", port=3002, timeout=5)
>>> vcd.get_viessmann_data()
{
"meta": {
"execution_time": "4.187 seconds",
"num_items": 2
},
"data": {
"getTempA": {
"value": 3.0,
"unit": "C",
"description": "Ermittle die Aussentemperatur",
"state": "success",
"execution_time": "2.094 seconds"
},
"getTempKist": {
"value": 65.8,
"unit": "C",
"description": "Ermittle die Kesseltemperatur",
"state": "success",
"execution_time": "2.094 seconds"
}
...
}
}
When you call get_viessmann_data(), it first creates a dynamic list of all commands, that shall be processed, based on the group filter (groups) and the status of the command (refer to the Configuration). When the list is created, all commands in this list will be processed sequentially.
Each command needs approximately 2 seconds to complete. It may be different for your heating controld system. The return data contains the time to complete as execution_time for each command and for the whole process. If you’re not interested in this data, you can exclude the timers with exclude_timers=True
>>> from vcontrold import vcontrold
>>> vcd = vcontrold.vcontrold(host="127.0.0.1", port=3002, timeout=5)
>>> vcd.exclude_timers = True
>>> vcd.get_viessmann_data()
{
"meta": {
"num_items": 1
},
"data": {
"getBetriebArtM1": {
"value": "H+WW",
"unit": "str",
"description": "Betriebsart M1",
"state": "success"
}
...
}
}
Limit the amount of returned data¶
For testing purposes you might want to limit the number of commands, as each command requires n seconds to complete. Therefore you can specify get_viessmann_data(max_values=1), to limit the number of processed commands.
max_values will return all commands, if 0 is provided (kind of any). If the number of max_values is greater than the number of commands in the dynamic list, the dynamic list is used instead.
Group Filter¶
As you may not always want to process all commands (it takes quite a long time), you can query specific commands by using the assigned groups. Each (get-)command is assigned to one or more groups. By defining a group filter with groups you can limit the requested data to just a single or multiple group of commands.
>>> vcd = vcontrold(host="127.0.0.1", port=3002)
>>> vcd.groups('temperature')
>>> vcd.get_viessmann_data(max_values=2)
{
"meta": {
"execution_time": "4.186 seconds",
"num_items": 2
},
"data": {
"getTempA": {
"value": 2.8,
"unit": "C",
"description": "Ermittle die Aussentemperatur",
"state": "success",
"execution_time": "2.095 seconds"
},
"getTempKist": {
"value": 67.5,
"unit": "C",
"description": "Ermittle die Kesseltemperatur",
"state": "success",
"execution_time": "2.091 seconds"
}
}
}
In this example, only commands, that are assigned to the group temperature are processed, limited to only 2 results by applying max_values=2. If you want to filter the command to more than one group, you need to provide a list instead.
>>> vcd = vcontrold(host="127.0.0.1", port=3002)
>>> vcd.groups = ['temperature', 'system']
>>> vcd.get_viessmann_data()
{
"meta": {
"execution_time": "61.205 seconds",
"num_items": 29
},
"data": {
"getDevType": {
"value": "V200KW1 ID=2094 Protokoll:KW",
"unit": "str",
"description": "Ermittle Device Typ der Anlage",
"state": "success",
"execution_time": "2.093 seconds"
},
"getError0": {
"value": {
"parsed": {
"date": "2016-12-29",
"time": "13:34:56",
"errorMessage": "Brennerstoerung (D1)"
},
"original": "2016-12-29T13:34:56+0100 Brennerstoerung (D1)"
},
"unit": null,
"description": "Ermittle Fehlerhistory Eintrag 1",
"state": "success",
"execution_time": "2.131 seconds"
},
...
"getSystemTime": {
"value": "2022-01-16 - 14:35:01",
"unit": "datetime",
"description": "Ermittle Systemzeit",
"state": "success",
"execution_time": "2.127 seconds"
},
"getTempA": {
"value": 2.9,
"unit": "C",
"description": "Ermittle die Aussentemperatur",
"state": "success",
"execution_time": "2.092 seconds"
},
...
}
}
If you want to reset the group filter, you can either create a new instance, or, preferably, use unset_group() to just reset everything back to any.
Receive groups and commands from configuration¶
To modifiy the groups within vcontrold_config.yml, you need to get an overview of all existing groups. This can be achieved by using get_groups(). This returns a list of all existing groups.
>>> vcd = vcontrold.vcontrold(host="127.0.0.1", port=3002, timeout=5)
>>> vcd.get_groups()
['burner', 'environment', 'error', 'mixer', 'operation-mode', 'power', 'pumps', 'solar', 'stats', 'system', 'temperature', 'timer']
The list of groups can be modified, as needed. Refer to the Configuration for more information.
However, usually you’ll want to know, which commands are assigned to which groups. This information can be received with get_items_per_group().
>>> vcd = vcontrold(host="127.0.0.1", port=3002)
>>> vcd.get_items_per_group()
{
"burner": {
"num_items": 4,
"items": [
"getBrennerStarts",
"getBrennerStatus",
"getBrennerStunden1",
"getBrennerStunden2"
]
},
"environment": {
"num_items": 4,
"items": [
"getNeigungM1",
"getNeigungM2",
"getNiveauM1",
"getNiveauM2"
]
},
...
}
The returned dict contains all groups and which commands are currently assigned to the group. It basically reflects the contents of the vcontrold_config.yml.
Device Filter¶
The device filter works almost in the same way like the group filter. In the vcontrold_config.yml you will find a list of devices for each command. Not each heating control system supports the same commands. Some command are only available for specific systems. Therefore, there is a filter applied internally, to only process commands on the devices (or device IDs), for which they’re available.
I assume, that everyone of us has only one heating controld system. So you can just identify your own device ID with device_id and do a search’n’replace within vcontrold_config.yml (refer to the Configuration).
My approach is to pre-define as much as possible here. If I will get a verified list of commands, that are available on other device IDs as well, I will pre-define more device IDs here. Feel free to open an issue or send me the information vial mail.
Units of measurement¶
Units are currently pre-defined within vcontrold_config.yml. Each type of unit results in another data type and unit of measurement. For now you can only use the pre-defined units. In the future there may be a chance to provide a callback function, to handle the sanitization on your own. But for now :py:module:`.vcontrold` is not yet advanced enough. The priority for such an implementation will be based on the feedback.
However, you can receive a list of the currently available units with get_units().
>>> vcd = vcontrold(host="127.0.0.1", port=3002)
>>> vcd.get_units()
['error', 'hours', 'none', 'number', 'percent', 'power', 'shift', 'slope', 'switch', 'temperature', 'text', 'time', 'timer']
The meaning of each unit is described within the Configuration.
Get informational output¶
While creating an instance of vcontrold, you can control whether to log informational output or not, by defining log_info=True. If you run this module for the first time, I recommend to use it. It helps to better understand what happens underneath. Additionally, processing commands can take a while. With informational output you will see, that there is still something happening.
>>> vcd = vcontrold(host="127.0.0.1", port=3002, log_info=True)
>>> vcd.groups = ['temperature']
>>> vcd.get_viessmann_data(max_values=2)
Failed to identify heating control system. Returned data doesn't meet expectations. Attempt 1 of 3
Device correctly identified as model V200KW1 (ID=2094, Protocol=KW) at attempt 2 of 3
Limited the maximum returned values to 2.
Executing command 02 of 02 (getTempKist)...
-------------------------------
{
"meta": {
"execution_time": "4.187 seconds",
"num_items": 2
},
"data": {
"getTempA": {
"value": 2.9,
"unit": "C",
"description": "Ermittle die Aussentemperatur",
"state": "success",
"execution_time": "2.093 seconds"
},
"getTempKist": {
"value": 71.4,
"unit": "C",
"description": "Ermittle die Kesseltemperatur",
"state": "success",
"execution_time": "2.094 seconds"
}
}
}
Output formats¶
The data can be returned in multiple formats. As of version 1.0.0 they are
json (Default)
dict
csv
You can define the output format with output_format, i.e. .output_format="dict".
To be honest, I don’t think, that it makes much sense to differ between JSON and dict. And CSV is very unlikely and it’s hard to convert the data structure within CSV. Therefore, CSV will be removed in future versions.
I’m thinking about removing the option to differ between output formats and just return the data as dict. If other formats are necessary, you can convert the data on your own. If there are requests for specific formats in the future, let me know and then we can discuss things.
Other options¶
There are a few more options available, that you can define after creating an instance of vcontrold.
device_model: Returns the device ID by processinggetDevTypecommand.device_id: Returns the device ID by processinggetDevTypecommand.device_protocol: Returns the device ID by processinggetDevTypecommand.switch_as_bool(bool): IfTrue(Default) commands with unitswitchreturn their values asbool. IfFalse, they are returned asstron/off.use_fahrenheit(bool): IfTrue, returned temperature values are converted from Celsius to Fahrenheit. IfFalse(Default), temperatures are returned as Celsius.
If you need more usage examples, just let me know.