Introduction

EIB stands for "European Installation Bus" and is a wide-spread domotic control system. It has become a world-wide standard and is also known as KNX. The standards body is the Konnex association.

The EIBnet/IP protocol (also known as KNXnet/IP) has been defined to transport EIB requests over an IP-based network, with several companies delivering EIB-to-IP gateways implementing it. Among these products is the Siemens IP Interface N148/21. At least this device, but probably others as well, is limited to one concurrent connection.

The EIB programming tool ETS uses one connection. A visualisation software requires a second one. And a domotic control solution obviously also needs to communicate on the bus. I trust you see the problem. :-)

Enter EIBnetmux. And this issue is resolved.

EIBnetmux extends the IP-reach of the KNX bus and supports multiple concurrent clients. In addition, it features a very simple, TCP/IP socket-based protocol which allows applications to easily retrieve and set data from/on the bus. This empowers developers to focus on their applications and implement these great and long-wished for features without having to agonising over the rather complex, not very well documented, timing critical, UDP-based EIBnet/IP protocol.

In particular, web application developers will like the possibility to use a simple scripting language such as PHP to gain access to the KNX bus. Client libraries for PHP and C are included and ready to use.

On top of that, EIBnetmux includes special security features allowing you to control who has access to your domotic system and what users can do. There is no need to hand over complete control of your house to anybody who manages to get access to your network. This is of paramount importance if you think about connecting your house to the Internet and remotely managing installations.

Features
Architecture
eibnetmux architecture

Figure 1: Architecture of EIBnetmux

Figure 1 shows the architecture of EIBnetmux.

Standard KNXnet/IP clients such as ETS v3 connect to the KNXnet/IP server. They cannot tell that it is not an IP interface. It also supports auto-detection (IP multicast search requests) and description requests.

Applications using the simpler EIBnetmux client interface connect to the enmx server.

Request flow inbound

  1. Attached devices send requests on the KNX bus where they are intercepted by the IP interface.
  2. The request is converted and forwarded to the KNXnet/IP client of EIBnetmux.
  3. EIBnetmux distributes the request to all currently connected clients. It uses a special queing mechanism where slow or unresponsive applications have no negative impact on the speed of request distribution to other clients. If a client does not react and accept the forwarded packets within a given timeframe, it is automatically disconnected and cleared from the internal tables.

Request flow outbound

  1. Any of the connected clients sends a request destined for the KNX bus to its EIBnetmux server.
  2. The request is internally forwarded to the KNXnet/IP client.
  3. This component sends it to the IP interface.
  4. Finally, the IP interface converts and forwards the request to the KNX bus where it is received by the attached devices.

Note that the requests are only forwarded to the KNXnet/IP client and not to any other client. The IP interface will return the request as an inbound request from the bus. At that time, it will be distributed to all cconnected clients as per the inbound request flow description above.

Installation
  1. Grab, compile, and install all required dependencies
  2. Grab the EIBnetmux sources from here.
  3. Unpack in a directory of your choice.
  4. In the chosen directory type:
./configure && make && make install

For Gentoo users: First, chose one of the following two alternatives:

  1. Grab all the ebuilds from here and put them in your local overlay.
  2. Add 'http://eibnetmux.sourceforge.net/gentoo/overlays.xml' as an overlay definition to your layman configuration.

Then do:

echo app-automation >> /etc/portage/categories
emerge eibnetmux

For Debian users: You may want to check this blog for a start script. The blog itself is in French but you should be able to locate the script anyway.

Configuration

EIBnetmux requires no complicated configuration (unless you wish to use its enhanced security features, see below). For standard operation, all you have to do is to specify the correct command line parameters.

Usage is:

eibnetmux [options] hostname[:port]
-s --eib_server [port]
Activate the EIBnet/IP server for standard applications like ETS, etc.
By default, the port is set to 3671, the standard EIBnet/IP port.
-t --tcp_server [[address:] port]
Activate the TCP socket server for EIBnetmux clients. The default port is 4390. If an IP address is specified, EIBnetmux will only accept requests sent to this specific address. It will not bind to the other system interfaces.
-u --unix_server [path]
Activate the UNIX socket server for EIBnetmux clients. The default path is /tmp/eibnetmux.
-l, --log_level <level>
Set the log level. Please refer to section LOGGING for possible values.
-L, --log_dest <destination>
Define where log information is sent to. Destination can be one of:
  • udp:<host:port>
    Send the unadorned log messages to host at port port, where a log receiver must be running.
  • file:<path>
    Dump all log messages, including timestamps, to the named file.
  • syslog:<facility>
    Send all log messages to the syslog service.
-r, --ring_level <level>
Set the levels which go to the (debug) ring log buffer. See section LOGGING for possible values.
-R, --ring_size <kilobytes>
Set size of debug ring log buffer.
-d, --daemon
Run EIBnetmux in daemon mode.
-i, --user <username>
Run EIBnetmux as user <username>.
-g, --group <groupname>
Run EIBnetmux as group <groupname>>.
-p, --pidfile <path>
If set, EIBnetmux writes a file after startup containing its process id. This can be used to tell the server to shutdown if it is running in daemon mode.
-S, --security <path>
Specify the file containing security definitions, such as access restrictions and user authorisations. See section Security below. If not defined, anonymous full access to EIBnetmux and, consequentyl, the KNX bus is enabled.
-A, --address <ip address>
The EIBnet/IP protocol requires that the sender puts his own IP address in some of the packets. While this poses a severe problem in NATed networks, it is also a challenge on a Unix system which can have multiple network interfaces and addresses. By default, EIBnetmux asks the Linux kernel and its routing table for the correct address to use. However, if you, for any reason, want to overwrite this behaviour, you can specify the address to use with this option. Please note that this address will be used for any connection, disregarding any differing routing. So, be careful! The parameter <ip address> must be a numeric IP address (format aaa.bbb.ccc.ddd).

As hostname, you usually specify the DNS name or IP address of the IP gateway (the N148/21 or equivalent). However, you can also "localhost" or EIBnetmux' ip address and port. This will automatically activate loopback mode with which you do not need a real KNX bus and no IP gateway to test your applications.

Logging

Log output of eibnetmux can be controlled very precisely. The log level is in fact a bit mask with each bit selecting a specific log facility. Using the following table, calculate the correct logging level by simply adding their associated values.

Value Level
0 None
1 info
2 verbose
4 warning
8 error
16 critical
32 fatal
64 user
128 debug
256 trace EIBnet/IP client
512 trace EIBnet/IP server
1024 trace socketserver
2048 trace EIBD
Security

EIBnetmux offers enhanced security features allowing to tightly restrict access. Due to the differences in the underlying two access protocols (EIBnet/IP and EIBnetmux client protocol, respectively), security comes in two flavours to address these two aspects.

The EIBnet/IP protocol does not include any security and the ETS tool does not offer the ability to authenticate users. This leaves us only with the possibility to grant or deny access based on the system trying to connect. Consequently, you can specify the IP addresses of the systems which are allowed to connect to EIBnetmux.

As this certainly is a rather limited protection - after all, IP addresses can be forged easily - EIBnetmux also allows to limit the request types. You could, for example, restrict any write access to EIBnet/IP clients making it impossible to re-program your devices or change any group value. Using the rather better protected management interface, you can re-enable write access just before you start ETS.

If this is still not enough protection for your requirements, I suggest you establish a VPN with mutual authentication and have EIBnetmux listen only on the VPN endpoint. Setting this up, however, goes beyond the scope of this documentation. I am sure you will find enough relevant tutorials and documents somewhere else in the Internet.

Configuration

To enable EIBnet/IP protection, add the following section to your security file.

[eibnetip]
allow: <address>/<mask>
deny: <address>/<mask>
read: <address>/<mask>
write: <address>/<mask>

For the EIBnetmux protocol clients, the situation is completely different. As the protocol is based on TCP instead of UDP, session management is built-in and can be used to establish authenticated connections. Based on these, user-specific access limitations can be introduced allowing fine-grained control over who can do what.

Configuration

Analogous to EIBnet/IP, clients can be restricted based on their IP addresses. If you whish to enable this feature, add the following section to your security file:

[clients]
allow: <address>/<mask>
deny: <address>/<mask>
read: <address>/<mask>
write: <address>/<mask>

For user authentication and authorisation, you have to add several other sections to the security file. First, you must lay the groundwork and specify the access levels.

[authorisations]
level: function [, function] ...

The level is simply a positive integer. A function is an item of the following list:

Code Description
read read data from bus
write set value of group on bus
monitor monitor all requests sent to groups
mgmt_client connect/disconnect eibnet/ip client
mgmt_status get status
mgmt_loglevel set log level
mgmt_block set access block level
mgmt_connection forcibly close connections
all all functions
bus_all all bus accessing funcions, no management
bus_group reading, writing, and monitoring to/from/of logical group addresses
bus_physical directly access physical KNX devices (layer 7 API)
mgmt_all all management functionality
none no access at all

Next, you list the users and their authorisations in the users section:

[users]
name: [level,] password-hash

The level corresponds with the definitions in the authorisations section. If it is missing in the user definition or not defined, level 0 is assumed. The name can be any string up to 64 letters, digits, and symbols, excluding the ':' character. The password is not specified in clear text. Rather, the security file only contains its SHA2 hash. A tool to compute such hashes is included in the distribution (eibnetmux_hash).

For performance reason, I chose not to support SSL-encryption of the EIBnetmux protocol. However, the password must still not be transmitted in the clear. To this end, a specific section defines the Diffie-Hellman-Merkle secure key exchange parameters which are used to encrypt and decrypt the password before it is sent over the wire and after receiving it:

[dhm]
file: /etc/eib/dh_prime.txt
P: AFB852BFC8F8A98312E1F5673E8039EDF7D131686E377F51...
G: 04

You specify either the name of a file containing the parameters or you include them directly in the security file. In the latter case, the P and G values are required. The distribution contains a program called eibnetmux_dhm which can be used to calculate them.

Client libraries

To ease development of applications accessing the KNX bus, EIBnetmux features a simple client interface. The client-side of the interface has already been implemented for you and is provided in two libraries:

Sample applications can be downloaded from here.

Credits

The EIBnet/IP protocol documentation is not publicly available. For its implementation, I took ideas and some code from a diploma thesis by Fritz Praus.

A very special thank you goes to Stef S. - without your relentless search for optimisations this new and much more complete and tested release would not have been possible.