Tutorials:
Sensors, interfaces and bus systems (SENIN, BUSSY)

Using a home automation software

last updated: 01/12/19

Introduction

Song of this chapter: Madness > Our house

In the market of IoT devices we have many proprietary solutions. To understand how automation software for buildings work we will lock in depth into one software designed for homes that is powerful in combining many proprietary protocols. The software is called openHAB, is open source and thus helps to understand the principles of building automation in depth. The documentation of openHAB is excellent, and there exists a big supporting community.

OpenHAB 2

OpenHAB stands for open Home Automation Bus and is developed in Java, so it runs an all platforms. The newest Version is 2.4 and to distinguish from the former 1.x versions it is often called openHAB. The documentation can be found in openhab.org/docs.

OpenHAB is very powerful and flexible but has a steep learning curve. So let's start :)

A short overview

We will install openHAB on a Raspberry Pi. This facilitates the installation procedure and the Raspberry Pi is a cheap and powerful possibility to use openHAB. Naturally it is also possible to install openHAB on a NAS or server or PC.

Bindings

The Raspberry Pi is our openHAB server. Now we want to connect our devices (called Things in openHAB) with the openHAB server to be able to manage them.

Devices need a "driver" called a Binding in openHAB. Bindings integrate physical hardware, web services and external systems in openHAB. In the first version of openHAB they were called "Add-ons", and some add-ons don't still exist exist in a 2.x version. All Bindings and add-ons can be found on: https://www.openhab.org/addons/.

A Binding is installed by using an graphical interface called PaperUI.

PaperUI

This interface is accessed with an internet browser on port 8080 of your Raspberry Pi (e.g.: 192.168.1.100:8080).

PaperUI PaperUI

Things

Things in the openHAB language are physical entities like devices, but also web services or information sources. Devices like actuators, sensors, cameras, lamps etc.. can sometimes be connected directly, but often they use proprietary (wireless protocols) and connect with these protocols to a bridge (also named gateway or hub). The bridge is then connected to openHAB (e.g. Homematic, Philips Hue, LoRaWan).

After the installation of the Binding, we can add our Things in PaperUI. This can be done in by using the + sign in Configuration > Things. New detected Things are shown in Inbox and are then added by clicking on the check mark .

PaperUI Things

In the same window we can edit and delete Things.

Thing Channels

A Thing has often more than one possibility to interact. In openHAB these possibilities are called [Channels]. E. g. an integrated motion sensor has 5 Channels: a switch notifying motion, a temperature sensor, a luminance sensor an alarm switch and a battery level indicator.

PaperUI Channels

Thing Status

Each Thing has a status object. This helps to identify possible problems. The following statuses are possible: UNINITIALIZED, INITIALIZING, UNKNOWN, ONLINE, OFFLINE, REMOVING and REMOVED. The status object has a status detail object wich gives even more information. More infos on status transition and the status objects can be found here.

Items

Bindings and Things belong to the the physical world. The whole concept of the application openHAB is built around the notion of Items. Items are decoupled from the physical things and play on a virtual layer. Items can be strings, numbers, switches and can be compared with base variable data types of a programming language.

Items have always have a state and some of them can be manipulated through events. They represent all properties and capabilities of the user’s home automation.

Through a binding an Item can e.g. be connected with a concrete channel of a thing. So the Item does not only store information set by software (e.g., ON, 247 or "Hello") but can also take action on the physical level. Items can be represented in sitemaps and can be grouped to create new logical items (group items). Al the rules in openHAB will be based on items and their status changes.

Items can be manipulated in PaperUI, but only with the newer 2.0 bindings and are then stored in JsonDB files (/var/lib/openhab), that are difficult to read and change. We will use the text-based configuration files with the extension .items under /etc/openhab2/items.

Example for an items file:

*.items

To create such a rough skeleton of an items files we can use the help of the HomeBuilder utility (copy/paste the text). This utility is also accessed with an internet browser on port 8080 of your Raspberry Pi (e.g.: 192.168.1.100:8080).

Sitemaps

Items can be represented in Sitemaps was stated above. An important feature of openHAB is to interact with the user and provide infos in a modern and pleasant way on tablets, smartphones or PC's.

Sitemaps are used to compose a user-oriented presentation of items for various User Interfaces (UIs) like e.g. BasicUI or the openHAB app for Android.

Sitemaps are also text files with the extension .sitemap and are stored under /etc/openhab2/sitemaps. The Sitemap name (inside the Sitemap file) should match the name of the text file.

Here an example of such a text file and the representation in the application BasicUI:

*.sitemap

BasicUI demo

To create such a sitemap file we can use also use HomeBuilder (copy/paste the text) and than change the file according our needs.

In the file above a label (Frame label="Some Items from Room SC4") was added to the second frame.

The result of our sitemap can be viewed with the application BasicUI (accessible with an internet browser on port 8080 of your Raspberry Pi (e.g.: 192.168.1.100:8080).)

Transformations

Short recap

Bindings (Add-Ons): a sort of "drivers" needed to communicate with the devices (Things)
Things: your physical devices represented in openHAB
Channels: your physical devices represented in openHAB
Items: properties and capabilities linked to Channels of your Things
Groups: collections or categories containing Items
Sitemaps: user-defined front-end interfaces to arrange Groups, Items, ...
Transformations: helper functions to transform your data
Persistence: services to store data over time
Rules automation logic, the “smart” in your Smart Home!

Install openHAB on Linux (debian)

More infos in https://www.openhab.org/docs/installation/linux.html.

We could use openHABian on our Raspberry Pi (see MQTT). This would be the easiest solution. To be more flexible with the platform, let's do it on a Debian based Linux system (package repo with apt).

OpenHAB is written in Java, so we first need a JAVA platform. As suggested we use Zulu. We add the repository of Zulu and install the package with the following commands:

    sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys 0xB1998361219BD9C9
    echo 'deb http://repos.azulsystems.com/debian stable main' | \
    sudo tee /etc/apt/sources.list.d/zulu.list
    sudo apt update
    sudo apt install zulu-embedded-8

The first command imports the needed public key and the second command adds the repository.
The backslash in the second line means that the command from line 2 continues in line 3. In the terminal you have to type the command in one line and remove the backslash.
After an update we can install the package.

Now we will install the openHAB stable release:

    wget -qO - 'https://bintray.com/user/downloadSubjectPublicKey?username=openhab' | sudo apt-key add -
    sudo apt-get install apt-transport-https
    echo 'deb https://dl.bintray.com/openhab/apt-repo2 stable main' | \
    sudo tee /etc/apt/sources.list.d/openhab2.list
    sudo apt update
    sudo apt install openhab2

Now we can start openHAB by and test if its running:

    sudo systemctl start openhab2.service
    sudo systemctl status openhab2.service

Quit with ctrl-c.

To start on installation, execute the following commands to configure openHAB to start automatically using systemd:

    sudo systemctl daemon-reload
    sudo systemctl enable openhab2.service

Upgrade openHAB:

    sudo apt update
    sudo apt upgrade

Command Line interface (CLI) to use in terminal:

    openhab-cli backup [--full] [filename]   -- Stores the current configuration of openHAB.
    openhab-cli clean-cache                  -- Cleans the openHAB temporary folders.
    openhab-cli console                      -- Opens the openHAB console.
    openhab-cli info                         -- Displays distribution information.
    openhab-cli reset-ownership              -- Gives openHAB control of its own directories.
    openhab-cli restore filename             -- Restores the openHAB configuration from a backup.
    openhab-cli showlogs                     -- Displays the log messages of openHAB.
    openhab-cli start [--debug]              -- Starts openHAB in the terminal.
    openhab-cli status                       -- Checks status (openHAB running?)
    openhab-cli stop                         -- Stops any running instance of openHAB.

Installing a samba network share on the Raspberry Pi:

To be able to access our openHAB installation files from our local PC we will set up a Samba network share. More infos in the openHAB documentation. We begin with installing samba:

    sudo apt install samba samba-common-bin

Next we have to edit the samba configuration file smb.conf.

    sudo nano /etc/samba/smb.conf

Add the following to the bottom of the file:

    [openHAB2-userdata]
      comment=openHAB2 userdata
      path=/var/lib/openhab2
      browseable=Yes
      writeable=Yes
      only guest=no
      public=no
      create mask=0777
      directory mask=0777

    [openHAB2-conf]
      comment=openHAB2 site configuration
      path=/etc/openhab2
      browseable=Yes
      writeable=Yes
      only guest=no
      public=no
      create mask=0777
      directory mask=0777

    [openHAB2-logs]
      comment=openHAB2 logs
      path=/var/log/openhab2
      browseable=Yes
      writeable=Yes
      only guest=no
      public=no
      create mask=0777
      directory mask=0777

Next, we need to set up a user and a password for our Samba share. Run the following command to create the user "pi" and set a password.

    sudo smbpasswd -a pi

Change the ownership of the openHAB files to "pi" with:

sudo chown -hR pi:pi /etc/openhab2

Restart the server:

sudo systemctl restart smbd

Now you are able to access the files from your PC.

Using the openHAB karaf console

The openHAB console offers the option to monitor the log in real time and to execute runtime commands. So it may be good to know it exists.

The connection is only allowed from localhost (machine running openHAB) due to security concerns. We access the console with

openhab-cli console

The most useful command is help (q to quit). It lists all the other commands. When finished with the console you get out with logout.

Example to view all active add-ons using MQTT:

bundle:list |grep -i MQTT

To view the log in real-time:

log:tail

Paths for openHAB files

In /etc/default we find the config file openhab2. In this file we find the links to the openHAB default paths:

OPENHAB_HTTP_PORT=8080
OPENHAB_HTTPS_PORT=8443
OPENHAB_BACKUPS=/var/lib/openhab2/backups
OPENHAB_HOME=/usr/share/openhab2
OPENHAB_CONF=/etc/openhab2
OPENHAB_RUNTIME=/usr/share/openhab2/runtime
OPENHAB_USERDATA=/var/lib/openhab2
OPENHAB_LOGDIR=/var/log/openhab2

Finishing the setup

Use your favourite web-browser to access openHAB on port 8080 (e.g.: 192.168.1.100:8080). We land on a page saying "Welcome to openHAB 2 - Initial Setup". Choose the standard setup.


openHAB welcome screen

The new screen shows 4 apps:

Edit the openHAB files from a local PC with Visual Studio Code

As we need to configure openHAB partially using text files, we need an editor. We can use nano with openHAB highlighting on the pi, but it is more comfortable to use an editor on the local machine and work on the pi via network share.

The best support for the moment is offered by "openHAB VS Code", an extension for Visual Studio Code. More infos on editors can be found on in the documentation of openHAB.

Download Visual Studio Code on your PC and install the openHAB extension. Go to File > Preferences > Settings > Extensions > openHAB Configuration click on "Edit in settings.json". Add the following lines to the json file:

    "openhab.host": "192.168.xxx.xxx",
    "openhab.port": 8080,
    "openhab.karafCommand": "ssh pi@%openhabhost% -p 8101 -t 'log:tail'",

More infos are on the github page of the extension.

"Just do it" Openhab 1:

Using Z-Wave devices in openHAB

Z-Wave

Z-Wave is a wireless communications protocol operating with a throughput up to 40 kbit/s in the unlicensed Industrial, Scientific, and Medical (ISM) band of 868 MHz in Europe. It is a mesh network using low-energy radio waves used primarily for home automation. In the mesh network, mains powered nodes can route messages between battery driven nodes. The network supports hop distances of up to four hops. Communication distance between two nodes is about 30 meters. more about Z-Wave in the openHAB documentation.

Z-Wave allows interoperability between home control systems of different manufacturers (2.600 products by 2019). A wide range of devices are supported and the Z-Wave certification guarantees that certified devices will be compatible with each other and the network. OpenHAB supports 941 things from 132 manufacturers.

Z-Wave Binding

The Z-wave Binding uses a standard Z-Wave serial USB stick to communicate with the Z-Wave devices. There are many sticks available, and they all support the same interface so the Binding does not distinguish between them.

Open PaperUI, go to Add-ons > Bindings and install the Z-Wave Binding. Before the Binding can be used, the serial adapter (Thing!) must be added. We use a Z-Wave USB stick on the Raspberry Pi. We need to provide the used serial port to openHAB. Go to Configuration > Things and click on +. After two further clicks we are able to add the serial port. Normally this is /dev/ttyACM0. If you are not sure, insert the stick and use the command dmesg to acquire the information about the used serial port.

Next we must add the openHAB user to the dialout group with:

    sudo usermod -a -G dialout openhab

Adding Z-Wave Things

To detect our Z-Wave devices we use the + sign in Configuration > Things. new detected devices are shown in Inbox. They are added by clicking on the check mark .

"Just do it" Openhab 2:

Connecting Items to Channels

Let's have a closer look to items. An Item has different fields with a defined order. The two first fields itemtype and itemname are obligatory. The other fields are optional. Fields may be separated by one or more spaces, or tabs and the Item definition may use multiple lines.

*.items

So for us the most interesting field is {bindingconfig}. Here we add our channels to the Item.

"Just do it" Openhab 3:

Using the MQTT Things in openHAB

As we built our own IoT devices publishing and subscribing by using MQTT we naturally want to add them to openHAB.

MQTT Binding

More infos can be found in the openHAB doc on Bindings. The MQTT Binding allows to configure connections to brokers via openHAB Things. T

As for the Z-Wave Binding we first install the Binding (PaperUI, Add-ons > Bindings). Search for MQTT (mqtt-binding - 2.4.0) and click on "INSTALL".

Now we can add MQTT Things in the Configuration > Things menu: Click on + , choose the MQTT binding. As Things are not automatically found, we can add them by clicking on MANUALLY ADD THING.

The first Thing to add is the MQTT Broker (server). Now it is a good idea to give the server a Thing ID that is not cryptic, but readable. We name the broker thing "mosqui-sc1". OpenHAB needs to know at least the IP address of our mosquitto server. Under "SHOW MORE" we can specify e.g. a password.

Now it is important to restart openHAB, to take the changes in account (known bug in 2.4.0):

    sudo systemctl restart openhab2.service

If all went well we will see the following in /var/log/openhab2/openhab.log:

Starting MQTT broker connection to ...

(OpenHAB has also an embedded simple MQTT server (less features especially on security than mosquitto) if you don't want to use an external broker (Configuration > Things > + > Mqtt Binding > ADD MANUALLY > System MQTT Broker)).

Configuring openHAB for the SmartyReader

The SmartyReader is reading the energy consumption and production of Luxembourgish smartmeters and sends the data over MQTT as JSON string.

MQTT Things

We need a configuration text file for the smartyreader (our Thing) in /etc/openhab2/things/. Here is the link to openHAB doc on Things.

The syntax for Things is defined as follows (parts in <..> are required):

    Thing <binding_id>:<type_id>:<thing_id> "Label" @ "Location" [ <parameters> ]

So we create a text file named SmartyReader_LAM_SC1.things (directory /etc/openhab2/things/) and add the following text to the file:

    Thing mqtt:device:SmartyReader1 "SmartyReader" @ "LAM SC hallway" [ip="192.168.131.15"]

MQTT Items

coming soon :)

Interesting links: