openhab-docs/concepts/items.md

layout
documentation

{% include base.html %}

Items

Eclipse SmartHome has a strict separation between the physical world (the "things", see below) and the application, which is built around the notion of "items" (also called the virtual layer).

Items represent functionality that is used by the application (mainly user interfaces or automation logic). Items have a state and are used through events.

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

Itemname	Description	Command Types
Color	Color information (RGB)	OnOff, IncreaseDecrease, Percent, HSB
Contact	Item storing status of e.g. door/window contacts	OpenClose
DateTime	Stores date and time
Dimmer	Item carrying a percentage value for dimmers	OnOff, IncreaseDecrease, Percent
Group	Item to nest other items / collect them in groups	-
Number	Stores values in number format	Decimal
Player	Allows to control players (e.g. audio players)	PlayPause, NextPrevious, RewindFastforward
Rollershutter	Typically used for blinds	UpDown, StopMove, Percent
String	Stores texts	String
Switch	Typically used for lights (on/off)	OnOff

Group Items can derive their own state depending on their member items.

• AVG displays the average of the item states in the group.
• OR displays an OR of the group, typically used to display whether any item in a group has been set.
• other aggregations: AND, SUM, MIN, MAX, NAND, NOR

State and Command Type Formatting

DateTime

DateTime objects are parsed using Java's SimpleDateFormat.parse() using the first matching pattern:

1. yyyy-MM-dd'T'HH:mm:ss.SSSZ
2. yyyy-MM-dd'T'HH:mm:ss.SSSX
3. yyyy-MM-dd'T'HH:mm:ssz
4. yyyy-MM-dd'T'HH:mm:ss

DecimalType, PercentType

DecimalType and PercentType objects use Java's BigDecimal constructor for conversion. PercentType values range from 0 to 100.

HSBType

HSB string values consist of three comma-separated values for hue (0-360°), saturation (0-100%), and value (0-100%) respectively, e.g. 240,100,100 for blue.

PointType

PointType strings consist of three DecimalTypes separated by commas, indicating latitude and longitude in degrees, and altitude in meters respectively.

Enum Types

Type	Supported Values
IncreaseDecreaseType	INCREASE, DECREASE
NextPreviousType	NEXT, PREVIOUS
OnOffType	ON, OFF
OpenClosedType	OPEN, CLOSED
PlayPauseType	PLAY, PAUSE
RewindFastforwardType	REWIND, FASTFORWARD
StopMoveType	STOP, MOVE
UpDownType	UP, DOWN