[MQTT Generic] update documentation #4766
Conversation
Add example and clarify the differences when using a bridged setup for the MQTT broker or a non-bridge setup (broker as a stand alone Thing). I also fixed a missing " in the MQTT 1.x heat pump example... Signed-off-by: Garrett Porter [email protected]
|
This pull request has been mentioned on openHAB Community. There might be relevant details there: https://community.openhab.org/t/mqtt-2-4-documentation/65916/15 |
|
Since the reaction to revert my pull request from yesterday was so quick - I figured I may as well learn a bit more and figure out the other configuration options. I was right in my guess that the differences show up between bridge/non-bridge broker connections in the things files. |
| @@ -258,16 +260,30 @@ Bridge mqtt:broker:myUnsecureBroker [ host="192.168.0.42", secure=false ] | |||
| } | |||
| ``` | |||
|
|
|||
| demo.items: | |||
| demo.Things (using non-bridge setup): | |||
There was a problem hiding this comment.
But the wording is strange. It is not a "non-bridge" setup. The bridge is just separately declared. This is true for all OH 2 bindings. I really don't understand why we need this to the detail in the MQTT documentation. Do people not read the official documentation?
There was a problem hiding this comment.
I like to keep parts of this PR. But could you please remove what is written in parentheses.
|
I wrote all of this before my comment I just added to the forums page. Leaving it here in case we continue having the .things and .items examples.
I agree, I was struggling with that wording but I didn’t think of a better way to describe it. One configuration is to have the broker as a bridge (declared as “bridge” in the things file). In this setup the Generic MQTT things are listed inside of { } as a set of things that use this bridge. The other option is to declare the broker as a thing then declare each MQTT thing as a thing - but not as a set. Obviously the openhab things file needs more information in this case so it knows which broker to use with those things - since it’s not a { } set of bridged items.
Is this not the official documentation? I’ve read through most of the docs about the openhab setup but when I want to set up a new binding I had straight for the instructions for that binding. I think it’s important to have clear examples in that case, as shown by how quickly the last changes I made were questioned (took less than 12 hours!) It took me a couple of hours yesterday to go through the forums to find the examples and differences between separate things and {curly bracket} version. To me it would be nice to have that information here with the MQTT examples. What should we call the different options? How are they referred to elsewhere? |
|
Related issue: openhab/website#152 The suggestion there is to generate parts of the binding-docs automatically. |
|
I would vote against the textual bridge thing part within a binding documentation. Yes, there was a problem, since textual bridge things were not covered yet, but openhab/openhab-docs#888 will close this gap. Also we will find a conclusion for referencing tha bsaic articles within the addons section through openhab/website#152 sooner or further. |
Then, we should at least have a link to that section. So we can save the reader a bit of hunting. |
|
That's why we are discussing a long term solution for this problem in openhab/website#152. Writing down the same link in each and every binding readme.md (which we would have to do to be consequent), is not really efficient. |
|
For my case - I think I've learned what I came to learn. I'm not set on this PR, I was trying to help out by providing another example of a different way to configure the binding - but I think people will be better off using the bridged setup on the MQTT binding. That's my plan (unless I ultimately go with paper ui). I'll leave this and keep watching. I'm happy to modify the examples and understand if we just close this one and focus on other stuff. Thanks, all! |
| @@ -242,7 +242,9 @@ Have a look at the following textual examples. | |||
|
|
|||
| ### A broker Thing with a Generic MQTT Thing and a few channels | |||
|
|
|||
| demo.Things: | |||
| Note: the [broker connection](https://www.openhab.org/addons/bindings/mqtt/) may be set up as a Bridge or as a stand-alone Thing. | |||
There was a problem hiding this comment.
I like to keep parts of this PR. But could you remove this sentence. It might just confuse.
David - take a look. I'm happy to keep adjusting until we like it. I'm trying to group them a little so users can see that it's 2 different examples... Signed-off-by: Garrett Porter [email protected]
|
Thanks |
Add example and clarify the differences when using a bridged setup for the MQTT broker or a non-bridge setup (broker as a stand alone Thing). I also fixed a missing " in the MQTT 1.x heat pump example... Signed-off-by: Garrett Porter <[email protected]> Signed-off-by: Pshatsillo <[email protected]>
Add example and clarify the differences when using a bridged setup for the MQTT broker or a non-bridge setup (broker as a stand alone Thing). I also fixed a missing " in the MQTT 1.x heat pump example... Signed-off-by: Garrett Porter <[email protected]> Signed-off-by: Maximilian Hess <[email protected]>
Add example and clarify the differences when using a bridged setup for the MQTT broker or a non-bridge setup (broker as a stand alone Thing). I also fixed a missing " in the MQTT 1.x heat pump example...
Signed-off-by: Garrett Porter [email protected]