Conversion functions

Domogik is using a fixed data format (Data types <data_types/index>) to store sensor data in the database and to generate the xpl commands. Some hardware can not work directly with this data format and need some sort of conversions. For the above purpose Domogik introduced Conversion functions, these are very simple python functions that input a value and need to return a single value. These python functions are called in 2 places inside Domogik. 1- During xpl command generation: The input value is coming from REST or MQ and is then placed inside the transmitted XPL message. 2- During stat receival: The incoming xpl value is used as the parameter of the conversion function and the return value is stored in the database.

Limitations

Because the conversion code is using eval() the conversion code in the file should be very simple. There should be no comments in the file and there should only be one function per conversion file. See the example below.

Example

Some conversion may be needed for some features of a plugin. For example, the velbus plugin has some level features. Velbus hardware handle these levels with values from 0 to 255. For such features, Domogik has a datatype named DT_Scaling which allows a range from 0 to 100. So when data is sent from the velbus plugin over xPL, the data is in the range [0, 255]. When the xplgw component received it, before storing it in database, it will convert the value for the needed Domogik datatype : from [0-255] to [0-100]. To allow this, the plugin is delivered with a file from_level_to_DT_Scaling.py which contains:

def from_level_to_DT_Scaling(x):
    # 0 - 255 translated to 0 - 100
    return round(int(x) / 255 * 100)

This conversion function is used by a sensor, defined in the info.json file:

"sensors": {
    ...
    "level_range": {
            "name": "level sensor",
            "data_type": "DT_Scaling",
            "conversion": "from_level_to_DT_Scaling",
            "incremental": false,
            "history": {
                "store": true,
                "duplicate": false,
                "max": 0,
                "expire": 0,
                "round_value": 0
            }
    },
    ...

So, each time a value is caught by xplgw for such a sensor, it will be translated thanks to the conversion function to the appropriate value.