info.json for plugins - xpl_stats section

Purpose

The xpl_stats section will describe all xPL messages that may be received by some sensors. No difference is made between xpl-stat and xpl-trig messages : as some xpl client implement these messages not as required in the xPL specification, we process them in the same (this is not an issue as basically xpl-trig and xpl-stat contains the same data : xpl-trig is just used for events and data changes and xpl-stat for all other usages).

Example 1

This example is the diskfree plugin. See the device types documentation for more informations.

"xpl_stats": {
   "get_percent_used": {
        "name": "Percent used",
        "schema": "sensor.basic",
        "parameters": {
                "static": [
                    {
                            "key": "type",
                            "value": "percent_used"
                    }
                ],
                "device": [],
                "dynamic": [
                    {
                         "key": "current",
                         "ignore_values": "",
                         "sensor": "get_percent_used"
                    }
                ]
        }
   },
   "get_used_space": {
           ...
   },
   "get_total_space": {
           ...
   },
   "get_free_space": {
           ...
   }
},

Description

Here there is 4 sorts of xpl messages that may be received. Each one has its proper subsection here:

  • “get_percent_used”: {…}
  • “get_used_space”: {…}
  • “get_total_space”: {…}
  • “get_free_space”: {…}

The key used is free and you can put anything you want. In this plugin, each sensor has its own xpl message, so we choose to use for this key the name of the related sensor. This key will be inserted in database only for reference (it is not used, it is just in the database to help for debugging to find the related data in the json file).

For each message you need to set:

  • name: it will be displayed in the user interface when you will configure a widget.
  • schema: the xPL schema used by the plugin.
  • parameters: all the parameters of the xPL message.
    • static: all the static keys of the xPL message. Static keys will always be the same, whatever the device is. They will never be displayed in the user interface.
      • key: The xpl key
      • value: The value the xpl key must have
    • device : the static parameters. Their value is defined on a per device basis (input is requested) in the user interface. The values can be different for the xpl_commands and xpl_stats* parts (if both exists).
      • description : short description of this field
      • type : the value type for this field. The available values are the same as the ones used in the configuration part of the json
      • key : The Xpl key
      • default : Optionally a default value for this parameter, will be pre filled in in the admin interface during device creation
      • multiple : Optional parameter, if this parameter is set to a one char string, then we can set multiple values for the parameter separated by the char. Example input: <value1><separator><value2><separator><value3>
    • dynamic : all the dynamic parts of the xPL message. It is all the keys which are not related to the device address : values for the sensors. They are stored in the sensor history table.
      • key : The Xpl key
      • ignore_values : What values to ignore, see below for more info
      • sensor : The sensor to store this value in

ignore_values

This parameter for a dynamic xpl_stat parameter is used to ignore certain values. If the received value (in the xpl_stat message) is found in this list then the value will not be stored in the sensor_history table, if we don’t find it in the list or if the list is empty the value will be stored in the sensorHistory table.