OpenHAB
/
openhab-docs
mirror of https://github.com/openhab/openhab-docs.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
openhab-docs/configuration/items.md

22 KiB
Raw Blame History

layout title
documentation Items

{% include base.html %}

Items

In openHAB "Items" represent all properties and capabilities of the user’s home automation.

While a device or service might be quite specific, Items are unified substitutions inside the openHAB world. Items can be Strings, Numbers, Switches or one of a few other basic Item types, a programmer can rightly compare Item Types with base variable types of a programming language.

One unique feature of openHAB Items (in comparison to normal variables) is the possibility to connect them to the outside world (via Bindings, more about that later). An Item does not simply hold a certain information (e.g., "No Error", 3.141, OFF), the information is synchronized with the real world in both ways.

But let's not get ahead of ourselves. The rest of this page contains all details regarding Items and is structured as follows:

{::options toc_levels="2..4"/}

  • TOC {:toc}

Introduction

Items are basic data types and have a state which can be read from, or written to, in order to interact with them.

Items can be bound to Bindings or linked to Channels. For example, an Item bound to a sensor receives updated sensor readings and an Item linked to a light's dimmer Channel can set the brightness of the light bulb. Read the docs page for the respective Binding to get more information about possible connections and examples.

There are two methods for defining Items:

  1. The first is through PaperUI. Generally all 2.x version Bindings can be configured through PaperUI. Other 1.x and legacy Bindings do not offer this path.

  2. The second method is through text .items files in the items folder. Files here must have the extension .items and you can create as many .items files as you need/want - however, each Item must be unique across them all. Refer to the installation docs to determine your specific installations folder structure. Generally 1.x version Bindings can only be bound to Items through .items files. 2.x Bindings can also be used with this method

Assumptions for PaperUI: The following content will discuss details of item definition on the example of .items files.

Editor Recommendation: It's recommended to edit .items files using the Eclipse SmartHome Designer. Doing so you will have full IDE support like syntax checking, context assist, etc.

Item Definition and Syntax

Items are defined in the following syntax. The parts of an Item must be defined in this order. Besides the itemtype and itemname all parts are optional.

itemtype itemname "labeltext" <iconname> (group1, group2, ...) ["tag1", "tag2", ...] {bindingconfig}

Examples:

Number BathRoom_WaschingMachine_Power "Power [%.0f W]" <energy> (gPower) {channel="homematic:HG-HM-ES-PMSw1-Pl:ccu:LEQ1275872:2#POWER"}
Switch Kitchen_Light "Kitchen Light OnOff" {mqtt="<[...], >[...]" }
String BedRoom_Sonos_CurrentTitle "Title [%s]" (gBedRoom) {channel="sonos:PLAY3:RINCON_C5E93734496A0A400:currenttitle"}

Number LivingRoom_Temperature "Temperature [%.1f °C]" <temperature> (gTemperature, gLivingRoom) ["TargetTemperature"] {knx="1/0/15+0/0/15"}

The last example above defines an Item with the following parts:

  • Item type Number
  • Item name LivingRoom_Temperature
  • Item state formatted in a way which will produce for example "21.5 °C" as its output
  • Item displaying icon with the name temperature
  • Item belongs to groups gTemperature and gLivingRoom
  • Item is tagged as a thermostat ("TargetTemperature")
  • Item is bound to the openHAB Binding knx with binding specific settings

The remainder of this article describes the Item definition parts in more detail.

Type

The Item type defines which kind of state can be stored in that Item and which commands can be sent to it, e.g. String, Number or binary Switch. They are comparable with basic variable data types in programming languages.

Each Item type has been optimized for certain components in your smart home. This optimization is reflected in the data types, and command types.

All available openHAB2 Item types and their relevant commands can be viewed here: Item Types.

Dimmer vs. Switch: While a Dimmer Item can accept either On/Off, Increase/Decrease, or Percent updates or command, a Dimmer Item stores its state as a Percent value. See the following example:

Item:

Dimmer Office_Light "Dimmer [%d %%]" {milight="bridge01;3;brightness"}

Sitemap:

Switch item=Office_Light
Slider item=Office_Light

When the Switch widget is used, it sends ON or OFF commands to the Item which are mapped to 100% and 0%, respectively. When the Slider widget is used, it sends Percent commands (values between 0 and 100) to the Item, which are used as the Item's state. In the example above, if you move the Slider widget to 60%, move the Switch to OFF, and finally move the switch to ON, the Item's state will be 100%.

Name

The Item name is the unique identified of the Item. The name should only consist of letters, numbers and the underscore character. Spaces and special characters cannot be used. A good naming schema can be advised.

Label

The label text has two purposes. First, this text is used to display a description of the specific Item (for example, in the Sitemap).

Secondly, the label also includes the value displaying definition for the Item's state. This part is contained inside "[ ]" in the label and can be left out to not display the state of an Item.

State

The state part of the Item definition determines the Item value presentation, e.g., regarding formatting, decimal places, unit display and more. The state definition is part of the Item Label definition and contained inside square brackets ()"[ ]").

State Formatting

Formatting is done applying Java formatter class syntax, therefore the syntax is

[%[argument_index$][flags][width][.precision]conversion]

Only the leading '%' and the trailing 'conversion' are mandatory. The argument_index$ must be used if you want to convert the value of the Item several times within the label text or if the Item has more than one value. Look at the DateTime and Call Item in the following example.

Number    MyTemperature  "The Temperature is [%.1f] °C"   { someBinding:somevalue }
String    MyString       "Value: [%s]"                    { someBinding:somevalue }
DateTime  MyLastUpdate   "Last Update: [%1$ta %1$tR]"     { someBinding:somevalue }

The output would look like this:

Temperature 23.2 °C
Value: Lorem ipsum
Last Update: Sun 15:26

State Transformations

Another possibility in label texts is to use a transformation. They are used for example to translate a status into another language or convert technical value into human readable ones. To do this you have to create a .map file in your transform folder. These files are typical key/value pair files.

key1=value1
key2=value2
...

Let's make a small example to illustrate this function. If you have a sensor which returns the number 0 for a closed window and 1 for an open window, you can transform these values into the words "opened" or "closed". Create a map file named window.map for example and add the desired keys and values.

0=closed
1=opened
NULL=unknown
-=unknown

Next we define two Items. One showing the raw value as it is provided from our sensor and one with transformed value.

Number WindowRaw          "Window is [%d]"                  { someBinding:somevalue }
Number WindowTransformed  "Window is [MAP(window.map):%s]"  { someBinding:somevalue }

The output will be:

Window is 1
Window is opened

Transform files use UTF-8 encoding, so Unicode symbols will also work.

ARIES=♈ Aries
TAURUS=♉ Taurus
WAXING_CRESCENT=🌑→🌓 Waxing Crescent
FIRST_QUARTER=🌓 First Quarter

Icons

The icon name is used to reference an image presented next to an Item, e.g. in BasicUI.

openHAB provides a set of classic icons by default. Additional icons can be placed under icons/classic/ inside the openHAB configuration folder.

Custom Icons must abide to the following file name restrictions to be accepted by openHAB:

  • png or svg file format

  • Only lowercase letters, numbers and underscores (_)

  • No uppercase letters or special characters.

  • Hyphens (-) are reserved for Dynamic Icons (see below)

  • Examples:

    • Good: switch.svg, power_meter.png, error2.svg
    • Bad: PC_Display.svg, power-meter.png, tür⇔.svg

Bitmaps or Vector Graphics: openHAB can work with either Bitmap (.png) or Vector (.svg) icon files. The format used needs to be configured for the individual interfaces (e.g. BasicUI). It is thereby important to decide on one format beforehand, vector graphics are recommended. The setting can be done via PaperUI or inside the configuration files classicui.cfg and basicui.cfg. Images in the respective other format will be ignored.

Predefined icons from the default icon set can be replaced.

Dynamic Icons

An icon can consist of an icon family, from which one icon is dynamically selected depending on the Item's state. The state related part of an icon is appended to the icon name after the special hyphen delimiter.

To give an example:

File name Description
switch.svg default, used when no other matching icon is found
switch-off.svg Matches OFF or "off" state
switch-on.svg Matches ON or "on" state

Dynamic icon families must meet the following criteria:

  • there must be a default icon

  • the state part of the icon must consist of all lower case letters (even if the state of the Item includes uppercase letters)

The name of dynamic icons must meet the following format:

<name>-<state>.<png or svg>
  • <name> is the name of the icon set
  • -<state> is the state that particular icon maps to, the icon without the state part is the default
  • <png or svg> based on the format of the icon, use the default format as explained above.

To use the dynamic Items the default icon name without state and extension is used.

Switch  Light_FrontDoor  "Front Door light is [MAP(en.map):%s]"  <switch>  {somebinding:someconfig}

State Matching Rule: For Number Items openHAB will use the equal or next lowest state icon that can be found. For a dimmer light (0 - 100%), you might provide icons as in the example:

File name Description
dimmer.svg default icon (used in the undefined state)
dimmer-0.svg off light icon (0%)
dimmer-1.svg dimmed light icon (1% up to 74%)
dimmer-75.svg bright light icon (75% up to 100%)

Warning about the Influence of Transformations: As mentioned above, the state used by the Sitemap to select the proper icon is the transformed state. When using a MAP in the label, the icon name must match the mapped state displayed on the Sitemap, not the raw Item's state. To use the Number Window example from above, the icons for Number Window would be:

  • window.png
  • window-1.png
  • window-0.png

and the icons for Number WindowTransformed would be:

  • window.png
  • window-open.png
  • window-closed.png

Groups

The Group is a special Item Type. It is used to define a category or collection in which you can nest/collect other Items or other Groups. Groups are supported in Sitemaps, Automation Rules and other areas of openHAB.

A simple example Group definition is:

Group Temperatures

Group State: A Group also has a state. The Group's state is an aggregation of the states of all its members. Sending a command to a Group will cause that command to be forwarded to all the Group's members.

Items can be in none, one, or multiple groups, groups can be nested inside other groups.

Nested Groups

Groups can be nested inside each other. This functionality is commonly used to define hierarchies of Items from different perspectives.

  • Regional perspective: e.g. Stories of a Building → Corridors on that story → Rooms along the corridor ...
  • Data perspective: e.g. Room temperatures, power consumption, all lights in the Building, ....
  • Maintenance perspective: e.g. Error states, Battery health, ...
  • and so on ...

Let's look at the example below:

Group gAll
Group gRoom        (gAll)
Group gLivingRoom  (gRoom)
Group gSensor      (gAll)
Group gTemperature (gSensor)

Number Sensor_Temperature  "Temperature [%.1f °C]"  <temperature>  (gTemperature)  {knx="1/0/15+0/0/15"}

The Item Sensor_Temperature is a member of the Group gTemperature, which is itself a member of the Group gSensor, which is a member of the Group All.

This relation can be exploited in sitemaps or in automation rules.

Group Types

Group Items can also be used to easily determine one or more Items with a defined value or can be used to calculate a value depending on all values within the Group. Please note that this can only be used if all Items in the Group have compatible types (otherwise the calculated state will most likely be UNDEF.

The format for this is:

Group:itemtype:function  itemname  ["labeltext"]  [<iconname>]  [(group1, group2, ...)]

As an example consider a group of switches:

Group:Switch:OR(ON,OFF)  mySwitches

The state of the mySwitches group will be ON if any of the members states are ON. But this means that once one Item in the group has its state changed to ON, the group's state gets set. Each subsequent Item that changes state to ON will not trigger "mySwitches changed" because the group isn't changing.

This is not a bug, it is the expected and designed behavior. Because the group state is an aggregate, every change in the Item members does not necessarily result in a change to the group's state.

If you omit the type or function definitions for a group the following behavior is used:

If there is a type but no function like in the example below,

Group:Switch  mySwitches

the function EQUAL (Equality) will be used.

If you omit the type AND the function the group state will NOT be influenced by its members, i.e. such a group is only useful for grouping items in GUIs.

Group functions can be any of the following:

Function Description
EQUAL Default, if no function is specified. (a type for the group MUST be set). If ALL members have state X the group state will be X, otherwise it is UNDEF.
AND(value1, value2) This does a logical 'AND' operation. Only if all items are of 'value1' this is returned, otherwise the 'value2' is returned.
AVG Calculates the numeric average over all item values of decimal type.
MAX This calculates the maximum value of all item values of decimal type.
MIN This calculates the minimum value of all item values of decimal type.
NAND(value1, value2) This does a logical 'NAND' operation. The value is 'calculated' by the normal 'AND' operation and than negated by returning the opposite value. E.g. when the 'AND' operation calculates the value1 the value2 will be returned and vice versa.
NOR(value1, value2) This does a logical 'NOR' operation. The value is 'calculated' by the normal 'OR' operation and than negated by returning the opposite value. E.g. when the 'OR' operation calculates the value1 the value2 will be returned and vice versa.
OR(value1, value2) Does a logical 'OR' operation. If at least one item is of 'value1' this is returned, otherwise the 'value2' is returned.
SUM Calculates the sum of all items in the group.

Tagging

Tagging is a new feature under development. Tags are used by some I/O add-ons, see Hue Emulation for more details.

Tags are only of interest if an add-on or integration README explicitly discusses their usage.

Binding Configuration

As mentioned above, there are two ways to bind/link a device to an Item: 1.x Binding Configs and 2.x Channel Linking.

When you install a Binding through PaperUI it will automatically create a .cfg file in conf/services/ for the appropriate Binding. Inside these files are a predefined set of variables which are required for the Binding to operate. In many cases you will need to view and edit these to suit your system. These variables can hold IP addresses, API keys, user names, passwords etc. These are all in plain text, so be careful who you share these with if some data is sensitive.

1.x Binding Configuration

The 1.x Binding configuration defines from where the Item gets it values, and where a given value/command should be sent.

You bind an Item to a Binding by adding a Binding definition in curly brackets at the end of the Item definition:

{ ns="192.168.1.123:80" }

Where "ns" is the namespace for a certain Binding like "network", "netatmo", "zwave" etc. Every Binding defines what values must be given in the Binding configuration string. That can be the id of a sensor, an ip or mac address or anything else. You must have a look at your Bindings configuration section to know what to use. Some typical examples are:

Switch Phone_Mobile        "My Mobile Phone"               { nh="192.168.1.123:80" }
Number Netatmo_Indoor_CO2  "CO2 [%d]"                      { netatmo="00:00:00:00:00:00#Co2" }
Number Azimuth             "Azimuth [%d]"                  { astro="planet=sun, type=position, property=azimuth" }
Contact Garage             "Garage is [MAP(en.map):%s]"    { zwave="21:command=sensor_binary,respond_to_basic=true" }

If you need to use legacy openHAB 1.x Bindings then you need to enable this feature through the PaperUI menu by turning on "Include Legacy 1.x Bindings" found at /configuration/services/configure extension management/. After downloading the legacy .jar files, they need to be placed in the /addons/ folder. If further configuration is required then you will need to create an openhab.cfg file in /conf/services/ and paste the appropriate Binding configuration into this. For all other native openHAB2 Bindings, configuration is done through a bindingname.cfg file in the same location.

2.x Binding Configs

The 2.x Bindings introduce the concept of Things and Channels. Unlike with 1.x version Bindings which each define their own format for the Binding config that is defined on the Item itself, 2.x Bindings define those parameters in a Thing. Each Thing has one or more Channels and Items are linked to one or more Channels.

Some Bindings support automatic discovery of Things in which case discovered Things will appear in the Inbox in PaperUI. Once accepted it will appear under Configuration > Things.

Other Bindings support defining Things in a .things file.

See the Bindings configuration section to know how to discover or manually define Things for a given Binding.

PaperUI Linking

One can link an Item with a Channel using PaperUI.

  1. First create the Item in PaperUI under Configuration Items.
  2. Next navigate to the Thing that has the Channel to link to the Item.
  3. Click on the expand icon to the right of the Channel to link to the Item and press the + next to "Linked Items."
  4. Select the Item from the list and press "Link".
Text File Linking

One can also link an Item with a Channel using the .items file. Information about available Channels and options can be found in the Binding readme or discovered via PaperUI.

In PaperUI select a Thing to learn about all Channels the Thing support.

Linking an Item to a Channel is of the form {channel="channel id"}. Some examples:

Switch  Phone_Mobile       "My Mobile Phone"               { channel="network:device:devicename:online" }
Number  Netatmo_Indoor_CO2 "CO2"                           { channel="netatmo:NAMain:home:inside:Co2" }
Number  Azimuth            "Azimuth"                       { channel="astro:sun:home:position#azimuth" }
Contact Garage             "Garage is [MAP(en.map):%s]"    { channel="zwave:21:command=sensor_binary,respond_to_basic=true" }

Multi Binding/Channel Linkage

One Item can be linked to multiple Bindings and/or Channels. Commands and Updates from and to these will be mixed/combined and can be used in interesting ways.

Switch Office_PC { nh="192.168.3.203", wol="192.168.0.2" }
Number Temperature { mysensors="24;1;V_TEMP", expire="5m,-999" }

The first example shows a symbiosis of the network health Binding and the Wake-on-LAN Binding to interact with a PC. The second example shows a prominent use case for the expire Binding where the mysensors Binding will update temperature readings regularly but the expire Binding will also listen and eventually modify the Item state.

Exception autoupdate

autoupdate="false" is a special instruction which keeps the current state of the item, even if a command has been received. This way, the Item is always unchanged unless you explicitly post an update to the item.

Switch Garage_Gate { binding="xxx", autoupdate="false"}

Restore States

When restarting your openHAB installation you may find there are times when your logs indicate some Items are UNDEF. This is because, by default, Item states are not persisted when openHAB restarts. To have your states persist across restarts you will need to install a Persistence extension.

Specifically, you need to use a restoreOnStartup strategy for all your Items. Then whatever state they were in before the restart will be restored automatically.

Strategies {
    default = everyUpdate
}

Items {
    // persist all Items on every change and restore them from the MapDB at startup
    * : strategy = everyChange, restoreOnStartup
}