Something is not right here. There’s a difference between complexity and ignorance (not the negative connotation, just, not knowing something.)
Just yesterday I did my first contribution to the documentation. Scroll down to the page, click in “edit in GitHub”, login to GitHub, and follow the instructions (commit with your real email instead of the anonymous one for example.)
It was easy (even when I did something wrong, the maintainers were kind enough to correct me.)
So really, if you found it too complex, please take the time to check it out again. It’s simple.
I follow the topic with interest because I also fear that at some point openHAB will end up dying. I will give you my feedback. I am an electronics engineer by training, I do quite well in IT (Linux, C programming) but I do not know the languages used for OH programming (I am not capable of developing a binding for example.)
I started with OH1 and quickly realized that it was a reliable, robust and powerful solution. I grew my installation then moved to OH2 with a mixed textual and UI configuration. There things got a little complicated with the introduction of the concepts of Things, Channels, Profiles, Tags… However, I was able to develop a reliable installation with rules developed thanks to the help of the documentation and the forum.
Then came OH3. At that time I saw that there were breaking changes and also the stopping of support for 1.x bindings. I decided not to migrate to OH3 for these reasons.
After a while, I began to fear for the sustainability of my system. Many of my colleagues were telling me about HomeAssistant. So I tried HomeAssistant. I was amazed by the ease of implementation. In less than 2 hours, I had connected all my devices and I had nice dashboards, particularly for energy management, with graphs. Doing the same thing with OH would have required days of work. I was then thinking of migrating to HA. But I didn’t do it because I realized that advanced automation required a lot of learning.
Finally, I saw that OH4 was released and wanted to give it a chance. I did a new installation on a raspberry 4.
What progress! I can finally define all items from the UI. I can also write advanced rules in script. Now it’s decided, I’m going to stay at OH4. However, I am aware that I can easily adapt to OH4 because I have a significant background in OH since OH1. But I also realize that for a novice, the concepts of OH are complicated and the learning process takes a long time. And I also ask myself a lot of questions. What will be the future of OH? What approach should I adopt to guarantee the sustainability of my installation? Just one example: there are several possible languages for rules. I use DSL. Is a language that will be supported over time, or will it disappear in a future version?
Your example shows much of what people know and think of OH (and HA in comparison) is… well, outdated. Wrong in fact. And in part result of OHs long history.
The GUI stuff you discovered in OH4 had been there since OH3 about 2,5 years that is.
If you were to start today you maybe wouldn’t be using files or DSL to do the config and programming. But you still can. It’s there and what’s even more important it keeps being maintained, there’s even smallish new features.
Docs were very much improved telling you how you can do in DSL and JS or marketplace templates.
Feature parity UI or text config for automated deployments or just because you like it. Binding or 3rd party component for e.g. ZigBee.
Semantic model, custom widgets or from the marketplace or ancient(v1!) text config of sitemaps.
This is what beginners, reviewers and even to some extent long termers often do not understand: there is not THE one way of doing things. There’s choices, and they’re ALL up to date.
Most people just don’t know about more than one of these options and quite some have a history like you do or they read/watched some information snippet so they believe this is how OH is.
That has a downside, of course. Freedom of choice means being forced to choose and spend efforts to evaluate options and educate yourself upfront to be able to make an educated choice that’ll stay, turning the effort into a beneficial invest mid to long term.
OH will never become a no-brainer but real home automation is hard and will remain to be so any home automation system that’s comparable in capabilities will be more or less as hard and costly to learn and use.
We try to make it easier to apply to less complex use cases but we won’t be sacrifying flexibility.
HA in comparison is simple. It just provides a single method to do things. Interactive only, essentially.
That’s a lot more appealing to users as it matches the Zeitgeist of getting things effortless (no thinking, no preparations required) done quick.
But there’s limits and downsides to that, too.
OH has overcome these limitations, initially at the cost of apparent user unfriendlyness and now at the cost of being complex, still confusing at times and somewhat unappealing as it is giving users a feeling of inferiorness maybe.
But we’re improving faster than users and reviewers notice - granted it’s still somewhat confusing due to complexity and the sheer amount of options.
And we’re getting there, we’re already way further in than noticed outside our community.
There’s the semantic model, there’s UI files feature parity and greatly improved alike documentation, the marketplace, Getting Started tutorials and more.
Getting back to the title which is all to the point: all of this is incredibly hard to document and to communicate, and that’s where we currently fail for the most part.
This thread should not be about OH and your experience with OH but on how to improve on communications.
Imho this is one of the greatest strengths of openHAB but also what is too much if you first try openHAB.
The unmatched flexibility and that’s really something where there should be more emphasis on.
Configuration:
You like GUIs, you can configure openHAB through the GUI,
You like files, you can configure openHAB through files
Rules
You like javascript, you can write rules in javascript.
You like ruby, you can write rules in ruby.
You like python, you can write rules in python
You like graphical rules, you can do blockly or NodeRed
It’s a little bit shown here but I think there should be more emphasis on this flexibility. Especially old forum posts (not in this forum) still complain about RulesDSL when now there really is a rule engine for everyone.
I know the developer sidebar and use it sometimes although this is something I constantly forget about. Perhaps at it is not so prominent/has to be activated manually, not so self explaining? It helps in some situations when looking up an item, … but as it needs the correct spelling to search it does not help if you got lost in your own naming conventions, like: Did I use Outdoor, or Porch or Terrace, or maybe Patio, or an Abbreviation of one of these words in the name or label? Sorting items, … in a grid with a colum location sorted from A-Z would bring me quite fast to the result. Or I know that the item belongs to a thing that uses a special binding and I sort by binding first and then by location in a second column. And I could see in following columns parameters I want to check out to make a new item identical to existing items, find the cause of an error in deviating parameters, … And, one wish more: Perhaps could even do mass changes without editing every single item in the selection I made.
And for the widgets: The first “problem” is, that from within openHAB, where I work on a new widget there is no functio/link to publish the new widget. The same, when you open the marketplace from within openHAB searching for a widget. So without searching out of openHAB you will not see, that you have the chance to publish a widget to the marketplace and that this is wanted. Instead you feel like “There must be a secret team somewhere that is able to develop and publish widgets to the marketplace and you are not part of it, your contribution may be unwanted”.
If you find the right place, the first impression is: There is a lot of text. Then the mask does not look like a mask for offering a new widget, but to post a text article in a forum (as it is). Furthermore you see that some of the text already in the mask has to be edited and that there are obvioulsy parts you should not change/that are necessary for functionality, but it is not easy to see, what has to be changed an what not. Is the [ and the ] necessary for each position? What about these ## and ###? Should I add my input instead of the text in the brackets, or instead of the red pen or both?
The title field above the text seem to be the field for the name of the widget, but is this correct? Are there naming conventions? Where can/should I make clear that my widget belongs to a certain binding or certain things/items? Then there is this tag field. For what? In the text I see that there should be tags used for maturity, and that I am obviously free to decide, OK. They should go in this tag field? But are other tags needed or recommended, like the binding or type of devices the widget can be used with?
As my widget is dead simple, working for months and will not have any additional features in the future I could call it stable, but below I see a version history starting with 0.1. Is this correct then? Or am I free to decide for a version number?
Then there are several ways mentioned to publish the widget itself. Code-fences with YAML are what for? Yes, I know that I obviously could use them to copy and paste the code from the openHAB editor within these fences, but would everybody understand it that way?
To be honest I made myself here more stupid that I am, but I wanted to point out that for a beginner or someone who does not work with openHAB on a daily basis it is often really hard and timeconsuming to find through the different systems needed as they are often not linked to each other that well and the level on which you find explanations is often quite high/not very detailed.
Well, you found exactly the point: You need a second tool/system with an account and you have to learn how this tool works. I know that a in the developer comunity a GitHub account and the knowledge how to use it is a nobrainer. But not everybody is a developer. And just for the sake of “After hours of searching I found a solution to a special problem for which I could leave a little hint in the docs”, who will start by opening a GitHub account and first making himself comfortable with GitHub? I have a GitHub account, use it quite seldom and normally have forgotten everything about how to use ist, when I need it again. Therefor I also do not make PRs when I face some problem within openHAB. I use the forum, and leave the PR to people who are native GitHub users.
And GitHub is just one of many tools in the eco system you have to make yourself familiar with.
I agree that there is this “Zeitgeist” but there are also other aspects. OH has a great basis of IT professionals and people with no other hobby. They are all familiar with 1001 tools, programing and scripting languages, … and they keep up there knowledge as they use it on a everyday basis. If they find some lines of code somewhere they know which language it is and how to handle it. They do not mind rewriting code in a different language and having an installation that uses all the choices you wrote about.
But besides “Zeitgeist” and an existing wish to learn more, get more into it, … there is a majority of people out there that has a special need or a wish for some automation but no big IT background and limited time and limited needs and therefor often get frustrated when they see how much knowledge is needed and has to be kept up to make use of OH. I really would love to do more with OH but often it takes weeks or even months to find time for it again, and I think a lot of people have such a situation. And then the complexity of OH strikes again. You forgot a lot of thinks you first have to find again and with every addiditonal component and tool, scripting language, … this situation ist getting worse.
If you don’t know how to read it let me just say that my heatmap is very cold.
The best I can do is fumble on GitHub.
But the key part in my statement is:
What you’re saying is “I don’t want to do it.”
And you didn’t do it.
What I’m saying is “I’m going to try to do it.”
And I did it.
Don’t know what else to tell you. You have to make an effort, otherwise it comes out as whining, I’m terribly sorry to say. And I whine a lot, trust me. But when the openHAB team makes an effort to have a process where everyone can give feedback and improve on the documentation, code, application etc, in a transparent and standard way, you saying “I forget how to use it, I don’t use it often, it’s a different tool” I’m sorry to say, you’re whining. And you’re not really helping either because you’re not sharing your knowledge. So… if you want to improve your condition, why not create a best practice, step by step on how to login to GitHub and update openhab documentation. That way you know exactly what to do, you aren’t limited by your memory, and you can even go one step further: share the best practice in the community to allow other members who don’t know how to use GitHub to collaborate also.
That would actually be awesome, because I’d probably refer to it myself.
Well, we are talking about marketing here and potential hurdles for people not to use OH or not become part of the active community. Writing about myself as someone who uses OH since 1.8, has no technical background by education but a good technical understanding and is interested in such things and willing to spend some time (but also has more than e fulltime job, a quite big old house and a familiy) was just to show how high the hurdles are and must be for people being even more on the user/consumer side as OH requires really a lot knowledge around itself to become more involved.
GitHub is a great tool and is a great tool to help working on the docs for someone who is already familiar with it, or sees a use/potential that is worth learning it, far beyond correcting some typo in an OH doc. But for everybody else it is just an additional hurdle. And as easy it may be to really use it, when you overcame the first hurdle of getting a GitHub account, I bet there are lots of people who will - just emotionally as they expect things to be complicated - not even try.
But GitHub is just one example of many things within the eco system. For a lot of things you have to leave OH and make yourself familiar with quite a lot of stuff of the underlaying OS, and as much as I love openHABian, and though I have several LINUX devices in the house I am more or less able to manage, even after several years I still have to follow tutorials (often outdated or not really correct), search for hours on the internet when things are necessary like installing a MQTT server, connecting to a external database for persistence, and solve problems following advice I found on the forum. My LINUX knowhow is getting better in small steps as I do need it to manage not only my OH server (that is the difference compared to GitHub for me), but again: From a marketing perspective I can understand that people are afraid of the complexity and the necessary learning curve not only for OH but also for a lot of things around it and that they feel frustrated when they never feel real progress as they forget faster than they learn as there is so much to learn.
I’m going to keep my reply short because it’s veering off topic. Clearly I failed in that.
If you want to have a discussion on adding something to the marketplace please open a new thread and we can continue there in depth.
But I do want to say the following and answer the non-rhetorical questions (and the one’s I’m going to pretend are not rhetorical).
We’ve done our best to make contributing to the marketplace as easy as possible. If anyone has technically feasible ideas to make it even easier we welcome issues. I like the idea of being able to publish to the forum straight from MainUI, but doubt that would address even half of your complaints.
I don’t understand the question. But the general convention in documentation involving computers, stuff in [ ] or < > denote something that you need to replace with your content. The [ ] or < > are removed. To make this more obvious, the _ and are an attempt to make it even more clear these are the parts that you have to replace.
But what never ceases to amaze me is how few people are willing to just experiment. Create a post and see how it looks. See how it works. Adjust and see what changes.
The assumption is that anyone contributing to the marketplace is going to be somewhat even a little bit active on the forum. The number of # is the header level.
Yes.
Not really beyond the obvious stuff like don’t use the same name as someone else’s widget, be polite, etc.
In the description or in the title and the description. You can also add tags to the post. It’s up to you to decide how to document your widget.
However, it should not use hard coded Item names. Item should be parameters so the end users can name their Items how they see fit or use the Items they already have created.
Use what ever makes sense to you. Tags are useful to readers of the forum to help find and identify relevant posts. The only tags that are required is the maturity level which you supply and the “published” tag which a forum moderator will add after review, as described in the template.
You can decide to version it how ever you want. This is all information you are providing to the users of the widget. Whatever you think is best to inform your users what your widget it and how to use it is good.
Given that the very first reply to any post made to this forum where code is posted without code fences is
Please use code fences for all code and logs.
```
Code goes here
```
coupled with the assumption that these users are at least a little bit familiar with the forum, yes, we assume just about everyone would understand that. Note there are also icons at the top of the reply pane to add code fences.
Are these users likely to be publishing to the marketplace in the first place? Do we want these sorts of users publishing to the marketplace?
Personally, it never even occurred to me that these users would even want to publish to the marketplace. And I worry if these users do because for the beginners their offering might have quality issues and the user who isn’t engaged with OH that much is likely to abandon their contribution leaving the marketplace littered with broken and forgotten contributions.
There should be at least a little bit of friction to contributing to the marketplace. That doesn’t mean it shouldn’t be easier but the actual audience for marketplace contributors should be identified.
You don’t have to make yourself “comfortable” with GitHub. The page that opens up when you click the link walks you through all the steps necessary to make the edit and create the PR. @Oliver2 demonstrated above (? maybe it was another thread) even if you don’t know what you are doing, don’t know the difference between a Pull Request and a Press Release, managed to create and submit a PR. In his attempt to show how hard it is he managed to show that even someone who doesn’t know anything about the tools can figure it out.
We also have numerous tutorials here on the forum and have lots of people who will jump at the chance to help if necessary.
What other tools do you need to make updates to the docs? I routinely make small updates to the docs using nothing by a browser and my GitHub account. If you are going to make code changes then yes, you need lots of tools but that’s just software development which always requires lots of tools.
If you don’t even create an issue your problem will most likely never be addressed. You are the one with the problem. You are the one who is best able to provide the detail to solve the problem.
There are many alternative home automation products that are much less complicated. They are much less capable too but that is the trade off. If OH is too complicated to set up and keep up and your home automation needs are modest, perhaps OH isn’t the best choice for your. However, you can’t have your cake and eat it too. You can’t have both the flexibility and capability without the added complexity.
Home automation is hard. That’s just the way it is. We have thousands of little walled gardens, billions of unique use cases (or user stories if Agile is your thing), incompatible licensing, services that start up and close down, etc. The fact that OH does as much as it does, as well as it does, and makes this all as simple as it does is astonishing to me. Could it be even better and simpler? Yes! Absolutely!
But it’s never ever going to be so simple that my spouse will have the patience and willingness to set it up. For that to even become possible, there will have to be a massive consolidation in home automation technologies and APIs and a huge reduction in possibilities down to something about at the level of what Google Home offers as of this writing. Most users of OH though recognize that as the toy that it is though, it’s so limiting, and even that toy is beyond what a lot of users can handle.
This is way more detailed and thorough than is necessary but it explains everything. It’s a great resource. When I get lost or forget something (I’m always forgetting how to properly sign off, for example), I always search for this post.
Although deemed off-topic, I’ll try to get this small sidetrack back to the topic. I was curious about Home Assistant’s terminology within this context, and found that they even use the term thing to describe a sensor within their terminology. So maybe “thing” is not that far off. I’m considering if it would be worth adding a small section about HA vs. OH terminology to our Concepts page to ease the transition for anyone migrating from HA to OH. WDYT? It probably seems a bit optimistic, but I guess it could somehow help when not starting from scratch in the home automation domain, but already having some experience with HA.
I’m a little uncomfortable with this approach. First of all, HA is not the only other platform someone might migrate to OH from. Do we also include the others? For people who are not coming from HA would this not cause more confusion?
I’d rather see a separate HA to OH tutorial than adding a bunch of mappings between OH’s concepts and other platforms concepts.
Agreed. Or invest in more materials about the semantic model, an end to end approach for integration a bunch of the most popular devices like Shelly, a bunch of zigbee stuff and such. It’s such a great tool and I feel like it’s not being properly advertised.
First of all, wow! And I mean this in the most positive way. I pointed out that this mask might not be as selfexplaining as someone with more background might think, and you posted a complete set of answers to all the questions I thought someone could have. Thanks from my side, now you “forced” me to try out. And something I perhaps can give back would be to put this all together in a sort of a tutorial for others who might have all these questions in reality.
But what came out quite clear to me from your last posting is, that there is quite a broad span of people using / working on OH and that there are expectations from both ends of this span to the other end are hard to match. E.G. when you write about the forum software. I do use some other forums on a everyday basis and some are even based on the same software. But there are people like me, just writing plain text. And who feel already quite “educated” when they remember to set a simple “unformated text” fence around something or are able to include a picture or cite another posting where it seems necessary. I never had the need for more, therefore did not search for something more and did not try out something more. And when you look around in the forum the number of posts using more functionality is very limited and is limited to perhaps a handful of users. But now that you told me there is more and what for and how to use it, I hope I remember it when I could need it.
But isn’t that just another example for what I mean with the complex eco system around OH? We came from an expectation to have a GitHub account and be familiar in using it to the forum software. I already named quite some necessary LINUX knowhow, even when using openHABian (which is a great thing!). Then you constantly read about REST-API, YAML, JSON, XML, Framework7, different scripting languages, different JAVA-Versions, different GUIs, UoM, … and all this changes from time to time and you have to start over with the “next big thing”. This all has it’s value for people beeing more on the developer side, but to come back to “marketing”: For someone who want’s to have some “intelligent lightbulbs and an e-mail from the washing machine” as a first start into something more this is not attracting as he/she will not see what what all this “superfluous overhead” has to do with his/her demand. OH cannot be the perfect solution for everybody, I totally agree, but there are people out there with the wish and will to do more, learn more, interact more with a community. And I see nothing wrong in trying to “sell” OH to such people to keep OH alive by discussing what could be done to make things easier, like thinking about what is really necessary to become “part of the family”.
But that’s a home automation problem. It’s not an OH problem.
Everyone’s home automation requirements are unique. Does everyone need to know all that stuff? No, of course not. But some people will need to know X and others will need to know Y and yet a third set will need to know Z even for a simple case. If you want to use zigbee2mqtt, well you’re going to have to go learn how that service works and how to use MQTT with OH including installing and configuring Mosquitto (or other broker of your choice). But not everyone has that requirement. Others will need to learn how to read Modbus or KNX registers or how to pair a device with a Zigbee coordinator.
There isn’t a whole lot we can do to eliminate all that. The technologies work the way they work. There is only so much we can do about that.
And we can’t predict what each and every user needs to know for their specific requirements, particularly when it comes to the stuff outside of OH.
This is the same reason why How to get started (there is no step-by-step tutorial). There is around 350! combinations of add-ons that are possible with OH. I think that’s more than there are atoms that make up the planet. We’d be at this forever if we made a step-by-step for even a fraction of that. But that then means that the end users must be able to go and learn enough about their requirements and the technologies they need to use outside of OH.
Absolutely we can make things simpler and easier and there’s already been at least one issue created from this thread. But we have to do so in ways that fit in the scope of the actual problem at hand and the number of volunteers we have available.
I wouldn’t, I agree with Rich where would you stop doing that, iobroker? FHEM? SmartThings ?
It’s not about stealing users from each other. It’s not a saturated market.
It’s about making OH a) widerly known and b) represented right in the media (reviews, YT) in that it isn’t complicated for beginners (any more) so worth trying.
Also agree… get OH docs updated, fixed, sorted, improved, <insert term here>, before ‘doing’ other systems…
Writing is, in principle difficult for conveying tone and meaning… there is a point to
Jörg Lemmer’s posts… (at least I get most of it and can relate to) — the amount of stuff one has to content with to do OH automation is simply mind-boggling. If one sits down and gets something work, and then does not touch the system for many moths, it means relearning most of it. This happens to me all the time. I spend hours reading to get something done; can’t remember the naming I chose; because as my OH insight grew, my naming got more appropriate (e.g., for splits and concatenations of item names); old posts leading me down the wrong path.
I just encountered a Zigbee problem. Now I have to stick my nose into this to figure why it is not working and more so what to do about it, or how to get around it, or look for alternatives.
For newbies and people who do not dabble in OH on a very regular basis, it is hard to a) keep up, and b) to incorporate new things or functionality. [Maybe it’s me being an old-fart ]
Anyway, like others said, this is about marketing the whiz-bang new OH4
Just to make sure we are on the same page: These 350! possible combinations of add-ons are one of the big advantages of OH in my eyes and from a marketing perspective it is quite easy to communicate this advantage:
You do not have to decide for one producer, wireless protocol, … OH supports them all.
And the concept behind OH is so well designed that it is open for everything that may come in the future and can implement it in a consistant manner
You just have to make yourself a bit comfortable with this concept and as whatever you connect to OH in the future is treated in an as possible consistent way and can interact with everything already there you get your personal but still standard system that can grow over the time and include things you do not even think about now.
A potential new user with demands like “intelligent lightbulbs and an e-mail from the washing machine” as a start to something bigger reading this will be convinced that OH has a big advantage over using HUE for the lightbulbs an Miele@Home for the washing machine as these would be two individual systems having nothing to do with each other and without a chace to integrate the stereo set, some cameras, door locks, … in the future.
I am speaking about all that pure techical stuff that is so often needed and that I named allready. No potential new user - if he/she is not a software developer by chance - is interested in everything that has nothing to do (at first sight) with the problem/demand he/she wants to solve. But OH has a big focus on such things in communication and users are often demanded to make themself familiar with numerous of these things first, to be able to do quite simple things or become “part of the family”. You are absolutely right, that at a certain point with bigger demands you cannot avoid “going under the hood”, and OH has a big advantage over other solutions that you can go under the hood and find support for going under the hood. But from a marketing perspective it is a desaster if already “newborn users” or even potential users are always bombed with “You have to have/be familiar with this and that”.
are an attempt to make it even more clear these are the parts that you have to replace.
So maybe “thing” is not that far off. I’m considering if it would be worth adding a small section about HA vs. OH terminology to our 
]