MQTT 2.4 documentation

Thanks @crxporter for making the documentation consistent.
I don’t know how often the website rebuilds the documentation (could you help out, Yannick? @ysc).

Cheers, David

I can trigger a website build.
But addon repo merges should trigger that anyway within a short period. :slight_smile:

1 Like

You can check when the website was last deployed here: https://app.netlify.com/sites/openhab-website/deploys
(you need to login with GitHub, I think any account will do).

2 Likes

you need to login with GitHub

Nope, I can see when the last deploys were without being logged in…

1 Like

As I continue digging into this I am becoming more convinced that none of us really knows all of the many ways to configure MQTT…

We had a pull request just this morning as someone was trying a new combination of bridge/broker that unfortunately they did not specify. See here.

I suspect that menaceone had a combo between broker and thing config files that just didn’t work out.

Going through the forums, I see this post which appears to be the source of the heat pump example. There is a combo of bridge {} and separate bridge/thing files in this one.

I’m about to log in to my vpn to see if I can test the method of defining broker and Generic MQTT channels separately… stay tuned for more documentation updates if I figure anything out. Please comment if you have all of the answers (or if you’ve tested any of this)

1 Like

The following options all work:

Option 1 configure Broker as a bridge and items as things “under” that bridge.

Things file looks like:

Bridge mqtt:broker:WorkBroker "Work Broker" [ host="localhost", port="1883", secure=false, username="openhabian", password="ohmqtt", clientID="WORKOPENHAB24" ]
{
    Thing topic WorkSonoff "Work Sonoff" @ "Home" {
    Channels:
        Type switch : WorkLight "Work Light" [ stateTopic="stat/christmas3/POWER", commandTopic="cmnd/christmas3/POWER" ]
        Type switch : WorkLightTele "Work Tele" [ stateTopic="tele/christmas3/STATE", transformationPattern="JSONPATH:$.POWER" ]
    }
}

Option 2 configure Broker as a “thing” and generic other MQTT stuff as things.

Things file looks like:

Thing mqtt:broker:WorkBroker "Work Broker" [ host="localhost", port="1883", secure=false, username="openhabian", password="ohmqtt", clientID="WORKOPENHAB24" ]

Thing mqtt:topic:WorkBroker:WorkSonoff "Work Sonoff" (mqtt:broker:WorkBroker) @ "Home" {
    Channels:
        Type switch : WorkLight "Work Light" [ stateTopic="stat/christmas3/POWER", commandTopic="cmnd/christmas3/POWER" ]
        Type switch : WorkLightTele "Work Tele" [ stateTopic="tele/christmas3/STATE", transformationPattern="JSONPATH:$.POWER" ]
}

Option 3 same as option 2 - but broker is called “Bridge” instead of “Thing”

Things file looks like:

Bridge mqtt:broker:WorkBroker "Work Broker" [ host="localhost", port="1883", secure=false, username="openhabian", password="ohmqtt", clientID="WORKOPENHAB24" ]

Thing mqtt:topic:WorkBroker:WorkSonoff "Work Sonoff" (mqtt:broker:WorkBroker) @ "Home" {
    Channels:
        Type switch : WorkLight "Work Light" [ stateTopic="stat/christmas3/POWER", commandTopic="cmnd/christmas3/POWER" ]
        Type switch : WorkLightTele "Work Tele" [ stateTopic="tele/christmas3/STATE", transformationPattern="JSONPATH:$.POWER" ]
}

I’m beginning to see where the confusion comes from in the docs - everything depends on those { } after the bridge configuration. Surprisingly - the .items file that works with all of these is the same. It looks like:

Switch SW_WorkLight "Work Light Switch" { channel="mqtt:topic:WorkBroker:WorkSonoff:WorkLight", channel="mqtt:topic:WorkBroker:WorkSonoff:WorkLightTele" }

Interestingly - it doesn’t seem to matter between option 2 and 3 whether I type “bridge”, “thing”, or just nothing at all (start the line with mqtt:broker:...) - the broker connection is still working properly. The documentation for the MQTT 2.4 broker indeed shows it without bridge or thing, just starting mqtt:broker:...

I prefer Option 1 and plan to set up my system as such. I also see the benefit in the other approach (let’s call it non-bridged) if someone has many MQTT things in their house and would like to keep them separated into separate files but under the same broker. I think next I will put together a PR for the documentation showing these configuration options…

Does anyone have an example about what things look like with a functioning broker configured in paper ui with things and items files for defining their various channels?

Edit: new PR here.

3 Likes

I think option 2 would be considered non - standard. The broker serves the function of a bridge. A bridge is a thing that serves as a gateway through which related Things communicate.

Not really surprising as the Thing and Channel IDs are not changing in the three different approaches.

I think what you are seeing with the confusion is that none of this. things file stuff is really implemented by the binding of I understand correctly. There is a separate part of OH that parses the file and passes the Things to the binding.

what version are you using with? there is a known bug in 2.4 that requires a restart of OH after changes to the .things file which is fixed in 2.5 m1. Mahe sure you are not seeing this bug which could exclaim the behavior.

I going to make the picture a bit more complicated:
I saw that the required channel syntax might be differing. When creating the things via PaperUI the brokername is not needed in the channel definition ( as can be seen on PaperUI).My guess is that Options2 and 3 could use this other channel syntax since the broker to which the items are connected is set in the thing definition. But I can only guess that one ATM.

This is clearly an indication that the current .thing files are crap. Just saying.

But to be honest I’m that close to just remove all the textual examples from the mqtt binding. That’s more than half of the documentation now and with every PR that section is growing. (Alternatively I add pictured Paper UI explanations on top of that. But I wonder who is reading the resulting 30 pages doc then!)

Why does this poor bindings documentation need to take the fall for everybody who is not reading the official .thing-file syntax documentation. I know that the MQTT binding was the first (to be correct second) binding that has shown the nested bridge { thing { channels } } syntax. But that syntax existed forever.

2 Likes

I was expecting to see a difference here because of the confusion with how the channel structure shows up a bit differently in some places there’s been a question of whether it is mqtt:topic:<broker-name>… or mqtt:<broker-name>:topic... - I thought this might have explained that one.

I am using 2.4 stable as loaded on Monday of this week from fresh openhabian on a pi. That could explain the differences between option 2 and 3 I suppose. Really there seem to be 2 options - one with a separate bridge thing and one with the MQTT things and channels defined as a set { } of broker things.

Can you provide some clear screenshots on this? Maybe I’ll delete my .things files after work today to try it out.

I think your second part of this hits the nail on the head. the MQTT binding is one of the first. It’s also the most popular binding of openhab if I understand correctly. It seems everyone around here has their chosen hardware (knx, zwave, zigbee, insteon…) plus a few MQTT things.

The other big issue I realized is that with other bindings - the thing definition is basically “this is where to find my thing” and channels are all put together by default. The official document on .things files has 3 examples: network, astro, and ntp. Each of these just need to have an IP address or location and magically there is a set of channels to use in your items.

MQTT on the other hand is a whole new beast. We have tasmota, espeasy, espurna, the home assistant standard, the homie standard, and then anyone who just felt like adding the pubsubclient.h to their arduino sketch. In my case I have several tasmota and a few of my own creations. Eventually I’m hoping to write new firmware for all of them to use homie with discovery but step 0 in that was to understand how the MQTT binding works and that’s proving to be quite the project. The thing with MQTT is that the channels aren’t automatic or default. They are highly customizable. We each have our own list of very different channels that we think should go with our things.

I like it. But I also like the .things files. I don’t want to go through and enter each of my items into a web form (paper ui) because I make tons of typos as I go and I end up with 4 sonoff switches that are each configured differently instead of a nice little text file where I can copy-paste a line and rename it to work again… You have heard the arguments, this is nothing new. I do hope your next-gen paper ui catches on and becomes the thing of the future. I’m not excited to redo my whole setup again at that point. Oh wait - yes I am. This is my favorite hobby after all.

Do it. Let people read the forums if they want to struggle through things file setup. I have no objection. I was on a campaign to get the documentation fixed up because that’s always been my starting point to configure a binding. If the binding said “here’s how to do everything in paper ui” with some examples… I would probably just configure it in paper ui!

1 Like

Amen to that!! Well said

PS: Looking at the official things documentation there is no mention of the bridge{ thing{ channels }} syntax. Only the “typical” way to do it and then a link to go look at each of the individual bindings.

When creating a thing via file (Option 1)

And when creating it via PaperUI (also connecting to the broker “opusMQTT”):

Note that in the second example the brokername is not part of the channel-syntax.

Awesome.

Though this does not support what I’m coming to believe is incorrect syntax for channels that I’ve seen around. This is still mqtt:topic:... where the incorrect version goes mqtt:<broker-name>:topic...

Thanks for the screenshots! I’m headed out to work but I’ll probably fiddle with the paper UI tonight. Nothing else interesting to do in a hotel room…

Ok I can understand the fear of using Paper UI when reading this: https://www.openhab.org/docs/configuration/things.html#defining-things-using-files

  • “internal database”
  • “Please check each individual binding’s documentation for details”
  • “Benefits of defining Things, Items and other aspects of openHAB in configuration text files”

This text is highly biased and sounds like Paper UI defined Things could magically disappear at any time (internal “database” OMG!).

Could someone please fix that article. Maybe we just migrate all the MQTT examples over there (minus the mqtt1->mqtt2 migration section of course) and just add a link in the MQTT binding doc to that article.

I would do it myself, but then the article would contain sentences like “Please refrain from using .thing files whenever you can. The syntax is highly unusual and cannot be found anywhere outside of OH” and such.

Cheers, David

I would remoce the whole thing and leave:

Defining Things Using Files

Things can also be defined manually by creating .things configuration text files. These files are stored in $OPENHAB_CONF/things .

Please see the individual binding documentation for the text files configurations

But that sounds like the binding developer is responsible for the crappy .thing file syntax. And the binding developer is only the victim in this game.

1 Like

What about the existing documentation of eclipse smarthome? Is this going to be in cooperated into the openhab documentation? At least the part we are talking about in here has more detail on the Eclipse site! See Here
IMHO putting the examples for things AND bridges into the openhab docs would solve most of the problems.

Thank you for this link! This is great information that I had no idea where to find. This actually helps explain one of my original questions with the structure of the keywords and such. I don’t understand the relationship between OH and ESH - I just use OH so that’s where I read things.

And just like that we are back on the dispute between Paper UI and textual config. All I wanted to do was fix the incorrect examples and learn how the MQTT config works… this all gets complicated so quickly. Nothing new, just observing.

I’m going to file a change on the openHAB documentation, in order to show the examples for Things and Bridges (like in the eclipse documentation) now!

Edit: Done!

…and this time Github didn’t complain! :rofl:

2 Likes