Configuration

The library uses a configuration file, vcontrold_config.yml, in YAML format, which contains all known commands and defines several parameters for each command. The initial configuration will be created automatically within your project root (based on __file__ from which __main__ is called). After the creation you can modify the configuration file as you like.

vcontrold_config.yml

vcontrold_commands

As said above, the file is created automatically when starting for first time, or with other word, if the file doesn’t exist. If, at any point, you messed up with the configuration file, just delete it and it will be re-created at the next run.

Following is the structure of the file:

vcontrold_commands:
  get:
    getBetriebArtM1:
      description: Betriebsart M1
      devices:
      - 2094
      groups:
      - operation-mode
      status: enabled
      unit: text
    getBrennerStatus:
      description: Ermittle den Brennerstatus
      devices:
      - 2094
      groups:
      - burner
      status: enabled
      unit: switch
    getSystemTime:
      description: Ermittle Systemzeit
      devices:
      - 2094
      groups:
      - system
      status: enabled
      unit: time
    ...
  set:
    setBetriebArtM1:
      description: Setze Betriebsart M1
      devices:
      - 2094
      groups: []
      status: enabled
      unit: none
    ...

The file basically consists of a single dict, vcontrold_commands, with two sub items get and set, both are of type dict as well. These are used to differ between get- and set-commands. set-commands are currently not yet implemented, although they already exist in the configuration.

Each item of get or set is a vcontrold command, i.e.

getBrennerStatus:                   # <-- vcontrold command
  description: Brennerstatus        # <-- description of the command (used in output)
  devices:                          # <-- list of device IDs, for which this command is valid
  - 2094
  groups:                           # <-- list of groups, to which this command is assigned
  - burner
  status: enabled                   # <-- status of the command
  unit: switch                      # <-- pre-defined unit for sanitization

Each command contains the following parameters:

Parameter	Type	Description
description	str	A descriptive text for what the command returns. The description can be changed to anything else.
devices	list	Each heating system control unit has its own ID in vcontrold, documented at [Github openv Wiki](https://github.com/openv/openv/wiki/Ger%C3%A4te). Not each command is available for each heating system. Which commands are available need to be defined in vcontrold itself.<br/>This parameter controls, whether the command will be automatically executed for the detected system. If your device ID is not listed, just add it to the list or replace the existing ID with your own (I assume, that everyone has only one heating system :wink:).
groups	list	Each get-command is assigned to at least one group by default, to make filtering of read commands available. The list of groups may be expanded or changed as you like.
status	str	Used to skip single commands in general. If the status of a command is disabled, it will not be executed, independently from the group or anything else.<br />Additionally, the status is used to automatically disable commands, which return unexpected outputs or not supported by the heating system. If, during read_all execution a command returns data, that doesn’t match the expecation, it will be automatically disabled in the config file.
unit	str	The unity of measurement. This is used internally to sanitize the returned values and change the format, if necessary. The valid unit types are pre-defined and may be advanced in futurer.<br />Currently available units are error - Error messages. Especially for commands getError[0-9]. hours - Cast to float, round to 2 decimal places and append _hours_. none - Unspecified. Return as is. number - Cast to float and round to 2 decimal places. percent - Cast to float, round to 2 decimal places and append _%_. power - Cast to float, round to 2 decimal places and append _W_. shift - Cast to float, round to 2 decimal places and append _shift_. slope - Cast to float, round to 2 decimal places and append _slope_. switch - Returns either _on_/_off_ (str) or _true_/_false_ (bool), based on instance propery switch_as_bool. temperature - Cast to float, round to 2 decimal places and append _°C_. text - Return as is. time - Parsed as datetime object and returned with format _%Y-%m-%d - %H:%M:%S_. timer - Parsed the timetable, returnfed from vcontrold to a list of dict, where each time entry attribute is returned as _index_, _time_on_ and _time_off_ The parsing process may not be optimally implemented by now, because I didn’t have enough data for different systems. Changes may be necessary in future version, to reflect differences from the different heating control system models.

Other options

Currently there are no other configuration options available. Probably some of the class properties may be available in the future.