How to add a new Thing to OpenHab – a simple 5 minute guide

Published by Oliver on

This is a very quick guide on what a “Thing” is in and how to add a new Thing to OpenHab 2. All the information you will need to get started in as few sentences as possible.

If you are new to OpenHab: welcome! It is an awesome open source project that I have used for years to build my own smart home. I do know from my own experience that it can be quite daunting in the beginning. To make it easier for you to start here is a super quick rundown of what a Thing is in OpenHab and how to create a new one.

Quick note before we start: Things are a new concept in OpenHab 2. If you are still using OpenHab 1 this concept won’t apply.

What is a Thing in OpenHab?

OpenHab uses several concepts to manage all devices in your smart home. It is structured in several layers. The first layer is made of so called “Things”. Things are the physical layer, they mostly represent a real device. Any device you would like to include in your system can potentially be represented by a Thing in OpenHab. Some examples from my installation are my mobile phone, a smart fan, motion sensors or temperature/humidity sensors as well as smart light bulbs.

OpenHab can gain the ability to interact with all kinds of devices (or Things!) by installing addons, called bindings. There are bindings for pretty much all major systems, like Philips Hue, IKEA Tradfri, Zigbee, MQTT, Sonos and many more.

There is also a special kind of Thing called bridge. A bridge will group a lot of similar devices and act like a gateway. Examples would be a MQTT broker which exposes a lot of devices connected via MQTT or the Hue bridge (like the physical device) which controls Hue Things like a lightbulb, motion sensor or switch.

Things are not directly controlled in OpenHab. Instead they expose their data and ways of control via so called channels. For example the H801 LED controller I am using exposes its current signal strength as well as the ability to dim the light and change the color as different channels.

Each channel will be linked to an Item, the virtual layer in OpenHab, but more on that in another article. So how do you actually add a new Thing you are asking? There are two different ways: via the PaperUI or via text files. Here is how to do both.

How to add a new Thing to OpenHab via the PaperUI

The maybe easier but in my opinion less scaleable solution to adding a Thing in OpenHab is using the PaperUI. To reach this UI (if it is installed) you usually need to open http://nameOrIpOfOpenHabServer/paperui/index.html

The first step is installing a binding that supports the Thing you want to add. Go to “Add-ons” on the left side of your screen and select the “Bindings” tab in the page that opens. Find the binding you need, click install, and wait a couple of seconds until it finishes.

menu showing all bindings of openhab
Installing a binding for OpenHab to support new Things

Now go (back) to the “Inbox” on the left side of your screen. If the Thing you want to install already shows up here just click the check mark item to add it. Otherwise you need to click the “Search for Things” link underneath the list and select the binding you just installed. Wait for it to finish searching and new Things should show up. Otherwise you might have selected the wrong binding or it is not configured properly (go to the “Configuration” in the menu to fix this).

List of Things OpenHab automatically found

All things added to OpenHab can be found and configured in the “Things” tab under “Configuration”.

The list of added Things in OpenHab – you can edit or remove each one

Linking a channel of a Thing to an Item can also be done via the PaperUI

Linking Items to Things (via a channel)

How to add a new Thing to OpenHab via the things files

Another way of adding Things to OpenHab is by directly adding them to a configuration file. The configuration files of OpenHab can usually be found in /etc/openhab2 or /opt/openhab2/conf. This directory will include a bunch of different folders for the different layers of OpenHab. Each folder can contain several configuration files.

To add a new Thing to OpenHab via the config file either connect to the machine that is running OpenHab or expose the config files via a samba share. Now go to the “things” folder. Any file inside this folder with the .things extension will be loaded by OpenHab.

Open an existing .things file or create a new one (like things/examples.things). Add a new Thing to OpenHab by adding lines to this file:

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

// examples
astro:sun:home  [ geolocation="52.517223,13.283414", interval=60 ]  // the sun in Berlin
Bridge mqtt:broker:mosquitto [host="localhost", port=1883, clientID="openHAB2"] {

    // sonoff items
    Thing topic sonoffLamp "Lamp" @ "Living room" {
             Type switch    :   power               "Power"         [ stateTopic="sonoffs/tele/sonoff-steckdose-1/POWER", commandTopic="sonoffs/cmnd/sonoff-steckdose-1/POWER"]
             Type string    :   reachable           "Reachable"    [ stateTopic="sonoffs/tele/sonoff-steckdose-1/LWT" ]
             Type number    :   rssi                "WiFi Signal"   [ stateTopic="sonoffs/tele/sonoff-steckdose-1/STATE", transformationPattern="JSONPATH:$.Wifi.RSSI" ]
} // an MQTT bridge and a lamp Thing controlled via MQTT

This might seem complicated but the the exact syntax will be explained in the documentation of the binding that adds support for this kind of Thing. It is also really easy to create similar new things by just copying existing ones and changing small details. Once you are done just save the file and OpenHab should automatically add the new Thing. Check the logs or the PaperUI to see if it worked.

If you are looking for a good environment for working with these files I recommend Visual Studio Code and the OpenHab extension. I personally also use git to manage the folder with the config files. This allows me to see my changes over time, revert changes if I made a mistake and easily back up my configuration by pushing it to another git server.

Things created by the PaperUI will not show up in these files, they are saved in a separate database! Things created via this file will be visible in the PaperUI though.

You have questions? You need more?

If you are looking for more in-depth information here is the official documentation. If you are looking for some cool smart home projects to test your new OpenHab skills with check out the rest of my blog, follow me on Twitter or subscribe to my newsletter.

Categories: OpenhabBasics