Markdown source

#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.

This is the classic KNX communication layer stack:

<img src="./KNX_LayerStack.png" class="img-responsive center-block" width="50%"/>

##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 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 physical interfaces:

* [KNX Basic Course](
* [KNX Project Design with ETS](
* [Domotica e Building Automation](
* [Sviluppo di dispositivi KNX](
* [Accessing_the_KNX_bus](
* [EIB interface devices supported for FT1.2 and for EIBnet/IP](
* [EIB/KNX IP Gateway and Router with knxd](
* Non-commercial interfaces examples
	* [Guido PIC](
	* [GuiOtt](

Connecting the KNX bus requires a hardware that meets the physical layer specifications. The CM3-Home uses the Siemens official chip [TPUART-2](./TPUART2_Datenblatt_20130806_01.pdf). 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.

For a detailed description of the hardware connections, look at [TP-BUS interface and KNXD daemon]( article.

## 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:

<pre class="terminal">
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"

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:

<pre class="terminal">
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:

<pre class="terminal">
Description=KNX Daemon

# 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_OPTIONS


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:

<pre class="terminal">
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:
<pre class="terminal">
[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:~$ 


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. 

<pre class="terminal">
openhabian@RasPIguiott:~$ sudo openhabian-config

<img src="./ConfigKNX.png" class="img-responsive center-block" width="50%"/>

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 

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

<img src="./AddKNX.png" class="img-responsive center-block" width="50%"/>

Attach the KNX binding to knxd service

<pre class="terminal">
openhabian@RasPIguiott:~$ nano /etc/openhab2/services/knx.cfg

The default configuration needs to be changed in two rows:
<pre class="terminal">

An alternative configuration, using tunnel mode:
<pre class="terminal">

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:

<pre class="terminal">
rule "L_Laboratorio ON"
		Item L_Laboratorio received command ON
		val results = executeCommandLine(Cmd+"@@"+254+"@@"+254+"@@"+254,5000)

rule "L_Laboratorio OFF"
		Item L_Laboratorio received command OFF
		val results = executeCommandLine(Cmd+"@@"+0+"@@"+0+"@@"+0,5000)

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

To check the configuration, use the karaf console

<pre class="terminal">
[12:44:08] openhabian@RasPIguiott:~$ ssh -p 8101 openhab@localhost
Password authentication

                          __  _____    ____      
  ____  ____  ___  ____  / / / /   |  / __ )     
 / __ \/ __ \/ _ \/ __ \/ /_/ / /| | / __  | 
/ /_/ / /_/ /  __/ / / / __  / ___ |/ /_/ /      
\____/ .___/\___/_/ /_/_/ /_/_/  |_/_____/     
    /_/                        2.1.0
                               - release build -   

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

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

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

<pre class="terminal">
openhab> log:set debug

or enable the trace

<pre class="terminal">
log:set TRACE org.openhab.binding.knx
log:set TRACE

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

<pre class="terminal">
log:set DEFAULT org.openhab.binding.knx
log:set DEFAULT

All the useful information can be find in:

<pre class="terminal">

Or with the command 
in karaf console

Or with the browser at:

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:

<pre class="terminal">
openhab> config:delete org.openhab.knx

openhabian@RasPIguiott:~$ sudo systemctl restart openhab2

##Devices configuration

All the configuration files are in /etc/openhab2

<pre class="terminal">
[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...

<pre class="terminal">
openhabian@RasPIguiott:~$ nano /etc/openhab2/items/knx.items

Group Grele
Switch          L_Laboratorio       "Laboratorio"           <light>        (Grele)       { knx="1/6/25" }
Switch          L_SalAbatjour       "Salone Abatjour"       <light>        (Grele)       { knx="1/6/105" }
Switch          L_SalDX            	"Salone DX"         	<light>        (Grele)       { knx="1/5/217" }
Switch          L_SalSX         	"Salone SX"         	<light>        (Grele)       { knx="1/5/209" }
Switch          L_CucExt         	"Cucina Esterno"        <light>        (Grele)       { knx="1/5/225" }
Switch          L_Cuc         		"Cucina"        		<light>        (Grele)       { knx="1/5/233" }
Switch          L_CucPens         	"Cucina Pensili"        <light>        (Grele)       { knx="1/5/241" }
Switch          L_BagnoG         	"Bagno Giorno"        	<light>        (Grele)       { knx="1/6/97" }
Switch          L_Ingr	         	"Ingresso"       		<light>        (Grele)       { knx="1/6/81" }
Switch          L_CorridG         	"Corridoio Giorno"      <light>        (Grele)       { knx="1/6/33" }
Switch          L_TV         		"Mobile TV"        		<light>        (Grele)       { knx="1/6/113" }

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

Switch          S_LuciOff         	"Luci OFF"      		<light>        (Grele)       { knx="1/3/3" }
Switch          S_TvOff	        	"TV OFF"      			<light>        (Grele)       { knx="1/3/4" }
Switch          S_TvOn	        	"TV ON"      			<light>        (Grele)       { knx="1/3/5" }
Switch          S_TapGiu        	"Tapparelle GIU"   		<light>        (Grele)       { knx="1/3/1" }
Switch          S_TapSu	        	"Tapparelle SU"   		<light>        (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:

<pre class="terminal">
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"

<img src="./GuiKNX.png" class="img-responsive center-block" width="50%"/>

## 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

<img src="./OHcloud.png" class="img-responsive center-block" width="40%"/>

the following files will be available:

<pre class="terminal">

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.

<img src="./AppOH.png" class="img-responsive center-block" width="25%"/>

## Links

* [Official KNX Interfaces](
	* [TPUART-2](./TPUART2_Datenblatt_20130806_01.pdf)
	* [Development board](
* knxd
	* [knxd KNX demon](
	* [Manual configuration](
* OpenHAB
	* [Open HAB on Raspberry Pi](
	* [openHABian - Hassle-free openHAB Setup](
	* [Manual installation of OpenHAB on Raspberry PI 3](./opeHAB_RaspberryPI-3.pdf)
	* [Cloud service](
	* [Massimiliano Casini Slides about OpenHAB](


Le attività del TanzoLab si svolgono ogni mercoledi sera, salvo casi speciali, dalle ore 18:30 presso i locali della Acme Systems srl e consistono in:

  • Talk monotematici a cura di professionisti in vari settori tecnologici
  • Workshop pratici su elettronica embedded, produzione e informatica
  • Progettazione e realizzazione di nuovi prodotti embedded per l'IT

Le attività vengono coordinate tramite questo sito, in cui vengono pubblicati tutti i lavori svolti o in via di sviluppo, e tramite un gruppo Telegram con cui per interagire direttamente via chat con gli altri membri.