What is MQTT and How to use it with OpenHab?

This post is part of a tutorial on building Low-Cost Home Automation Sensors. If you have landed on this page directly I suggest you check first Low-Cost DIY Home Automation Sensors. In this part of the tutorial, you will build the gateway. The gateway will handle the communications for all the nodes in your network.

Installing and MQTT Broker is the first step towards building your own low-cost sensors for your Home Automation Project. By The end of this post, you will know the principals behind the MQTT protocol and more important than that, you will have your MQTT broker up and running.


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

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

sudo openhabian-config


OpenHabian Configuration - Main Screen


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.


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?

You are ready to move to the next step of the tutorial, the creation of the MySensors Gateway.


This Post Has 6 Comments

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

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

Leave a Reply

Close Menu