OpenHAB - Explanation of items

Post date: May 01, 2015 1:4:14 PM

introduction

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.

syntax

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...

itemtype

The following item types are currently available (alphabetical order):

Group items can also have a summary value displayed.

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}]

itemname

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.

labeltext

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.

iconname

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>

groups

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

bindingconfig

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" }

examples

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:

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:

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.