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:

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

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.

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:

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.

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: 

                          __  _____    ____      
  ____  ____  ___  ____  / / / /   |  / __ )     
 / __ \/ __ \/ _ \/ __ \/ /_/ / /| | / __  | 
/ /_/ / /_/ /  __/ / / / __  / ___ |/ /_/ /      
\____/ .___/\___/_/ /_/_/ /_/_/  |_/_____/     
    /_/                        2.1.0
                               - 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"

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

Guido Ottaviani (Author/Designer/Developer for electronics-firmware-robotics)
He deals with electronic design and embedded system firmware for Robotics and industrial and civil applications, as well as technical disclosure on the internet.
http://www.guiott.com - https://github.com/guiott - guido@guiott.com
Massimiliano Casini (Coordinatore tecnico Service Assurance presso www.kenamobile.it)
Sono cresciuto nel modo IT di aziende ad alto contenuto tecnologico e da sempre ho acquisto esperienze nel settore della domotica e sicurezza residenziale. Negli ultimi dieci anni ho acquisito competenze specifiche nel campo delle TLC in particolare sulla rete GSM e sui protocolli ad essa collegati.



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.