Stats manager’s goal is to store in database interesting data he can read on xPL network. To know which data should be stored, some XML files are used.
In order Stats Manager to know which data from xPL network to store in database and how to store it, XML files are used. These files are read by statmgr and define which xPL messages to listen and which data in these messages have to be store
Here is the structure choosen to store xml files : <xml folder for statmgr>/<Technology>/<xplSchema>.xml
Example:
x10/x10.basic.xml
computer/sensor.basic.xml
Xml files are provided by plugins. A plugin has to provide a file for each xpl message type. ^ So, several plugins can provide the same xml files. This problem is solved at plugin installation :
plugin installation lists plugin’s xml files provided
plugin installation lists statmgr’s xml files already installed
if there is a conflict (xml files already exists) :
- tell user that there is a conflict
- display a diff of the 2 (or more) conflicted files
- ask user to choose one file (default : the file already installed)
plugin installation installs xml files and continue his installation
A xml file for statmgr defines :
<?xml version="1.0" encoding="UTF-8"?>
<!-- All xml definition files must be in <domogik.cfg_path>/xml directory,
one mapping definintion per file.
-->
<!-- statistic : root element
attribute technology is mandatory
It specifies the technology for which this mapping is used.
-->
<statistic technology="plcbus">
<schema name="control.basic">
<xpltype type="xpl-trig">
<listener>
<filter>
<!-- list of 'key' nodes.
each node must have 2 parameters :
- name : the "key" of the pair
- command : the "value" of the pair
A message will be loggued only if schema and xpltype are corrects,
and only if for all "key" nodes specified, there is a name=value pair in the message.
-->
<key name="type" value="plcbus" />
<key name="command" value="on" />
</filter>
</listener>
<mapping> <!-- define the mapping between message keys and the database -->
<device field="device"/>
<!-- define the field containing device name/address
If there is no field containing device addres, you can use 'static_name' attribute to define a name. Use with caution and only when there is no other choice :
<device static_name="foo"/>
If it is a notification message, use this :
<device type="notification"/>
-->
<!-- The "value" node can have 2 attributes :
- field : mandatory ! define the key of the pair key=value to get in the Xpl message
- new_name: optionnal, if it's define, the 'name' of this value entry will be the value defined,
else it will be the filed name.
- filter_key : define one key to read for adding a filter on renaming name in new_name
- filter_value : the value for the filter
- history_size : optionnal, indicate number of values to keep in database for a device key
-->
<value field="command"/>
<value field="command" history_size="5"/>
<value field="command" new_name="bar" />
<value field="command" new_name="foo" filter_key="type" filter_value="plcbus" />
</mapping>
</xpltype>
<xpltype type="xpl-stat">
<listener>
<filter>
<key name="type" value="plcbus" />
<key name="command" value="off" />
</filter>
</listener>
<mapping> <!-- define the mapping between message keys and the database -->
<device field="device"/> <!-- define the device name -->
<value field="command"/>
<value field="command" name="bar" />
</mapping>
</xpltype>
</schema>
</statistic>
Note
If xpl-trig and xpl-stat parts are identical, you can use type=”*”
Example for x10/x10.basic:
<?xml version="1.0" encoding="UTF-8"?>
<statistic technology="x10">
<schema name="x10.basic">
<xpltype type="xpl-trig">
<listener>
<filter/>
</listener>
<mapping>
<device field="device"/>
<value field="command"/>
<value field="level" />
</mapping>
</xpltype>
</schema>
</statistic>
To see flow about statistics and events, see events page.
Stats manager read all xml files. for each files, it create listeners. Each listener will call a callback function that put data in database with good format.