Declaring Configurations, Bindings and Things

Specific services and bindings have to provide meta information which is used for visualization, validation or internal service mapping. Meta information can be provided by registering specific services at the OSGi service registry or by specifying them in a declarative way, which is described in this chapter.

Three kinds of descriptions/definitions exist:

  • Configuration descriptions: Used for visualization and validation of configuration properties (optional)
  • Binding definitions: Required to declare a binding (mandatory)
  • Bridge and Thing descriptions: Required to specify which bridges and Things are provided by the binding, which relations they have to each other and which channels they offer (mandatory)

Configuration Descriptions

Specific services or bindings usually require a configuration to be operational in a meaningful way. To visualize or validate concrete configuration properties, configuration descriptions should be provided. All available configuration descriptions are accessible through the org.eclipse.smarthome.config.core.ConfigDescriptionRegistry service.

Although configuration descriptions are usually specified in a declarative way (as described in this section), they can also be provided as org.eclipse.smarthome.config.core.ConfigDescriptionProvider. Any ConfigDescriptionProviders must be registered as service at the OSGi service registry. The full Java API for configuration descriptions can be found in the Java package org.eclipse.smarthome.config.core. In addition to this there is a org.eclipse.smarthome.config.core.validation.ConfigDescriptionValidator that can be used to validate a set of configuration parameters against their declarations in the configuration description before the actual configuration is updated with the new configuration parameters.

Configuration descriptions must be placed as XML file(s) (with the ending .xml) in the bundle’s folder /ESH-INF/config/.

Formatting Labels

The label and descriptions for things, channels and config descriptions should follow the following format. The label should be short so that for most UIs it does not spread across multiple lines. The description can contain longer text to describe the thing in more detail. Limited use of HTML tags is permitted to enhance the description - if a long description is provided, the first line should be kept short and a line break (<br>) should be placed at the end of the line to allow UIs to display a short description in limited space.

Configuration options should be kept short so that they are displayable on a single line in most UIs. If you want to provide a longer description of the options provided by a particular parameter, then this should be placed into the <description> of the parameter to keep the option label short. The description can include limited HTML to enhance the display of this information.

The following HTML tags are allowed -: <b>, <br>, <em>, <h1>, <h2>, <h3>, <h4>, <h5>, <h6>, <i>, <p>, <small>, <strong>, <sub>, <sup>, <ul>, <ol>, <li>. These must be inside the XML escape sequence - eg. <description><![CDATA[ HTML marked up text here ]]></description>.

XML Structure for Configuration Descriptions

<?xml version="1.0" encoding="UTF-8"?>
<config-description:config-descriptions
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:config-description="http://eclipse.org/smarthome/schemas/config-description/v1.0.0"
    xsi:schemaLocation="http://eclipse.org/smarthome/schemas/config-description/v1.0.0
        http://eclipse.org/smarthome/schemas/config-description-1.0.0.xsd">

  <config-description uri="{binding|thing-type|bridge-type|channel-type|any_other}:bindingID:...">
    <parameter-group name="String">
      <label>String</label>
      <description>String</description>
      <context>String</context>
      <advanced>{true|false}</advanced>
    </parameter-group>

    <parameter name="String" type="{text|integer|decimal|boolean}" min="Decimal" max="Decimal" step="Decimal" pattern="String" required="{true|false}" readOnly="{true|false}" multiple="{true|false}" groupName="String" unit="A|cd|K|kg|m|mol|s|g|rad|sr|Hz|N|Pa|J|W|C|V|F|Ω|S|Wb|T|H|Cel|lm|lx|Bq|Gy|Sv|kat|m/s2|m2v|m3|kph|%|l|ms|min|h|d|week|y">
      <context>{network-address|serial-port|password|password-create|color|date|datetime|email|month|week|dayOfWeek|time|tel|url|item|thing|group|tag|service|channel|rule|location}</context>
      <required>{true|false}</required>
      <default>String</default>
      <label>String</label>
      <description>String</description>
      <unitLabel>String</unitLabel>
      <options>
        <option value="String">String</option>
      </options>
      <filter>
        <criteria name="String">String</criteria>
      </filter>
    </parameter>
  </config-description>

  <config-description uri="{binding|thing-type|bridge-type|channel-type|any_other}:bindingID:...">
    ...
  </config-description>
...
</config-description:config-descriptions>
PropertyDescription
config-description.uriThe URI of this description within the ConfigDescriptionRegistry (mandatory).
parameterThe description of a concrete configuration parameter (optional).
parameter.nameThe name of the configuration parameter (mandatory).
parameter.typeThe data type of the configuration parameter (mandatory).
parameter.minThe minimal value for numeric types, or the minimal length of strings, or the minimal number of selected options (optional).
parameter.maxThe maximum value for numeric types, or the maximum length of strings, or the maximum number of selected options (optional).
parameter.stepThe value granularity for a numeric value (optional).
parameter.patternThe regular expression for a text type (optional).
parameter.requiredSpecifies whether the value is required (optional).
parameter.readOnlySpecifies whether the value is read-only (optional).
parameter.multipleSpecifies whether multiple selections of options are allowed (optional).
parameter.groupNameSets a group name for this parameter (optional).
parameter.unitSpecifies the unit of measurements. The unit declaration in the parameter definition shown above contains the set of valid units. The unit must only be set if the type of the parameter is either integer or decimal (optional).
advancedSpecifies that this is an advanced parameter. Advanced parameters may be hidden by a UI (optional).
verifySpecifies that this is parameter requires a verification stage with the user before sending. Parameters flagged with *verify=true* could be considered dangerous and should be protected from accidental use by a UI - eg by adding an "Are you sure" prompt (optional).
contextThe context of the configuration parameter (optional).
requiredThe flag indicating if the configuration parameter has to be set or not (deprecated, optional, default: false).
defaultThe default value of the configuration parameter (optional).
labelA human-readable label for the configuration parameter (optional).
descriptionA human-readable description for the configuration parameter (optional).
unitLabelThe unit label represents a human-readable label for the unit. It can also be used to provide unit labels for natural language units as iterations, runs, etc. The unit label must only be set if the type of the parameter is either integer or decimal (optional).
optionThe element definition of a static selection list (optional).
option.valueThe value of the selection list element.
multipleLimitIf multiple is true, sets the maximum number of options that can be selected (optional).
limitToOptionsIf true (default) will only allow the user to select items in the options list. If false, will allow the user to enter other text (optional).
criteriaThe filter criteria for values of a dynamic selection list (optional).
criteria.nameThe name of the context related filter.

Supported Contexts

Context is used to provide some semantic details about the parameter. The UIs use it to render different kind of input widgets. The following contexts require a specific format of the content:

custom input field</td>
NameTypeFormatSample implementation
network-addesstextIPv4,IPv6, domain name<input type="text"/>
serial-porttextSerial port name, e.g. COM1
passwordtextalphanumeric characters<input type="password"/>
password-createtextalphanumeric characterscustom password input
colortext#000000 - #ffffff (hex color)<input type="color"/>
datetextYYYY-MM-DD<input type="date"/>
datetimetextYYYY-MM-DD hh:mmcustom input field
emailtextusername@domain.com<input type="email"/>
monthtextmonth of yearcustom input field
weekintegerweek of yearcustom input field
dayOfWeektextMON, TUE, WED, THU, FRI, SAT, SUN
custom input field
timetext/integerhh:mm:ss/milliseconds since epoch<input type="time"/>
telephonetexttelephone numbercustom input field
urltextweb url<input type="url"/>
itemtextItem namecustom input field
thingtextUID of a thingcustom input field
grouptextgroup name to which this parameter belongs
tagtexttag namecustom input field
servicetextservice namecustom input field
channeltextUID of a channel
custom input field
ruletextUID of a rule
custom input field
locationtextlatitude,longitude[,altitude]
custom input field

Further, the item context can contain criteria to filter the list of items. For example:

<filter>
  <criteria name="type">Switch,Dimmer</criteria>
  <criteria name="tag">Light,Heating</criteria>
</filter>

In the case of above filter only those items will be shown that satisfy the filter’s conditions. The above filter is evaluated as follows:

(type=Switch OR type=Dimmer) AND (tag=Light OR tag=Heating) 

Similarly, the Channel context can contain criteria to filter channels based on kind field. The value of kind can either be STATE or TRIGGER. For example:

<filter>
  <criteria name="kind">STATE|TRIGGER</criteria>
</filter>

Groups allow parameters to be grouped together into logical blocks so that the user can find the parameters they are looking for. A parameter can be placed into a group so that the UI knows how to display the information.

PropertyDescription
group.nameThe group name - this is used to link the parameters into the group, along with the groupName option in the parameter (mandatory).
labelThe human-readable label of the group. (mandatory).
descriptionThe description of the group. (optional).
contextSets a context tag for the group. The context may be used in the UI to provide some feedback on the type of parameters in this group (optional).
advancedSpecifies that this is an advanced group. The UI may hide this group from the user (optional).

The full XML schema for configuration descriptions is specified in the ESH config description XSD file.

Hints:

  • Although the attribute uri is optional, it must be specified in configuration description files. Only for embedded configuration descriptions in documents for binding definitions and Thing type descriptions, the attribute is optional.

Example

The following code gives an example for one configuration description.

<?xml version="1.0" encoding="UTF-8"?>
<config-description:config-description uri="bridge-type:my-great-binding:my-bridge-name"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:config-description="http://eclipse.org/smarthome/schemas/config-description/v1.0.0"
    xsi:schemaLocation="http://eclipse.org/smarthome/schemas/config-description/v1.0.0
        http://eclipse.org/smarthome/schemas/config-description-1.0.0.xsd">

  <parameter name="ipAddress" type="text" required="true">
    <context>network-address</context>
    <label>Network Address</label>
    <description>Network address of the device.</description>
  </parameter>

  <parameter name="userName" type="text" required="true">
    <label>User Name</label>
  </parameter>

  <parameter name="password" type="text" required="false">
    <context>password</context>
  </parameter>

</config-description:config-description>

Binding Definitions

Every binding has to provide meta information such as binding id or name. The meta information of all bindings is accessible through the org.eclipse.smarthome.core.binding.BindingInfoRegistry service.

Although binding definitions are usually specified in a declarative way (as described in this section), they can also be provided as org.eclipse.smarthome.core.binding.BindingInfo. Any BindingInfo must be registered as service at the OSGi service registry. The full Java API for binding definitions can be found in the Java package org.eclipse.smarthome.core.binding.

Binding definitions must be placed as XML file(s) (with the ending .xml) in the bundle’s folder /ESH-INF/binding/.

XML Structure for Binding Definitions

<?xml version="1.0" encoding="UTF-8"?>
<binding:binding id="bindingID"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:binding="http://eclipse.org/smarthome/schemas/binding/v1.0.0"
    xsi:schemaLocation="http://eclipse.org/smarthome/schemas/binding/v1.0.0
        http://eclipse.org/smarthome/schemas/binding-1.0.0.xsd">

  <name>String</name>
  <description>String</description>
  <author>String</author>

  <config-description>
    ...
  </config-description>
  OR
  <config-description-ref uri="{binding|thing-type|bridge-type|channel-type|any_other}:bindingID:..." />

</binding:binding>
PropertyDescription
binding.idAn identifier for the binding (mandatory).
nameA human-readable name for the binding (mandatory).
descriptionA human-readable description for the binding (optional).
authorThe author of the binding (optional).
service-idThe ID (service.pid or component.name) of the main binding service, which can be configured through OSGi configuration admin service. Should only be used in combination with a config description definition (optional).
config-descriptionThe configuration description for the binding within the ConfigDescriptionRegistry (optional).
config-description-refThe reference to a configuration description for the binding within the ConfigDescriptionRegistry (optional).
config-description-ref.uriThe URI of the configuration description for the binding within the ConfigDescriptionRegistry (mandatory).

The full XML schema for binding definitions is specified in the ESH binding XSD file.

Hints:

  • The attribute uri in the section config-description is optional, it should not be specified in binding definition files because it’s an embedded configuration. If the uri is not specified, the configuration description is registered as binding:bindingID, otherwise the given uri is used.
  • If a configuration description is already specified somewhere else and the binding wants to (re-)use it, a config-description-ref should be used instead.
  • Normally the service id must not be defined, because it is implicitly set to “binding.<binding.id>”. A binding can register an OSGi service which implements the ManagedService interface and define the service.pid as e.g.”binding.hue” to receive the configuration.

Example

The following code gives an example for a binding definition.

<?xml version="1.0" encoding="UTF-8"?>
<binding:binding id="hue"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:binding="http://eclipse.org/smarthome/schemas/binding/v1.0.0"
    xsi:schemaLocation="http://eclipse.org/smarthome/schemas/binding/v1.0.0
        http://eclipse.org/smarthome/schemas/binding-1.0.0.xsd">

  <name>hue Binding</name>
  <description>The hue Binding integrates the Philips hue system. It allows to control hue bulbs.</description>
  <author>ACME</author>

</binding:binding>

Bridges and Thing Descriptions

Every binding has to provide meta information about which bridges and/or Things it provides and how their relations to each other are structured. In that way a binding could describe that it requires specific bridges to be operational or define which channels (e.g. temperature, color, etc.) it provides.

Every bridge or Thing has to provide meta information such as label or description. The meta information of all bridges and Things is accessible through the org.eclipse.smarthome.core.thing.binding.ThingTypeProvider service.

Bridge and Thing descriptions must be placed as XML file(s) (with the ending .xml) in the bundle’s folder /ESH-INF/thing/. The full Java API for bridge and Thing descriptions can be found in the Java package org.eclipse.smarthome.core.thing.type.

XML Structure for Thing Descriptions

<?xml version="1.0" encoding="UTF-8"?>
<thing:thing-descriptions bindingId="bindingID"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:thing="http://eclipse.org/smarthome/schemas/thing-description/v1.0.0"
    xsi:schemaLocation="http://eclipse.org/smarthome/schemas/thing-description/v1.0.0
        http://eclipse.org/smarthome/schemas/thing-description-1.0.0.xsd">

  <bridge-type id="bridgeTypeID" listed="{true|false}" extensible="channelTypeId1,channelTypeId2,...">
    <supported-bridge-type-refs>
      <bridge-type-ref id="bridgeTypeID" />
      ...
    </supported-bridge-type-refs>

    <label>String</label>
    <description>String</description>
    <category>String</category>

    <channels>
      <channel id="channelID" typeId="channelTypeID" />
      OR
      <channel id="channelID" typeId="channelTypeID">
        <label>String</label>
        <description>String</description>
      </channel>
      ...
    </channels>
    OR
    <channel-groups>
      <channel-group id="channelGroupID" typeId="channelGroupTypeID" />
      OR
      <channel-group id="channelGroupID" typeId="channelGroupTypeID">
        <label>String</label>
        <description>String</description>
      </channel-group>
      ...
    </channel-groups>

    <properties>
        <property name="propertyName">propertyValue</property>
        ...
    </properties>
    <representation-property>propertyName</representation-property>

    <config-description>
      ...
    </config-description>
    OR
    <config-description-ref uri="{binding|thing-type|bridge-type|channel-type|any_other}:bindingID:..." />
  </bridge-type>

  <thing-type id="thingTypeID" listed="{true|false}" extensible="channelTypeId1,channelTypeId2,...">
    <supported-bridge-type-refs>
      <bridge-type-ref id="bridgeTypeID" />
      ...
    </supported-bridge-type-refs>

    <label>String</label>
    <description>String</description>
    <category>String</category>

    <channels>
      <channel id="channelID" typeId="channelTypeID" />
      OR
      <channel id="channelID" typeId="channelTypeID">
        <label>String</label>
        <description>String</description>
      </channel>
      ...
    </channels>
    OR
    <channel-groups>
      <channel-group id="channelGroupID" typeId="channelGroupTypeID" />
      OR
      <channel-group id="channelGroupID" typeId="channelGroupTypeID">
        <label>String</label>
        <description>String</description>
      </channel-group>
      ...
    </channel-groups>

    <properties>
        <property name="propertyName">propertyValue</property>
        ...
    </properties>
    <representation-property>propertyName</representation-property>

    <config-description>
      ...
    </config-description>
    OR
    <config-description-ref uri="{binding|thing-type|bridge-type|channel-type|any_other}:bindingID:..." />
  </thing-type>

  <channel-type id="channelTypeID" advanced="{true|false}">
    <item-type>Dimmer</item-type>
    OR
    <kind>trigger</kind>
    <label>String</label>
    <description>String</description>
    <category>String</category>

    <tags>
      <tag>String</tag>
      ...
    </tags>

    <state min="decimal" max="decimal" step="decimal" pattern="String" readOnly="{true|false}">
      <options>
        <option value="String" />
        OR
        <option value="String">String</option>
        ...
      </options>
    </state>
    OR
    <event>
      <options>
        <option value="String" />
        OR
        <option value="String">String</option>
        ...
      </options>
    </event>

    <config-description>
      ...
    </config-description>
    OR
    <config-description-ref uri="{binding|thing-type|bridge-type|channel-type|any_other}:bindingID:..." />
  </channel-type>   

  <channel-group-type id="channelGroupTypeID" advanced="{true|false}">
    <label>String</label>
    <description>String</description>
    <category>String</category>

    <channels>
      <channel id="channelID" typeId="channelTypeID" />
      ...
    </channels>
  </channel-group-type>   

  ...

</thing:thing-descriptions>
PropertyDescription
thing-descriptions.bindingIdThe identifier of the binding this types belong to (mandatory).

Bridges and Things:

PropertyDescription
bridge-type.id | thing-type.idAn identifier for the bridge/Thing type (mandatory).
bridge-type.listed | thing-type.listedDenotes if user interfaces should list the bridge/Thing, e.g. for pairing (optional, defaults to true).
bridge-type.extensible | thing-type.extensibleIf the bridge/Thing supports a generic number of channels the allowed channelTypeIds can be listed here (optional). This provides a hint for UIs to support adding/removing channels. Channel groups are not supported.
supported-bridge-type-refsThe identifiers of the bridges this bridge/Thing can connect to (optional).
bridge-type-ref.idThe identifier of a bridge this bridge/Thing can connect to (mandatory).
labelA human-readable label for the bridge/Thing (mandatory).
descriptionA human-readable description for the bridge/Thing (optional).
categoryCategory this bridge/Thing belongs to, see categories) (optional).
channelsThe channels the bridge/Thing provides (optional).
channel.idAn identifier of the channel the bridge/Thing provides (mandatory).
channel.typeIdAn identifier of the channel type definition the bridge/Thing provides (mandatory).
labelA human-readable label for the channel (optional).
descriptionA human-readable description for the channel (optional).
channel-groupsThe channel groups defining the channels the bridge/Thing provides (optional).
channel-group.idAn identifier of the channel group the bridge/Thing provides (mandatory).
channel-group.typeIdAn identifier of the channel group type definition the bridge/Thing provides (mandatory).
propertiesName/value pairs for properties to be set to the thing (optional).
representation-propertyThe name of the property that contains a unique identifier of the thing (optional).
config-descriptionThe configuration description for the bridge/Thing within the ConfigDescriptionRegistry (optional).
config-description-refThe reference to a configuration description for the bridge/Thing within the ConfigDescriptionRegistry (optional).
config-description-ref.uriThe URI of the configuration description for the bridge/Thing within the ConfigDescriptionRegistry (mandatory).

Channels:

PropertyDescription
channel-type.idAn identifier for the channel type (mandatory).
channel-type.advancedThe flag indicating if this channel contains advanced functionalities which should be typically not shown in the basic view of user interfaces (optional, default: false).
kindThe kind of channel. state for channels which have a state, trigger for trigger channels. state is the default.
item-typeAn item type of the channel (mandatory if kind state, which is the default). All item types are specified in ItemFactory instances. The following items belong to the core: Switch, Rollershutter, Contact, String, Number, Dimmer, DateTime, Color, Image.
labelA human-readable label for the channel (mandatory).
descriptionA human-readable description for the channel (optional).
categoryThe category for the channel, e.g. TEMPERATURE (optional).
tagsA list of default tags to be assigned to bound items (optional).
tagA tag semantically describes the feature (typical usage) of the channel e.g. AlarmSystem. There are no pre-default tags, they are custom-specific (mandatory).
stateThe restrictions of an item state which gives information how to interpret it (optional).
state.minThe minimum decimal value of the range for the state (optional).
state.maxThe maximum decimal value of the range for the state (optional).
state.stepThe increasing/decreasing decimal step size within the defined range, specified by the minimum/maximum values (optional).
state.patternThe pattern following the printf syntax to render the state (optional).
state.readOnlyThe flag indicating if the state is read-only or can be modified (optional, default: false).
optionsA list restricting all possible values (optional).
optionThe description for the option (optional).
option.valueThe value for the option (mandatory).
eventThe restrictions of an trigger event which gives information how to interpret it (optional).
optionsA list restricting all possible values (optional).
optionThe description for the option (optional).
option.valueThe value for the option (mandatory).
config-descriptionThe configuration description for the channel within the ConfigDescriptionRegistry (optional).
config-description-refThe reference to a configuration description for the channel within the ConfigDescriptionRegistry (optional).
config-description-ref.uriThe URI of the configuration description for the channel within the ConfigDescriptionRegistry (mandatory).

Channel Groups:

PropertyDescription
channel-group-type.idAn identifier for the channel group type (mandatory).
channel-group-type.advancedThe flag indicating if this channel group contains advanced functionalities which should be typically not shown in the basic view of user interfaces (optional, default: false).
labelA human-readable label for the channel group (mandatory).
descriptionA human-readable description for the channel group (optional).
categoryThe category for the channel group, e.g. TEMPERATURE (optional).
channelsThe channels the bridge/Thing provides (mandatory).
channel.idAn identifier of the channel the bridge/Thing provides (mandatory).
channel.typeIdAn identifier of the channel type definition the bridge/Thing provides (mandatory).

The full XML schema for Thing type descriptions is specified in the ESH thing description XSD file.

Hints:

  • Any identifiers of the types are automatically mapped to unique identifiers: bindingID:id.
  • The attribute uri in the section config-description is optional, it should not be specified in bridge/Thing/channel type definition files because it’s an embedded configuration. If the uri is not specified, the configuration description is registered as bridge-type:bindingID:id, thing-type:bindingID:id or channel-type:bindingID:id otherwise the given uri is used.
  • If a configuration description is already specified somewhere else and the bridge/Thing/channel type wants to (re-)use it, a config-description-ref should be used instead.

Config Status Provider

Each entity that has a configuration can provide its current configuration status for UIs or specific services to point to issues or to provide further general information of the current configuration. For this purpose the handler of the entity has to implement the interface org.eclipse.smarthome.config.core.status.ConfigStatusProvider that has to be registered as OSGi service. The org.eclipse.smarthome.config.core.status.ConfigStatusService tracks each configuration status provider and delivers the corresponding org.eclipse.smarthome.config.core.status.ConfigStatusInfo by the operation getConfigStatus(String, Locale).