Binding descriptor files

Note that the format will change slightly at some stage to make it a bit easier to read in Java

The binding descriptor files are not strictly part of HABmin, and need to be included with the binding as part of openHAB. However, since they are needed by the REST interface, I'm defining this as part of HABmin for now. Expect this to move to openHAB later.

So, consider this a proposal to be included within openHAB (see openHAB issue 420).

The purpose of the binding descriptor is to allow the binding to describe its configuration requirements to the REST interface, and on to the web configuration interface. This therefore needs to describe all the configuration parameters, provide a description to assist the user, and provide checking information to allow cross checking within the GUI.

There are three parts of the file to be defined

• General binding configuration (the parameters currently in the openhab.cfg file
• Binding interface configuration. This is also currently in the openhab.cfg - it defines the interface specific parameters and is not used in all bindings. It is normally preceeded by a . (eg owserver.interface1.host=)
• The item binding configuration.

The following excerpts from the xml file should be reasonably self descriptive. Multiple sets of data would normally be defined for the different configuration parameters. A full example file is provided at the bottom of this page.

A few things to look at -:

• Linking the interface parameter in the item configuration to the interface definitions so that the user gets a list to select from.
• More validation required? Regex, type, length?

###Binding Information

<binding>
	<!-- Full name presented to the user -->
	<name>OWServer - EDS One Wire Server</name>
	<!-- PID name used within the OSGi layer -->
	<pid>owserver</pid>
	<!-- Binding type: protocol, ui -->
	<type>protocol</type>
	<!-- Author -->
	<author>Chris Jackson</author>
	<!-- Current version of the binding to which the file is applicable -->
	<version>1.3.0</version>
	<!-- Minimum version of openHAB required to run this binding -->
	<oh_version>1.3.0</oh_version>

###General Binding Configuration

    <!-- Binding configuration settings -->
    <binding.config>
        <setting>
            <name>cache</name>
            <label>Cache Timeout</label>
            <description>Sets the cache timeout in milliseconds.</description>
            <optional>true</optional>
            <default>5000</default>
            <minimum>250</minimum>
            <maximum>20000</maximum>
            <values></values>
        </setting>

Binding Interface Configuration

    <!-- The following lines specify the communications interface settings. These may be repeated multiple times -->
    </binding.interface>
        <setting>
            <name>host</name>
            <label>IP Address</label>
            <description>Set the IP address of the OW Server.</description>
            <optional>false</optional>
            <default></default>
            <minimum></minimum>
            <maximum></maximum>
            <values></values>
        </setting>

Binding Item Configuration

    <!-- Item binding configuration -->
    <binding.items>
        <binding.io>
            <type>Input</type>
            <description></description>
            <parameters>
                <parameter>
                    <name>interface</name>
                    <label>Communications Interface</label>
                    <description>Set the symbolic name of the communication interface.</description>
                    <optional>false</optional>
                    <default></default>
                    <minimum></minimum>
                    <maximum></maximum>
                    <values></values>
                </parameter>

Complete file

<!-- Binding configuration for the OWServer binding in openHAB -->
<binding>
	<!-- Full name presented to the user -->
	<name>OWServer - EDS One Wire Server</name>
	<!-- PID name used within the OSGi layer -->
	<pid>owserver</pid>
	<!-- Binding type: protocol, ui -->
	<type>protocol</type>
	<!-- Author -->
	<author>Chris Jackson</author>
	<!-- Current version of the binding to which the file is applicable -->
	<version>1.3.0</version>
	<!-- Minimum version of openHAB required to run this binding -->
	<oh_version>1.3.0</oh_version>

    <!-- Binding configuration settings -->
    <binding.config>
        <setting>
            <name>cache</name>
            <label>Cache Timeout</label>
            <description>Sets the cache timeout in milliseconds.</description>
            <optional>true</optional>
            <default>5000</default>
            <minimum>250</minimum>
            <maximum>20000</maximum>
            <values></values>
        </setting>
        <setting>
            <name>timeout</name>
            <label>Timeout</label>
            <description>Sets the number of milliseconds that the binding will wait for a response.</description>
            <optional>true</optional>
            <default>5000</default>
            <minimum>500</minimum>
            <maximum>10000</maximum>
            <values></values>
        </setting>
        <setting>
            <name>granularity</name>
            <label>Granularity</label>
            <description>Set the time between each of the OWServer item update checks (in milliseconds).</description>
            <optional>true</optional>
            <default>1000</default>
            <minimum>100</minimum>
            <maximum>10000</maximum>
            <values></values>
        </setting>
    </binding.config>

    <!-- The following lines specify the communications interface settings. These may be repeated multiple times -->
    </binding.interface>
        <setting>
            <name>host</name>
            <label>IP Address</label>
            <description>Set the IP address of the OW Server.</description>
            <optional>false</optional>
            <default></default>
            <minimum></minimum>
            <maximum></maximum>
            <values></values>
        </setting>
        <setting>
            <name>port</name>
            <label>IP Port</label>
            <description>Set the IP Port number of the OW Server.</description>
            <optional>true</optional>
            <default>80</default>
            <minimum>1</minimum>
            <maximum>65535</maximum>
            <values></values>
        </setting>
    </binding.interface>

    <!-- Item binding configuration -->
    <binding.items>
        <binding.io>
            <type>Input</type>
            <description></description>
            <parameters>
                <parameter>
                    <name>interface</name>
                    <label>Communications Interface</label>
                    <description>Set the symbolic name of the communication interface.</description>
                    <optional>false</optional>
                    <default></default>
                    <minimum></minimum>
                    <maximum></maximum>
                    <values></values>
                </parameter>
                <parameter>
                    <name>romid</name>
                    <label>ROM ID</label>
                    <description>Set the ROM ID of the One Wire device.</description>
                    <optional>false</optional>
                    <default></default>
                    <minimum></minimum>
                    <maximum></maximum>
                    <values></values>
                </parameter>
                <parameter>
                    <name>parameter</name>
                    <label>Parameter Name</label>
                    <description>Sets the Parameter Name from the One Wire device.</description>
                    <optional>false</optional>
                    <default></default>
                    <minimum></minimum>
                    <maximum></maximum>
                    <values></values>
                </parameter>
                <parameter>
                    <name>Polling period</name>
                    <description>Sets polling period (in milliseconds between each request.</description>
                    <optional>false</optional>
                    <default>5000</default>
                    <minimum></minimum>
                    <maximum></maximum>
                    <values></values>
                </parameter>
            </parameters>
        </binding.io>
    </binding.items>
</binding>