Recent changes to Configuration

Configuration modified by Damago

Damago — Fri, 20 Jun 2014 06:26:43 -0000

--- v8
+++ v9
@@ -73,6 +73,8 @@

 ## Objects definition section

+This is the main part of the linknx configuration. All KNX objects that linknx interacts with (in the rules) and which can be accessed by the web visualisation [KnxWeb] are defined here. 
+
 Here is an example of objects definition section: 

     <objects>
@@ -92,11 +94,16 @@

 ## Rules section

-A rule is composed of: 
+Rules section is a place where building automatisation is created. You can define what happens when state of some KNX objects has changed, define actions to be performed during specific time periods etc. It consists of a rules each defining some specific condition and action to be performed when the condition had been met. 
+
+A simplest 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 
+  * an action list to be executed when the condition is evaluated as true 
+
+however more complicated scenarios can be created as described in [Rules_section] 
+
+A sample rule: 

             <rule id="xxxx">
                 <condition type="....">
@@ -111,89 +118,4 @@
                 </actionlist>
             </rule>

-The following condition's types are available (see [Condition's_Syntax] section): 
-
-  * object: true if the object has the specified value (
-        
-                <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, but 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. 
-
-Last example, this time 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 (`wakeup_active on`) and if we are at home (`absence off`). 
+The detailed syntax, and a full list of condition and action types is available on the [Rules_section] page.

Configuration modified by Damago

Damago — Fri, 20 Jun 2014 06:26:43 -0000

--- v7
+++ v8
@@ -18,6 +18,8 @@
 [TOC]

 ## Services section
+
+Services section is responsible for defining the majority of linkx options (like exception days, type of persistence files, ip and port where XML interface is presented to the outside world), and for configuring all connections to external services uded by the server: like connection to backend KNX bus, i/o ports used, sms gateway etc. 

 Here is an example of services section 

@@ -54,77 +56,20 @@
             </ioports>
         </services>

-The **smsgateway** element configures sms service allowing to send text messages to mobile phones. Currently, only the [Clickatell](http://www.clickatell.com/) [HTTP API](http://www.clickatell.com/solutions/developers/api_http.php) is implemented and requires [libcurl](http://curl.haxx.se/) 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](http://www.stafford.uklinux.net/libesmtp/) to work.  
-SMTP authentication (optional) can be configured by adding login="xxxx" and pass="yyy" in config of emailserver.  
-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.  
-The **ioports** element contains a list of IO ports. See [IO_Ports] for more details.  
-The **location** element defines physical location of KNX installation (latitude and longitude in degrees, values have to be negative for south and westerh hemisphere respectively). This is needed for calculation of **sunrise**, **sunset** and **noon** time specification for conditions etc.  
-The **persistence** element defines where linknx stores it's persistent status information and/or logs. persistence type "**file**" stores values on the filesystem. The **path** attribute tells where to store persistent status and the **logpath** attribute tells where to store object's history logs. By default, **path** equals /var/lib/linknx/persist and **logpath** equals to **path**.  
-Under this directory, a file with the object id as name will be created for each persistent object (object with attribute init="persist"). This file contains the object's current value.  
-Under the logpath directory, a file with the object id as name and extension ".log" will be created for each logged object (object with attribute log="true"). This file contains the history of the object in format "yyyy-mm-dd hh:mm:ss > value".  
-
-    
-    <persistence type="file" path="/var/lib/linknx/persist/" logpath="/var/lib/linknx/logs/" />
-
-Since release 0.0.1.23, persistence type "**mysql**" is also supported (experimental).  
-Details in [Mysql_persistence] page 
+Detailed definition of the services and their syntax is explained on [Services_section] page. 

 ## Logging section

-Linknx support 2 different logging back-ends: 
+Logging section is responsible for controlling the creation and format of log files. Linknx support 2 different logging back-ends: 

   * Internal logger 
   * log4cpp external library 

-The choice between these 2 possibilities is made at compilation time. By default, the configure script will auto-detect the presence of the log4cpp library and use it if available. You can force log4cpp by passing --with-log4cpp option to configure script or disable it with option --without-log4cpp. 
-
-With Internal logger, the following parameters are available: 
-    
-    <logging format="simple" level="WARN"/>
-
-If parameter format is omitted or its value is different from "simple", the timestamp will be added in front of each log line.  
-The parameter level determine the minimum level of logging. The valid values are "DEBUG", "INFO", "NOTICE", "WARN" and "ERROR". The default value is "INFO". The level "DEBUG" is disabled in normal builds when using the internal logger.  
-The log messages for level ERROR or WARN go to stderr, all other messages go to stdout. 
-
-With log4cpp logger, the logging configuration looks like this: 
-    
-     <logging output="/var/log/linknx.log" format="%d{%Y%m%d %H:%M:%S,%l} %5p %c %x: %m%n" level="INFO"/>
-    
-
-The allowed parameters are: 
-
-  * output: the log file to write. Default=stdout 
-  * format: the logging format value can be "simple", "basic" or a pattern like in the example above. 
-  * level: the minimum level of logging. The valid values are "DEBUG", "INFO", "NOTICE", "WARN" and "ERROR". Default=INFO 
-  * maxfilesize: maximum size of a log file (in kb). When the size is reached, the logs are rotated 
-  * maxfileindex: maximum index of log files kept. Default=10 
-
-The format pattern syntax allows the following fields: 
-
-  * **%%%%** \- a single percent sign 
-  * **%c** \- the category 
-  * **%d** \- the date > Date format: The date format character may be followed by a date format specifier enclosed between braces. For example, %d{%H:%M:%S,%l} or %d{%d %m %Y %H:%M:%S,%l}. If no date format specifier is given then the following format is used: "Wed Jan 02 02:03:55 1980". The date format specifier admits the same syntax as the ANSI C function strftime, with 1 addition. The addition is the specifier %l for milliseconds, padded with zeros to make 3 digits. 
-  * **%m** \- the message 
-  * **%n** \- the platform specific line separator 
-  * **%p** \- the priority 
-  * **%r** \- milliseconds since this layout was created. 
-  * **%R** \- seconds since Jan 1, 1970 
-  * **%u** \- clock ticks since process start 
-  * **%x** \- the [NDC](http://log4cpp.sourceforge.net/api/classlog4cpp_1_1NDC.html) || 
-
-format="simple" corresponds to "%p - %m%n" and format="basic" to "%R %p %c %x: %m%n".  
-The default value (if format is not specified or empty) is "%d [%5p] %c: %m%n"  
-More details about pattern layout can be found in [log4j documentation](http://logging.apache.org/log4j/1.2/apidocs/org/apache/log4j/PatternLayout.html) but some of them are not supported by log4cpp 
-
-If parameter "config" is used, the value of that parameter is used as the name of the file containing log4cpp configuration. All other parameters are ignored. A sample configuration file that logs all warning and errors to a file and everything to the console can be found in linknx/conf/logging.conf (See [log4cpp configuration](http://logging.apache.org/log4j/1.2/apidocs/org/apache/log4j/PropertyConfigurator.html#doConfigure%28java.lang.String,%20org.apache.log4j.spi.LoggerRepository) for more details): 
+Example logging section is here: 

     <logging config="/var/lib/linknx/logging.conf"/>

-  
-
+Detailed syntax is explained in [Logging_section] page. 

 ## Objects definition section

Configuration modified by jef2000

jef2000 — Fri, 20 Jun 2014 06:26:43 -0000

--- v6
+++ v7
@@ -67,7 +67,7 @@
 Under the logpath directory, a file with the object id as name and extension ".log" will be created for each logged object (object with attribute log="true"). This file contains the history of the object in format "yyyy-mm-dd hh:mm:ss > value".

-    <persistence type="file" path="/var/lib/linknx/persist/" path="/var/lib/linknx/logs/" />
+    <persistence type="file" path="/var/lib/linknx/persist/" logpath="/var/lib/linknx/logs/" />

 Since release 0.0.1.23, persistence type "**mysql**" is also supported (experimental).  
 Details in [Mysql_persistence] page

Configuration modified by jef2000

jef2000 — Fri, 20 Jun 2014 06:26:43 -0000

--- v5
+++ v6
@@ -66,6 +66,8 @@
 Under this directory, a file with the object id as name will be created for each persistent object (object with attribute init="persist"). This file contains the object's current value.  
 Under the logpath directory, a file with the object id as name and extension ".log" will be created for each logged object (object with attribute log="true"). This file contains the history of the object in format "yyyy-mm-dd hh:mm:ss > value".

+    
+    <persistence type="file" path="/var/lib/linknx/persist/" path="/var/lib/linknx/logs/" />

 Since release 0.0.1.23, persistence type "**mysql**" is also supported (experimental).  
 Details in [Mysql_persistence] page

Configuration modified by jef2000

jef2000 — Fri, 20 Jun 2014 06:26:42 -0000

--- v4
+++ v5
@@ -61,9 +61,11 @@
 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.  
 The **ioports** element contains a list of IO ports. See [IO_Ports] for more details.  
-The **location** element defines physical location of KNX installation (latitude and longitude in degrees, values have to be negative for south and westerh hemisphere respectively). This is needed for calculation of **sunrise**, **sunset** and **noon** time specification for conditions etc. The **persistence** element defines where linknx stores it's persistent status information and/or logs. persistence type "**file**" stores values on the filesystem. The **path** attribute tells where to store persistent status and the **logpath** attribute tells where to store object's history logs. By default, **path** equals /var/lib/linknx/persist and **logpath** equals to **path**.  
+The **location** element defines physical location of KNX installation (latitude and longitude in degrees, values have to be negative for south and westerh hemisphere respectively). This is needed for calculation of **sunrise**, **sunset** and **noon** time specification for conditions etc.  
+The **persistence** element defines where linknx stores it's persistent status information and/or logs. persistence type "**file**" stores values on the filesystem. The **path** attribute tells where to store persistent status and the **logpath** attribute tells where to store object's history logs. By default, **path** equals /var/lib/linknx/persist and **logpath** equals to **path**.  
 Under this directory, a file with the object id as name will be created for each persistent object (object with attribute init="persist"). This file contains the object's current value.  
-Under the logpath directory, a file with the object id as name and extension ".log" will be created for each logged object (object with attribute log="true"). This file contains the history of the object in format "yyyy-mm-dd hh:mm:ss > value". 
+Under the logpath directory, a file with the object id as name and extension ".log" will be created for each logged object (object with attribute log="true"). This file contains the history of the object in format "yyyy-mm-dd hh:mm:ss > value".  
+

 Since release 0.0.1.23, persistence type "**mysql**" is also supported (experimental).  
 Details in [Mysql_persistence] page

Configuration modified by jef2000

jef2000 — Fri, 20 Jun 2014 06:26:42 -0000

--- v3
+++ v4
@@ -13,7 +13,7 @@
         <logging .... />
     </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. 
+The four 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. 

 [TOC]

@@ -164,38 +164,21 @@

 The following condition's types are available (see [Condition's_Syntax] section): 

-  * 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 
-  * ioport-rx: true if the expected message is received on the io-port. (See [IO_Ports]) 
-  * script: true if the return value of script is true. (See [Lua_Scripting]) 
-
-The rule will be evaluated only when one of its "trigger" conditions changes value. 
-
-The following action types are available (see [Action's_syntax] section): 
-
-  * set-value : Set an object to the specified value 
-  * cycle-on-off : Switch an object ON and OFF a specified number of times (delays on and off are also specified). The object is left in the off state after execution of this action. 
-  * send-sms : Send an SMS with specified text to the specified mobile phone number 
-  * send-email : Send an email with specified content to a specified receiver 
-  * dim-up : Send increasing or decreasing values to a scaling object during a predefined time period 
-  * shell-cmd : Execute the specified shell command 
-  * ioport-tx : Send the given message to an io-port. (See [IO_Ports]) 
-  * script : Execute the LUA script. (See [Lua_Scripting]) 
-
-First sample rule: 
-    
-            <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>
+  * object: true if the object has the specified value (
+        
+                <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.

Configuration modified by Damago

Damago — Fri, 20 Jun 2014 06:26:42 -0000

--- v2
+++ v3
@@ -17,7 +17,9 @@

 [TOC]

-### Let's first have a look at **services**:
+## Services section
+
+Here is an example of services section 

         <services>
             <smsgateway type="clickatell" user="xyz" pass="xxx" api_id="123456" />
@@ -46,6 +48,7 @@
                 <date day="13" month="5" year="2010" />
                 <date day="24" month="5" year="2010" />
             </exceptiondays>
+            <location lon="21.01" lat="52.15"/>
             <ioports>
                 <ioport host="192.168.0.18" port="21000" rxport="21001" id="irtrans"/>
             </ioports>
@@ -57,16 +60,15 @@
 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.  
-The **ioports** element contains a list of IO ports. See [IO_Ports] for more details. 
-
-The **persistence** element defines where linknx stores it's persistent status information and/or logs. persistence type "**file**" stores values on the filesystem. The **path** attribute tells where to store persistent status and the **logpath** attribute tells where to store object's history logs. By default, **path** equals /var/lib/linknx/persist and **logpath** equals to **path**.  
+The **ioports** element contains a list of IO ports. See [IO_Ports] for more details.  
+The **location** element defines physical location of KNX installation (latitude and longitude in degrees, values have to be negative for south and westerh hemisphere respectively). This is needed for calculation of **sunrise**, **sunset** and **noon** time specification for conditions etc. The **persistence** element defines where linknx stores it's persistent status information and/or logs. persistence type "**file**" stores values on the filesystem. The **path** attribute tells where to store persistent status and the **logpath** attribute tells where to store object's history logs. By default, **path** equals /var/lib/linknx/persist and **logpath** equals to **path**.  
 Under this directory, a file with the object id as name will be created for each persistent object (object with attribute init="persist"). This file contains the object's current value.  
 Under the logpath directory, a file with the object id as name and extension ".log" will be created for each logged object (object with attribute log="true"). This file contains the history of the object in format "yyyy-mm-dd hh:mm:ss > value". 

 Since release 0.0.1.23, persistence type "**mysql**" is also supported (experimental).  
 Details in [Mysql_persistence] page 

-### The logging configuration is described here:
+## Logging section

 Linknx support 2 different logging back-ends: 

@@ -120,20 +122,26 @@

-  
-
-
-  
-
-
-### Now have a look at the **object** controller configuration:
+## Objects definition section
+
+Here is an example of objects definition section: 
+    
+    <objects>
+          <object type="16.000" id="text_salon" gad="9/1/153" flags="cwtu">Text on LCD in salon</object>
+          </object>
+          <object id="hall_lamps_central" gad="3/2/1" init="request">Hall central lamp</object>
+          <object id="hall_lamps_LED" gad="3/2/2" init="request">Hall LED floor lights</object>
+          <object id="gate_open" gad="0/1/0" init="request"><listener gad="4/1/0"/>gate open close</object>
+          <object id="gate_status" gad="4/1/0" init="request">gate state status</object>
+          <object id="salon_scene1" gad="3/2/2" init="persist">Salon teleconference start scene</object>
+    </objects>

 Since version 0.0.1.25, the object definition uses Datapoint Types defined in KNX standard instead of EIS datatypes.  
 The current syntax is described in [Object_Definition_Syntax] section.  
 The deprecated syntax (before 0.0.1.25) is still supported but will be converted to the new one when loaded by the application.  
 The old syntax is described in [Object_Definition_Syntax_before_0.0.1.25] section. 

-### Now we enter the 3rd section dedicated to **rules**:
+## Rules section

 A rule is composed of:

Configuration modified by Damago

Damago — Fri, 20 Jun 2014 06:26:42 -0000

--- v1
+++ v2
@@ -85,7 +85,8 @@

 With log4cpp logger, the logging configuration looks like this: 

-    <logging output="/tmp/linknx.log" format="%d %5p > %c %x - %m%n" level="DEBUG"/>
+     <logging output="/var/log/linknx.log" format="%d{%Y%m%d %H:%M:%S,%l} %5p %c %x: %m%n" level="INFO"/>
+    

 The allowed parameters are: 

@@ -153,7 +154,7 @@
                 </actionlist>
             </rule>

-The following [condition types](Condition's_Syntax) are available: 
+The following condition's types are available (see [Condition's_Syntax] section): 

   * object: true if the object has the specified value 
   * timer: true if the timer occured 
@@ -165,10 +166,10 @@

 The rule will be evaluated only when one of its "trigger" conditions changes value. 

-The following [action types](Action's_syntax) are available: 
+The following action types are available (see [Action's_syntax] section): 

   * set-value : Set an object to the specified value 
-  * cycle-on-off : Switch an object ON and OFF a specified number of times (delays on and off are also specified) 
+  * cycle-on-off : Switch an object ON and OFF a specified number of times (delays on and off are also specified). The object is left in the off state after execution of this action. 
   * send-sms : Send an SMS with specified text to the specified mobile phone number 
   * send-email : Send an email with specified content to a specified receiver 
   * dim-up : Send increasing or decreasing values to a scaling object during a predefined time period

Configuration modified by jef2000

jef2000 — Fri, 20 Jun 2014 06:26:41 -0000

Looking at the XML configuration file (example here), we can see 4 main sections: services, logging, objects and rules. Services contains all the system wide parameters like ip-address/port of EIBD, sms or email server parameters. Logging contains the logging configuration. 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.

&lt;config&gt;
    &lt;objects&gt;
        ....
    &lt;/objects&gt;
    &lt;rules&gt;
        ....
    &lt;/rules&gt;
    &lt;services&gt;
        ....
    &lt;/services&gt;
    &lt;logging .... /&gt;
&lt;/config&gt;

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:
The logging configuration is described here:
Now have a look at the object controller configuration:
Now we enter the 3rd section dedicated to rules:

Let's first have a look at services:

    &lt;services&gt;
        &lt;smsgateway type="clickatell" user="xyz" pass="xxx" api_id="123456" /&gt;
        &lt;emailserver type="smtp" host="smtp.myprovider.com:25" from="linknx@mydomain.com" /&gt;
        &lt;xmlserver type="inet" port="1028" /&gt;
        &lt;knxconnection url="ip:192.168.0.10" /&gt;
        &lt;persistence type="file" path="/var/lib/linknx/persist"/&gt;
        &lt;exceptiondays&gt;
            &lt;date day="1" month="1" /&gt;
            &lt;date day="1" month="5" /&gt;
            &lt;date day="21" month="7" /&gt;
            &lt;date day="15" month="8" /&gt;
            &lt;date day="1" month="11" /&gt;
            &lt;date day="11" month="11" /&gt;
            &lt;date day="25" month="12" /&gt;
            &lt;date day="9" month="4" year="2007" /&gt;
            &lt;date day="17" month="5" year="2007" /&gt;
            &lt;date day="28" month="5" year="2007" /&gt;
            &lt;date day="24" month="3" year="2008" /&gt;
            &lt;date day="1" month="5" year="2008" /&gt;
            &lt;date day="12" month="5" year="2008" /&gt;
            &lt;date day="13" month="4" year="2009" /&gt;
            &lt;date day="21" month="5" year="2009" /&gt;
            &lt;date day="1" month="6" year="2009" /&gt;
            &lt;date day="5" month="4" year="2010" /&gt;
            &lt;date day="13" month="5" year="2010" /&gt;
            &lt;date day="24" month="5" year="2010" /&gt;
        &lt;/exceptiondays&gt;
        &lt;ioports&gt;
            &lt;ioport host="192.168.0.18" port="21000" rxport="21001" id="irtrans"/&gt;
        &lt;/ioports&gt;
    &lt;/services&gt;

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.
SMTP authentication (optional) can be configured by adding login="xxxx" and pass="yyy" in config of emailserver.
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.
The ioports element contains a list of IO ports. See [IO_Ports] for more details.

The persistence element defines where linknx stores it's persistent status information and/or logs. persistence type "file" stores values on the filesystem. The path attribute tells where to store persistent status and the logpath attribute tells where to store object's history logs. By default, path equals /var/lib/linknx/persist and logpath equals to path.
Under this directory, a file with the object id as name will be created for each persistent object (object with attribute init="persist"). This file contains the object's current value.
Under the logpath directory, a file with the object id as name and extension ".log" will be created for each logged object (object with attribute log="true"). This file contains the history of the object in format "yyyy-mm-dd hh:mm:ss > value".

Since release 0.0.1.23, persistence type "mysql" is also supported (experimental).
Details in [Mysql_persistence] page

The logging configuration is described here:

Linknx support 2 different logging back-ends:

Internal logger
log4cpp external library

The choice between these 2 possibilities is made at compilation time. By default, the configure script will auto-detect the presence of the log4cpp library and use it if available. You can force log4cpp by passing --with-log4cpp option to configure script or disable it with option --without-log4cpp.

With Internal logger, the following parameters are available:

&lt;logging format="simple" level="WARN"/&gt;

If parameter format is omitted or its value is different from "simple", the timestamp will be added in front of each log line.
The parameter level determine the minimum level of logging. The valid values are "DEBUG", "INFO", "NOTICE", "WARN" and "ERROR". The default value is "INFO". The level "DEBUG" is disabled in normal builds when using the internal logger.
The log messages for level ERROR or WARN go to stderr, all other messages go to stdout.

With log4cpp logger, the logging configuration looks like this:

&lt;logging output="/tmp/linknx.log" format="%d %5p &gt; %c %x - %m%n" level="DEBUG"/&gt;

The allowed parameters are:

output: the log file to write. Default=stdout
format: the logging format value can be "simple", "basic" or a pattern like in the example above.
level: the minimum level of logging. The valid values are "DEBUG", "INFO", "NOTICE", "WARN" and "ERROR". Default=INFO
maxfilesize: maximum size of a log file (in kb). When the size is reached, the logs are rotated
maxfileindex: maximum index of log files kept. Default=10

The format pattern syntax allows the following fields:

%%%% - a single percent sign
%c - the category
%d - the date > Date format: The date format character may be followed by a date format specifier enclosed between braces. For example, %d{%H:%M:%S,%l} or %d{%d %m %Y %H:%M:%S,%l}. If no date format specifier is given then the following format is used: "Wed Jan 02 02:03:55 1980". The date format specifier admits the same syntax as the ANSI C function strftime, with 1 addition. The addition is the specifier %l for milliseconds, padded with zeros to make 3 digits.
%m - the message
%n - the platform specific line separator
%p - the priority
%r - milliseconds since this layout was created.
%R - seconds since Jan 1, 1970
%u - clock ticks since process start
%x - the NDC ||

format="simple" corresponds to "%p - %m%n" and format="basic" to "%R %p %c %x: %m%n".
The default value (if format is not specified or empty) is "%d [%5p] %c: %m%n"
More details about pattern layout can be found in log4j documentation but some of them are not supported by log4cpp

If parameter "config" is used, the value of that parameter is used as the name of the file containing log4cpp configuration. All other parameters are ignored. A sample configuration file that logs all warning and errors to a file and everything to the console can be found in linknx/conf/logging.conf (See log4cpp configuration for more details):

&lt;logging config="/var/lib/linknx/logging.conf"/&gt;

Now have a look at the object controller configuration:

Since version 0.0.1.25, the object definition uses Datapoint Types defined in KNX standard instead of EIS datatypes.
The current syntax is described in [Object_Definition_Syntax] section.
The deprecated syntax (before 0.0.1.25) is still supported but will be converted to the new one when loaded by the application.
The old syntax is described in [Object_Definition_Syntax_before_0.0.1.25] section.

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

    &lt;rule id="xxxx"&gt;
        &lt;condition type="...."&gt;
            .....
        &lt;/condition&gt;
        &lt;actionlist&gt;
            &lt;action ..... /&gt;
            .....
        &lt;/actionlist&gt;
        &lt;actionlist type="on-false"&gt;
            &lt;action ..... /&gt;
        &lt;/actionlist&gt;
    &lt;/rule&gt;

The following condition types are available:

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
ioport-rx: true if the expected message is received on the io-port. (See [IO_Ports])
script: true if the return value of script is true. (See [Lua_Scripting])

The rule will be evaluated only when one of its "trigger" conditions changes value.

The following action types are available:

set-value : Set an object to the specified value
cycle-on-off : Switch an object ON and OFF a specified number of times (delays on and off are also specified)
send-sms : Send an SMS with specified text to the specified mobile phone number
send-email : Send an email with specified content to a specified receiver
dim-up : Send increasing or decreasing values to a scaling object during a predefined time period
shell-cmd : Execute the specified shell command
ioport-tx : Send the given message to an io-port. (See [IO_Ports])
script : Execute the LUA script. (See [Lua_Scripting])

First sample rule:

        &lt;rule id="cur_time_date"&gt;
            &lt;condition type="timer" trigger="true"&gt;
                &lt;every&gt;3600&lt;/every&gt;
            &lt;/condition&gt;
            &lt;actionlist&gt;
                &lt;action type="set-value" id="cur_time" value="now" /&gt;
                &lt;action type="set-value" id="cur_date" value="now" /&gt;
            &lt;/actionlist&gt;
        &lt;/rule&gt;

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:

        &lt;rule id="heating_morning"&gt;
            &lt;condition type="and"&gt;
                &lt;condition type="object" id="heating_auto" value="on" /&gt;
                &lt;condition type="or"&gt;
                    &lt;condition type="timer" trigger="true"&gt;
                        &lt;at hour="6" min="30" exception="no" wdays="12345" /&gt;
                        &lt;until hour="8" min="0" /&gt;
                    &lt;/condition&gt;
                    &lt;condition type="timer" trigger="true"&gt;
                        &lt;at hour="8" min="0" wdays="67" /&gt;
                        &lt;until hour="12" min="0" /&gt;
                    &lt;/condition&gt;
                    &lt;condition type="timer" trigger="true"&gt;
                        &lt;at hour="8" min="0" exception="yes" /&gt;
                        &lt;until hour="12" min="0" /&gt;
                    &lt;/condition&gt;
                &lt;/condition&gt;
            &lt;/condition&gt;
            &lt;actionlist&gt;
                &lt;action type="set-value" id="heating_kitchen" value="comfort" /&gt;
                &lt;action type="set-value" id="heating_living" value="standby" /&gt;
                &lt;action type="set-value" id="heating_bathroom" value="on" /&gt;
                &lt;action type="set-value" id="heating_bedroom1" value="comfort" /&gt;
                &lt;action type="set-value" id="heating_bedroom2" value="comfort" /&gt;
            &lt;/actionlist&gt;
            &lt;actionlist type="on-false"&gt;
                &lt;action type="set-value" id="heating_kitchen" value="frost" /&gt;
                &lt;action type="set-value" id="heating_living" value="frost" /&gt;
                &lt;action type="set-value" id="heating_bathroom" value="off" /&gt;
                &lt;action type="set-value" id="heating_bedroom1" value="frost" /&gt;
                &lt;action type="set-value" id="heating_bedroom2" value="frost" /&gt;
            &lt;/actionlist&gt;
        &lt;/rule&gt;

This rule will only execute its action lists at specific times, but 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.

Last example, this time with a "dim-up" action:

        &lt;rule id="wakeup_alarm"&gt;
            &lt;condition type="and"&gt;
                &lt;condition type="object" id="absence" value="off" /&gt;
                &lt;condition type="object" id="wakeup_active" value="on" /&gt;
                &lt;condition type="timer" trigger="true"&gt;
                    &lt;at hour="6" min="30" exception="no" wdays="12345" /&gt;
                &lt;/condition&gt;
            &lt;/condition&gt;
            &lt;actionlist&gt;
                &lt;action type="dim-up" id="dim_value_bedroom2"
                    start="0" stop="240" duration="1800" /&gt;
            &lt;/actionlist&gt;
        &lt;/rule&gt;

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 (wakeup_active on) and if we are at home (absence off).