Looking at the XML configuration file (example
here), we can see 3 main sections: services, objects and rules. Services contains all the system wide parameters like ip-address/port of EIBD, sms or email server parameters. Objects contains the description of all group objects. Rules contains a list of rules with a condition and list of actions that are executed based on this condition.
<?xml version="1.0" ?>
<config>
<objects>
....
</objects>
<rules>
....
</rules>
<services>
....
</services>
</config>
The three sections can be in any order, some of them can be missing, but if a section appears more than once, only the first occurence of that section will be processed.
Let's first have a look at services:
<services>
<smsgateway type="clickatell" user="xyz" pass="xxx" api_id="123456" />
<emailserver type="smtp" host="smtp.myprovider.com:25" from="linknx@mydomain.com" />
<xmlserver type="inet" port="1028" />
<knxconnection url="ip:192.168.0.10" />
<persistence type="file" path="/var/lib/linknx/persist"/>
<exceptiondays>
<date day="1" month="1" />
<date day="1" month="5" />
<date day="21" month="7" />
<date day="15" month="8" />
<date day="1" month="11" />
<date day="11" month="11" />
<date day="25" month="12" />
<date day="9" month="4" year="2007" />
<date day="17" month="5" year="2007" />
<date day="28" month="5" year="2007" />
<date day="24" month="3" year="2008" />
<date day="1" month="5" year="2008" />
<date day="12" month="5" year="2008" />
<date day="13" month="4" year="2009" />
<date day="21" month="5" year="2009" />
<date day="1" month="6" year="2009" />
<date day="5" month="4" year="2010" />
<date day="13" month="5" year="2010" />
<date day="24" month="5" year="2010" />
</exceptiondays>
</services>
The smsgateway element configures sms service allowing to send text messages to mobile phones. Currently, only the
Clickatell HTTP API is implemented and requires
libcurl to work.
The emailserver element configures email service via an external SMTP server. The "host" parameter must contain server name AND port number. This feature requires
libesmtp to work.
The xmlserver element configures the interface to access linknx using the XML based protocol. Type can be "inet" or "unix". For "inet", the port parameter is the TCP port the server will listen on (default = 1028). For "unix", the port parameter must contain the unix socket path (default /tmp/xmlserver.sock)
The knxconnection element configures the connection to EIBD. The url parameter can be "local:/path/to/unix/socket" if EIBD uses unix sockets or "ip:ip-address:port" if EIBD uses internet sockets (port is optional; default = 6720)
The exceptiondays element contains a list of days requiring special behavior. The timer conditions in the rules section can be configured to ignore exceptiondays or to evaluate as true or false in case of exceptiondays. Missing day, month or year parameter in a date element is considered as wildcard
Now have a look at the Object Controller configuration:
<objects>
<object id="alarm_active" init="persist">
Alarm activated</object>
<object id="heating_living" gad="1/1/70" type="heat-mode">
Temperature controller mode for living room</object>
<object id="cur_date" gad="1/1/151" forcewrite="true" type="EIS4">
Current Date</object>
<object id="cur_time" gad="1/1/150" type="EIS3">
Current Time</object>
<object id="dim_living" gad="1/1/41" type="EIS2">
Living room dimmer</object>
<object id="dim_value_living" gad="1/1/42" type="EIS6">
Living room dimmer value</object>
<object id="light_office" gad="1/1/7">
Office light</object>
<object id="light_room1" gad="1/1/8">
Bedroom 1 light</object>
<object id="setpoint_living" gad="1/1/71" type="EIS5">
Setpoint temperature of living room</object>
<object id="temp_living" gad="1/1/72" type="EIS5">
Actual temperature of living room</object>
</objects>
Each object element describes a communication object.
The parameter "id" is mandatory and will be used to identify the object in rules and by the XML based protocol.
Parameter "gad" is optional. If specified, the object will be linked to that group address on KNX bus. If not, the object will only be accessible in rules and in XML based protocol.
The "type" parameter can be one of
- EIS1: switching (on/off)
- EIS2: dimming (control of dimmer using up/down/stop)
- EIS3: time
- EIS4: date
- EIS5: value (floating point number)
- EIS6: scaling (integer from 0 to 255)
- heat-mode: heating mode (comfort/standby/night/frost)
- EIS15: string (max 14 ASCII char)
It's optional and the default value is EIS1.
The "flags" parameter is similar to the ETS flags. The value of each flag is represented by a letter:
c : Communication (allow the object to interact with the KNX bus)
r : Read (allow the object to answer to a read request from another participant)
w : Write (update the object's internal value with the one received in write telegram if they are different)
t : Transmit (allow the object to transmit it's value on the bus if it's modified internally by a rule or via XML protocol)
u : Update (update the object's internal value with the one received in "read response" telegram if they are different)
f : Force (force the object value to be transmitted on the bus, even if it didn't change)
i : Init (useless for the moment. Will perhaps replace the parameter init="request" in the future)
Each letter appearing inside the value of this parameter means the corresponding flag is set.
If "flags" is not specified, the default value is "cwtu" (Communication, Write, Transmit and Update)
The "init" parameter configures the initial object value at application startup. It can be any valid value for the object or one of the special keywords "request" and "persist". "Request" will perform a read operation on the KNX bus when the value is needed for the first time. "persist" will try to load a value from persistant storage (see persistence element in services section). If no "init" parameter is given, the default behavior is "request".
A last parameter "forcewrite" (deprecated since 0.0.1.20; use letter "f" in "flags" parameter instead) can be used with value "true" to force write operation on KNX bus, even if the internal state seems unchanged. It can be useful when actuators change state without giving any status feedback.
Now we enter the 3rd section dedicated to rules.
A rule is composed of one condition an optional action list to be executed when the condition is evaluated as true, and another optional action list to be executed when the condition is evaluated as false.
<rule id="xxxx">
<condition type="....">
.....
</condition>
<actionlist>
<action ..... />
.....
</actionlist>
<actionlist type="on-false">
<action ..... />
</actionlist>
</rule>
The available condition types are:
- object: true if the object has the specified value
- timer: true if the timer occured
- and: true if all sub-conditions are true
- or: true if one of the sub-conditions is true
- not: true if the sub-condition is false
The rule will be evaluated only if one of its sub-conditions with parameter "trigger" set to "true" changes its value.
Let's see the available actions:
- SetValueAction : Set an object to the specified value
- SendEmailAction : Send an email with specified content to a specified receiver
- SendSMSAction : Send an SMS with specified text to the specified mobile phone number
- CycleOnOffAction : Switch an object ON and OFF a specified number of times (delays on and off are also specified)
- DimUpAction : Send increasing or decreasing values to a scaling object during a predefined time period
- ShellCommandAction : Execute the specified shell command
Now a couple of examples with rules:
First start with a simple one:
<rule id="cur_time_date">
<condition type="timer" trigger="true">
<every>3600</every>
</condition>
<actionlist>
<action type="set-value" id="cur_time" value="now" />
<action type="set-value" id="cur_date" value="now" />
</actionlist>
</rule>
This rule will trigger and evaluate to true every 3600 seconds. The configured actions will then send current time/date on the KNX bus. Now we can have a look at a more complex timer condition:
<rule id="heating_morning">
<condition type="and">
<condition type="object" id="heating_auto" value="on" />
<condition type="or">
<condition type="timer" trigger="true">
<at hour="6" min="30" exception="no" wdays="12345" />
<until hour="8" min="0" />
</condition>
<condition type="timer" trigger="true">
<at hour="8" min="0" wdays="67" />
<until hour="12" min="0" />
</condition>
<condition type="timer" trigger="true">
<at hour="8" min="0" exception="yes" />
<until hour="12" min="0" />
</condition>
</condition>
</condition>
<actionlist>
<action type="set-value" id="heating_kitchen" value="comfort" />
<action type="set-value" id="heating_living" value="standby" />
<action type="set-value" id="heating_bathroom" value="on" />
<action type="set-value" id="heating_bedroom1" value="comfort" />
<action type="set-value" id="heating_bedroom2" value="comfort" />
</actionlist>
<actionlist type="on-false">
<action type="set-value" id="heating_kitchen" value="frost" />
<action type="set-value" id="heating_living" value="frost" />
<action type="set-value" id="heating_bathroom" value="off" />
<action type="set-value" id="heating_bedroom1" value="frost" />
<action type="set-value" id="heating_bedroom2" value="frost" />
</actionlist>
</rule>
This rule will only execute its action lists at specific times, if heating_auto object is "on".
First action list will be executed:
- At 6:30 am every week day that is not flagged as an exception day in "services" section
- At 8:00 am every weekend day or day flagged as an exception day
Second action list will be executed:
- At 8:00 am every week day that is not flagged as an exception day in "services" section
- At 12:00 am every weekend day or day flagged as an exception day
Note that the object condition on "heating_auto" has no trigger flag. This means that if "heating_auto" is turned on at 7:00 am a week day, the action list will not be executed at that time because the rule is not evaluated on change of "heating_auto"'s value. And a last one with a "dim-up" action:
<rule id="wakeup_alarm">
<condition type="and">
<condition type="object" id="absence" value="off" />
<condition type="object" id="wakeup_active" value="on" />
<condition type="timer" trigger="true">
<at hour="6" min="30" exception="no" wdays="12345" />
</condition>
</condition>
<actionlist>
<action type="dim-up" id="dim_value_bedroom2"
start="0" stop="240" duration="1800" />
</actionlist>
</rule>
This rule will start dimming the bedroom light progressively from 0 to 94% (=240/255) during half an hour (=1800 sec). It will only execute at 6:30 am every week day that is not flagged as an exception day, if it is activated and if we are at home.