Binding Definitions

Every binding has to provide meta information such as binding id or name.

Background information: 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.

For the declarative way, you add your binding information in form of a binding.xml file to the bundle's folder /src/main/resources/ESH-INF/binding/binding.xml.

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="https://openhab.org/schemas/binding/v1.0.0"
    xsi:schemaLocation="https://openhab.org/schemas/binding/v1.0.0
        https://openhab.org/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|channel-type|any_other}:bindingID:..." />

</binding:binding>

Property	Description
binding.id (opens new window)	An identifier for the binding	mandatory
name	A human-readable name for the binding	mandatory
description	A human-readable description for the binding	optional
author	The author of the binding	optional
service-id	The ID (service.pid or component.name (opens new window)) 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-description	The configuration description for the binding within the ConfigDescriptionRegistry	optional
config-description-ref	The reference to a configuration description for the binding within the ConfigDescriptionRegistry	optional
config-description-ref.uri	The 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 (opens new window) 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 (opens new window)>". 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="bindingID"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:binding="https://openhab.org/schemas/binding/v1.0.0"
    xsi:schemaLocation="https://openhab.org/schemas/binding/v1.0.0
        https://openhab.org/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>

• Stable
• Latest

Caught a mistake or want to contribute to the documentation? Edit this page on GitHub (opens new window)