OpenHAB is a Java based software that can be used on a computer connected to your Local Area Network (LAN) to monitor (or control) various “smart devices” in your home (or building). Typically, it is meant to be installed to a headless machine like a Raspberry Pi, but any computer you have sitting around should work. The machine needs to always be running and connected to your LAN.
If you install OpenHAB using
aptpackages, then the section about Controlling a system service in Linux (systemctl) may be beneficial.
Setting Up an MQTT broker (Mosquitto) and configure it to use your LAN.
You can use the same machine to host the MQTT broker and the OpenHAB server. Usually people use a Raspberry Pi to do this.
I highly recommend following the OpenHAB Getting Started instructions to get a feel for using the interface. The rest of this tutorial will assume that you are logged into the OpenHAB interface with an OpenHAB administrator account. This should have been covered in the OpenHAB Getting Started instructions
Some of the images here are hyperlinked to the http://openhabian:8080 domain for quicker access. If you are using a different hostname or a static IP address, then you can adjust the address in your browser’s address bar.
Installing the MQTT binding¶
Building off OpenHAB’s “Add a Thing - Simple (Install the Binding)” instructions, look for a
MQTT binding in the “bindings add-ons” list.
Click or tap the
show <n> more button at the bottom of the OpenHAB Distribution list if
you don’t see the MQTT binding.
The MQTT binding is one of the official OpenHAB addons. It is not a Community addon.
Click or tap the
install button to install the binding and add MQTT capability to your
Homie v3 vs Homie v4
The OpenHAB MQTT Homie binding will say that it supports Homie v3.x specifications. This library implements Homie v4 specifications. Homie v4 is mostly backward compatible with Homie v3 with the following exceptions:
Node Arrays are not supported in Homie v4. Incidentally, Arrays aren’t implemented in OpenHAB’s MQTT Homie binding because the Homie specification was too vague which is why it was removed in Homie v4 (see this HomieIoT thread comment).
These missing features are memory and process intensive for microcontrollers. At this time, there is no plan to add Homie v3 support for this library.
Adding the MQTT broker as an OpenHAB Thing¶
After Installing the MQTT binding, navigate back to the settings page and open the “Things” category. You may think that installing the MQTT binding didn’t change anything, but automatic discovery of MQTT-capable devices still requires an OpenHAB Thing to represent the MQTT broker.
Click or tap the floating
+button at the bottom of the page.
You should see a list of the installed bindings to choose from. Click or tap on the MQTT binding.
At the top of the list of options that you can add as OpenHAB Things, you should see the MQTT broker option. It will have a badge on it that says
Bridge. Click or tap on the MQTT broker option.
Enter the hostname or IP address of the machine that is running the MQTT broker.
Typically, the same machine can be used for serving OpenHAB and the MQTT broker. If you’re using the openhabian OS installed on a Raspberry Pi, then the hostname will be
Getting the IP address
If you’re also using a DNS sink hole to block advertisements across the entire network (ie. PiHole), then resolving the hostname may fail. In this case, use the IP address for the machine running the MQTT broker.
- Advanced Options
The following settings are only shown in the advanced options:
Password(in case you followed the steps to Setting a username and password)
Passwordfields are not related to the OpenHAB user account. Actually, these are the values used when Setting a username and password.
Your internet browser may suggest otherwise if your OpenHAB account credentials are saved in the browser’s settings.
Portnumber (in case you are not using the default
8883with SSL/TLS enabled)
The advanced options are only shown if the “Show advanced” checkbox at the top of the list is checked.
Click or tap on the
Create Thingbutton at the bottom of the page when done entering the MQTT broker criteria. Now in your OpenHAB list of Things, you should see the status of the MQTT broker.
If you see a badge that says
ERROR:COMM(where it should say
ONLINE), it means that there’s something wrong with the values you entered in step 4. Click or tap on the MQTT broker Thing to change the settings accordingly. Don’t forget to hit
saveat the top of the page after making the necessary changes.
Hover your mouse (or tap and hold) over the
ERRORbadge to see a tooltip briefly explaining the reason for the error.
Adding a Homie Device as an OpenHAB Thing¶
Once you have finished Adding the MQTT broker as an OpenHAB Thing, you are now ready to start using OpenHAB’s automatic
discovery of Homie Devices. This section should be repeated for any instantiated
Only do this once
Once completed, there is no need to repeat these steps again for the same
unless you have changed the
device_id parameter to the
HomieDevice constructor. Connecting
& disconnecting a Homie Device that are already added as OpenHAB Things should be automatically
handled by the OpenHAB MQTT Homie binding.
First lets get a library example running on a circuitPython enabled board (with WiFi support). See the Examples to understand how to run a library example. For this tutorial, we’ll be using the Simple test example.
Once you’ve got an example running on your circuitpython board, The
HomieDevice must be added to
OpenHAB as an OpenHAB Thing. The
HomieProperty values are used in OpenHAB as a OpenHAB Item, and each
OpenHAB Item must be “linked” to an OpenHAB Thing’s “channel”
To see any new Homie devices discovered by the MQTT binding, navigate to Settings -> Things. Click or tap on the notification titled
Inboxat the bottom of the screen.
Click or tap on the discovered Homie Device and select
Add as Thingfrom the pop-up menu. It will ask you for a customized name to be assigned to the OpenHAB Thing. By default it will use the
device_idif not changed, so this step is optional. Click or tap the
OKbutton when done.
You should now see the Homie Device in your list of OpenHAB Things.
To use this Homie Device’s properties in the OpenHAB user interfaces, you need to create an OpenHAB Item for each Homie Device property (programmatically instantiated with
HomiePropertyor one of its derivatives). Each OpenHAB Item must be linked to a Homie Device property via an OpenHAB Thing’s channel(s).
To see the channels, navigate to the configuration of the OpenHAB Thing that represents your Homie Device (in your list of OpenHAB Things). Click or tap on the tab named
Channelsat the top of the page.
You should now see a list of properties belonging to your Homie Device. Using the Simple test example, this list only has a
colorproperty. There are various ways to create OpenHAB Items from the OpenHAB Thing’s
Channelsconfiguration page. Choosing 1 will depend on how you wish to craft your OpenHAB User Interface, Dashboard, or Sitemap.
Click or tap on an available channel and select
Add link to Item..., then select
Create a new Item. This will create a single OpenHAB Item, but the item’s ID must be unique in OpenHAB (cannot reuse the same ID for multiple OpenHAB Items linked to the same OpenHAB Thing’s channel). While this is the most flexible, it can also become the most tedious.
Click or tap on the button titled
Add points to Model. This will create the necessary OpenHAB Item(s) and link them to the respective property’s channel.
Click or tap on the button titled
Add Equipment to Model. This is similar to
Add points to Model, however the created OpenHAB Item(s) are put into a group that represents a category of equipment.
It is important to understand OpenHAB’s Semantic Model and how they can be used when crafting a User Interface.
This tutorial does not cover how to use OpenHAB in general. The main point of this tutorial is how to use the CircuitPython_Homie library for automatic discovery of DIY devices in OpenHAB.