Migrating MQTT1 items to MQTT2.4 items

Hi community,

After migrating from MQTT1 to MQTT2.4 Binding, i think it might help to have a short howto.
Please note that i’m not using credentials, so i can only tell something about the basic broker configuration

Step1: Migrating the data from mqtt.cfg:
mqtt.cfg (I’ve only connetced to the broker using credentials)


PaperUI (for MQTT 2.4)
Go to the inbox, add a new thing and select MQTT Thing Binding:

Next, you need to define a connection to your broker. Select MQTT broker and use the data that you also have used with the MQTT 1 binding

When you now save the thing, it should go to online (I’ve named my thing Mosquitto)

Ok now for the part that I was struggling a bit. The channel and items definition.

In MQTT1, i have had the following item definition for a sonoff device

Switch Sonoff4CH_Garden_Left_Relay1 "Relais 1" <poweroutlet> {mqtt=">[mosquitto:cmnd/Home/Garden/Sonoff/Left/power1:command:*:default], <[mosquitto:stat/Home/Garden/Sonoff/Left/POWER1:state:default]"}

Now, with MQTT 2.4, you need to do the following:

Step 1: Add a new thing in PaperUI and select a Generic MQTT Thing
Step 2: Give it a proper name (e.g. Sonoff4CH_Garden_Left) and select your previously defined broker
Step3: Go to the thing and add a new channel. For the Outlet in the example, a ON/OFF switch is sufficient:

A word for the channel ID and the Label: I tend to keep them the same which makes it easy to identify afterwards.

Step 3: Configure the MQTT topic for state and command and save this thing:

Step 4: You can now use the newly created channel within your item:

Switch Sonoff4CH_Garden_Left_Relay1 "Relais 1" <poweroutlet> {channel="mqtt:topic:08c64b74:Power1"}

And that’s it.
Sorry for the messed up layout here - i’m not really good at writing documentations

Migration MQTT to 2.4
First time setup of MQTT [solved]
Need help to migrate to the mqtt binding v2 in openhab 2.4
Sonoff Tasmota with MQTT Binding 2.4 (using config files)
First time setup of MQTT [solved]
Sonoff Tasmota with MQTT Binding 2.4 (using config files)
Configuring ESP Easy GPIO as MQTT items in Paper UI
Problems when creating an Item
MQTT evenbus.cfg
How to connect IP150 to OpenHAB?
OpenHAB 2.4 + Tasmota (MQTT + JSON) on RF Bridge and PIR Motion Sensor
How to show mqtt topic values?
MQTT bus events replacement for v2.4?
MQTT 1.x Binding vs 2.x
MQTT 1.x Binding vs 2.x
Openhab binding tasmota
Set up mqtt2 from scratch on linux
MQTT Binding 2.4 via Docker on Synology - Aqara Sensor & Osram Smart Plug
Error 500 and 503 after ver2.4 upgrade
[CLOSED] MQTT binding version 2.4 (Pre-release !)
Fresh OH 2.4 and MQTT binding
New user configuring v2.4.x with sonoff switches using Paper UI - Help appreciated
OpenHab, Shelly1, Mosquitto/REST - does not work
Openhabian does not work anymore and can not get it to work anymore
Using Sonoff Power Switches with Tasmota firmware and openHAB2 MQTT2 binding
MQTT not working 2
Broadlink with MQTT in Openhab
Setpoint Number Clarification
Feeling Frustated :-( MQTT setup
Migrate OpenHAB 2.5.12 to OpenHAB3 MQTT 1x Items Help
Problems migrating MQTT 1 to MQTT 2 Binding
OpenHAB3 MQTT Configuration with Text Files on Windows 10
OH3 how best to delete an add-on and all related things and items?
MQTT Binding: I don´t understand
Rademacher DuoFern via Fhem and MQTT
Tasmota version through MQTT?
Mqtt 2.x Vs Mqtt 1
POW Values Using PaperUI and No Things File
[SOLVED] After update openhab from 2.3 to 2.5 - Migration to MQTT 2.5

Thank you for taking the time to share your knowledge. I need to do some migration, so this will help immensely.

1 Like

Thanks for that, great start to helping me understand the changes.
I did read the blog on the changes but as it was filled with images it went over my head :frowning: and as it was quite long none of the family wanted to explain it to me.

One thing, I have around 150 MQTT devices and would therefore like to start from a do as little as possible to get OH and my MQTT devices working.
And slowly add my devices across in batches, can someone explain how we can simply configure 2.4 to connect to an existing mosquito install and no other change required? I can then add the changes to items and things in batches say 10 at a time.

Hoping this approach is possible


1 Like

That’s great thanks!
I was working on something like this but I work in the retail industry and at this time of year don’t have much time on my hands.

Small tip: In step 2 also add Give it a proper Thing Id too
For example:
Thing Name: Sonoff4CH_Garden_Left
Thing Id: Sonoff4CHGardenLeft

This way, the channels are human readable in the items file:

instead of

This is very useful because when reading the item file, I want to know what device my item is linked to.
Using human readable Thing Ids goes a long way to achieve that.


Yes. Enable legacy addons and install mqtt1 and you are good to go.

1 Like

Thank you very much, works exactly as you described :+1::+1:

Thanks David, I am looking forward to many of the new enhancement (including the new MQTT 2) after I have stabilised the base capabilities that my family enjoy.

For others reading this thread the missing piece for me was the need to go into PaperUI then Configuration > System goto ‘Add-On Management’ section and enable ‘Include Legacy 1.x Bindings’ option, don’t forget to say the change.
Then wander down to Add-Ons > Bindings tab and you should now see a MQTT Binding 1.x (1.13.0) version as well as the new MQTT Binding 2.4.0

Installing the old MQTT 1.x binding enables the old MQTT mode of operation prior to the upgrade to 2.4 in my case using an external mosquito server.

On to the next upgrade issue and I will hopefully get this upgrade stable so I can PLAY.



Thank you so much. I have been struggling with the migration and you helped me out big time with this post.

Note that some of the items had slightly different names on my system, but the instruction were still easy to follow.

i have followed your guide and cant not seem to make it work… I have a test sonoff basic item:

Switch mqtt6 "mqtt6"   {mqtt=">[broker:/ESP_Easy_6/gpio/12:command:ON:1],>[broker:/ESP_Easy_6/gpio/12:command:OFF:0],<[broker:/ESP_Easy_6/relay/state:state:MAP(onoff.map)]"}

i use a simple transformation 1=on and 0=off
that with old mosquito binding work like a charm.
Trying to migrate it to the new way but it doesnt work at all.This is my channel

What am i doing wrong?After i save i get “Status: OFFLINE - COMMUNICATION_ERROR java.lang.Exception: No MQTT client”

You did everything right. This is a know bug fixed in oh 2.5 snapshot.

1 Like

Hi all,

I have also moved to MQTT V2 (OH 2.4)
What I have problem with is for my Osram Lightify Lamp. I’m not able to create a transformation that send values from a Slider as MQTT command like this:
Value is from 0 to 100 as a numeric value.

General communication to this Items is not a issue, e.g. a Switch for turning On/OFF works well.

I tried several times to create a Numeric channel but I’m not able to set a JSON Transformation.
Where could I setup such a tranformation for outgoing values?!?
And how could I define that the MQTT JSON is send as described above?

Thanks a lot

You can’t. This is a feature coming with OH 2.5 after Christmas :slight_smile:

This is already possible. Have you read the documentation? You can use the output pattern. It is not a transformation as defined by OH, but can add suffix and prefix to a string. And that is what you need here. Along the line of {“brightness”:“%s"} should do it.


That’s it! Thanks!
Sometimes the easiest way seems not the right…or sometimes you can’t see the forest for the trees. :wink:

Many Thanks to your and the community for that awsome support and help!

1 Like

Hello all, I’ve been following all the tips and I’m struggling to migrate from MQTT1 to MQTT2. But I have some doubts:

  • do I need to delete the file MQTT.cfg after I finish all these procedures?
  • if I configure the MQTT Broker at Paper UI, it means that I don’t need to write a configuration file at Broker.things, is that right? And if I write the parameters at one file a Broker.things, so I don’t need even to install the MQTT Binding??

Thanks so far if you could help me on these questions


Deleting a cfg file will not delete the configuration. You need to remove the cache as well.

If you don’t install a binding, you can’t use the functionality. Or what do you mean with your second question?

I’m confused on your text. If I write the broker.thing file do I still need to install and configure the mqtt binding? Can I do both (write the file and configure binding)? Or maybe I’ll be setting up 2 Mqtt brokers if I configure the broker using file and the binding?

broker.thing file:

mqtt:broker:mySecureBroker [ host="", secure=true, certificatepin=true, publickeypin=true ]
mqtt:broker:myUnsecureBroker [ host="", secure=false ]

mqtt:broker:myAuthentificatedBroker [ host="",secure=true, username="user", password="password" ]

mqtt:broker:pinToPublicKey [ host="
1 Like

Please read documentation! Choose either mqtt1 or mqtt2, don’t mix them if you are already confused. In both cases you MUST install the corresponding binding. Of course. That’s logic. You can’t turn your computer on and expect it to work if there is no operating system installed. I really don’t understand your question I guess.

1 Like

Thank you for your answer @David_Graeff! My question is: after I install the binding, if I do the text configuration at .thing, it would be the same if I do the graphical configuration at Paper UI? If I do both, will I have a conflict??


You should either create a broker and the device things via PaperUI OR via file.


Hello and happy holidays!

After reading all that I could (and a lot of trial and error), I managed to migrate my v1 mqtt items to v2.4. However, I couldn’t find an option for not auto-updating the item’s state when sending a command (like autoupdate=“false” in the old configuration). Is that possible?
I’m using text configuration.

I was using it in scenarios where I wanted feedback from the module (switch, light, water-heater etc.) in order to know that the command worked (and maybe start a timer or update the icon).