How to add a new Item to OpenHab – a simple 5 minute guide
This is a very quick guide on what an “Item” is in and how to add a new Item 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 an Item is in OpenHab and how to create a new one.
Quick note before we start: while Items also existed in OpenHab 1 I will be concentrating on OpenHab 2 here.
What is an Item in OpenHab?
OpenHab uses different conceptual layers to manage all devices in your smart home. The first layer is made up of so called “Things” – a representation of real devices. I already described how to add a new Thing to OpenHab. Things (i.e. a light bulb) can not be controlled directly. Instead they provide channels with their data (i.e. connection strength and current brightness) and their possible actions (e.g. dimming the light).
This is where the second layer is used: Items. Items are virtual where Things are physical. They can either exist purely in OpenHab (e.g. a switch to turn on or off rules) or they can be linked via channels to Things. For example you could create a dimmer to control the brightness of a Thing (the lightbulb).
Items can be different according to the data they hold: Color, Dimmer, Number, Switch and more. One special case of Items is the Group. A Group can control (well and group) a list of other Items. So how do you actually add a new Item you are asking? There are three different ways: via the PaperUI, automatically when creating Things or via text files. Here is how to do all three of them.
How to add a new Item to OpenHab via the PaperUI
A simple and visual way of creating Items in OpenHab is using the PaperUI. If you click on “Configuration” and then select “Items” you will see a list of all Items in your OpenHab instance (also the ones created via other ways).
Each existing Item can be changed by clicking on the edit icon. New ones can easily be created via the plus icon at the top.
Linking Items to a channel of a Thing has to be done via the Thing config though.
How to add new Items to OpenHab automatically when creating Things
OpenHab supports a so called “simple mode” where it will automatically create matching Items for all channels of new Things you add. You can enable this if you plan to fully manage your OpenHab instance from the PaperUI and don’t care about a lot of (potentially unneeded) Items being created.
To change this setting go the the “Configuration” tab in the PaperUI and select “System”. Scroll down until you find “Item linking”. If you enable “simple mode” here the Items will be created automatically. I find this to be more annoying than helpful so I deactivated it. It will not stop you from creating additional Items in any other way though.
How to add a new Item to OpenHab via the items files
Another way of adding Items 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 Item 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 “items” folder. Any file inside this folder with the .items extension will be loaded by OpenHab.
Open an existing .items file or create a new one (like items/examples.items). Add a new Item to OpenHab by adding lines to this file:
itemtype itemname "labeltext [stateformat]" <iconname> (group1, group2, ...) ["tag1", "tag2", ...] {bindingconfig}
// examples
Group grCharts (grHistory) // a group of charts, they all belong to the group history
Number CPU_Load1 "Load (1 min)" <none> (grSensor) { channel="systeminfo:computer:raspi:cpu#load1" } // a number item that is linked to the CPU load of the Raspberry Pi (Thing raspi), it is part of the sensor group and has no icon
String miNetSSID "Network SSID [%s]" <network> (gVac,gVacNetwork) {channel="miio:generic:070B9EBA:network#ssid" } // the network SSID of my vacuum robot, has a network icon, displays its values as "Network SSID abcd" and is part of several groupsThis might seem complicated but the the exact syntax is explained more in depth in the official documentation and most of the time you can copy examples from the documentation of the bindings. It is also really easy to create similar new Items by just copying existing ones and changing small details. Once you are done just save the file and OpenHab should automatically add the new Item. Check the logs or the PaperUI to see if it worked.
These Item definitions also already include the link to a Thing, or rather a channel, so no additional work is needed here. The linking is done via this part systeminfo:computer:raspi:cpu#load1 where raspi is the Thing name and load1 the channel.
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.
Items created by the PaperUI will not show up in these files, they are saved in a separate database! Items created via this file will be visible in the PaperUI though.
