KNX Gateway

KNX Gateway

Configuration

We here outline the different steps necessary before the KNX gateway can be used.

Application configuration file

Before compiling and deploying the application, several properties can be configured in the /src/main/resources/knx.properties file of the ga-web project. First, we suggest to replace the default password. Then, if storage is active, you will need to set up a database instance where the historical data will be stored (SQL is furnished in the externalResources directory). The (Web GUI) parameters can for their part be configured through the gateway's Web GUI. Finally, the datapointFilePath property points to a folder where the (generated or loaded) XML datapoint file will be placed.

password=knxwot

# Database parameters
db.url=jdbc:mysql://localhost/KNXGateway
db.user=root
db.password=greenpc

#DNS Parameters (Web GUI)
dns.ip=192.168.1.31
dns.zone=epfl.ch

#KNX Parameters (Web GUI)
knx.ip=192.168.1.33
knx.addr=0.0.0

#Enable local historical storage (Web GUI)
storage=true

datapointFilePath=/home
maxCharsLogRead=5000

Generating the datapoint file

The first step is to generate the XML file containing all the datapoints descriptions of the KNX network. We assume that you are in possession of the knxproj export archive of the ETS 4 software.

Launch the DatapointGenerator.jar Java executable (provided in the externalResources directory) on your local machine. Then select the knxproj archive on your computer and also the output folder where the datapoints.xml file will be written, as visible in the figure below. When this is done, press the Generate button.

Configure the gateway

Once the XML file generated, you can upload it on the gateway. This is done by accessing the Web interface located on the gateway with following URL: http://:8080/knx/index.html where represents the IP your gateway device (figure below). Log into the application with the password defined in the knx.properties file (default knxwot).

You then have to put some information necessary for proper working of the gateway as shown in the figure below:

• The first one is to indicate the IP of the KNX IP Gateway. You can either select discovered gateways from the list or put manually an IP address.
• The KNX local address is the physical KNX address that will be used by the KNX IP Gateway
• The DNS configuration requires the IP address of the DNS server used and also the main zone of this server
• Check data storage if you want to offer the possibility to clients for saving data onto the gateway. A login to the local database must be provided.
• You can load a knxproj or a XML file onto the gateway. We suggest loading a XML file in order to avoid long processing of the knxproj file. After the XML being loaded, it can take a few minutes until the gateway is fully operable.

Usage

The gateway offers RESTful APIs (Web services) for manipulating KNX devices or data, considered as resources. Every interaction is done via a HTTP or CoAP request so that the gateway is platform and language independent, meaning you can interact from Java, .net, JavaScript, C/C++ or any other language able to perform these kinds of requests. It is also possible to use the gateway by installing a REST plugin for your browser, like the RESTClient for Firefox.

Discovery

The gateway reflects the building’s structure inside the URLs generated for interacting with endpoints. The KNX specification describes datapoints as communication endpoints offering some functionalities, like reading or changing a state.

The first step would be to discover device or more specifically the endpoint to interact with. To do so, you can perform HTTP/CoAP GET on parts of the building’s hierarchical structure. The gateway will respond with a JSON structured data informing about all the child nodes, e.g. calling http://2emeetage.leso.epfl.ch:8080. The resulting data is of following type:

{"isGroup":false,"name":"bureau201","url":"bureau201.2emeetage.leso.epfl.ch"}

• isGroup indicates if the child is a group containing datapoints or a sub-location.
• name is the name of the child location
• url is a link for accessing detailed information

Once a group is found, you can ask about the datapoints it contains by following its URL, e.g. http://luminosite205est.bureau205.2emeetage.leso.epfl.ch:8080/*. The resulting data is of following type:

{"datapoint_info":"2-byte unsigned value","datapoint_type":"DPT_Value_2_Ucount","description":"pulses","bits_size":16,"datapoint_number":"7.001","url":"luminosite205est.bureau205.2emeetage.leso.epfl.ch/dpt_value_2_ucount"}

• datapoint_info is the full name of the datapoint
• datapoint_type is the given name of the datapoint
• description can give some insights
• bits_size indicates the numbers of bits of the value
• datapoint_number is the number according to the KNX specification
• url is a link for interacting with the datapoint

Interactions

Once you have discovered a datapoint you are interested in, you can retrieve the actual value or change its state. This is achieved by calling the URL that was indicated previously, e.g. http://luminosite205est.bureau205.2emeetage.leso.epfl.ch:8080/dpt_value_2_ucount. If you want to read the actual value, you will have to perform a HTTP/CoAP GET. To change a state (actuate), you will send a HTTP/CoAP PUT request containing the new state inside the payload.

Notifications

If you want to be notified as soon as a value of a datapoint changes, you can ask the gateway to act this way. This is achieved by registering yourself on the datapoint you want to watch. The keywords register and unregister placed after the name of the datapoint are used for this purpose. When registering or unregistering, you have to put your callback URL inside the payload. This is an example of an URL for registration (only HTTP POST requests) http://luminosite205est.bureau205.2emeetage.leso.epfl.ch:8080/dpt_value_2_ucount/register.

The gateway also supports CoAP observation to watch datapoints.

Storage

By default the gateway will store no data. In order for it to act as logger, it is necessary to announce storage needs. This is achieved by sending an HTTP PUT request to the storage sub-resource of a datapoint, e.g. http://luminosite205est.bureau205.2emeetage.leso.epfl.ch:8080/dpt_value_2_ucount/storage. The number of days data should be stored has to be indicated inside the payload data. Additionally, the request must contain a HTTP/CoAP header called Referer where you have to put an ID of your choice. This ID will be used when removing the storage with an HTTP/CoAP DELETE request also containing the Referer header.

Once you have announced your storage needs, you are now able to retrieve stored data. There are two different ways for it. The first one is by specifying the numbers of days one wants to go back in the past, e.g. HTTP/CoAP GET to http://luminosite205est.bureau205.2emeetage.leso.epfl.ch:8080/dpt_value_2_ucount/storage?days=X. The second way is by specifying an interval with a start and an end date in format yyyy-MM-dd, e.g. HTTP/CoAP GET to http://luminosite205est.bureau205.2emeetage.leso.epfl.ch:8080/dpt_value_2_ucount/storage?from=X&to=Y. The returned JSON data is of following format:

{
“storage”:[
{”value”:”on”,
”timestamp”:”2013-01-10 08:12:34”},
{”value”:”off”,
”timestamp”:”2013-01-10 09:05:57”},
{”value”:”on”,
”timestamp”:”2013-01-10 13:40:03”},
{”value”:”off”,
”timestamp”:”2013-01-10 17:33:11”}]
}

Classes

We here describe the purpose of the various classes in the ga-web project.

Package ch.eiafr.web.knx:

• KNXServlet - Is the Web entry point of the gateway. It implements the do*() methods of the Servlet interface. It exposes this way the RESTful API.
• TypeRequest - Enumeration listing the possible types of requests. Means what the client wants to perform.
• KNXRequest - Parses the request HTTP request in order to determine what type of action should be performed.
• KNXRegisters - Manages the various observers that register or unregister on a resource.
• KNXObserver - Watches the various resources and notifies observers in the case of a change.
• KNXStorage - Offers various functionalities to access the database.
• StorageData - Bean to represent an historical value, containing the value and the timestamp.

Package ch.eiafr.web.knx.admin (related HTML pages are placed in src/main/webapp/knx):

• AdminServlet - It exposes the RESTful API used by the HTML pages to configure the gateway. It implements the do*() methods of the Servlet interface.
• TypeRequest - Enumeration listing the possible types of requests. Means what the client wants to perform.
• Datapoint - Bean to represent a KNX datapoint.
• Subscriber - Bean to represent a registered observer.
• KNXConfig - Allows to retrieve and update the properties set in the configuration file knx.properties.
• KNXFileWorker - Receives as input the ETS archive file and processes it along with the XSL stylesheet to get the XML.