You really should upgrade to Firefox. Even this simple page is not rendered correctly by Internet Explorer.
You really should upgrade to Firefox. Even this simple page is not rendered correctly by Internet Explorer.
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.
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
Request flow outbound
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.
./configure && make && make install
For Gentoo users: First, chose one of the following two alternatives:
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.
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]
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.
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 |
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.
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.
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.