OH2 MQTT standalone server with text file config

Setting up MQTT on Openhab2 via text files and a standalone mqtt server can be quite a struggle. There are plenty of topics around but with some syntax changes most of them are somehow wrong or not exactly what I wanted to archive.

Therefore I read, tried, read again and tried my way through those to find ultimately a working setup.
Below some examples and hopefully this will help someone to cut down the searching time and implementation of MQTT to your openhab.
Comments are appreciate to show your gratitude or point out mistakes/additions. If I like them I may add them later via edit :slight_smile:

1) Setup

  • Openhabian on RPI4
  • MQTT on same RPI but as standalone server (mosquitto)
  • Openhab Version 2.5.11-1

2) broker file
At first we need to let Openhab know which broker(s) we want to communicate with. A Broker is basically your mqtt server which could be in the local network or online.
let’s call this file: mqtt_broker.things within your things folder:

Bridge mqtt:broker:mosquitto "Mosquitto" @ "Systems" [

Above assumes your mosquito server to be found under without any security (only for local use, if exposed it’s highly recommended to increase the security level).

3) Things file(s)
For your devices another file in the things folder is needed, let’s call it mqtt.things
You can define as many files as you want the naming is entirely up to you.
For example you can define one file to hold all your tasmota devices under tasmota.things while all zigbee2mqtt devices are in z2m.things.

Some examples:
receive simple text from topic

Thing topic button_living {
Type string : battery  [ stateTopic="zigbee2mqtt/office/living_button"]

Above will receive the message under zigbee2mqtt/office/living_button and store it under your openhab item.
While this is great stuff it’s often not sufficient. Many sensors actually sends a json message with several information at the same time.
So let split the one topic into several channels:

split up json message into channels
Thing topic button_living {
Type string : battery [ stateTopic=“zigbee2mqtt/office/living_button”, transformationPattern=“JSONPATH:$.battery” ]
Type string : linkquality [ stateTopic=“zigbee2mqtt/office/living_button”, transformationPattern=“JSONPATH:$.linkquality” ]
Instead of having a JSON message in openhab we have now split it to 2 channel, one for the battery and one for linquality. Further channels can be added as your sensor message.
This looks better already, but once we see it at Paper UI it looks quite ugly. The sensor appears under no room and we don’t know which value is what.
So let’s give this things some formatting to make it look better in Paper UI.

split up json message into channels with human readable naming
Thing topic button_living “Button Livingroom” @ “Livingroom” {
Type string : battery “Battery” [ stateTopic=“zigbee2mqtt/office/living_button”, transformationPattern=“JSONPATH:$.battery” ]
Type string : linkquality “Link quality” [ stateTopic=“zigbee2mqtt/office/living_button”, transformationPattern=“JSONPATH:$.linkquality” ]

Above will now show our sensor properly in the Paper UI. However we can’t do anything with it. What if we want to update a mqtt topic via Openhab?
In this case we need to tell OH where to send the text to. It may be the same topic or another one. This is different for MQTT devices and you need to check for each device how they like to have it.
send values from OH to MQTT topic

PLACEHOLDER :slight_smile:

4) items/*.items file
Additionally to the things file you still need an .items file in your items folder. The naming of the file is again to your liking. Most people follow the things filenaming but it’s not mandatory to do so (but probably easier to understand if you want to go back to it in a couple of months)

PLACEHOLDER :slight_smile:

5) some traps to avoid

  • the type of item must be identical between .things and .items file
  • in items file give your channels a name. Otherwise it’s confusing in paper UI as it just calls them “value” on all channels
  • occassionally updates to the file are not effective. A service openhab2 restart may help after changing the files and something not working as expected.

Remark: this is work in progress and will be edited once times permits :stuck_out_tongue:

And if above is still not working I’d would recommend following to study further:

Openhab MQTT binding documentation

getting Tasmota flashed Sonoff Basic connected to OH2


I tend to link the following page, which is official documentation, but unfortunately not where most people would look:

Note that there are two main ways of setting up a broker (Broker Thing) and (device) Things via files:

  1. Your device Things are nested within the Broker Thing. This has a specific syntax.
  2. The Broker Thing is separate (can even be in a separate file), and the device Things reference the Broker Thing. This has a different specific syntax.

Both options have examples in the link above.

If your server itself is appropriately secured then not using a password is not an issue.

I made a generic-ish MQTT tutorial based on a Tasmota flashed Sonoff Basic - see if anything from there would fit for examples in your post.


openHAB 3

openHAB 2

Ultimately it depends on what info you search for or tutorial you follow.

Vscode is your friend

1 Like

This is for Things files. For some, restarting openHAB is a huge pain in the backside. Perhaps try the following first:

  1. Deliberately corrupt your Things file, by making a deliberate syntactical error: remove a { somewhere.
  2. Save the corrupted Things file. If you’re watching the logs you will see openHAB complain and unload all the Things defined in that file.
  3. Un-corrupt the Things file by fixing the syntax: put the { back.
  4. Save the fixed Things file. If you’re watching the logs you’ll see all the Things loading back!

Thank you so much! It took me a while to figure out the OH2 mqtt textual config as the examples I found were quite confusing. I’m sure your post will help many!
And even though I got it already up and running, I learned some new things, too! :slight_smile:

Incredible, but this procedure is still needed, even with openHAB 4…

Are maintainers aware of this?