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 18, 2015 · 28 revisions

This page describes the XML product database used within HABmin for defining the Z-Wave devices. 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.

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.

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. HTML can be used by using the CDATA escape in the XML (eg <description><![CDATA[Universal <b>Dimmer</b> 500W]]></description>). The first line should be short if using HTML to provide a brief description that can be displayed alongside the input. Longer data can be formatted using HTML and images can be inserted using the <img src="data:image/jpeg;base64 ... /> convention.

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
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
SENSOR_BINARY Used to bind to a sensor.
SENSOR_MULTILEVEL Used to bind to a sensor.
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

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 two 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>

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 options short enough that they fit in the selection boxes UIs use. Add extended information into the parameter description

Configuration parameters are defined as follows. Note that the groupName="configuration" is important. -:

			<parameter name="config_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. 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_fgd211_01_004">
		<label>Fibaro System FGD211</label>
		<description><![CDATA[Universal Dimmer 500W]]></description>
		<channels>
			<channel id="dimmer-0" typeId="dimmer">
				<properties>
					<property name="endpoint">0</property>
                    <property name="commandClass">SWITCH_MULTILEVEL,BASIC</property>
                    <property name="commandClass:restoreLastValue">true</property>
                    <property name="commandClass:invertPercent">false</property>
				</properties>
			</channel>
		</channels>
		<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>
		<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" 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>
			<parameter name="config_2" type="integer" groupName="configuration">
				<label>2: Radio protection</label>
				<description><![CDATA[Enables/disables RF protection. If activated device stops responding to command frames. Configuration and polling still possible.]]></description>
				<default>0</default>
				<options>
					<option value="0">No protection. Roller Shutter responds to
						command frames.
					</option>
					<option value="1">RF Protection active. Roller Shutter does not
						respond to the Z-Wave control frames.
					</option>
				</options>
			</parameter>
			<parameter name="config_3" type="integer" groupName="configuration">
				<label>3: Reports type</label>
				<description><![CDATA[Parameters value shoud be set to 1 if the module operates in Venetian Blind mode.]]></description>
				<default>0</default>
				<options>
					<option value="0">Blind position reports sent to the main
						controller using Z-Wave Command Class.
					</option>
					<option value="1">Blind position reports sent to the main
						controller using Fibar Command Class.
					</option>
				</options>
			</parameter>
			<parameter name="config_10" type="integer" groupName="configuration">
				<label>10: Roller Shutter operating modes</label>
				<description><![CDATA[]]>
				</description>
				<default>1</default>
				<options>
					<option value="0">Roller Blind Mode, without positioning
					</option>
					<option value="1">Roller Blind Mode, with positioning</option>
					<option value="2">Venetian Blind Mode, with positioning</option>
					<option value="3">Gate Mode, without positioning</option>
					<option value="4">Gate Mode, with positioning</option>
				</options>
			</parameter>
			<parameter name="config_12" type="integer" groupName="configuration">
				<label>12: Turning time/ delay time</label>
				<description><![CDATA[In Venetian Blind mode (parameter 10 set to 2) the parameter determines time of full turn of the lamellas. In Gate Mode (parameter 10 set to 3 or 4) the parameter defines the delay time after which an open gate starts closing.
Type    range]]></description>
				<default>150</default>
			</parameter>
			<parameter name="config_13" type="integer" groupName="configuration">
				<label>13: Lamellas positioning mode</label>
				<description><![CDATA[Parameter influences the lamellas positioning in venetian blind mode (parameter 10 set to 2)]]></description>
				<default>1</default>
				<options>
					<option value="0">Lamellas return to previously set position
						only in case of the main controller operation.
					</option>
					<option value="1">Lamellas return to previously set position in
						case of the main controller operation, momentary switch operation,
						or when the limit switch is reached.
					</option>
					<option value="2">Lamellas return to previously set position in
						case of the main controller operation, momentary switch operation,
						when the limit switch is reached or after receiving a “STOP”
						control frame (Switch Multilevel Stop).
					</option>
				</options>
			</parameter>
			<parameter name="config_14" type="integer" groupName="configuration">
				<label>14: Switch type</label>
				<description><![CDATA[parameter settings are relevant for Roller Blind Mode and Venetian Blind Mode (parameter 10 set to 0, 1, 2).]]></description>
				<default>0</default>
				<options>
					<option value="0">Momentary switches</option>
					<option value="1">Toggle switches</option>
					<option value="2">Single, momentary switch.</option>
				</options>
			</parameter>
			<parameter name="config_17" type="integer" groupName="configuration">
				<label>17: Delay time after S2</label>
				<description><![CDATA[In roller blind mode or venetian blind mode (parameter 10 set to 0, 1, 2) the parameter determines when the Roller Shutter relays are turned off after reaching a limit switch. In Gate Mode (parameter 10 set to 3 or 4) the parameter determines a time period after which a gate will start closing after a S2 contact has been disconnected.]]></description>
				<default>10</default>
			</parameter>
			<parameter name="config_18" type="integer" groupName="configuration">
				<label>18: Motor operation detection</label>
				<description><![CDATA[Power threshold to be interpreted as reaching a limit switch.]]></description>
				<default>10</default>
			</parameter>
			<parameter name="config_22" type="integer" groupName="configuration">
				<label>22: Motor operation time</label>
				<description><![CDATA[Time period for the motor to continue operation.]]></description>
				<default>10</default>
			</parameter>
			<parameter name="config_29" type="integer" groupName="configuration">
				<label>29: Forced Roller Shutter calibration</label>
				<description><![CDATA[Seting the parameter to 1 Roller Shutter enters the calibration mode. Parameter is only only relevant if a Roller Shutter is set to work in positioning mode (parameter 10 set to 1, 2 or 4).]]></description>
				<default>0</default>
				<options>
					<option value="0">Deactivated</option>
					<option value="1">Start calibration process</option>
				</options>
			</parameter>
			<parameter name="config_30" type="integer" groupName="configuration">
				<label>30: Response to General Alarm</label>
				<description><![CDATA[]]>
				</description>
				<default>2</default>
				<options>
					<option value="0">No response to alarm frames</option>
					<option value="1">Open Blind</option>
					<option value="2">Close Blind</option>
				</options>
			</parameter>
			<parameter name="config_31" type="integer" groupName="configuration">
				<label>31: Response to Water Flood Alarm</label>
				<description><![CDATA[]]>
				</description>
				<default>0</default>
				<options>
					<option value="0">No response to alarm frames</option>
					<option value="1">Open Blind</option>
					<option value="2">Close Blind</option>
				</options>
			</parameter>
			<parameter name="config_32" type="integer" groupName="configuration">
				<label>32: Response to Smoke, CO, CO2 Alarm</label>
				<description><![CDATA[]]>
				</description>
				<default>3</default>
				<options>
					<option value="0">No response to alarm frames</option>
					<option value="1">Open Blind</option>
					<option value="2">Close Blind</option>
				</options>
			</parameter>
			<parameter name="config_33" type="integer" groupName="configuration">
				<label>33: Response to Temperature Alarm</label>
				<description><![CDATA[]]>
				</description>
				<default>1</default>
				<options>
					<option value="0">No response to alarm frames</option>
					<option value="1">Open Blind</option>
					<option value="2">Close Blind</option>
				</options>
			</parameter>
			<parameter name="config_35" type="integer" groupName="configuration">
				<label>35: Managing lamellas in response to alarm</label>
				<description><![CDATA[In Venetian Blind Mode (parameter 10 set to 2), the parameter determines how the lamellas will react upon alarm detection.]]></description>
				<default>1</default>
				<options>
					<option value="0">Do not change lamellas position</option>
					<option value="1">Set lamellas to their extreme position
					</option>
				</options>
			</parameter>
			<parameter name="config_40" type="integer" min="0" max="100"
				groupName="configuration">
				<label>40: Power reports</label>
				<description><![CDATA[Power level change that will result in new power value report being sent. value is a percentage of the previous report.]]></description>
				<default>10</default>
			</parameter>
			<parameter name="config_42" type="integer" min="-32767"
				max="32767" groupName="configuration">
				<label>42: Periodic power or energy reports</label>
				<description><![CDATA[Time to the next report. Value of 0 means the reports are turned off.]]></description>
				<default>3600</default>
			</parameter>
			<parameter name="config_43" type="integer" min="-126" max="127"
				groupName="configuration">
				<label>43: Energy reports</label>
				<description><![CDATA[Energy level change which will result in new energy value report being sent. Value of 0 means the reports are turned off.]]></description>
				<default>10</default>
			</parameter>
			<parameter name="config_44" type="integer" groupName="configuration">
				<label>44: Self-measurement</label>
				<description><![CDATA[Enables/disables to include the power and energy used by itself in reports to main controller.]]></description>
				<default>0</default>
				<options>
					<option value="0">Disabled</option>
					<option value="1">Activated</option>
				</options>
			</parameter>
			<parameter name="config_50" type="integer" groupName="configuration">
				<label>50: Scenes/ Associations activation</label>
				<description><![CDATA[Parameter determines whether scenes or associations are activated by the switch keys.]]></description>
				<default>0</default>
				<options>
					<option value="0">Associations Active</option>
					<option value="1">Scenes Active</option>
				</options>
			</parameter>
			<parameter name="group_1" type="integer" multiple="true"
				groupName="association">
				<label>Momentary click</label>
				<description><![CDATA[Triggered through a momentary switch click or a toggle switch position change]]></description>
				<multipleLimit>16</multipleLimit>
			</parameter>
			<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>
			<parameter name="group_3" type="integer" groupName="association">
				<label>Controller Updates</label>
			</parameter>
		</config-description>
	</thing-type>
	<channel-type id="dimmer">
		<item-type>Dimmer</item-type>
		<label>Dimmer</label>
		<description>Set the light level</description>
		<category>Light</category>
	</channel-type>
</thing:thing-descriptions>

Overview

Installation

Dashboard Menu

Automation

Binding Specific

Clone this wiki locally