MQTT Binding (v1.11) Getting Started 101

After countless threads regarding initial configuration issues, here is a short guide on how to get started with MQTT, the MQTT binding and openHAB.

This thread is a wiki article and can be improved by everyone. Please do!

MQTT is a machine-to-machine (M2M)/“Internet of Things” connectivity protocol.
It was designed as an extremely lightweight publish/subscribe messaging transport.

A few resources first:

  • Read all you ever need to know about MQTT in the MQTT Essentials

  • The openHAB MQTT Binding (v1.11) README

  • An MQTT broker is needed to proceed! For testing purposes you can use an open one but it’s better to install one locally. A good option is Eclipse Mosquitto on a normal Linux system. Mosquitto is part of the optional components of openHABian

  • A standalone MQTT client is needed for troubleshooting, e.g.

Please follow these links to learn more. You’ll need the knowledge to have fun in the later steps below.


The following steps will guide you through setting up a working connection between the openHAB MQTT Binding and openHAB to publish messages and subscribe to topics.

  1. Connect with the standalone MQTT client to your Broker (You didn’t skip the list above, did you?).

    This way you can check the error-free operation and verify your login credentials. Later you’ll be glad to have the client open to see what’s going through the Broker.
    Subscribe to a topic. If you are unsure to which, the global selector # will do.

  2. Install the MQTT Binding (binding-mqtt1) through Paper UI


  3. Configure the Binding settings. Because it is a openHAB 1.x Binding, we need to do that through a configuration file (A new openHAB 2 Binding is on its way!)
    You should see a configuration file mqtt.cfg among your service files ($OPENHAB_CONF/services/mqtt.cfg). In short the file has to contain the URL of your broker and login credentials (if available):

  4. Check the openHAB log to see if the binding was able to connect to the broker: You can do so via file or console or on an openHABian system via the openHAB Log Viewer (frontail) at: http://openhabianpi:9001

    The lines you are looking for are:

    2017-07-22 17:15:24.084 [INFO ] [] - MQTT Service initialization completed. 
    2017-07-22 17:15:24.089 [INFO ] [t.mqtt.internal.MqttBrokerConnection] - Starting MQTT broker connection 'broker'

    Head over to the Troubleshooting section if the connection was not successful!

  5. Now that we know, that the Binding is connected to the Broker, let’s do a quick test:

    Define a very simple testing item (e.g. in $OPENHAB_CONF/items/test.items):

    Switch MQTT_Test "Testing..." { mqtt="<[broker:testing/mqtt/topic:state:default], >[broker:testing/mqtt/back-topic:command:*:default]" }  
    // ^-- Item Type              ^-- Item linked Channel
    //         ^-- Item Name              ^-- Inbound MQTT configuration              ^-- Outbound MQTT configuration
    //                   ^-- Item Label
  6. Use the standalone MQTT client from before to publish an MQTT Message with the Content/Payload “ON” to Topic “testing/mqtt/topic”. Hit Publish.

  7. The openHAB log should confirm the working connection between Client --> Broker --> Binding and show the received message:

    2017-09-05 21:44:11.170 [ItemStateChangedEvent     ] - MQTT_Test changed from OFF to ON


You have followed the instructions above but openHAB wasn’t able to connect to the Broker? First check your connection details again. Make sure the given IP address is correct and the login credentials match.
In rare cases a bug in openHAB causes a wrong or old configuration to be stored in the internal storage of openHAB. If in doubt, please follow these intructions:

  1. Stop the openHAB service (e.g. sudo systemctl stop openhab2)
  2. Add the following line at the beginning of $OPENHAB_CONF/services/mqtt.cfg:
  3. Restart the openHAB service (e.g. systemctl start openhab2)


You are ready to define Items to communicate with all kinds of devices and applications via MQTT!

Next Ideas

Look at one of the many options:

Good luck and Happy Hacking.


Thank you for writing this up. Working with mqtt is one of my weakest and there have been so many beginner mqtt threads lately. This will be a tremendous help.

1 Like

:+1: :+1: :+1:

1 Like

@ThomDietrich this is great! Thank you!

I can’t edit the content of this post though. Only the title and category.
I wanted to add this:
MQTTLens (Chrome extension for troubleshooting) to the MQTT client section :wink:

1 Like

Do you happen to know more about this, e.g. the status of development, conceptual changes (ref. the Exec binding controversy, :-)), etc.

1 Like

I believe @ThomDietrich was referring to this pull request.

The development of

  • the core MQTT integration,
  • the MQTT broker configuration binding,
  • an embedded MQTT broker that is ready with a button press,
  • and a generic MQTT topic to OpenHAB Thing binding

is finished.

But a lot of smaller and bigger issues with the core (Eclipse Smarthome) appeared. For example:

  • a central provider for SSL configurations,
  • nested configuration parameters.

So it still might take some time to get everything merged.



That’s what I thought. So despite the hopefully soon available new binding, I decided to write this thread as a quick help here and now. @David_Graeff Please feel free to take as much as you can from the OP for the new Bindings README. A short introduction, some links and setting up of a testing Item might be useful to new users, even with the new binding.

Oh :sweat_smile: corrected. I’ve added MQTTLens. Thanks!

@rlkoshak @Dim from now on you just have to link it when a new user with old problems arises. Remember do to add details when possible. It would be great if we could have more threads like this… :wink:


Thanks for the info! Cool stuff!!!

Agreed. I can point to the Solving Exec Binding Problems thread as another one. I’m going to convert that to a wiki right now. Honestly, I’m pretty weak with Exec too. I only know as much as I do from helping others with their problems. I don’t use it myself. Others please contribute to this one too.

@David_Graeff, the new binding is very ambitious. I look forward to using it!

Even if it were available today, we would be fielding MQTT 1.x version questions for at least another year. People migrate painfully slowly. :frowning:

1 Like

All, I’ve added a section regarding the config bug where one needs to manually delete the file mqtt.config to get rid of old configuration.


Thanks Thom for this very simple and working example.

But I feel I have only half of the solution:
I can update OH2 switch status from MQTT, but OH2 does not send back the status changes to MQTT when I click on the switch.

Yes that is correct. The Item is only there to test the connection between openHAB and the broker. For more options you should check out the MQTT Binding README.

Anyhow. As it doesn’t hurt I’ve added an outbound connection to the example. (Btw. In order to do that I had to consult the README. No magic involved…)

Is it worth adding an example showing how the MQTT Action fits in? Or is that a little bit overkill. It is well documented and a one liner.

First of all, the Tutorial shouldn’t be a replacement for the need to read documentation. :wink:

The focus should stay on “How to get started with the Binding” and the Binding is able to publish data just fine. Imo the Action is something rather special and I’m not sure if we would even need it in a “101 Tutorial”…

But yeah whatever :smiley: Feel free to add it’s README to the references list in the beginning and mention the action before or after the Troubleshooting chapter.

Really great Thom,

This mini tutorial got me running in few minutes, while I spent hours to try already.
I think most of the oddity was because I did not realize we should use all config files since other examples uses PaperUI to define the entire solution.

Great job,

i didn’t understand 5th step. i am not able to find any file name " test.items ". please can you help me to create one. i installed everything on windows not respberry pi.

Create a file named test.items in c:\whereeveryouunzippedopenhab\conf\items and put the code in step 5 into that file.

1 Like

Not sure how this can be improved. “test” is clearly a placeholder name and if a file doesn’t exist you can simply create it. What do you suggest we should improve?


Thank you for this tutorial, works fine with the temperature und the luminance of my Fibaro Motion sensors connected to my PI with the Razberry module running with openHABian.

Still got some Problems to get the motion-detection to work:

22:20:08.061 [WARN ] [] - given new state is NULL, couldn't post update for '61_FibaroSensorAnwesenheit'

My mqtt.items are the same as for temperature and luminance:

Number 61_FibaroSensorAnwesenheit "Anwesenheit [%s]" <Motion> { mqtt="<[pi:zway/60Flur/bewegung:state:default]"}

I run in the same issue with my AeonLabs Door/Window Sensors.

Is there something wrong with my item definition?