/-> User Interfaces
hardware -> binding -> Things -> Channels -> Items |-> Rules
\-> Persistence
\-> Model
I still somehow had it in my mind as the “steps to go through” when adding “hardware”
So I browsed the 3 tutorials on adding things, but never found the tutorial on adding items, and I did not proceed to the “Semantic Model” as I felt it had to happen in a step before “modelling”…
For the benefit of those (beginners) that have this model/approach in mind, would it be an idea to add a tutorial section of “Adding Items”?
It would probably be a very short text, as it would only refer the reader to proceed to next chapter in order to define/update his model first, and only then add/create items from the model view.
The text could also be added in last part of the three “adding things”, although I’d prefer it as a separate item, so you can see it in the “menu”:
BTW, In “Configuration Guide” section you have an “items” element.
That one mentions the UI in like one line, without referring to where this UI may be found.
I think the UI is the one in Getting Started/Semantic Model, but I’m not sure.
I think it would be great to spend a line referring readers back to that Tutorial.
PS
I think the model above would be very welcome in the “Getting Started” section, it’s a good way to set the stage.
PPS,
I have not yet found an introduction to “Automation” (That is scripting, rules, events etc)
Such an intro could also come in handy, in the getting started section. (When to use what, etc).
E.G. I have just realized, that scripts running frequently, (like every 5 min) in not handled by the scheduler. I am yet to discover how that is supposed to work then.
Would you be willing to contribute to the docs? Anyone can. No worries if you don’t have the time (I’ve only recently started submitting edits), but if you’ve got ideas then there’s no better time to jump in.
At the bottom of each page there’s a link to make edits in GitHub. You’ll need to create a GitHub account, and then you can edit away and submit PRs.
IMHO we should push the use of the ‘add equipment from thing’ feature to always auto create the items. The docs can always be improved, especially after massive changes have been made like the V2 to V3 transition so as suggested, will you or anyone else step up to help? Someone that is new to openHAB often can provide insights on what is confusing that an older user can not.
BTW if someone does want to help out and can not program there is always this that needs doing…
Even if you only change a few of them it all helps.
Hi Russ.
I’ll certainly give it a try. I had noticed the “Caught at mistake…”
Here I’m suggesting to add a page, but I’ll see if I can figure out.
I already have a github account.
I guess the autocreated “Items” will “float around” until attached the right place in the model.
Maybe that is a problem that hinders auto creation of items. I don’t know.
(Just realized yesterday that the “Syntactic Model” is the key here. )
A stated in post above, I’ll give it a try. Right now, a walk in the snow is next on the schedule
Thank you.
Hi.
Is there a description on how to setup some kind of tools environment in case you are going to contribute a little more to documentation than just fixing a typo here and there?
I have worked RCS systems before, Latest Mercurial through the TortoiseHG interface, but not with Git.
Thanks, Henrik
I would suggest to use vscode.
It will be part of the tutorial for contributing to the docs, which i hopefully can finish at some point in the future.
Edit:
Maybe some context, since the tutorial is a work in progress especially for the vscode part.
vscode brings git support included in the ide
You have to install git for your operating system and it will work in vscode
rest is learning
how to work with git (not especially ide related)
how our docs work and where to find special contents (partly explained in the link above already)
EditEdit:
Feel free to ping me for questions on the setup (here or on github in the docs repo).
I will try to get some more love in the wiki article next weeks again. Last few weeks were a bit busy.
I know it’s probably a big ask but did you do what the first page of the tutorial asked and
This new user tutorial assumes that you have at least a basic understanding of the concepts of openHAB (opens new window), and already have a working installation of openHAB.
The path from hardware all the way to Items and beyond should be covered in the concepts section of the docs. Did you skip reading that or was it not clear? If it wasn’t clear, is there anything we can do to make it more clear?
The Getting Started Tutorial assumes that that knowledge is already understood.
It also states:
This tutorial presents a series of concepts and steps that build upon one another, so please review the tutorial in the recommended order.
Which is supposed to mean that when one completes one page they should move on to the next.
At most I would add Items to the title of the Semantic Model page. It used to have that but I think during one of the editing pages it was shortened to fit better in the sidebar without wrapping.
It’s the UI. The thing you are looking at when you bring up http://ipaddress:8080. It’s the UI that was brought up in “First Steps” page of the getting started tutorial. There isn’t any other UI for this stuff.
One of the things that needs to be balanced is between making each and every page stand alone and complete unto itself and limiting the amount of duplicated documentation that gets created all over the docs.
Most of these reference pages will assume that the user has read the Concepts section of the Docs and gone through the Getting Started Tutorial and will therefore not repeat a lot of the basics that are presented there (e.g. like where the UI is). But adding one or two sentences wouldn’t hurt if it helps make things more clear.
Also, keep in mind there is a ton of documentation to write, review, and rewrite for OH 3. There are very few of us actually contributing to doing that work. So most of the docs are going to be the same as they were written in OH 2.5 with maybe a short section at the top saying “oh by the way you can do this in the UI too” until such time that someone gets around to rewriting those pages.
That is supposed to come from reading the Concepts sections which is a prerequisite for the Getting Started tutorial. I don’t want to duplicate that information in the Getting Started Tutorial because it doubles the maintenance work and there are not enough of us actually maintaining the docs.
The rest of the Getting Started Tutorial is still in work. You can find the pages that start after Persistence at Building Pages in the OH 3 UI - Introduction. Note there is some duplication in the Pages sections. Editing that down is still in work.
The Scheduler just shows those Time triggered rules that have “Schedule” as a tag. That’s it. There is nothing special there. Note that it does not work with Ephemeris.
No, we’ve been down that path and it caused way more problems and support issues here on the forum than any time it ever saved. Items should be deliberately created and it’s easiest to do so through the Model “Create Equipment from Thing”. But I don’t think anyone expects each and every Channel for each and every Thing to get an Item. If I only use three Channels from the OWM Thing, why should I have to have in my system the hundred+ additional Items?
Not all Items need to be part of the model. In fact you should have a good number of Items that are not a part of the model.
For anyone who wants to contribute to the Getting Started Tutorial itself, particularly the parts that have not yet made their way to the docs, please refer to the wiki pages linked to above. Make changes or start a conversation there. I’ll lock the wiki (maybe even the thread) when I start to migrate that page to the actual docs so if the post is still a wiki, it’s still in progress. Though I hope to start getting the Pages submitted to the docs sometime this week.
I did. That overview page is a bit sketchy in explaining the OH world .
I’m trying to compose my view of what (at my beginner level) that I will share, then we can see if any of that is usable.
Yes, but as I was transposing some semi auto generated based in EspHome mqtt, I did not find any place nor a handle to add a channel, which was next (as I remember now).
Probably there the train derailed, as I could not find my way back to follow the tutorial. Mentally missing the next logical step, the “item”, kept me from reading “Semantic Model” I had already concluded making my model.
As written a short notice after “thing” on “Item” would have pushed me further in the right direction.
Yes I know but did not at start.
As said above the train was already derailed at that point, so I was grasping at straws.
I still think UI should have more mention, If I understand correctly, the UI is the future, files not. So why overexpose files with deep syntax etc in a beginners tutorial.
Oops. Wrong, I had skipped the tutorial. My bad.
That is what happens when derailing…
Well that kind of proves that I had read that “Concepts” section
We don’t. The page you were talking about is the reference documentation, not the getting started tutorial. The tutorial is only those parts directly under the Getting Started heading on the sidebar. Everything else (except for Concepts) is reference documentation. As reference documentation it must be complete. A lot of the reference docs for UI stuff hasn’t been written which is why I mentioned that above. You won’t find a whole lot of UI stuff in the reference documentation…yet. Over time the amount of UI stuff will grow. but it probably will never be as long or thorough as the text config reference docs because because the UI stuff is somewhat self describing.
But you will only find the UI in use and discussed in Getting Started. We state that up front on the first page of the tutorial in the files vs. UI section. If you are using text configs, the reference docs is all you will have. The Getting Started Tutorial is only going to show how to do stuff through the UI.
If the derailment happened at the Concepts section, then I think we need to focus on that section to make sure that all the information necessary is presented and it’s presented in such a way that is understandable. The Concepts section hasn’t changed much since OH 2.0 so I’ve no doubt it can use a fresh look and edit.
)