KNX

OpenHAB KNX binding

This article illustrates how to use the OpenHAB KNX binding on the TP-BUS hardware implemented
on the CM3-Home board.

Please note:
The CM3-Home board IS NOT a certified KNX device but implements just a hardware circuitry based on a Siemens TP-UART-2.
We do not provide any warranty about its functionality with the KNX devices.

The TP-UART-2 circuitry is powered up by the external bus so, in order to guarantee the correct operation, provide the power supply to the bus before turning on the CM3-Home.

Example: a KNX relay PLANA 1453 made by Vimar wired as shown below. The relay address was already configured with a valid KNX group address.

The Classic UI and the HabPanel supplied show some examples of lights and roller shutters, driven individually or in a group. They are organized as a separated frame in the UI and in a separate panel in the Habpanel.

The orange buttons drive all the devices in one shot.

Editing the items/knx.items file it’s possible to assign the relation between the name displayed and the KNX address of your devices.

Group:Switch:OR(ON, OFF) Gday "All Lights [(%d)]"

Switch L_Laboratorio "Lab"  (Gday) { knx="1/6/25" }
Switch L_SalAbatjour "Living room Abatjour"  (Gday) { knx="1/6/105" }
Switch L_SalDX "Living room DX"  (Gday) { knx="1/5/217" }
Switch L_SalSX "Living room SX"  (Gday) { knx="1/5/209" }
Switch L_CucExt "Kitchen Outside"  (Gday) { knx="1/5/225" }
Switch L_Cuc "Kitchen"  (Gday) { knx="1/5/233" }
Switch L_CucPens "Kitchen Top"  (Gday) { knx="1/5/241" }
Switch L_BagnoG "Bathroom"  (Gday) { knx="1/6/97" }
Switch L_Ingr "Entrance"  (Gday) { knx="1/6/81" }
Switch L_CorridG "Corridor"  (Gday) { knx="1/6/33" }
Switch L_TV "TV set"  (Grele) { knx="1/6/113" }

Group:Rollershutter:OR(UP, DOWN) Shutter "Roller Shutter [(%d)]"

Group:Rollershutter:OR(UP, DOWN) ShutterDay "Roller Shutters ALL [(%d)]"

Rollershutter T_Salone "Living Room" (Shutter, ShutterDay) { knx="1/5/202, 1/5/201" }
Rollershutter T_Laboratorio "Lab" (Shutter, ShutterDay) { knx="1/5/250, 1/5/249" }
Rollershutter T_BagnoG "Bathroom" (Shutter, ShutterDay) { knx="1/6/122, 1/6/121" }
Rollershutter T_CucinaP "Kitchen Door" (Shutter, ShutterDay) { knx="1/5/186, 1/5/185" }
Rollershutter T_CucinaF "Kitchen Win." (Shutter, ShutterDay) { knx="1/5/194, 1/5/193" }
Please note that the rollershutters have two different addresses, one for UP and one for DOWN commands.
Links

KNX integration via TPUART

How to create an OpenHAB interface on a KNX based home-automation system through a TPUART physical interface.
Practical information about interfacing the CM3-Home to a TP KNX bus.

Please note:
The CM3-Home board IS NOT a certified KNX device but implements just a hardware circuitry based on a Siemens TP-UART-2.
We do not provide any warranty about its functionality with the KNX devices.The TP-UART-2 circuitry is powered up by the external bus so, in order to guarantee the correct operation, provide the power supply to the bus before turning on the CM3-Home.

This is the classic KNX communication layer stack:

Interfacing standard home-automation systems

OpenHAB is designed to be interfaced also with more or less open commercial systems derived from EIB, like KNX and SCS.
The KNX is an open protocol used by many different manufacturer. Vimar, for example, in the ByMe domestic system uses a version of the protocol compatible with the others but with a proprietary system to assign the devices addresses. Their devices are not included in the knx.org database and cannot be configured with the ETS software like Siemens, Gewiss and others. The addressing is realized with a sort of DHCP system through a dedicated console.
The BTicino SCS is based on concepts very similar to KNX but with some differences even of the first communication stack layers.

Interfacing EIB with OpenHAB requires hardware devices physically attached to the twisted pair on a side and USB or ethernet on the other side. There are many devices for this purpose. Depending on the complexity of the gateway the data can be read already decoded or in raw mode, in this case requiring additional drivers to be used in OpenHAB environment.

Below some links for different resources:

TPUART

Connecting the KNX bus requires a hardware that meets the physical layer specifications. The CM3-Home uses the Siemens official chip TPUART-2. This is an example of a development board using TPUART-1. The new TPUART-2 is smaller, cheaper and with some more features while maintaining compatibility with the previous version. As evidenced in the stack diagram, TPUART manages the lower layers of the protocol exchanging the already decoded datagrams on a 19.2kbps serial interface.

KNX demon

knxd is a program that can be started as a service and creates a gateway towards practically all the KNX bus interfacing systems.
The installation on the CM3-Home board is eased a lot by some ready-made scripts, even if it can be compiled for the majority of Linux distributions.
The github wiki describes all the available interfaces: serial, USB or IP. The demon must run on the same machine were the TP bus is physically connected. This computer publishes on the network a service that can be used by OpenHAB or other programs like knxtools available on github, in order to manage all the field bus operations.
Even ETS, the devices management software officially distributed by the KNX consortium, can interface the bus through knxd and CM3-Home TPUART.
The ttyAMA0 CM3-Home port is used to interface TPUART, therefore it must be freed up from the operating system console service.

The default configuration proposed by the installation scripts is good:

openhabian@RasPIguiott:~$ nano /etc/default/knxd
KNXD_OPTIONS="--eibaddr=1.1.128 --client-addrs=1.1.129:1 -d -D -T -R -S -i --listen-local=/tmp/knx -b tpuarts:/dev/ttyAMA0"

ATTENTION
Starting from knxd version 0.14.22, the openhabian-config script (option 20 | Install optional add-ons of openhabian-config) still adds -d parameters in the KNXD_OPTIONS row of the configuration file used by systemd to launch the service at startup (/etc/default/knxd). This parameter, as well explained in the knxd wiki, is used to start the program as a demon when launched via the cli. Used with systemctl does not allow the program to start correctly. So, the line must be corrected manually in:

openhabian@RasPIguiott:~$ nano /etc/default/knxd
KNXD_OPTIONS="--eibaddr=1.1.128 --client-addrs=1.1.129:1 -D -T -R -S -i --listen-local=/tmp/knx -b tpuarts:/dev/ttyAMA0"

The installation script overrides this configuration if re-launched, therefore the correction must be repeated if knxd is installed again or upgraded.

Check if the file /lib/systemd/system/knxd.service looks like this:

[Unit]
Description=KNX Daemon
After=network.target
[Service]
EnvironmentFile=/etc/default/knxd
# Wait for all interfaces, systemd-networkd-wait-online.service must be enabled
#ExecStartPre=/lib/systemd/systemd-networkd-wait-online --timeout=60
# Wait for a specific interface
#ExecStartPre=/lib/systemd/systemd-networkd-wait-online --timeout=60 --interface=eth0
ExecStart=/usr/local/bin/knxd -p /run/knxd/knxd.pid $KNXD_OPTIONS
#Type=forking
Type=simple
PIDFile=/run/knxd/knxd.pid
User=knxd
Group=knxd
#TimeoutStartSec=60

[Install]
WantedBy=multi-user.target network-online.target

To check the correct operation, the knxtool program can be used. It is installed together with knxd by the script.

E.g.: monitor datagrams on KNX bus:

openhabian@RasPIguiott:~$ knxtool busmonitor1 ip:localhost
LPDU: B4 11 F0 0D D1 E1 00 81 16 :L_Data urgent from 1.1.240 to 1/5/209 hops: 06 T_DATA_XXX_REQ A_GroupValue_Write (small) 01
LPDU: B4 :Unknown LPDU: B4
LPDU: B4 11 F0 0D D1 E1 00 80 17 :L_Data urgent from 1.1.240 to 1/5/209 hops: 06 T_DATA_XXX_REQ A_GroupValue_Write (small) 00
LPDU: B4 :Unknown LPDU: B4
LPDU: B4 11 F0 0E 69 E1 00 81 AD :L_Data urgent from 1.1.240 to 1/6/105 hops: 06 T_DATA_XXX_REQ A_GroupValue_Write (small) 01
LPDU: B4 :Unknown LPDU: B4
LPDU: B4 11 F0 0E 69 E1 00 80 AC :L_Data urgent from 1.1.240 to 1/6/105 hops: 06 T_DATA_XXX_REQ A_GroupValue_Write (small) 00
LPDU: B4 :Unknown LPDU: B4

Control KNX devices:

[13:00:36] openhabian@RasPIguiott:~$ knxtool on ip:localhost 1/6/105
Send request
[13:02:25] openhabian@RasPIguiott:~$ knxtool off ip:localhost 1/6/105
Send request
[13:02:34] openhabian@RasPIguiott:~$
Installation

In order to have an OpenHabian2 environment correctly configured it is advisable to start from the official distribution distributed as an SD card image and follow all the instructions.
At the first login the system starts the installation of all the needed add-ons. This could last even for an hour.

Once the installation is complete, use openhabian-config (the raspbian raspi-config equivalent in Openhabian environment) to install any additional software and configure the board.

openhabian@RasPIguiott:~$ sudo openhabian-config

Before installing knxd, it is necessary to free-up the ttyAMA0 serial port from the console service

* 30 | System Settings A range of system and hardware related configuration steps ►
* 35 | Serial Port Prepare serial ports for peripherals like R
* [*] 1 (RPi) Disable serial console (Razberry, SCC, Enocean)
* [*] 2 (RPi3) Disable Bluetooth module (Razberry)
* [*] 3 Add common serial ports to openHAB JVM (Razberry, Enocean)

install knxd follow the menu item 20 -> 27

* 20 | Optional Components Choose from a set of optional software components ►
* 27 | knxd KNX specific, the KNX router/gateway daemon knxd
Openhabian

To install KNX binding, open the Openhabian interface at URL “http://your-cm3-home-address:8080″.
Using paper UI add the KNX binding

Attach the KNX binding to knxd service

openhabian@RasPIguiott:~$ nano /etc/openhab2/services/knx.cfg

The default configuration needs to be changed in two rows:

type=ROUTER
localIp=localhost

An alternative configuration, using tunnel mode:

ip=localhost
busaddr=1.1.129
ignorelocalevents=true
type=TUNNEL
port=3671
localIp=localhost

Using TUNNEL mode, the binding is connected in transparent mode to the KNX bus. In this way every event on the bus is captured and the corresponding items updated, allowing also the use if rules like this one:

rule "L_Laboratorio ON"
when
   Item L_Laboratorio received command ON
then
   val results = executeCommandLine(Cmd+"@@"+254+"@@"+254+"@@"+254,5000)
   logInfo("Exec",results)
end
   rule "L_Laboratorio OFF"
when
   Item L_Laboratorio received command OFF
then
   val results = executeCommandLine(Cmd+"@@"+0+"@@"+0+"@@"+0,5000)
   logInfo("Exec",results)
end

To manage, for example, a DALI light through a KNX switch.

To check the configuration, use the karaf console

[12:44:08] openhabian@RasPIguiott:~$ ssh -p 8101 openhab@localhost
Password authentication
Password:
              Welcome to            __  _____    ____  _
            ____  ____  ___  ____  / / / /   |  / __ )(_)___ _____
           / __ \/ __ \/ _ \/ __ \/ /_/ / /| | / __  / / __ `/ __ \
          / /_/ / /_/ /  __/ / / / __  / ___ |/ /_/ / / /_/ / / / /
          \____/ .___/\___/_/ /_/_/ /_/_/  |_/_____/_/\__,_/_/ /_/
              /_/
                  openHAB 2.3.0-1 (Release Build)

Hit '' for a list of available commands
and '[cmd] --help' for help on a specific command.
Hit '' or type 'system:shutdown' or 'logout' to shutdown openHAB.

openhab> config:list "(service.pid=org.openhab.knx)"
----------------------------------------------------------------
Pid: org.openhab.knx
BundleLocation: mvn:org.openhab.binding/org.openhab.binding.knx/1.10.0
Properties:
localIp = localhost
service.pid = org.openhab.knx
type = ROUTER
openhab>

In case of any problem, it can be useful to increase the debug level to verify possible configuration errors:

openhab> log:set debug tuwien.auto.calimero

or enable the trace

log:set TRACE org.openhab.binding.knx
log:set TRACE tuwien.auto.calimero

It is advisable to disable them at the end of the debug:

log:set DEFAULT org.openhab.binding.knx
log:set DEFAULT tuwien.auto.calimero

All the useful information can be find in:

/var/log/openhab2/event
/var/log/openhab2/openhab.log

Or with the command
log:tail
in karaf console

Or with the browser at:
http://cm3home.local:9001/

The configuration is dynamically loaded as soon as the cfg file is saved (/etc/openhab2/services/knx.cfg in the example). It could happen that the previous configurations are cached even at service restart. In that case clean up the cache before restarting the service:

openhab> config:delete org.openhab.knx

openhabian@RasPIguiott:~$ sudo systemctl restart openhab2

Devices configuration

All the configuration files are in /etc/openhab2

[13:02:34] openhabian@RasPIguiott:~$ cd /etc/openhab2/
[13:08:30] openhabian@RasPIguiott:/etc/openhab2$ ll
total 52K
drwxrwxr-x+ 13 openhab openhabian 4.0K Aug 10 19:25 ./
drwxr-xr-x 92 root root 4.0K Aug 12 16:44 ../
drwxrwxr-x+ 2 openhab openhabian 4.0K Aug 10 19:25 html/
drwxrwxr-x+ 3 openhab openhabian 4.0K Aug 10 19:25 icons/
drwxrwxr-x+ 2 openhab openhabian 4.0K Aug 12 17:06 items/
drwxrwxr-x+ 2 openhab openhabian 4.0K Aug 10 19:25 persistence/
drwxrwxr-x+ 2 openhab openhabian 4.0K Aug 10 19:25 rules/
drwxrwxr-x+ 2 openhab openhabian 4.0K Aug 10 19:25 scripts/
drwxrwxr-x+ 2 openhab openhabian 4.0K Aug 12 21:25 services/
drwxrwxr-x+ 2 openhab openhabian 4.0K Aug 12 17:19 sitemaps/
drwxrwxr-x+ 2 openhab openhabian 4.0K Aug 10 19:25 sounds/
drwxrwxr-x+ 2 openhab openhabian 4.0K Aug 10 19:25 things/
drwxrwxr-x+ 2 openhab openhabian 4.0K Aug 10 19:25 transform/
[13:08:31] openhabian@RasPIguiott:/etc/openhab2$

Once the environment is ready, you can create the items on OpenHAB, connect them to the binding…

openhabian@RasPIguiott:~$ nano /etc/openhab2/items/knx.items
Group Grele
Switch L_Laboratorio "Laboratorio" (Grele) { knx="1/6/25" }
Switch L_SalAbatjour "Salone Abatjour" (Grele) { knx="1/6/105" }
Switch L_SalDX "Salone DX" (Grele) { knx="1/5/217" }
Switch L_SalSX "Salone SX" (Grele) { knx="1/5/209" }
Switch L_CucExt "Cucina Esterno" (Grele) { knx="1/5/225" }
Switch L_Cuc "Cucina" (Grele) { knx="1/5/233" }
Switch L_CucPens "Cucina Pensili" (Grele) { knx="1/5/241" }
Switch L_BagnoG "Bagno Giorno" (Grele) { knx="1/6/97" }
Switch L_Ingr "Ingresso" (Grele) { knx="1/6/81" }
Switch L_CorridG "Corridoio Giorno" (Grele) { knx="1/6/33" }
Switch L_TV "Mobile TV" (Grele) { knx="1/6/113" }

Switch L_CamMat1 "Camera Matrimoniale 1" (Grele) { knx="1/6/41" }
Switch L_CamMat2 "Camera Matrimoniale 2" (Grele) { knx="1/6/49" }
Switch L_Testata "Testata Letto Matr" (Grele) { knx="1/6/129" }
Switch L_Camera1 "Camera 1" (Grele) { knx="1/6/57" }
Switch L_Camera2 "Camera 2" (Grele) { knx="1/6/65" }
Switch L_BagnoN "Bagno Notte" (Grele) { knx="1/6/73" }
Switch L_CorridN "Corridoio Notte" (Grele) { knx="1/6/89" }

Switch S_LuciOff "Luci OFF" (Grele) { knx="1/3/3" }
Switch S_TvOff "TV OFF" (Grele) { knx="1/3/4" }
Switch S_TvOn "TV ON" (Grele) { knx="1/3/5" }
Switch S_TapGiu "Tapparelle GIU" (Grele) { knx="1/3/1" }
Switch S_TapSu "Tapparelle SU" (Grele) { knx="1/3/2" }

Group Tapparelle
Rollershutter T_Salone "Salone" (Tapparelle) { knx="1/5/202, 1/5/201" }
Rollershutter T_Laboratorio "Laboratorio" (Tapparelle) { knx="1/5/250, 1/5/249" }
Rollershutter T_BagnoG "Bagno Giorno" (Tapparelle) { knx="1/6/122, 1/6/121" }
Rollershutter T_CucinaP "Cucina Porta" (Tapparelle) { knx="1/5/186, 1/5/185" }
Rollershutter T_CucinaF "Cucina Fin." (Tapparelle) { knx="1/5/194, 1/5/193" }
Rollershutter T_Camera "Camera" (Tapparelle) { knx="1/6/18, 1/6/17" }
Rollershutter T_CameraMat "Camera Mat." (Tapparelle) { knx="1/6/10, 1/6/9" }
Rollershutter T_BagnoN "Bagno Notte" (Tapparelle) { knx="1/6/2, 1/6/1" }

… and assign them to the switches on the graphic UI:

openhabian@RasPIguiott:~$ nano /etc/openhab2/sitemaps/knx.sitemap
sitemap knx label="GUIOTT home"
{
Frame label="Zona Giorno"
{
   Switch item=L_Laboratorio
   Switch item=L_SalAbatjour
   Switch item=L_SalSX
   Switch item=L_SalDX
   Switch item=L_CucExt
   Switch item=L_Cuc
   Switch item=L_CucPens
   Switch item=L_BagnoG
   Switch item=L_Ingr
   Switch item=L_CorridG
   Switch item=L_TV
}

Frame label="Zona Notte"
{
   Switch item=L_CamMat1
   Switch item=L_CamMat2
   Switch item=L_Testata
   Switch item=L_Camera1
   Switch item=L_Camera2
   Switch item=L_BagnoN
   Switch item=L_CorridN
}

Frame label="Tapparelle"
{
   Switch item=T_Salone
   Switch item=T_Laboratorio
   Switch item=T_BagnoG
   Switch item=T_CucinaP
   Switch item=T_CucinaF
   Switch item=T_Camera
   Switch item=T_CameraMat
   Switch item=T_BagnoN
}

Frame label="Scenari"
{
   Switch item=S_LuciOff
   Switch item=S_TvOff
   Switch item=S_TvOn
   Switch item=S_TapGiu
   Switch item=S_TapSu
}

}

An example of the result for this configuration at “http://your-cm3-home-address:8080/classicui/app

Openhab 2.x version

Starting from OpenHAB 2.3 the KNX binding has been upgraded to the “OH2.x style”. No more services but things. In this way it can be configured using PaperUI, knx.things file and all the other new tools introduced with OH2.0.

As well as any other 2.x binding the KNX one is composed by two main parts: the gateway, a sort of bridge that directly interfaces the physical KNX bridge to the OpenHAB world, and the device, the wrapper that contains all the single channels.

The bridge configuration UI presents an easier configuration of the same parameters already discussed.

Then a device “container” has to be created to include all the channels.

And all of the single channels (physical KNX devices) have to be added in the container.

Connecting Visual Studio Code to the CM3-Home via the rest API, it helps a lot on the configuration of the items.

Mobile App

To use all the CM3-Home OpenHAB features on mobile devices even when not in the same domestic network, it can be used the open cloud service offered by openhab and the corresponding app available for both iOS and Android

After installing the openHAB Cloud Connector

the following files will be available:

/var/lib/openhab2/uuid
/var/lib/openhab2/openhabcloud/secret

The files content is needed to setup the cloud service. A complete tutorial about installation and configuration is available on Youtube.

The same functions available on local UI can be used also on mobile device once connected with the cloud service.

Links

Share