Post date: May 01, 2015 1:4:14 PM
Items are objects that can be read from or written to in order to interact with them.
Items can be bound to bindings i.e. for reading the status from e.g. KNX or for updating them. Read the wiki page for the respective binding for more help and examples.
Items can be defined in files in folder ${openhab_home}/configurations/items.
All item definition files have to have the file extension .items Just create a new file called thenameyouwish.items.
Groups are also defined in the .items files. Groups can be inside groups, and items can be in none, one or more groups.
Typically items are defined using the openHAB Designer by editing the items definition files. Doing so you will have full IDE support like syntax checking, context assist etc.
Items are defined in the followng syntax:
itemtype itemname ["labeltext"] [<iconname>] [(group1, group2, ...)] [{bindingconfig}]
Parts in square brackets [are optional.
Example:
Number Temperature_GF_Living "Temperature [%.1f °C]" <temperature> (GF_Living) {knx="1/0/15+0/0/15"}
Above example defines an item...
The following item types are currently available (alphabetical order):
Group items can also have a summary value displayed.
AVG displays the average of the items in the group.
OR displays an OR of the group, typically used to display whether any item in a group has been set.
other summaries: AND, SUM, MIN, MAX, NAND, NOR
Example for a group summary:
Group:Number:AVG() itemname ["labeltext"] [<iconname>] [(group1, group2, ...)] [{bindingconfig}] Group:Switch:OR(ON, OFF) itemname ["labeltext"] [<iconname>] [(group1, group2, ...)] [{bindingconfig}]
The item name is the unique name of the object which is used e.g. in the sitemap definition or rule definition files to access the specific item.
The label text is used on the one hand side to display a description for the specific item e.g. in the sitemap, on the other hand to format the output of number or string item types.
Formatting is done applying standard Java formatter class syntax.
Example:
An item defined like Number MyTemp "Temperature [%.1f] °C" would be formatted for output as: "Temperature 23.2 °C"
Another possibility in labeltexts is to use so-called maps for replacing the item status name by e.g. human-readable words:
Example:
An item defined like Number WindowBathroom "Window is [MAP(en.map):%s]" would be formatted for output as: "Window is open" if there is a file called en.map in folder configurations/transform.
These map files have to be structured as simple key/value pairs: 0=closed 1=opened UNDEFINED=unknown
See the sample map files in the source code repository online here:https://github.com/openhab/openhab/tree/master/distribution/openhabhome/configurations/transform
Example:
An item defined like DateTime Weather_LastUpdate "Last Update [%1$ta %1$tR]" outputs two components which both are taken from the DateTime variable itself. So both have to reference the variable. This is done by 1$. Following t marks a time object. a and Rrepresent the date formatter "abbreviated month name" and "24-hour clock", respectively.
Note: The first 1$ is optional, as the first components always takes the first input argument. However, as the second components would take the second input argument by default but there is only one input argument (namely the DateTime variable itself), the second 1$ is essential.
The icon name is used to reference a png image file from folder${openhab_home}/webapps/images/. These icons are used in the openHAB frontends.
Please use the filename (without extension) of icons in above mentioned folder. If you append e.g. "-on" and "-off" to the file name the icon will change its appearance depending on the switch item state. Resp. you can add "-0", "-1" etc. to the filename for number items, "-on" / "-off" for switches and anything else for string items etc. A file amongst files having such additions that has no addition representes an uninitialized state. Make shure to to use small letters for filenames only.
Example:
You can use two icons "present-on.png" and "present-off.png" like this:
Switch DanHome "Dan at home" <present>
Items can be linked to specific groups by referencing these in a comma separated list embraced by round brackets.
Example:
An item defined like Number MyTemp (gTempOutside, gTemperatures) would be member of the groups gTempOutside and gTemperatures
Items can be bound to specific openHAB bindings by adding a binding definition in curly brackets at the end of the item definition:
{ ns1="bindingconfig1", ns2="bindingconfig2", ...}
where "nsx" is the namespace for a certain binding (e.g. "knx", "bluetooth", "serial" etc.).
For detailed binding configuration syntax of openHAB bindings please see the openHABBindings configuration section.
Example:
Switch Light_GF_Living_Table "Table" (GF_Living, Lights) { knx="1/0/15+0/0/15" } Switch Presence { bluetooth="123456ABCD" } Switch Doorbell "Doorbell" <bell> { serial="/dev/usb/ttyUSB0" }
from the demo file
The openHAB runtime comes with a demo items file, here is a short excerpt from it:
Group gAll Group Status (gAll) Group gGF (gAll) Group gLights (gAll) Group gShutters (gAll) Group gGF_Living "Living room" <video> (gGF) Group:Number:AVG gTemperature "Avg. Room Temp. [%.1f °C]" <temperature> /* Lights */ Switch Light_GF_Living_Table "Table" (gGF_Living, gLights) /* Rollershutters */ Rollershutter Shutter_GF_Living "Shutter" (gGF_Living, gShutters) /* Indoor Temperatures */ Number Temperature_GF_Living "Temperature [%.1f °C]" <temperature> (gTemperature, gGF_Living) Number Temperature_GF_Kitchen "Temperature [%.1f °C]" <temperature> (gTemperature, gGF_Kitchen)
Groups can be inside groups, and items can be in none, one or more groups. For example:
Group gGF (All) This statement defines the gGF group and states that it belongs to the All group.
Group GF_Living "Living room" <video> (gGF) This statement defines the group GF_Living, defines that the user interface will show it as "Living room", defines the icon to be shown and states that it belongs to (gGF). Notice that the gGF group belongs to the ALL group, hence GF_Living inherits that group, and it belongs to the All group too.
Group:Number:AVG Temperature "Average lighting [Lux](%.1f)" <temperature> (Status): this statement means that there is a group called Temperature, which has a value calculated as an average of all its members, and its value is a float with one decimals. It will show a temperature icon and it belongs to the Status group.
knx example
The items may include the KNX group address to use them. They might be actively read by openHAB or not. They look like this:
Number Lighting_Room_Sensor "Lighting in the Room [Lux](%.2f)" <switch> (Room,Lighting) { knx = "<0/1/1" }: This is a sensor item. It uses the 0/1/1 group address and openHAB will ask for its value periodically because there is a "<" sign before the address. It is a number item, called Lighting_Room_Sensor, and belongs to Room and Lighting groups.
Switch Light_Room_Table "Table Light" (Room, Lights) { knx = "<0/1/10+0/1/30"}: This is a switch item that has two addresses. openHAB may responds to events in any of them, but may actively read the first one.
For more info about other options have a look at the demo.items file and the wiki bindings pages.
Further examples for defining items can be found in our openHAB-samples section.
The currently implemented item types can be found in source code.