ESH-INF.binding.binding.xml Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of org.eclipse.smarthome.binding.bluetooth Show documentation
Eclipse SmartHome Bluetooth Binding
The newest version!
<?xml version="1.0" encoding="UTF-8"?>
<binding:binding id="bluetooth"
        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>Bluetooth Binding</name>
    <description><![CDATA[
        The Bluetooth binding brings support for bluetooth devices into Eclipse SmartHome Framework.
        <br/> The following main use cases are supported by the binding:
        <br/>
        <ul>
            <li>Bluetooth adapters and devices automatic discovery</li>
            <li>Presence detection. Bluetooth devices can be monitored whether they are in range of a bluetooth adapter (or multiple bluetooth adapters).
            This feature makes it possible to detect if an object or a person enters or leaves a building or a room.</li>
            <li>Indoor positioning. Location of a bluetooth device can be identified based on estimated distance between the device and adapters.
            This feature allows you to locate things (like your phone or keys) in your house or detect who exactly is in a room. </li>
            <li>Comprehensive support for Bluetooth Low Energy (Bluetooth Smart) devices. If a bluetooth device supports the Bluetooth specification 4.0,
            then the standard <a href="https://www.bluetooth.com/specifications/gatt" target="_blank">GATT services and characteristics</a> can be automatically recognized and
            corresponding thing channels be created for each GATT characteristic and its GATT fields. This feature allows you to connect
            Bluetooth Smart sensors and other bluetooth devices.</li>
            <li>Custom built (non-standard) BLE Bluetooth devices support. A custom built bluetooth device can be automatically recognized like a standard one
            by specifying a folder on the system disk with custom GATT service and characteristic definitions in XML files.</li>
            <li>Robustness in maintaining connectivity (automatic connection recovery)</li>
        </ul>
            ]]>
    </description>
    <author>Vlad Kolotov</author>

    <config-description>
        <!-- the following parameter is used only for debugging-->
        <!--<parameter name="combinedDevicesEnabled" type="boolean">-->
            <!--<label>Combine devices</label>-->
            <!--<description>If selected all discovered devices that have the same address (discovered through different adapters) are combined into a single thing and therefore can be controlled as a single unit.</description>-->
            <!--<required>true</required>-->
            <!--<default>true</default>-->
        <!--</parameter>-->
        <parameter name="updateRate" type="integer" min="1" max="60" unit="s">
            <label>Bluetooth devices update rate</label>
            <description>How often bluetooth devices are checked/updated (seconds, default: 10s)?</description>
            <default>10</default>
            <required>true</required>
            <advanced>true</advanced>
        </parameter>
        <parameter name="initialOnlineTimeout" type="integer" min="0" unit="s">
            <label>Initial online timeout</label>
            <description>Bluetooth devices not showing any activity are considered to be offline after exceeding this timeout (seconds). Can be customized for each bluetooth device.</description>
            <default>35</default>
            <required>true</required>
        </parameter>
        <parameter name="initialConnectionControl" type="boolean">
            <label>Initial connection control</label>
            <description>If enabled, connection is kept on for newly added bluetooth devices, otherwise off. Can be customized for each bluetooth device.</description>
            <default>false</default>
        </parameter>
        <parameter name="serialPortRegex" type="text">
            <label>Regular expression for BlueGiga adapters autodiscovery (serial ports)</label>
            <description><![CDATA[
                WARNING!: It is very important not to make the regular expression too wide so that ONLY Bluegiga adapters/ serial ports are matched by the regular expression. If the regular expression is too broad, this can lead to hardware malfunction/damage of other devices that are accidentally matched by the regular expression. USE THIS FEATURE AT YOUR OWN RISK.<br/>
                Regular expression examples:<br/>
                <ul>
                    <li>Defining some specific serial ports (preferable option): (/dev/ttyACM1)|(/dev/ttyACM2)</li>
                    <li>Matching all serial ports on Linux: ((/dev/ttyACM)[0-9]{1,3})</li>
                    <li>Matching all serial ports on OSX: (/dev/tty.(usbmodem).*)</li>
                    <li>Matching all serial ports on Windows: ((COM)[0-9]{1,3})</li>
                    <li>Matching all serial ports with some exclusions: (?!/dev/ttyACM0|/dev/ttyACM5)((/dev/ttyACM)[0-9]{1,3})</li>
                    <li>Default regular expression is to match nothing: (?!)</li>
                </ul>
            ]]></description>
            <!-- commented because limitToOptions and options does not play well together -->
            <!--<options>-->
                <!--<option value="((/dev/ttyACM)[0-9]{1,3})|(/dev/tty.(usbmodem).*)|((COM)[0-9]{1,3})">All ports</option>-->
                <!--<option value="(?!)">Nothing</option>-->
            <!--</options>-->
            <!--<limitToOptions>false</limitToOptions>-->
            <default>(?!)</default>
        </parameter>
        <parameter name="backgroundDiscovery" type="boolean">
            <label>Enable background discovery</label>
            <description>If enabled, adapters and devices are discovered automatically, otherwise discovery process has to be triggered manually.
                If you live on a busy road, your inbox can be cluttered with bluetooth devices, disable this config to stop adding devices into your inbox.
                This config does not affect actual discovery status of your adapters, it only prevents adding discovered devices into your inbox.
            </description>
            <default>true</default>
        </parameter>
        <parameter name="extensionFolder" type="text">
            <label>GATT services and characteristics extension folder</label>
            <description><![CDATA[
                A folder on the system disk which contains your custom definitions for GATT services and characteristics for automatic recognition of bluetooth GATT attributes.<br/>
                See more: https://github.com/sputnikdev/bluetooth-gatt-parser<br/>
                Example: /home/pi/.bluetooth_smart]]></description>
            <required>false</required>
            <advanced>true</advanced>
        </parameter>
        <parameter name="advancedGattServices" type="text" multiple="true" pattern="^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$">
            <label>Advanced GATT services</label>
            <description>List of GATT service UUIDs to be excluded from the automatic channel linkage. No items/channels will be automatically created for these services. Generic Access and Generic Attribute services are selected by default.</description>
            <options>
                <option value="00001800-0000-1000-8000-00805f9b34fb">00001800-0000-1000-8000-00805f9b34fb (Generic Access)</option>
                <option value="00001801-0000-1000-8000-00805f9b34fb">00001801-0000-1000-8000-00805f9b34fb (Generic Attribute)</option>
            </options>
            <limitToOptions>false</limitToOptions>
            <advanced>true</advanced>
        </parameter>
        <parameter name="gattParsingStrategy" type="text">
            <label>GATT services and characteristics parsing strategy</label>
            <description><![CDATA[Controls how recognised and unrecognised GATT attributes are handled:
                <ul>
                    <li><b>Recognised only (Default value)</b> - Human-readable channels are created for only recognised attributes, all other "unknown" attributes are ignored</li>
                    <li><b>Recognised + System + Unknown + unrecognised as binary</b> - Human-readable channels are created for recognised, system and unknown attributes, binary channels are created for all other "unknown" attributes</li>
                    <li><b>All as binary</b> - All channels are binary</li>
                </ul>
            ]]></description>
            <options>
                <option value="RECOGNISED_ONLY">Recognised only</option>
                <option value="UNRECOGNISED_AS_BINARY">Recognised + System + Unknown + unrecognised as binary</option>
                <option value="ALL_BINARY">All as binary</option>
            </options>
            <limitToOptions>true</limitToOptions>
            <advanced>true</advanced>
            <default>RECOGNISED_ONLY</default>
            <required>true</required>
        </parameter>
        <parameter name="rssiReportingRate" type="integer" min="0" unit="ms">
            <label>RSSI reporting rate</label>
            <description>Controls how frequently RSSI should be reported. This parameter does not affect the "indoor positioning system". Important note: setting it to a low value might cause an excessive CPU load.</description>
            <default>5000</default>
            <advanced>true</advanced>
            <required>true</required>
        </parameter>
    </config-description>
</binding:binding>