# Documentation on Item creation in OH3 **URL:** \ **Category:** Tutorials & Examples\ **Tags:** documentation, beginners, items\ **Created:** [February 14, 2021, 12:09am UTC](https://community.openhab.org/t/documentation-on-item-creation-in-oh3/116987 "2021-02-14T00:09:31Z")\ **Posts on this page:** 11\ **Page:** 1
**Author:** ![Henrik\_Wahlberg](https://community.openhab.org/user_avatar/community.openhab.org/henrik_wahlberg/32/60911_2.png) [@Henrik\_Wahlberg](https://community.openhab.org/u/Henrik_Wahlberg)\ **Post date:** [February 14, 2021, 12:09am UTC](https://community.openhab.org/t/documentation-on-item-creation-in-oh3/116987/1 "2021-02-14T00:09:32Z")
Hi. Without knowing this: ```auto /-> 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”: ![image](https://community-openhab-org.s3.dualstack.eu-central-1.amazonaws.com/original/3X/6/b/6b7334f61cafbf3fd7e05ccacd97968183b3f327.png) 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. Thank you. ---
**Author:** ![rpwong](https://community.openhab.org/user_avatar/community.openhab.org/rpwong/32/36036_2.png) [@rpwong](https://community.openhab.org/u/rpwong)\ **Post date:** [February 14, 2021, 1:53am UTC](https://community.openhab.org/t/documentation-on-item-creation-in-oh3/116987/2 "2021-02-14T01:53:45Z")
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. ![image](https://community-openhab-org.s3.dualstack.eu-central-1.amazonaws.com/original/3X/e/2/e2f0723aad9482863bdcfb9cee2abbf3ce38a850.png) ---
**Author:** ![matt1](https://community.openhab.org/user_avatar/community.openhab.org/matt1/32/19930_2.png) [@matt1](https://community.openhab.org/u/matt1)\ **Post date:** [February 14, 2021, 2:11am UTC](https://community.openhab.org/t/documentation-on-item-creation-in-oh3/116987/3 "2021-02-14T02:11:58Z")
> [@Henrik\_Wahlberg](#): > > would it be an idea to add a tutorial section of “Adding Items”? 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. [Update Paper UI and HABmin references in add-on documentation · Issue #8607 · openhab/openhab-addons (github.com)](https://github.com/openhab/openhab-addons/issues/8607) ---
**Author:** ![Henrik\_Wahlberg](https://community.openhab.org/user_avatar/community.openhab.org/henrik_wahlberg/32/60911_2.png) [@Henrik\_Wahlberg](https://community.openhab.org/u/Henrik_Wahlberg)\ **Post date:** [February 14, 2021, 1:30pm UTC](https://community.openhab.org/t/documentation-on-item-creation-in-oh3/116987/4 "2021-02-14T13:30:58Z")
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. ---
**Author:** ![Henrik\_Wahlberg](https://community.openhab.org/user_avatar/community.openhab.org/henrik_wahlberg/32/60911_2.png) [@Henrik\_Wahlberg](https://community.openhab.org/u/Henrik_Wahlberg)\ **Post date:** [February 14, 2021, 1:38pm UTC](https://community.openhab.org/t/documentation-on-item-creation-in-oh3/116987/5 "2021-02-14T13:38:31Z")
> [@matt1](#): > > IMHO we should push the use of the ‘add equipment from thing’ feature to always auto create the items. 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.🙂 ) > [@matt1](#): > > 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. 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. ---
**Author:** ![Henrik\_Wahlberg](https://community.openhab.org/user_avatar/community.openhab.org/henrik_wahlberg/32/60911_2.png) [@Henrik\_Wahlberg](https://community.openhab.org/u/Henrik_Wahlberg)\ **Post date:** [February 14, 2021, 8:32pm UTC](https://community.openhab.org/t/documentation-on-item-creation-in-oh3/116987/6 "2021-02-14T20:32:06Z")
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 ---
**Author:** ![Confectrician](https://community.openhab.org/user_avatar/community.openhab.org/confectrician/32/105046_2.png) [@Confectrician](https://community.openhab.org/u/Confectrician)\ **Post date:** [February 14, 2021, 8:45pm UTC](https://community.openhab.org/t/documentation-on-item-creation-in-oh3/116987/7 "2021-02-14T20:45:15Z")
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. > [@\[Wiki\] How to contribute to the openHAB Documentation](https://community.openhab.org/t/wiki-how-to-contribute-to-the-openhab-documentation/111308): > > Contributing to the Documentation can be tricky, especially when you don’t have a software/programming background. One reason for this may be way of how we are storing and processing the documentation pages. We do it with a version control system like it is known in software development. This tutorial/wiki aims to lower down the entry hurdle for interested users, who would like to help us improve/fix the documentation. We will cover some facts about our documentation and what we are doing wi… 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. ---
**Author:** ![rlkoshak](https://community.openhab.org/user_avatar/community.openhab.org/rlkoshak/32/75251_2.png) [@rlkoshak](https://community.openhab.org/u/rlkoshak)\ **Post date:** [February 15, 2021, 7:36pm UTC](https://community.openhab.org/t/documentation-on-item-creation-in-oh3/116987/8 "2021-02-15T19:36:20Z")
> [@Henrik\_Wahlberg](#): > > Without knowing this: 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)](https://www.openhab.org/docs/concepts/), 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. > [@Henrik\_Wahlberg](#): > > That one mentions the UI in like one line, without referring to where this UI may be found. It’s _the_ UI. The thing you are looking at when you bring up [http://ipaddress:8080](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. > [@Henrik\_Wahlberg](#): > > I think the model above would be very welcome in the “Getting Started” section, it’s a good way to set the stage. 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. > [@Henrik\_Wahlberg](#): > > I have not yet found an introduction to “Automation” (That is scripting, rules, events etc) 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](https://community.openhab.org/t/wiki-building-pages-in-the-oh-3-ui-introduction/115689). Note there is some duplication in the Pages sections. Editing that down is still in work. What there is of automation discussion starts at [[wiki] Getting Started with OH3: rewriting the tutorial - 8. Rules](https://community.openhab.org/t/wiki-getting-started-with-oh3-rewriting-the-tutorial-8-rules/109360). To be written is an intro to Blockly and a brief intro to writing Script Actions and Script Conditions in JavaScript (maybe Rules DSL too). > [@Henrik\_Wahlberg](#): > > 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. 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. > [@matt1](#): > > IMHO we should push the use of the ‘add equipment from thing’ feature to always auto create the items. 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? > [@Henrik\_Wahlberg](#): > > I guess the autocreated “Items” will “float around” until attached the right place in the model. 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. ---
**Author:** ![Henrik\_Wahlberg](https://community.openhab.org/user_avatar/community.openhab.org/henrik_wahlberg/32/60911_2.png) [@Henrik\_Wahlberg](https://community.openhab.org/u/Henrik_Wahlberg)\ **Post date:** [February 16, 2021, 7:58pm UTC](https://community.openhab.org/t/documentation-on-item-creation-in-oh3/116987/9 "2021-02-16T19:58:44Z")
Hi Rich > [@rlkoshak](#): > > I know it’s probably a big ask but did you do what the first page of the tutorial asked and 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. > [@rlkoshak](#): > > Which is supposed to mean that when one completes one page they should move on to the next. 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. > [@rlkoshak](#): > > It’s _the_ UI. The thing you are looking at when you bring 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… > [@rlkoshak](#): > > That is supposed to come from reading the Concepts sections which… Well that kind of proves that I had read that “Concepts” section 🙂 Thank you Rich. ---
**Author:** ![rlkoshak](https://community.openhab.org/user_avatar/community.openhab.org/rlkoshak/32/75251_2.png) [@rlkoshak](https://community.openhab.org/u/rlkoshak)\ **Post date:** [February 16, 2021, 9:04pm UTC](https://community.openhab.org/t/documentation-on-item-creation-in-oh3/116987/10 "2021-02-16T21:04:49Z")
> [@Henrik\_Wahlberg](#): > > If I understand correctly, the UI is the future, files not. Both are the present and the future. > [@Henrik\_Wahlberg](#): > > So why overexpose files with deep syntax etc in a beginners tutorial. 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. > [@Henrik\_Wahlberg](#): > > Well that kind of proves that I had read that “Concepts” section 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. ---
**Author:** ![system](https://community-openhab-org.s3-eu-central-1.amazonaws.com/original/2X/6/6a52f2ac5d00e4c7b50471a354b3a9221188be90.png) [@system](https://community.openhab.org/u/system)\ **Post date:** [March 30, 2021, 1:04pm UTC](https://community.openhab.org/t/documentation-on-item-creation-in-oh3/116987/11 "2021-03-30T13:04:52Z")
This topic was automatically closed 41 days after the last reply. New replies are no longer allowed.