Skip to content
This repository has been archived by the owner on May 23, 2019. It is now read-only.

ZWave Product Database OH2

Jump to bottom
Chris Jackson edited this page Jul 24, 2015 · 28 revisions

NOTE THAT THIS IS PRELIMINARY AS THE BINDING IS STILL IN HEAVY DEVELOPMENT

This page describes the XML product database used within HABmin for defining the Z-Wave devices. This is a different format than used for OpenHAB1 as we've used the Eclipse SmartHome thing definition format (see the ESH documentation).

The database itself is not part of HABmin, but is linked into the Z-Wave binding to ensure that it is version controlled - errors in the database can cause problems with the device or binding operation. Modifications therefore need to be made to the database, and the binding recompiled.

You are encouraged to add your devices to the database and submit a pull request. If you are not comfortable submitting a PR, then please generate the XML files and raise an issue, pasting the XML into the issue.

The OH2 database does not (currently!) use a product index file - everything about the device is stored in the single file. This does make maintenance a little easier...

I have created a simple converter to convert much of the OpenHAB1 database over to the new format. This provides the overall format, and the configuration elements of the file. It doesn't provide channel configuration, will likely have issues with naming, and there will no doubt be other issues that need to be manually resolved, but it's a good start. These files can be found here - remember - they are provided to get you started, but please read below and modify the files as required.

Database Structure

The database uses the standard ESH format for defining things - this document describes the customisation employed within the ZWave binding to define ZWave devices, and how HABmin will display descriptions etc.

The filename for things should follow the following conventions to ensure uniformity - manufacturer_model_versionMaj_versionMin.xml. eg fibaro_fgd211_01_004.xml. The version number contains two parts - the major and minor parts. The major part is specified as two numbers, and the minor part as three numbers - so version 1.4 will be specified as 01_004 as in the above example.

The version used in the filename should be the minimum version for this device type. So, for example Fibaro often provide the same configuration for versions 1.4 to 1.8, so we would use 01_004 (version 1.4) for the filename.

Label Conventions

Labels should be kept short enough to fit within the space used by most UIs. HTML probably shouldn't be used for labels.

Descriptions can be longer to provide detailed information on the device or the configuration options. Markdown can be used, however to ensure formatting is maintained, the CDATA escape should be used in the XML for anything longer than short labels (eg <description><![CDATA[ markdown here ]]></description>). The first line should be short if using markdown to provide a brief description that can be displayed alongside the input. Longer data can be formatted using markdown.

Note that this may note be supported in all user interfaces.

The two images below show the same configuration description information displayed in HABmin. The first image is the compressed version that is displayed under the input entry, and the second is the extended description that is displayed in a separate dialog box when you click on the ellipsis at the end of the short description.

Short Description

Short Description

Thing Properties

Thing properties are used to define the device level configuration as shown below.

	<properties>
		<property name="vendor">Fibaro System</property>
		<property name="model">FGD211</property>
		<property name="manufacturerId">010F</property>
		<property name="manufacturerRef">0100:*</property>
		<property name="versionMin">1.4</property>
		<property name="versionMax">1.8</property>
		<property name="commandClass:ASSOCIATION:0:default">3</property>
	</properties>
Property Name Description
vendor Name of the manufacturer
model Model name of the device
manufacturerId The ZWave manufacturer ID specified as a 4 digit hexadecimal value
manufacturerRef The device Type and ID for this device. These must be specified as 4 digit hexadecimal numbers with a colon separating the Type and ID. Note that multiple sets of Type:ID can be specified by separating them with a colon. It is also possible to use the * as a wildcard in the ID (eg 0104:* would select all devices with Type 0104 and any ID)
versionMin The minimum device version number for this product - major and minor parts (eg 1.4)
versionMax The maximum device version number for this product - major and minor parts (eg 1.8)
commandClass:ASSOCIATION:0:default Sets a command class specific option. This is specified by having the commandClass specifier at the beginning of the line. This is followed by the command class name, the endpoint number, and the option. Note that endpoint 0 is used to specify the root endpoint (ie not using multichannel encap).

Channel Properties

Channels provide the interfaces into the ZWave devices functionality. They allow (for example) definition of a dimmer or switch, or metering data, temperatures etc. Channels could be defined for parameters associated with the configuration class, but this should be limited to the situation where such parameters are needed in a UI which is normally not the case.

Channels are defined as follows.

<properties>
<property name="endpoint">0</property>
<property name="commandClass">SWITCH_MULTILEVEL,BASIC</property>
<property name="commandClass:restoreLastValue">true</property>
</properties>
Property Name Description
endpoint
commandClass Defines the applicable ZWave command classes for this channel. It should be noted that multiple command classes can be defined if necessary, in which case they should be separated by a comma.

Note that the order is important because the binding will use the first named class for sending any command. In the above example SWITCH_MULTILEVEL,BASIC means that messages from both the SWITCH_MULTILEVEL and BASIC command classes will be used to set the state, but when sending commands to the device, the SWITCH_MULTILEVEL class will be used.
commandClass:arg Defines an argument to be passed into the command class converter when converting data from the ZWave format to the ESH format. Arguments specific to each command class are defined below. The following arguments are defined for all (or most!) command classed.

getSupported: true or false - defaults to true. Used to stop polling for devices that do not respond when polling a specific command class.

Command Classes

The following table defines the command classes supported within the binding that are available to be bound to channels. Additional command classes are supported internally within the binding for internal use within the binding (eg to get the manufacturer information) however these can not be directly bound to a channel.

Command Class Description
ALARM Options:
alarmType
BASIC Provides basic SET and GET of the default node value
CONFIGURATION
METER Used to get measurements from a node.

Options:
meterCanReset (default: false)
meterType: Sets the meter type
meterScale: Sets allowable scales. Separate multiple scales using a comma

Meter Types:
ELECTRIC: Electricity
GAS: Gas
WATER

Meter Scales:
E_KWh: Electricity watt hours
E_KVAh: Electricity kilowatt hours
E_W: Electricity Watts
E_V: Electricity Volts
E_A: Electricity Amps
E_Pulses: Electricity pulse counter
E_Power_Factor: Electricity power factor
G_Cubic_Meters: Gas use in cubic meters
G_Cubic_Feet: Gas use in cubic feet
G_Pulses: Gas pulse counter
W_Cubic_Meters: Water use in cubic meters
W_Cubic_Feet: Water use in cubic feet
W_Gallons: Water use in Gallons
W_Pulses: Water pulse counter
SENSOR_ALARM Options:
alarmType
SENSOR_BINARY Used to bind to a sensor.
Options:
sensorType
SENSOR_MULTILEVEL Used to bind to a sensor.
Options:
sensorType
sensorScale
SWITCH_BINARY Used to bind directly to a SWITCH
SWITCH_MULTILEVEL Used to bind directly to a DIMMER.

Options:
invertPercent
invertState
THERMOSTAT_FAN_MODE
THERMOSTAT_FAN_STATE
THERMOSTAT_MODE
THERMOSTAT_OPERATING_STATE
THERMOSTAT_SETPOINT Options:
setpointType
setpointScale

Configuration Parameters

The description of configuration parameters is described in the ESH documentation. This section describes additional conventions that should be used within the ZWave binding to ensure that we have a consistent look and feel, and so the binding can know how things are defined.

The binding expects you to define the parameter groups (as below) to group configuration parameters and association groups. The XML definition needs to use these groups to ensure they are displayed correctly.

			<parameter-group name="configuration">
				<context>setup</context>
				<label>Configuration Parameters</label>
				<description></description>
			</parameter-group>
			<parameter-group name="association">
				<context>link</context>
				<label>Association Groups</label>
				<description></description>
			</parameter-group>
			<parameter-group name="tools">
				<context>menu</context>
				<label>Tools</label>
				<description></description>
			</parameter-group>

The last group tools is used to add any configuration parameters that need to be treated as an action, and these may be placed into a menu. Typically this is linked with write_only parameters which are used in some devices to reset the device, or perform a function that has no meaningful information to be displayed.

A few comments on parameters and conventions -:

  • Defaults should be usable defaults - not just what the manufacturer sets!
  • Configuration parameter names should have the parameter ID at the beginning of the label so it ties up with zwave documentation
  • Keep option labels short enough that they fit in the selection boxes UIs use. Add extended information on each option into the parameter description

Configuration parameters are defined as follows. Configuration parameters must be named config_x_y where x is the configuration parameter number and y is the length of the parameter. The binding uses this convention to know how to send the update to the device.

Adding _wo to the end of the configuration marks this as ``write only(eg:config_1_1_wo```). This is needed to stop the binding requesting a readback of parameters that don't support reads and which will timeout if read.

Note that the groupName="configuration" is important. -:

			<parameter name="config_1_1" type="integer" groupName="configuration">
				<label>1: Local protection</label>
				<description><![CDATA[Enables/disables local entry. If activated module stops responding to S1 and S2 push buttons, SCENE ID and association commands will not be sent. Only exception is the B-button.]]></description>
				<default>255</default>
				<options>
					<option value="0">No protection. Roller Shutter responds to push
						buttons
					</option>
					<option value="2">Local protection active. Roller Shutter does
						not respond to push buttons
					</option>
				</options>
			</parameter>

Association group definitions are defined as follows. Association groups must be named group_x where x is the association group number. The binding uses this convention to know how to send the update to the device. Note that the groupName="association" is important. -:

			<parameter name="group_2" type="integer" multiple="true"
				groupName="association">
				<label>Momentary hold</label>
				<description><![CDATA[Triggered through a momentary switch hold]]></description>
				<multipleLimit>16</multipleLimit>
			</parameter>

Example Configuration File

Note that this isn't necessarily a correct configuration for this device and is provided as an example so some additional configuration may have been added as an example.

<?xml version="1.0" encoding="UTF-8"?>
<thing:thing-descriptions bindingId="zwave"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:thing="http://eclipse.org/smarthome/schemas/zwave-thing-description/v1.0.0"
    xsi:schemaLocation="http://eclipse.org/smarthome/schemas/zwave-thing-description/v1.0.0 http://eclipse.org/smarthome/schemas/zwave-thing-description/v1.0.0">
    <thing-type id="fibarosystem_fgs221_00_000">
        <label>Fibaro System FGS221</label>
        <description>Double Relay Switch 2x1.5kW</description>
        <channels>
            <channel id="switch1" typeId="switch">
                <label>Switch 1</label>
                <properties>
                    <property name="endpoint">1</property>
                    <property name="commandClass">SWITCH_BINARY,BASIC</property>
                </properties>
            </channel>
            <channel id="switch2" typeId="switch">
                <label>Switch 2</label>
                <properties>
                    <property name="endpoint">2</property>
                    <property name="commandClass">SWITCH_BINARY,BASIC</property>
                </properties>
            </channel>
        </channels>
        <properties>
            <property name="vendor">Fibaro System</property>
            <property name="model">FGS221</property>
            <property name="manufacturerId">010F</property>
            <property name="manufacturerRef">0200:0102,0200:0103,0200:0104,0200:0105,0200:0106,0200:0107,0200:0109,0200:100A,0200:300A</property>
            <property name="commandClass:ASSOCIATION:0:default">3</property>
        </properties>
        <config-description>
            <parameter-group name="configuration">
                <context>setup</context>
                <label>Configuration Parameters</label>
                <description></description>
            </parameter-group>
            <parameter-group name="association">
                <context>link</context>
                <label>Association Groups</label>
                <description></description>
            </parameter-group>
            <parameter name="config_1_1" type="integer" groupName="configuration">
                <label>1: Enable/Disable ALL ON/OFF</label>
                <description><![CDATA[Activate/Deactive ALL ON/OFF]]></description>
                <default>255</default>
                <options>
                    <option value="0">ALL ON disabled / ALL OFF disabled</option>
                    <option value="1">ALL ON disabled / ALL OFF active</option>
                    <option value="2">ALL ON active / ALL OFF disabled</option>
                    <option value="-1">ALL ON active / ALL OFF active</option>
                </options>
            </parameter>
            <parameter name="config_3_1" type="integer" groupName="configuration">
                <label>3: Enable/Disable OFF-delay</label>
                <description><![CDATA[Activate/Deactivate Automatic turning off relay after set time]]></description>
                <default>0</default>
                <options>
                    <option value="0">Auto OFF disabled for both relays</option>
                    <option value="1">Auto OFF active only for relay 1</option>
                </options>
            </parameter>
            <parameter name="config_4_1" type="integer" groupName="configuration">
                <label>4: Relay 1: OFF-delay time (10ms steps)</label>
                <description><![CDATA[Automatic turning off relay 1 after set time, in 10ms increments (default: 200ms)]]></description>
                <default>20</default>
            </parameter>
            <parameter name="config_6_1" type="integer" groupName="configuration">
                <label>6: Separation of association sending (key 1)</label>
                <description><![CDATA[Activate/Deactivate association sending for group
                1 - Also see param #16]]></description>
                <default>0</default>
                <options>
                    <option value="0">Map status to all devices in group 1</option>
                    <option value="1">Map OFF status to all devices in group 1,
                        Double click on key 1 will send ON to all devices in group 1, all
                        dimmers set to prev.value</option>
                    <option value="2">Map OFF status to all devices in group 1,
                        Double click on key 1 will send ON to all devices in group 1, all
                        dimmers set to 100%</option>
                </options>
            </parameter>
            <parameter name="config_13_1" type="integer" groupName="configuration">
                <label>13: Inputs behaviour</label>
                <description><![CDATA[In case of bi-stable switches, define their behaviour (toggle
                or follow)]]></description>
                <default>0</default>
                <options>
                    <option value="0">Toggle</option>
                    <option value="1">Follow switch contact (closed=ON, open=OFF)</option>
                </options>
            </parameter>
            <parameter name="config_14_1" type="integer" groupName="configuration">
                <label>14: Inputs Button/Switch configuration</label>
                <description><![CDATA[Binary inputs type configuration]]></description>
                <default>1</default>
                <options>
                    <option value="0">Mono-stable input (button)</option>
                    <option value="1">Bi-stable input (switch)</option>
                </options>
            </parameter>
            <parameter name="config_15_1" type="integer" groupName="configuration">
                <label>15: Dimmer/Roller shutter control</label>
                <description><![CDATA[Enable/Disable operation of dimmer or roller shutter devices
                associated to group 1.
                Available only when using mono-stable inputs (buttons) - Hold button 1 or
                double-tap for operation]]></description>
                <default>0</default>
                <options>
                    <option value="0">Disable Dimmer/Roller shutter control</option>
                    <option value="1">Enable Dimmer/Roller shutter control</option>
                </options>
            </parameter>
            <parameter name="config_16_1" type="integer" groupName="configuration">
                <label>16: Saving state before power failure</label>
                <description><![CDATA[Saving state before power failure]]></description>
                <default>1</default>
                <options>
                    <option value="0">State NOT saved at power failure, all outputs
                        are set to OFF upon power restore</option>
                    <option value="1">State saved at power failure, all outputs are
                        set to previous state upon power restore</option>
                </options>
            </parameter>
            <parameter name="config_30_1" type="integer" groupName="configuration">
                <label>30: Relay 1: Response to General Alarm</label>
                <description><![CDATA[]]>
                </description>
                <default>3</default>
                <options>
                    <option value="0">DEACTIVATION - no response to alarm frames</option>
                    <option value="1">ALARM RELAY ON - relay will turn ON upon
                        receipt of alarm frame</option>
                    <option value="2">ALARM RELAY OFF - relay will turn OFF upon
                        receipt of alarm frame</option>
                    <option value="3">ALARM FLASHING - relay will turn ON and OFF
                        periodically (see param.39)</option>
                </options>
            </parameter>
            <parameter name="config_31_1" type="integer" groupName="configuration">
                <label>31: Relay 1: Response to Water Flood Alarm</label>
                <description><![CDATA[]]>
                </description>
                <default>2</default>
                <options>
                    <option value="0">DEACTIVATION - no response to alarm frames</option>
                    <option value="1">ALARM RELAY ON - relay will turn ON upon
                        receipt of alarm frame</option>
                    <option value="2">ALARM RELAY OFF - relay will turn OFF upon
                        receipt of alarm frame</option>
                    <option value="3">ALARM FLASHING - relay will turn ON and OFF
                        periodically (see param.39)</option>
                </options>
            </parameter>
            <parameter name="config_32_1" type="integer" groupName="configuration">
                <label>32: Relay 1: Response to Smoke, CO, CO2 Alarm</label>
                <description><![CDATA[]]>
                </description>
                <default>3</default>
                <options>
                    <option value="0">DEACTIVATION - no response to alarm frames</option>
                    <option value="1">ALARM RELAY ON - relay will turn ON upon
                        receipt of alarm frame</option>
                    <option value="2">ALARM RELAY OFF - relay will turn OFF upon
                        receipt of alarm frame</option>
                    <option value="3">ALARM FLASHING - relay will turn ON and OFF
                        periodically (see param.39)</option>
                </options>
            </parameter>
            <parameter name="config_33_1" type="integer" groupName="configuration">
                <label>33: Relay 1: Response to Temperature Alarm</label>
                <description><![CDATA[]]>
                </description>
                <default>1</default>
                <options>
                    <option value="0">DEACTIVATION - no response to alarm frames</option>
                    <option value="1">ALARM RELAY ON - relay will turn ON upon
                        receipt of alarm frame</option>
                    <option value="2">ALARM RELAY OFF - relay will turn OFF upon
                        receipt of alarm frame</option>
                    <option value="3">ALARM FLASHING - relay will turn ON and OFF
                        periodically (see param.39)</option>
                </options>
            </parameter>
            <parameter name="config_39_2" type="integer" groupName="configuration">
                <label>39: ALARM FLASHING alarm time</label>
                <description><![CDATA[Amount of time (ms) the device keeps on flashing after receipt of Alarm Frame]]></description>
                <default>600</default>
            </parameter>
            <parameter name="group_1" type="integer" multiple="true"
                groupName="association">
                <label>Switch 1</label>
                <description><![CDATA[***Add description here***]]></description>
                <multipleLimit>16</multipleLimit>
            </parameter>
            <parameter name="group_2" type="integer" multiple="true"
                groupName="association">
                <label>Switch 2</label>
                <description><![CDATA[***Add description here***]]></description>
                <multipleLimit>16</multipleLimit>
            </parameter>
            <parameter name="group_3" type="integer" groupName="association">
                <label>Controller Updates</label>
                <description><![CDATA[***Add description here***]]></description>
            </parameter>
        </config-description>
    </thing-type>
    <channel-type id="switch">
        <item-type>Switch</item-type>
        <label>Switch</label>
        <description>Switch the light on and off</description>
        <category>Light</category>
    </channel-type>
</thing:thing-descriptions>

Overview

Installation

Dashboard Menu

Automation

Binding Specific

Clone this wiki locally