[OH3] MQTT Setup and Configuration


In order to use MQTT devices, the following is required:

  1. An MQTT broker installed
  2. MQTT Binding installed in openHAB
  3. MQTT Bridge Thing configured in openHAB

This tutorial was written with openHAB3 running on a headless Raspberry Pi 3B with Raspberry Pi OS, with SSH access.


1. Install the MQTT broker

Install Mosquitto

On the Raspberry Pi, perform the following commands to install Mosquitto, and ensure it runs when re-starting the Pi:

sudo apt install mosquitto
sudo systemctl start mosquitto
sudo systemctl daemon-reload
sudo systemctl enable mosquitto


1a. Configure newer versions of Mosquitto

Default behaviour has changed in Mosquitto v2 and up - without editing the configuration file Mosquitto will only listen on the local host, and not allow anonymous connections.

In order to allow anonymous connections and allow any device within your network to communicate with Mosquitto, modify the mosquitto.conf configuration file as follows:

sudo nano /etc/mosquitto/mosquitto.conf

and add the following two lines to the end of the file:

listener 1883
allow_anonymous true

Save (Ctrl+x, then hit y and enter) and re-start Mosquitto.

sudo systemctl restart mosquitto

2. Install the MQTT binding in openHAB3

Settings → Bindings → Blue + → MQTT → Install


3. Connect openHAB3 to the MQTT broker

OpenHAB3 is connected to the MQTT broker through a Bridge Thing. To create a Bridge Thing:

  • Settings → Things → Blue + → MQTT Binding → MQTT Broker


Configure the Bridge to suit.

  • Unique ID: You can leave this default, or provide a more convenient ID. Once created, the ID cannot be changed.
  • Label: Friendly name for your MQTT Bridge Thing
  • Broker Hostname/IP: Enter the IP address of the device hosting the Mosquitto MQTT broker.

If you didn’t change any Mosquitto settings after install, you can leave the rest of the options as default.

Click Create Thing. Your Bridge Thing will be created and appear in your list of Things. After a couple of seconds, it will appear as ONLINE.


You can view the YAML code for you Bridge Thing by opening the Code tab within your Bridge Thing.


The code for this example is below:

UID: mqtt:broker:MosquittoMqttBroker
label: Mosquitto MQTT Broker
thingTypeUID: mqtt:broker
  lwtQos: 0
  publickeypin: true
  keepAlive: 60
  clientid: 98397d65-4f22-41f9-b259-40e6ddde640f
  qos: 0
  reconnectTime: 60000
  secure: false
  certificatepin: true
  lwtRetain: true
  enableDiscovery: true
location: Loft


You now have a working MQTT broker, and openHAB is connected to the MQTT broker via the Bridge Thing. You can now start to add individual devices as a Generic MQTT Thing. If you have a Tasmota device, this tutorial may be useful.


Saw there is option to create LWT message for the thing
With the bridge/thing itself, is there an option to send birth messages? I.e., when the bridge connects for the first time to MQTT broker, can it send a birth message which can be used by broker to send updated messages about the devices. I think homeassistant does this.

According to the docs it looks like this is possible.

An MQTT last will and testament can be configured:

lwtMessage: An optional last will and testament message. Defaults to empty.
lwtTopic: The last will topic. Defaults to empty and therefore disables the last will.
lwtQos: The optional qos of the last will. Defaults to 0.
lwtRetain: Retain last will message. Defaults to false.

I was actually referring to birth message, i.e, sending the first message rather than last message which the broker will send when the bridge/thing dies.
I don’t think it’s possible…but let’s see if any more knowledgeable can confirm

Yes, indeed you were - I didn’t read properly! I guess you could use the MQTT action within a rule which triggers when the system is started (which should normally be after the MQTT Bridge has initialised).

Thank you for the Tutorial, that helped!


Thank you for this tutorial, very clear and complete.
My question is quite “philosophic”, I have been using OH2 for many years, with only one problem concerning Zoneminder binding. Now I installed OH3 on a different processor, and Zoneminder seems to work, so I wanted to migrate all my system, but I realized that more or less I must completely redo it.
Sincerely I do not like the new OH3 visual programming setting (I am a very old software developer :smile: ), but in particular the new MQTT seems more complex with the need of a much more work: with OH2, one item and rule framework and “copy/paste” allowed to develop the connections of almost 50 devices, while with OH3 it seems I must do one by one a lot of channels, items and things. Please let me know if there is a fast way to connect many similar devices. Thanks

Yeah: stick with your Items, Things and other configuration files :smile:

Despite writing this tutorial, and a few others, using the UI, I found tinkering too slow with all the clicking around and page refreshing that was required. And once I’d worked out how to configure the Semantic Model and Metadata in the configuration files (to adjust and configure default UI widgets) I haven’t looked back…

You shouldn’t have to redo anything unless:

  • You were using v1 bindings
  • Your rules used specific date/time functions

I am happy I’m not alone in not appreciating the visual paradigm :slight_smile:.
Unfortunately I used the MQTT 1.x. However perhaps it is possible tu use YAML (copy/paste?) in order to speed up the development, isn’t it? In case can you provide any example? tx

Ah, that changes things. I usually provide this link for those who need to convert from v1 to v2. v3 syntax is identical to v2.

Yes, you can use the YAML to work out what your Things file should look like, but you first need to understand the Things file syntax to have any chance of getting it right - the syntax is different! So check out the link above first, then try configuring one of your Things with a Channel in the UI, and post the YAML here for help.

1 Like

Ok thanks, I’ll try

PS I just gave an eye to the link, seems great! You are very clever at least for what I can judge in explaining technical matters

Credit for the Github page contents doesn’t go to me at all: that content is from the maintainers! I like the link because I learn best via working examples, not paragraphs of explanatory text!

ok anyway the tutorials are very good

First thing is you need to get around in your head is the structural change.

The problem is in openHAB you can do it however you want as long as it works.

For me in OH2 was mostly config files however in OH3 I have changed to UI because its just as easy.

So first you need a MQTT broker bridge to get MQTT working.

Then you create generic things, Make sure you change the label to some sort of good Identifier like Bedroom Lamp and change the identifier if you wish.

Next click on bridge and select the one you created.

Goto the channel tab and add channel

Create any channel you like maybe a switch for the Bedroom Lamp

Once you have finished goto the code tab.

It will show something like

UID: mqtt:topic:1fc045960e
label: Bedroom Lamp
thingTypeUID: mqtt:topic
configuration: {}
bridgeUID: mqtt:broker:myMQTTBroker
  - id: Power
    channelTypeUID: mqtt:switch
    label: Light
    description: ""
      commandTopic: light/command
      stateTopic: light/state

Now you can copy paste new channels in. You can’t change the channelTypeUID once it has been created.

Once you have all your channels in your thing you got to the Model page. It is well worth the effort to configure you model so create a Location bedroom

Then while the location is selected Create Equipment from Thing.

Select all and create.

This will generate all the items for your thing from the channels you setup. You can also use expert mode to have a oh2 config file familiar setup.

1 Like

Thanks for the explanation. If you like, just a further one, which is the meaning of the channel at the broker level and at the generic mqtt thing level (in the tutorial, are used both, but it is not completely clear to me for which logical purpose)?

Which tutorial? MQTT Broker/Bridge Things do not have Channels.

Sorry, I, tried to use both, not in the tutorial.
I mean this broker channel

OK, so I wasn’t quite right - Bridge/Broker Things can have a Channel, but you likely don’t need it.

For each physical device that you have, setup a Generic MQTT Thing. Within that Thing, create Channels for each property that your device exposes: a switch, a temperature, a humidity etc.