Using Homie with OpenHAB¶

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.

Prerequisite¶

1. Install OpenHAB using their excellent download instructions.

   See also

   If you install OpenHAB using apt packages, then the section about Controlling a system service in Linux (systemctl) may be beneficial.

2. Setting Up an MQTT broker (Mosquitto) and configure it to use your LAN.

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

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.

Click or tap the install button to install the binding and add MQTT capability to your OpenHAB server.

Installing the MQTT binding in OpenHAB will also install Homie support automatically. More info about Homie support can be found at the MQTT Homie binding page.

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.

1. Click or tap the floating + button at the bottom of the page.

2. You should see a list of the installed bindings to choose from. Click or tap on the MQTT binding.

   

3. 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.

   

4. 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 openhabian.

   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.

   How to get the IP address in Linux CLI¶

   hostname -I
   

   Advanced Options:

   The following settings are only shown in the advanced options:

   • Username and Password (in case you followed the steps to Setting a username and password)

     Note

     The Username and Password fields 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.

   • the Port number (in case you are not using the default 1883 or 8883 with SSL/TLS enabled)

   The advanced options are only shown if the “Show advanced” checkbox at the top of the list is checked.

5. Click or tap on the Create Thing button 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 save at the top of the page after making the necessary changes.

   Hint

   Hover your mouse (or tap and hold) over the ERROR badge 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 HomieDevice object.

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”

1. To see any new Homie devices discovered by the MQTT binding, navigate to Settings -> Things. Click or tap on the notification titled Inbox at the bottom of the screen.

2. You should see your new HomieDevice listed by it’s device-_id (a required parameter in the HomieDevice constructor).

   

   Click or tap on the discovered Homie Device and select Add as Thing from 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_id if not changed, so this step is optional. Click or tap the OK button when done.

3. 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 HomieProperty or 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 Channels at 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 color property. There are various ways to create OpenHAB Items from the OpenHAB Thing’s Channels configuration 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.

   Going Forward

   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.