The Need for Tutorials : I Thought I Was The Only One

Continuing the discussion from Is OpenHab Dying?:

As a user of openHAB for a number of years I find it to be a solid platform for my limited use of controlling lights via the Insteon binding and HUE Emulation and integrating with Alexa for voice control.

I know that people have put a great deal of effort into building the platform and am thankful for that but I too find that there is a deficit when it comes to simple, complete and easy to follow examples / instructions on how to accomplish things with openHAB.

I can’t help but think that the disconnect between having such a robust and solid platform and easy to follow instructions is negatively impacting the adoption rate of openHAB.

For me openHAB documentation is closer to unix man pages then instructional guides, maybe this is reflective of the great minds that developed openHAB.

Case and point I have been attempting to implement MQTT over the past couple of weeks so that I can control openHAB controlled devices via the Home Assistant UI. I have kludged something together and it is working but I highly doubt that it is working the way it should or was intended to.

Removing HA from the equation for the moment I find it frustrating that there is no clear concise guide aka tutorial on how to setup and Insteon Switch or any other switch to work with MQTT. ( ie Step 1. Step 2. Step 3. ). DigitalOcean is a great example on how tutorials could be developed for openHAB.

The ability to create such tutorials are in the hands of those who have a strong grasp of openHAB unfortunately I am not one of those people.

I think this is one of the more important disconnects here. Tutorials on this forum and anything that gets added to the documentation can be added by anyone. This actually doesn’t work as well when it’s a one-sided affair. It has to be a collaboration between the power users and the people who know what tutorials are needed or what the gaps in the current tutorials are.

Sounds like you’ve got the backbone for a tutorial already for something that’s important to you, but you don’t know if it’s ready for public use. That’s where the collaboration comes in. Put it up here in the tutorials section. Gather comments on it. Point out those parts that you think might be weak or unclear and “those who have a strong grasp of openHAB” will almost certainly contribute their two cents and help you improve it until it is at a point where you think it’s a strong tutorial.

There just aren’t enough “those who have a strong grasp of openHAB” to do all the tutorial every user of OH has ever asked for. Period. End of story. But there are enough users of OH regardless of their level to do it if they work together.

That’s the thing I don’t when it comes to MQTT. I am clueless when it comes to command and state topic and how to get that information from the DEVICE to MQTT. If I knew that I could construct the tutorial but then again that would likely mean that there was already a SIMPLE to understand tutorial on MQTT.

That’s ok. Happens to me too…all the time. I never let what I don’t know get in the way of what I want to do, and it sounds like you’ve done the same.

This is exactly what I’m talking about. You:

That’s enough of a starting point. Turn that into a tutorial with a big disclaimer at the top that says “THIS IS A WORK IN PROGRESS, USE AT YOUR OWN RISK”. Then the MQTT power users (NOT me btw), will help you with those parts that you’ve kludged. You will learn more about MQTT and the community will eventually get a tutorial that doesn’t need the disclaimer any more.

In addition to what @JustinG said, just realize that to do this as asked would require N! separate tutorials where N is going to be much greater than 350 (350! BTW is 123587405826548875014395199766546457224532073946919515879429330230093035357491314216934583295011178445941552109432761532449767761892237043444942213964090091669490545661255111334533069825455607852789836451585122902099649977304226794874840601811017764137584868137504975397325925882541777117706619490238363409254589994079334626893194608016888986949684994333459029365214555784862353939102567266745712846824819004146064184543888123533464975621179287075018586481357643313075153359002713294611632614208134036650116689052585573350955360246170451786972351365370405722036294385680478287278827977511411909071460914807681131728232182991517416470483157998067487290163200000000000000000000000000000000000000000000000000000000000000000000000000000000000000). Why greater than 350? Because that’s just how many bindings there are. Each binding may require more than one tutorial and of course that doesn’t include Profiles, Transformations, and Rules.

I don’t think there is enough time between now and the heat death of the universe to write that many tutorials.

~That’s~ why the docs and many tutorials read like Unix man pages. We can’t write a cradle-to-grave tutorial for every combination of everything that everyone would want to use. But we can write a tutorial on “how to use the MQTT binding to do X”. Several in fact

When someone gets something working that was tricky to figure out, we encourage the posting of a tutorial in the tutorials and solutions category. It’s a great resource and the posters get the benefit of a review and revision (as @JustinG points out) and the community benefits as well.

MQTT is hard, especially if you don’t have a good understanding of the underlying technology (see Introducing the MQTT Protocol – MQTT Essentials: Part 1) and especially if you don’t understand your data flows. Based on that other thread, that was the source of your issues and no tutorial would help you with that. If you don’t understand the pub/sub topics you can’t ever get to a configuration that works, or if you stumble upon one you won’t understand it (which is what I suspect is the case here).

In short, the underlying technology may be such that a simple to understand tutorial isn’t feasible. I mean, we’ve given it about a dozen tries based on the list above and still haven’t managed to achieve a simple to understand tutorial involving MQTT.

Here’s the good news though. Once you are working in Items, it doesn’t matter that they are linked to MQTT. An Item is an Item whether it’s linked to MQTT, Zwave, HTTP, or any of the other 350 technologies and APIs OH supports.

So no, you won’t necessarily find a step by step showing how to link an Insteon Switch to an MQTT Switch (you could but you shouldn’t expect it), but you will find lots of docs and tutorials working with Items and how to define behaviors on Items. Causing something to happen on an Item (e.g. commanding) when an event occurs (e.g. a Switch changes state or is commanded) is a behavior. That’s what Rules and Profiles are for.


This topic was automatically closed 41 days after the last reply. New replies are no longer allowed.