What is MQTT and How to use it with OpenHab?

MQTT is the bread and butter of the Open Source IoT world and on this tutorial, you will learn everything you need to know about MQTT and how to integrate MQTT messaging in openHAB. MQTT and openHAB are a killing combination to start integrating  DIY Home Automation Sensors in your Smart Home Project.

Here is what you will learn today:

  1. What is MQTT?
    1. The architecture of the network.
    2. MQTT Topics.
  2.  openHAB MQTT
    1. Installing Mosquitto
    2. Configure the MQTT Binding in openHAB.
    3. Subscribe to an MQTT Topic from openHAB.
    4. Publish to an MQTT topic using openHAB.

 

What is MQTT?

MQTT is a protocol created by IBM that stands for Message Queue Telemetry Transport and it is primarily focused on M2M (Machine-to-Machine) communication.

You might be wondering what does this have to do with Home Automation…

Although MQTT has been used for a number of applications, it is heavily used as a communication protocol for IoT devices.

Why Is That?

  • MQTT was designed for applications where the required bandwidth is very low.
  • It consumes very little resources.
  • It is available on many different platforms.

Those reasons make MQTT the perfect protocol to run on microcontrollers that aren’t very powerful, like Arduino for example.

 

MQTT Architecture

 

MQTT uses a Star Topology with a central node called Broker and clients connected to it.

The Broker runs the party. It is in charge of sending and receiving the messages from the clients. Considering how lightweight the protocol is, it is worth mentioning that MQTT can work with encrypted messages, which is pretty impressive.

MQTT - Star Topology

 

How does this apply to Home Automation?

When you implement MQTT communication in your sensors, there will be primarily two elements:

  1. MQTT Broker: It allows the clients to publish or consume messages to/from topics.
  2. Sensors/Actuators: The clients can be sensors or actuators.
    1. Sensors: They publish messages on topics so the subscribers can read them. An example of this is a temperature sensor.
    2. Actuator: They are subscribed to a topic waiting for a command to execute an action, for example by turning on a light.

Clients can communicate between them but they still need the broker to distribute the message.

 

MQTT Topics

The communication in the MQTT protocol is based on topics. A sensor can publish messages on a topic and all the subscribers to that topic will receive that message.

Let’s walk through an example:

 

MQTT - Topics

 

Let’s say that we have a gas sensor in the kitchen that sends a radio signal when the gas levels go over a given threshold.  The sensor will publish a message on the topic Home/Floor1/Kitchen/Gas_Sensor with the number 1, indicating that a gas leak has been detected.

Every subscriber to the topic Home/Floor1/Kitchen/Gas_Sensor will get a copy of the message.

MQTT topics are built on a hierarchy, that means that if a subscriber is listening to Home/Floor1/Kitchen, it will get everything under the node kitchen.

 

MQTT And OpenHab

Installing Mosquitto in openHAB

As I explained before, a sensor on its own cannot do much, it is isolated. For the sensor to be able to publish messages there needs to be an MQTT broker. The broker is in charge of receiving and distributing messages from and to the other clients. In this post, I am going to explain to you how to install Mosquitto, an MQTT broker that is heavily used in IoT applications.

If you are using OpenHabian, installing Mosquitto is extremely easy. If you have not installed Openhab using OpenHabian it is never too late, Here you have a step by step tutorial.

1. SSH into your OpenHab Server, get into the OpenHabian Configuration and select Optional Components

 

 

2. In the Optional Components Menu select Mosquitto

 

 

 

3. Openhabian will ask you to confirm the installation

 

4. Provide a password for the MQTT Broker 

 

5. Once Openhabian shows you the following message you can restart the Raspberry Pi for the changes to take effect. 

 

OpenHab MQTT Binding

Now that you have an MQTT Broker installed on your server, it is time to connect your OpenHab server to the Broker.

1. Open PaperUI and go to Addons.

2. Select BINDINGS, look for MQTT Binding and install It.

There are compatibility issues on the lastest release of openHAB (2.4). I will review this i more depth but for the moment you can add the compatibility with legacy bindings and install MQTT1 instead of the new binding.

 

Once you have enable it, you should be able to install the legacy version of the binding.

 

Install MQTT Binding

 

 

3. Edit the MQTT config file on /etc/openhab2/services/mqtt.cfg to tell OpenHab where and how to connect to the MQTT Broker.

 

 

 

 

 

 

 

 

4. At this point, we have integrated Mosquitto with OpenHab. Let’s do some testing. 

 

Testing MQTT Connectivity

This is only a simulation to make sure that OpenHab is connected to the MQTT broker. For this test, you will create an item to receive the values from the gas sensor. After that, you will have to use mosquitto_pub to simulate the sensor sending a value.

1. Create a file called sensors.items under /etc/openhab2/items and paste the following content.

Number mqtt_kitchen_gas "Gas Level [%.1f]" {mqtt="<[mosquitto:Home/Floor1/Kitchen/Gas_Sensor:state:default]"}

OpenHab is now acting a client and it is subscribed to the topic Home/Floor1/Kitchen/Gas_Sensor. Every time the gas sensor publishes a message, the item will be updated.

 

2. Add the new item to your sitemap.

Text item=mqtt_kitchen_gas icon="gas"
3. When you open your sitemap for the first time you will see something like this:
 Sitemap - Gas Sensor Before Updating MQTT value
You can see that there is a gas sensor that should give you the gas level but it has no value.
4. Publish a value to the topic Home/Floor1/Kitchen/Gas_Sensor using mosquitto_pub.
SSH into you OpenHab server and type:
mosquitto_pub -u openhabian --pw smarthomeblog -t "Home/Floor1/Kitchen/Gas_Sensor" -m 10
5. After refreshing your browser you will see that the gas sensor has a value of 10. 
Sitemap - Gas Sensor AfterUpdating MQTT value

The MQTT broker is up and running! It wasn’t that difficult, was it?

 

 

This Post Has 14 Comments

  1. zhanxw 27 Jun 2018

    This tutorial works only when I removed “mqtt:” in the /etc/openhab2/services/mqtt.cfg.

  2. David C. 28 Jun 2018

    Hi Zhanxw,

    Thanks for the feedback. I am still running with that config and it works just fine, however, since it is not really required to specify the service because we are using a specific file for MQTT I am going to remove it from the blog post and my own config. Out of curiosity, which version of OpenHab are you on? I am in OpenHab 2.3 and I haven’t had issues with that config so far.

    Thanks again for commenting!.

  3. Bruno M 3 Sep 2018

    Hello,

    I am having trouble Creating files and adding sitemaps because I have zero understanding on how to access folders and editing files. When I access a folder (and I don’t even know if i’m doing it right, I type nano /etc/openhab2/items but it doesn’t show any files, it’s just so confusing. I bought all the parts you mentioned in the post but I don’t know how to use the terminal correctly. I searched on youtube and everything but nobody shows how to do this. Could be kind enough to include these tutoria-lrt in this post so I can continue to do the automation? I’m sure others are having the same problem as I am in the process. Thank you so much.

  4. David C. 4 Sep 2018

    Hi Bruno,

    No worries, we will figure it out. Sorry for the late response, I have been out of town for the weekend.
    I will enrich the post to add more detai-lrt on how to edit the files but just to get you out of the woods I will email you some detai-lrt.

    I hope the email in the comment is correct!

  5. rundekugel 18 Nov 2018

    Hi,
    hope, you can help me:
    I can send and receive any mqtt topic with python to the broker. But with openhab it works only, if I created a channel in paperUI for every msg I wanna have.

    must I insert the name of the topics in a *.things file ? How can I do this?

  6. David C. 18 Nov 2018

    Hi Rundekugel,

    You need to create an item for each topic you need to subscribe to in your items file:

    Like this:
    Number item_name “Item Value [%.2f]” {mqtt=”<[mosquitto:mygateway1-out/5/2/1/0/48:state:default]"} Let me know if it helps.

  7. David 18 Dec 2018

    On the openHAB forum we have the first people coming from this blog tutorial (thank your for this nice article) and struggling, because openHAB 2.4 replaced the mqtt binding with a new incompatible version. It would be really helpful if you could add a short sentence about how to enable legacy addons and install mqtt1 and not mqtt1 to solve this confusion.

    Thanks, david

  8. David C. 18 Dec 2018

    Hi David,

    Before I actually answer let me tell you that going this far to keep the information up to date and the user experience up to code is just astounding. It comes at no surprise that openHAB is one of the best open source home automation platform.

    Thanks for letting me known.

    I have added a quick note to avoid confusion but I was planning to upgrade to 2.4 today so I will check how to get things up and running with the new binding and update the post.

  9. Eric 17 Feb 2019

    I am brand new to openhab. Can you give me more detail on Step 2 in the Testing MQTT Connectivity?

    2. Add the new item to your sitemap.

    Text item=mqtt_kitchen_gas icon=”gas”

  11. Tommy Thompson 11 Oct 2019

    I admit I dont know what Im doing but you change styles too much in writing.
    Not easy to follow

  12. David C. 26 Oct 2019

    Hi Tommy,

    Which part is unclear. Maybe I can help adding more details.

  13. Robert 24 Aug 2020

    What about people who choose not to use OpenHabian? Are we just out of luck?

  14. David C. 25 Oct 2020

    Hi Robert,
    What do you use?

Leave a Reply