I’m an OpenHAB3 newbie and have been climbing its learning curve. With that in mind, I wanted to share a few suggestions for the Introduction documentation to make it easier for other new users.
Currently, the “A Quick Overview” provides a high-level relatively abstract definition for the key concepts. Please consider adding a concrete example (e.g., an MQTT-based smart plug with power sensor) to solidify the concepts. Also, I suggest replacing the Sitemap concept with Pages and adding an entry for Points. A picture to visualize how the various concepts relate to each other would be helpful.
I understand and appreciate that OpenHAB is a volunteer effort and would be happy to contribute to the documentation.
The quick overview is not intended to be complete nor is it intended to be comprehensive. All it is supposed to do is define some terms. The next stop is the Getting Started Tutorial and that’s where there are at least three concrete examples explained in detail for each of the OH concepts along with explanations on how they all work together. There is also the Concepts section which the Getting Started Tutorial lists as a prerequisite which goes into more depth on Things, Items, etc as a concept to further elaborate on the concept.
You’ll notice that the MQTT example in the Getting Started Docs is almost as long as the Quick Overview itself. If we add that kind of detail to the Quick Overview, it won’t be quick any more.
But if you’ve more detail about what you are suggesting we are open to discuss it.
Are you talking about the links in the table of the Quick Overview page? I agree, that bottom row should be replaced with a link to User Interface Design Overview | openHAB which is the introduction to MainUI (notice there are eight sections in the docs that discuss MainUI Pages).
Points don’t stand on their own. They are one of the concepts built into the semantic model. It makes no sense to go straight to Points on the Quick Overview page.
However, it does make sense to incorporate the semantic model into the various pages that document Items. But that hasn’t been done yet.
Many have tried and all have failed to come up with a diagram that is:
accurate
complete enough to be useful
not so detailed as to be unusable.
I for one welcome new attempts at a drawing or drawings.
But, ideally, the Quick Overview is not meant to be your one stop shop for learning openHAB. The intent is to go through the Getting Started Tutorial as the next step once you learn the terminology.
That sounds great, feel free to discuss all your ideas in this thread
Tell us about things you got more easily and things that needed more explaning
Rich who answered you above writes a lot of the documentation
I got off to a rocky start with OpenHAB since the terminology/concepts were unfamiliar. I needed to adapt my mental model of home automation which includes devices, device controllers, device status, configuration user interface that includes rules and schedules and a customizable home automation user interface. Admittingly, this model is very different (and very simplistic) when compared to OpenHAB. The motivation for suggesting a concrete example of the concepts is to help a new user bridge their mental model to the OpenHAB way.
There’s a lot of legacy/superfluous documentation. For example, references to DSL rules. Writing scripts in ECMAScript 5.1 is made easier because Blockly rules get converted to ECMAScript 5.1, but then ECMAScript-2021 is recommended over ECMAScript 5.1. Please consider removing or marking deprecated/legacy aspects.
In my opinion, Persistence documentation does not belong in Getting Started. It’s an interesting feature, but I really didn’t need to understand persistence to get started.
On the other hand, the Semantic Model is very important, but its importance is not stated. I would go so far as to say that the the semantic model is a key concept that belongs in the introduction as it allows the Locations tab to be auto-magically created.
I think the Introduction section would benefit by stating the intended audience and setting expectations. It took me more than 4 hours to be able to control a simple switch. I’m guessing a non-techie would be overwhelmed and would be better served with an “easier” home automation solution.
The challenge there is everyone comes to OH with a different set of concepts and they need to learn OH’s concepts. And that’s why we created a wholly separate section of the docs prominently located at the top of the documentation hierarchy to discuss them. Also, the for various reasons, the documentation is written to be linear (at least up to a point). When you read through Quick Overview, it tells you to go to Getting Started. When you go to Getting Started, it suggests reading Concepts if you don’t have a good grasp of the key concepts. The rest of the docs are intended to be reference where you would look things up as needed.
There is a very simple concrete example for a Thing in the Thing’s Concept page though.
I’ve been down this path before and what ends up happening is everyone wants everything documented everywhere so they don’t have to jump around the docs. To put it bluntly, we don’t have the man power to maintain something like that. So we have a DRY policy in place: do not repeat yourself.
Persistence is required for the charting that automatically happens and is demonstrated in the next section on pages. Skipping it and then presenting stuff that requires it in the same tutorial doesn’t feel right and it leaves holes in understanding for the rest of the tutorial.
But, even more so than Persistence, the Semantic Model is optional. You don’t really need it. If you choose to use Sitemaps, of HABPanel or some other UI, the Semantic Model is pretty pointless to you, and yet it can be a whole lot of work to implement.
Still, the Sematic Model is presented as soon as possible in Getting Started. However, it’s hard to state how important it is to MainUI when up to that point in the tutorial we haven’t even mentioned MainUI yet. We do talk about the import of the semantic model as soon as feasible, when we start talking about the Overview page. I’m not sure how we could introduce that earlier though.
That’s what the “What You Need to Know Before You Start” section is supposed to cover. If you feel it doesn’t we welcome concrete suggestions and/or PRs to address that. The first two sentences there state
When home automation just seems to work, it is always the result of hard work. Home automation is fascinating and requires a considerable investment of your time.
If you’ve a better way to state it we are open to suggestions.
Ultimately, the biggest problem with the OH docs is that we can’t document everything everywhere all at once.If we had more volunteers contributing more reliably maybe we could. But since we don’t we have to choose where things get documented because we can’t have the same thing documented in more than one place. This unfortunately imposes a burden on the readers since they have to navigate the docs to find all the info needed.
@rlkoshak: Your responses show you’ve given the documentation a lot of thought. I very much appreciate your words and efforts.
The purpose of this post was simply my way of giving something back to OpenHAB by expressing a few challenges facing a newbie.
As for rules and their re-design, from my newbie perspective, here’s a suggestion to make it easier for a non-expert user to understand…
Replace the word “Rules” with either “Automation” or “Automation Rules” with submenus “Triggered by Event (if X do Y)”, “Scenes (set Y)” and “Schedule (do Y at T)” and remove the Scripts and Schedule menu items. Each of these Automation submenus would have its own purposeful user interface (e.g., Triggered by Event presents the event selector page followed by the If/Then page, Scenes presents a new page that shows controllable items and settings for items, Schedule presents a time picker and action to either run a scene or directly control items). Behind the curtain, all of the Automation logic can be rules written in some language which an advanced user may copy or edit. The overall idea is to make the user interface and terms more intuitive/familiar/streamlined so that the need for documentation to explain a spaghetti of overlapping features/concepts is reduced.
On a tangent to Rules, but in the spirit of specific newbie feedback, I was confused by the distinction between Equipment and Points. At the risk of sounding stupid, can’t they be merged and have a checkbox to show/hide what auto-magically appears in the Equipment tab? I was also confused by the Profiles vs. Transformations concept. It seemed like overlapping complexity without a clear benefit.
Have the OpenHAB stakeholders considered designating someone as a feature gatekeeper to enforce intuitiveness? My concern is that OpenHAB’s complexity will render it an increasingly niche home automation solution (which is perfectly fine if that’s what the stakeholders want).
openHAB has been around for about a decade now. They have always been called rules. I don’t see that ever changing. It would be a HUGE effort to do so as it will affect pretty much everything across the dozens of openHAB repos.
Here you are talking about code changes which would be out of scope for this thread. Please file issues on GitHub but be aware that what you are describing has been discussed, some work has been done towards some of it, but in all likelihood unless you are willing to implement it yourself it will take a lot of convincing to find someone else to volunteer to do it.
No, they are really different. For example, a thermostat could be an Equipment. You have exactly one thermostat (e.g. many home have many). A thermostat has multiple sensors (e.g. ambient temperature, humidity, etc) and actuators (temperature setpoint, heating/cooling mode, fan switch, etc.) Each of those are represented by separate Items. Each of these sensors and actuators are Points. The Points belong to the overall thermostat equipment.
That’s an advanced concept that will probably take us down a whole other rabbit hole. We can go there but it’s probably better to start a new thread. At a very high level, they are different but ultimately Profiles are a case where a new concept and feature was added to OH as a point feature rather than as a well thought out design.
But Transformations can be used by Things in their Channel configs or by Profiles. Profiles can apply some function as events flow from the Channel to the Item. It’s not always transformational. Sometimes it does something functional (e.g. follow, button press, etc).
OH is broken up into a couple dozen different repos that address different parts of OH. Each repo has it’s own set of maintainers (gatekeepers). There is an architectural council which, despite it’s name, is mostly a conflict resolution board to address conflicts between maintainers and to help coordinate and adjudicate changes that span multiple repos. But it doesn’t really have a lot of power or ability to push things.
It’s all self directed volunteer effort. Neither the AC nor the maintainers have the ability to tell anyone “go work on this.” Maintainers have the ability to reject work which is the extent of the “gatekeeper” function. But that’s it. It all bubbles up based on what people volunteer to work on.
One thing I’ve noticed is that people new to OH and especially people who are new to home automation in general, greatly underestimate the complexity of this problem space. There are commercial options that hide a lot of the complexity with the cost of greatly reduced capability. To support the kinds of things that tools like OH and HA do requires a lot of complexity.
And new users in particular, new users do not see how far OH has come over the past decade in making home automation easier. The transition from OH 1 to OH 2 was huge in both simplifying things as well as adding amazing new capabilities. The transition from OH 2 to OH 3 was an equally big leap in usability.
Capability
OH 1
OH 2
OH 3
administration
All textual, some with custom syntax
Some primitive UI support for some things
About 80% now configurable in the UI
integrating devices
All textual config spread across two files, each binding has it’s own syntax
Automatic discovery where possible
binding config
one giant config file for all bindings
separate configs for each file, some configs moved to Things
UI support for binding configs
UIs
Only text based sitemaps with limited capability
More capable UI options, a separate admin UI
A unified admin/end user UI with almost unlimited customization options, large portions auto-generated
automation
one custom language with a few intrepid users on different languages
introduction of UI rules and a little better support for other languages
great support for UI rules, official support for lots of modern languages, introduction of Blockly to code graphically
Items
text files
primitive support in the admin UI
fully supported in the UI, introduction of the Semantic Model, quickly create lots of Items using “create equipment from thing”
sharing
copy and paste from the forum
introduction of a marketplace for third party add-ons, HABPanel support for third party custom widgets
marketplace supports third party add-ons, custom widgets, rule templates and Blockly libraries, multiple marketplaces are supported
documentations
wiki based
automatically built from readmes
introduction of a Getting Started Tutorial to walk one through all the important concepts and how they work together, better versioning for those who do not keep up with releases
We really do care about ease of use and have made great strides in that direction. And we will continue to do so. But the general consensus among the maintainers is we won’t do so at the cost of flexibility. Only rarely are features removed and then only for good reason.
