Rework of items wiki page

Hi at all.

I wrote the last few days a complete rework of the items explanation wiki page. A few seconds ago I put it online. I tried to write it from the view of a beginner and included my knowledge of the items and the items file.

It would be great if you can have a fast look at the page and tell me, or better fix directly mistakes and errors.

My next work will be the sitemap wiki page.

Greetings. Hagen

I’ve just a few quick comments.

  1. The < > characters that are a part of the icon definition are lost across the board

  2. Lost the hotlinks between the table of Item types and their respective sections. This is more of a problem now that the sections are not in the same order as they are in the table.

  3. This isn’t a complaint against what you have written as I had issues with it before, but the explanation of how Groups aggregate values, particularly in the OR and AND cases is in my opinion inadequate.

As a general question, is there a way to see what it was before? I couldn’t find a previous versions and I’ve not read the old one recently enough to get a good feel for what has changed

Thank you. I have a look at 1 and 2.

3: Wasn’t described in the old version. :smile:

Yep, you can open the history and diff two revisions.

Looks good to me. I think I even learned a couple of things!

I know and it is something that has been bugging me. But I’ve not had time to run the experiments necessary to really describe how it works. For example if I do Group gMyGroup:Switch:OR(OFF,ON) what does it do? How is it different from doing OR(OFF) or OR(ON) or OR:(ON, OFF)? Since we are on this page I figured I’d throw that out as something someone might consider. Clearly I’ve not gotten to it yet. :slightly_smiling:

Hm… I tried it. That feature doesn’t work on my OH 1.8… I tried several variants and none does anything. A few throwed a lot of exceptions. I’m confused now. :confused:

I use them all the time on 1.8 and they do change the state of the Groups as my Items change state. But I have not done the rigorous testing I would need to do or a review of the code to understand the behavior. I should say though that I’ve only ever used OR.

Great that people take the effort to update the wiki:)

Points that maybe should be mentioned is:

  1. what items really are, like for newbies( like a physically button for instance)
  2. Use bold to emthanise that only items in item folder and stricly ending in items will be considered as items, any spelling mistakes will not include them.
  3. Good practice to split items in several files. How items are loaded on startup, the need for initilization script
  4. For GPIO use items needs to be reset at restart
  5. which command that is valid for each item, with example
  6. item.sendcommand
  7. other valid methods
  8. what types the method can take in.
    10 example of parsing data to items.
  9. pictures of different items in use(pictures tell more than words…
  10. where icons are stored, how to use them and which that are available, how to download more etc.

Keep updating it and more and more people will start using openhab, and not just hardcore java people…

Please refine and improve the wiki as you see the need, to improve readability, organization, accuracy, grammar, clarity. If you see a problem, fix it! Just please avoid verbosity/rambling, bad formatting, English mistakes, guessing, narrow focus on your setup, etc. If you don’t think of yourself as a good writer, please instead suggest things to those who are! :smile:

@skatun brings up some points that warrant a bit of a discussion about where certain things are appropriate to be discussed. For example, 1, 2, 3, 11, and 12 are, to me, perfectly at home to be discussed on the Items page.

However, 4 should be documented on the GPIO binding page. We don’t want to have to document every special case from every binding in the generic Items doc. That is what the binding pages are for.

5, 6, 7, 8, and 9, in my opinion, should be documented in the Rules and/or Scripts page as these are all things you can only do from within a rule or script.

10 is a bit tricky and I would almost go so far as to propose that it needs its own page.

I really do not understand why OH has this reputation for requiring strong Java skills to use. The rules are not written in Java. The items and sitemap have nothing to do with Java. You do need to know Java to write your own binding but that is necessarily a small portion of the user population. I never hear people saying “You have to be a hard core Java program to 3D model in Maya” which, like OH, is largely written in Java (or at least it used to be) and offers a non-Java scripting language and plugins mechanism.

Also, my experience on this forum is that hardcore java people are the minority of OH users, though that is admittedly a biased sampling.

1 Like

I agree with Rich – please don’t try to put everything possibly related to items on the items wiki page. In my opinion, the page should be a reference explaining items: their concepts, what kinds of items openHAB has to offer, and how to define them. When documentation is well organized, you can instead link to other wiki pages. Don’t try to compensate for any perceived disorganization by putting everything on the one page – that only makes it harder for the reader to follow. Only provide (concise) examples for the specific areas the page is about, not more elaborate examples or tutorials; those belong elsewhere.

1 Like

Handy tip if you want to monitor changes to the openHAB wiki from Windows or Mac, to help ensure that only high quality changes are made:

  1. Download, install and launch SourceTree.
  2. Click + New Repository and choose Clone from URL.
  3. Enter as the Source URL. Choose some directory on your local disk to hold the clone (SourceTree will suggest one).
  4. Double click on the new repository to open it. You should see a list of all changes to the wiki, and who made them.
  5. Under Preferences, enable “Check default remotes for updates every __ minutes”.
  6. If you see a change to a wiki page that could be improved, go improve it, or start or find a discussion to make sure you understand why the change was made.


Please don’t use HTML tables in the wiki pages, but instead use the much cleaner and easier-to-maintain markdown format. For example:

OpenHAB provides you the following item types (alphabetical order):

Item Type | Description | Accepted Data Types | Accepted Command Types
Call | Telephone call by origin and destination | Call |
Color | Color information (RGB)| OnOff, Percent, HSB | OnOff, IncreaseDecrease, Percent, HSB
Contact | OPEN or CLOSED (e.g., door/window contacts) | OpenClosed |
DateTime | date and time | DateTime| DateTime
Dimmer | Level for dimmers | OnOff, Percent | OnOff, IncreaseDecrease, Percent
Group | group other items | |
Location | latitude, longitude and optional altitude | Point |Point
Number | numerical value | Decimal | Decimal
Rollershutter | blinds or similar devices | UpDown, Percent | UpDown, StopMove, Percent
String | textual information | String, DateTime | String
Switch | Typically used for lights (on/off) | OnOff | OnOff

Also, please verify every difference you’ve introduced from the previous versions of the wiki page against the actual source code. For the descriptions of item types, please use the long-standing descriptions in the source code as well.

Thanks very much!

[quote=“rlkoshak, post:11, topic:6860”]
I really do not understand why OH has this reputation for requiring strong Java skills to use. [/quote]

In fact, I didn’t (and don’t :smile:) have any skills in java or even skills in one part of used software in openHAB, but I’m at least willing to learn what to do for something to reach. And not to forget, openHAB is (and will be) completely free of charge, so anyone should be willing to invest at least time to learn :wink:

I ment as a link to the GPIO page of course, but it is important to write something about initializing of items, especially GPIO. This has been a showstoper for OH for some of my mates, due to missing explanation that GPIO pins needs to be reset when using them.

However get more pictures in the wiki:) Makes it more interesting for people to start with OH. I absolutely love OH but a bunch of text without pictures and examples has scared of most of my colluges. The more people we get to use OH the better it gets!!

I still disagree. All the documentation, including any special cases like needing to reboot OH, belongs on the GPIO Binding page, not the high level Items page. This high level page should document how it is supposed to work. When a binding doesn’t work that way it should be documented on the binding’s page. If we are to keep references and links on these top level pages for all the special cases across the 150+ addons it will become a maintenance nightmare and make the higher level page overwhelming and less useful.


My sentence would be along these lines.
Items are not initialized during startup, to initialize items you need to make startup rule(hyperlink), this is especially critical for GPIO blocking (hyperlink), temperature sets among others.

Personally i mean there should be an option for initializing items in .items files. For instance if I am on holiday in Thailand and i have a power shortage at home where it might be -15C things starts to freeze pretty quickly. So if I am not using a startup rule saying that heating should be ON and not OFF which is default it can be an expensive holiday. In totally there a lot of items that needs to be initialized with some sensible value, and now if I change name of the item or add items, I have to rember to update the initialization rules. Its OK, but it would be nicer and more elegant to do so in the item file itself.

There is a way to initialize items at startup without a rule. Persistence with the restoreOnStartup strategy restores your Item’s state to whatever they were before OH went down, which in my experience is far preferable to a hard coded initial value 99% of the time. That will cover most cases and in the few remaining cases where the last value isn’t good enough (or you are using rrd4j and you have String Items to restore) then a System started rule that somehow polls for the current value or hard codes a value. This is the correct solution IMHO.

However, there is a small gap which requires some extra work to boot strap your Item’s value when you first create an Item so it doesn’t have a value in Persistence yet. In this case you may need to temporarily add a System started rule or add something to your sitemap to give the new Item its very first value. This is the only argument I can see right now in favor of adding a way to define an initial value in the .items files.

I would be much more in favor of a section that discusses:

  1. The behavior: when OH first starts up or any rules file is changed the State of all Items is reset to undefined. This is actually something that has come up a lot on the Forum.
  2. Something along the lines of the paragraph above with links to the restoreOnStartup section of Persistence and the System started section in Rules.

I think it is reasonable for the top level pages to link to each other. I am still strongly against linking a top level description page to a specific binding’s page.

I’m also strongly in favor of @watou’s admonition to only make edits to the wiki that you are certain you have the full understanding of how OH works. So in this case before I would make the changes I proposed I would take the time to review the Items loading code to make sure what I seem to observe is indeed what the code is doing.

Great Rich:)

I am waiting for a wiki that tells me how to set up persistence on startup then. I just mean this is an important topic that somehow easily should be clarified(linked somehow) to the items page, so that beginners easily can grasp whats going on on startup and why the values are what they are. I leave it up to you native speakers and and OH experts to modify the wiki. I will just keep commenting on things that I as a beginner find hard to grasp as i dig deeper in the the mystic of OH. Keep up the amazing work. I’m blessed away with the capabilities of OH.

Items are not initialized during startup, to initialize items you need to make startup rule(hyperlink) or / and use persitance(link), this is especially critical for GPIO blocking (hyperlink), temperature sets among others.

[quote=“skatun, post:20, topic:6860, full:true”]
I am waiting for a wiki that tells me how to set up persistence on startup then[/quote]

You don’t have to wait, just read it :grinning: and
especially for startup further down that page