General

Some principals of the EIB/KNX bus

In an EIB/KNX-bus installation you have several devices (sensors (aka switches) and actors (relays)) that have a physical address. They are connected in groups using a group address. Each sensor (switch) can send exactly one group address but each actor (relays) can listen to one or more group addresses.
Rleibd currently only uses group addressing.
For example, you can have a switch in the living room and an actor which actually connects power to the lights there. You program the switch (via ETS-software) to send group 1.0.1 and you program the actor to listen on group 1.0.1. So when you press the switch, it sends the value (0=off, 1=on) on group 1.0.1 and the actor will do the work.
For some devices, more than one group will affect the actor value. A dimmer can be set to a defined brightness (in percent), it can be switched on or off and it can be dimmed a step up or down. So it is complicated to track the actual value just by listening for telegrams. It is more secure to simply ask the actor for the value.
When you plan your EIB/KNX installation, it is useful to structurize your group address. You should use one main group (1.x.x) for lighting, one for windows, one for heating and so on. You should use one middle group (x.1.x) for each floor and the low group (x.x.1) for each device. This will ease explanation of telegrams and filtering on certain types.

Installation and configuration

Download the package and extract it into an empty directory. Additionally you must have the following packets installed for rleibd to work:

1. Gnu-C++ compiler to build the rleibd
2. the eib driver from tu-wien
3. Apache webserver to display the results
4. mod_php
5. Perl and  perlcgi
6. mxml library (available here)

Install the eib-driver according to the instructions from tu-wien. Test it using the eibdump-tool (again from tu-wien). Currently eibdump is only contained in one of the earlier packages (for Kernel 2.2 or so) so if you can't find it, search there. /dev/eib[0123] must exist and function properly before you continue. Make a Link /dev/eib to the appropriate eib-device.
Copy the sample cgi-script to your cgi-bin directory and adapt the eib-addresses to reflect your personal eib-installation.
Adapt the eibdef.xml-file according to your eib-installation. Run make. Rleibd should compile with no errors (shame on me if not ;-)). All the errors that appear now are on your duty. Correct them and your system should work.

Operation

Requesting values

EIB-Values are read via http-like requests on port 1215. For example, you read the group value 1.2.3 by sending the request GET /eib/grp/1.2.3. The portserver replies the value in clear text, i.e. on or off for a switch, open or close for a window, 25% for a percent-value and so on. Currently there is no possibility (and no need) to request the binary value.

Transmitting Values

To send a value over EIB/KNX, just add a ?val=... at the end of the request. No further checking is done. The portserver is just looking for the substring "val=" and is using the string thereafter as the value, which is also clear text. Currently, you can only send numeric values (e.g. 0 and 1 instead of off and on) and percent-values. An eventual % is ignored. The value string is simply passed to atoi() and sent as value.

• For a binary value, everything that evaluates to anything else than 0 sets the value. (But you should only use 0 and 1 of course!)
• For a percent-value, only values between 0 and 100 do set the Value. (Fractions are ignored. Only the integer value is used)
• The portserver will always reply Ok.
• The state of the corresponding group is set to unknown so the server will ask on the bus next time its value is requested.

When testing by sending the requests via your browser, you may have to hit the ctrl-refresh-button (ctrl-F5 for IE and Firefox) or clear your browsercache for the request to be actually sent.

The asker thread

The asker thread requests values on the bus in fixed time intervals (15 s). This helps detecting missing invalidate arguments and prevents inconsistencies between the actual state and the image of your installation in memory. It steps through all the groups in the xml-file. So the total time for an asker period is 15 s times the number of groups. Only groups with the ask-tag are actually asked for. Be carefully not to ask for central function groups since all your lights will turn off this time. If you do not have any ask-tags, nothing will happen at all but I recommend to have an ask-tag for at least every single action light group. You will see a mismatch notice via syslog for each group with a different actual value than the value in memory. This can happen very rarely due to a race condition in a properly configured system (when the actual state changes just while the asker  is requesting this group) and it will happen for temperature values unless you have the nomismatch-tag in it.
If you have, lets say, 100 groups defined which seems ok for a one-family-home, the asker thread will therefore take about 25 minutes for a complete run, regardless how many ask-tags you have.
The very first asker round is done at 1s intervals to speed up building the internal database.

Internal operation

rleibd starts three threads,  one servicing the serial port doing the communication with the BCU and one listening on the ethernet (port 1215) communicating with the user. When your browser calls the cgi-script it will fetch the information via port 1215, format it and send it to your browser. The third is the asker-thread explained above which synchronizes the state of your installation and the image in memory.

Description of some functions

rcvThread

runs in an endless loop catching the telegrams from the eib-driver. For interesting telegrams it stores the data in the grpClass-vector from where the client will fetch it. The BAU should be in link layer mode to receive any telegrams.

portserv

also runs in an endless loop listening on port 1215 for user requests. Requests can be made with a standard http-browser for testing and have the url eib/grp/x.y.z. Although the correct http-protocol does not irritate, portserv only searches for the GET keyword followed by the url. The response is the formated value in plain text. See the sample script how to use it. If the requested value is actually unknown, it will ask on the eib bus. Since this requires a wait (200ms) it can take long for the page to appear for the first time. This also implies, you should not use lots of addresses which cannot be asked on one page.
Note: asking and receiving the value is an asynchronous process so it is not guaranteed the value is received after 200ms. Normally this works but in case of high bus load it may require a second request.
If you get no value for a group, be sure that you set the read-flag for the actor of the group (and only for the actor).

getBauBytes

reads data from the BAU's internal memory (ram or eeprom). Note that this function will only work reliable when the BAU is not in link layer. Else unexpected telegrams may scramble the data read.

bauSetRcvTable

This function sets the length of the receive table to 0 so that the BAU will receive all telegrams in link layer mode. To prevent unnecessary eeprom writes, getBauBytes is called to determine if a write is actually necessary. This is usually true if you used ETS-software before.

bauToLinkLayer

switches the BAU into link layer mode. In this is the mode, the BAU will receive all telegrams addressed to the entries in its receive table (or simply all telegrams if its receive table length is 0). rcvThread expects this mode.

bauReset

causes a BAU reset. The BAU will not receive any telegrams thereafter. This is called when rleibd terminates normally.

Signals

rleibd catches the SIGUSR1-signal and writes the stats.xml file then. You can use this in a cron-script to limit the amount of stats to be lost if your machine (or rleibd) crashes. I do this once per night.

Future extensions

I already plan the following extensions to be implemented in one of the next releases:

• Conditions in scripts. You could flicker the lights if you switch of your bedroom lights and there are still open windows.
• Insertable Triggers. You can set Triggers on the fly and delete them if no longer useful.

Support

I developed rleibd in my spare time without getting paid for it. So please accept that I cannot spend much time in supporting your setup. If  you tried to set it up and it does not work, please try again. I repeatedly tried over months only for the eibdriver to work. If you tried again and it still does not work feel free to contact me. I will try what I can as long as time allows.
I will also set up a FAQ for this project if I have enough questions 😀. Please look there first.

Do you use it?

If you use rleibd, I would be glad to receive feedback from you (even if it is just something like Yes, I use it). Feel free to contact me but be prepared for me to contact you then... I love to get in contact to people somewhere out in the world!