vcontrold package¶

Submodules¶

vcontrold.vcontrold module¶

class vcontrold.vcontrold.vcontrold(host: str, port: int, timeout: int = 10, log_info: bool = False, log_debug: bool = False)¶

Bases: object

Class to interact with vcontrold via network.

During the initialization the connection to vcontrold is made automatically. After the connection is established, the command getDevType is executed to identify the current heating control system. This will create the properties device_model, device_id, device_protocol.

Note

Outputs to stdout are disabled by default, as it is assumed, that the module will be used within projects, where only the pure data is relevant. If you use the module for other purposes, it could make sense to enable informational logging, by calling with log_info=True.

Parameters

host (str) – vcontrold IP address or hostname
port (int) – Port, on which vcontrold listens
timeout (int) – Timeout in seconds to establish a tcp connection. Defaults to 10.
log_info (bool) – Write informational logs to stdout. Defaults to False.
log_debug (bool) – Write debug logs to stdout. Defaults to False.

Todo

Multi-language support (at least english)
Caching for returned data

get_groups() → list¶

list: Get the groups, configured in the configuration file.

The returned groups can be used in vcontrold_config.yml to modify existing group assignments or to create your own groups. Within vcontrold_config.yml you can add custom groups or replace existing ones with your own, if you’re not happy with the pre-defined groups.

Refer to the Configuration for more information.

Returns: List of sorted groups, found in the configuration file.
Return type: list

Example

>>> vcd = vcontrold(host="127.0.0.1", port=3002)
>>> vcd.get_groups()
['burner', 'environment', 'error', 'mixer', 'operation-mode', 'power', 'pumps', 'solar', 'stats', 'system', 'temperature', 'timer']

get_items_per_group() → dict¶

dict: Get the groups with all assigned commands.

The returned groups contain commands, which are assigned to the group. This is meant to be helpful for you, to create you own overview of the groups and assigned commands.

Returns: Contains groups as items, with assigned commands.
Return type: dict

Example

>>> 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"
        ]
    },
    ...
}

get_units() → list¶

list: Get the units, configured in the configuration file.

Be aware that the returned unit names are used internally, to sanitize the returned data and identify the real unit of measurement.

The use of this command is only to modify units in vcontrold_config.yml, if necessary. If you don’t see a problem with the pre-defined units, don’t change them.

Returns: List of sorted units, found in the configuration file.
Return type: list

Example

>>> 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']

get_viessmann_data(max_values: Optional[int] = None)¶

Requests and returns the actual data from vcontrold.

This method uses groups() to filter the executed commands, if defined. Otherwise, all available commands are executed.

The argument max_values is intended for testing purposes, where you want to query a group of commands, but don’t want to wait until all commands are executed, because you only need an example of the returned data. I’ve used this extensively while sanitizing the returned data.

Note

Please be informed, that vcontrold takes some time, until an executed command returns any data. Each command will approximately need 2.5 seconds to complete. If all available commands are executed, the whole process can take several minutes, untils the reponse is generated. You should consider this when thinking about timeouts or max execution times.

Parameters: max_values (int) – Max number of executed commands.
Returns: Returns data based on self.output_format. Defaults to JSON.
Return type: mixed

unset_group() → None¶

Resets the group filter to any.

Resets the group to any, if a group filter was previously defined with groups().

property csv_delimiter: str¶

Sets the delimiter character for CSV output.

Parameters: delimiter (str) – Defaults to ,.
Returns: The current setting.
Return type: str

Warning

Avoid the use of CSV output in output_format(). It will be completely removed in version 3.0.0.

Type: str

property csv_linebreak: str¶

Sets the linebreak sequence for CSV output.

Parameters: linebreak (str) – Defaults to \n.
Returns: The current setting.
Return type: str

Warning

Avoid the use of CSV output in output_format(). It will be completely removed in version 3.0.0.

Type: str

property device_id: str¶

Identified heating device ID.

Returns: Heating control system device ID.
Return type: str

New in version 2.0.0: Replaced the previous method get_device_id

property device_model: str¶

Identified heating device model.

Returns: Heating control system model.
Return type: str

New in version 2.0.0: Replaced the previous method get_device_model

property device_protocol: str¶

Identified heating communication protocol, used to communicate via Optolink.

Returns: Heating control system communication protocol.
Return type: str

New in version 2.0.0: Replaced the previous method get_device_protocol

property exclude_timers: bool¶

Controls if the returned data contains meta information about the execution time of each command and a global timer for the whole process.

Parameters: exclude_timers (bool, optional) – Defaults to False.
Returns: The current setting.
Return type: bool

New in version 2.0.0.

Type: bool

property groups: Optional[list]¶

Controls the group filter to a specific group or list of groups.

groups() filters the commands, executed when get_viessmann_data() is called, by the applied group or list of groups.

The group assignments in vcontrold_config.yml are made for this filter method.

Note

You can provide either a single group (str) or a list of groups (list). I would recommend to always use the str type, as the single group selector may be removed in future versions.

Parameters: group (str or list) – Group to filter commands. Defaults to None.
Returns: The current list of groups to filter.
Return type: list

New in version 2.0.0: Replaces previous method set_group. Accepts list instead of only a single group name. Returns always list, if defined.

property output_format: str¶

Controls the output format of get_viessmann_data()

Parameters: fmt (str, optional) – Output format. Defaults to json. Supported formats: json, dict, csv
Returns: The current output format.
Return type: str

Example

>>> vcd = vcontrold(host="127.0.0.1", port=3002)
>>> vcd.output_format
json
>>> vcd.output_format = "dict"
>>> vcd.switch_as_bool
dict

New in version 2.0.0: Replaced the previous method set_output_format

property switch_as_bool: bool¶

Controls the returned type for command units of type switch. True will return a bool value to signal whether something is on or off, while False returns on/off as str.

Parameters: use_bool_return (bool, optional) – Defaults to True.
Returns: The current setting.
Return type: bool

Example

>>> vcd = vcontrold(host="127.0.0.1", port=3002)
>>> vcd.switch_as_bool
True
>>> vcd.switch_as_bool = False
>>> vcd.switch_as_bool
False

New in version 2.0.0.

Type: bool

property use_fahrenheit: bool¶

Changes the temperature output to Fahrenheit.

Parameters: use_fahrenheit (bool, optional) – Whether to use Fahrenheit or not. Defaults to False.
Returns: The current value.
Return type: bool

New in version 2.0.0.

vcontrold package¶

Submodules¶

vcontrold.vcontrold module¶

Module contents¶

Documentation

Contents