MQTT Binding (v1.11) Getting Started 101

Tags: #<Tag:0x00007f6165c105e8>

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.

MQTT config under OH2
OH2 mqtt commands
MQTT not talking to OH2
[SOLVED] MQTT not starting
Using nodemcu with Openhab
[SOLVED] Mqtt Temp and humidity setup
Integrate Xiaomi things without gateway
[SOLVED] Can't get mqtt binding to work
Receiving from MQTT
[Solved] Items not working with MQTT
MQTT - Configuration
Item with inbound MQTT binding corrupts file
Zwave sensor value to Zabbix via MQTT
Switching on and off a relay as a beginner with mqtt
How to connect generic PIRs to OpenHAB?
Mqtt bindings not showing up
Mqtt bindings not showing up
Need help to setup MQTT Binding on OH2
[SOLVED] Mosquitto stopped working after upgrade to v 1.5
Need help to setup MQTT Binding on OH2
Two pi’s - one OpenHAB the other home assistant?
General question regarding TCP/UDP Binding/Setup Server and Item config
Installed MQTT binding not displaying in Paper UI nor is binding working
Cannot start MQTT Broker
How to install 3rd Party Addons - Broadlink RM Pro
Desparate for a simple GPIO tutorial "hello world"?
[SOLVED] MQTT for SONOFF/TASMOTA this is difficult
Starting out... OH2, Z-wave lights/dimmers working, nothing else Z-wave is (multisensor, etc)
MQTT Issue- new to openhab
Having Trouble configuring Items
How to connect device to openhab2
openHAB - Raspberry Pi 3 - MQTT binding issue
MQTT Binding Config - Where did I do that?
Ignition SCADA + openHAB integration
Openhab as a broker
How to convert MQTT into command?
SOLVED: Sonoff 10A, MQTT and openHAB
Xiaomi Mi Flora Plant Sensor MQTT Client/Daemon
How to show mqtt state on sitemap
[Solved] Items not working with MQTT
Linking openhab to home alarm system
Where to post sitemap created in home builder
[RESOLVED] OH2.0 MQTT - Errors in log
How do i connect MQTT.fx to Openhab2 as both installed on pc
How to connect Openhab and Raspberry Pi through MQTT?
Using mqtt from ESP to Openhab2
How to on off realy in ardiuno via openhab 2 useing mqtt
Send a mqtt command
Openhabian 2.2 Initial Setup Configuration file
New in OpenHAB - Tasmota and RFLINK
[SOLVED] Arduino >> openhab. howto handle received payload string to toggle switch state
[SOLVED] Arduino >> openhab. howto handle received payload string to toggle switch state
Looking for the ultimate beginners guide
Sync Software switch State with Physical Switch
How to create OH2 Item to send mqtt command to Sonoff 433 RF Bridge
Collecting data from a buch of devices using UDP
ITEAD Sonoff switches and sockets - cheap ESP8266 Wifi+MQTT hardware
New Install - OH2 will not turn my light on
Noob: Simple button which makes mqtt call
[SOLVED] MQTT configuration error
Help Using Rest Api or MQTT with Eventghost/Python
MQTT disconnects
At wits end with MQTT configuration
[SOLVED] Mqtt recieves data but it does not show
How to save message from mqtt to String in openhab
Missing EOF at 'Group' - OH2 upgraded to new version, now default.items not loading
ITEAD Sonoff switches and sockets - cheap ESP8266 Wifi+MQTT hardware
Setting up openHAB2 from scratch
SOLVED: Sonoff 10A, MQTT and openHAB
ITEAD Sonoff switches and sockets - cheap ESP8266 Wifi+MQTT hardware
[SOLVED] Cannot install MQTT binding on Raspberry Pi
MQTT evenbus.cfg
New user, MQTT woes
Testing OpenHAB with Domoticz via MQTT
New user configuring v2.4.x with sonoff switches using Paper UI - Help appreciated
Sonoff tasmota link to openhab on windows 10 pc
OpenHAB2 will not talk to working MQTT broker - Error no connection
[Solved] MQTT - OpenHab2 communication issue
[SOLVED] MQTT binding exits with error: MqttException
Rollershutter MQTT
[SOLVED] Broadlink Mqtt binding config
[SOLVED] Broadlink Mqtt binding config
Windows PC remote control (Shutdown, …)
OPENHABIAN doesn´t show MQTT Temp
Testing OpenHAB with Domoticz via MQTT
Openhab2 2.1 MQTT Service initialization completed but not starting?
[SOLVED] Mqtt binding (1.13 SNAPSHOT) is not subscribing
Sonoff POW - How to read Voltage, Current, Power,
How to integrate GeoFency or Locative app?
Vaules from python script in OH2 import
[SOLVED] Mqtt state espurna
Help with MQTT and Arduino
[SOLVED] MQTT not working after changing the broker ip
Howto use zigbee2mqtt with openHAB, removing proprietary bridges / gateways
[SOLVED] Mqtt client setup on openhabian
[SOLVED] Can't get my MQTT Binding to work (still connected but it does nothing)
Binding version confusion (e.g. MQTT - is it 1.12? 1.9? 2.3?)
Where to find syntax for createTimer command
Sensors? I'd like to buy the < $5 ones, not the > $30 ones

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?