ZWave Product Database OH2
NOTE THAT THIS IS PRELIMINARY AS THE BINDING IS STILL IN HEAVY DEVELOPMENT
Note: A new online database editor has been produced to make it easier for most people to add devices and update the database. It will also ease maintenance of both the OH1 and OH2 databases which have different formats. Please support it here.
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.
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, and the UID, for things should follow the following conventions to ensure uniformity - manufacturer_model_versionMaj_versionMin.xml. eg fibarosystem_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.
Labels should be kept short enough to fit within the space used by most UIs. HTML probably shouldn't be used for labels.
The label and descriptions for things, channels and config descriptions should follow the following format. The label should be short so that for most UIs it does not spread across multiple lines. The description can contain longer text to describe the thing in more detail. Limited use of HTML tags is permitted to enhance the description - if a long description is provided, the first line should be kept short, and a line break (<br>) placed at the end of the line to allow UIs to display a short description in limited space.
Configuration options should be kept short so that they are displayable in a single line in most UIs. If you want to provide a longer description of the options provided by a particular parameter, then this should be placed into the <description> of the parameter to keep the option label short. The description can include limited HTML to enhance the display of this information.
The following HTML tags are allowed -: <b>, <br>, <em>, <h1>, <h2>, <h3>, <h4>, <h5>, <h6>, <i>, <p>, <small>, <strong>, <sub>, <sup>, <ul>, <ol>, <li>. These must be inside the XML escape sequence - eg - <description><![CDATA[ HTML marked up text here ]]></description>.
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.
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). |
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="binding:*:HSBType">COLOR;colorHue=true</property>
<property name="binding:*:PercentType">SWITCH_MULTILEVEL,BASIC</property>
<property name="binding:Command:OnOffType">SWITCH_MULTILEVEL</property>
</properties>or
<properties>
<property name="binding:*:OnOffType">SWITCH_BINARY:1,BASIC:1</property>
</properties>The binding string is made up of the following parts -:
name="binding:<<binding type>>:<<data type>>" : This sets the type of binding. The binding part is required, followed by the colon. The <<binding type>>> can be *, State or Command. This allows the selection of what command class will be used to send commands depending on the incoming data type from ESH. Using a * selects this binding for both commands and state readback - State or Command will just be used for one direction. The <<data type>> sets the ESH data type that is linked to this binding string.
The text in the property is made up of a list of command classes, and options. 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 if multiple classes are defined for a Command binding. In the above example SWITCH_BINARY:1,BASIC:1 means that messages from both the SWITCH_BINARY and BASIC command classes will be used to set the state using endpoint 1, but when sending commands to the device, the SWITCH_MULTILEVEL class will be used.
Options specific to each command class can follow the command class definition, separated by a semi colon (as in the first example above). The following options 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.
The following channel types are defined for use in the ZWave binding
| Channel | Description |
|---|---|
| color | Color channel |
| brightness | Used for dimmer |
| color_temperature | |
| switch | |
| door | |
| temperature | |
| motion | |
| smoke |
To keep things as standard as possible, the channel names should be the channel type, followed by a number (eg color-1, switch-1, switch-2).
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 |
| COLOR | Sets the color of an RGB light Options: colorMode: if set to RGB, only the hue part of the HSB will be used. If set to COLD_WHITE, or WARM_WHITE only these color channels will be sent (a PercentType is expected). DIFF_WHITE will use warm and cold white channels to adjust the color temperature. |
| CONFIGURATION | |
| METER | Used to get measurements from a node. Options: meterCanReset (default: false)meterType: Sets the meter typemeterScale: Sets allowable scales. Separate multiple scales using a commaMeter Types: ELECTRIC: ElectricityGAS: GasWATERMeter Scales: E_KWh: Electricity watt hoursE_KVAh: Electricity kilowatt hoursE_W: Electricity WattsE_V: Electricity VoltsE_A: Electricity AmpsE_Pulses: Electricity pulse counterE_Power_Factor: Electricity power factorG_Cubic_Meters: Gas use in cubic metersG_Cubic_Feet: Gas use in cubic feetG_Pulses: Gas pulse counterW_Cubic_Meters: Water use in cubic metersW_Cubic_Feet: Water use in cubic feetW_Gallons: Water use in GallonsW_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: sensorTypesensorScale
|
| SWITCH_BINARY | Used to bind directly to a SWITCH |
| SWITCH_MULTILEVEL | Used to bind directly to a DIMMER. Options: invertPercentinvertState
|
| THERMOSTAT_FAN_MODE | |
| THERMOSTAT_FAN_STATE | |
| THERMOSTAT_MODE | |
| THERMOSTAT_OPERATING_STATE | |
| THERMOSTAT_SETPOINT | Options:setpointTypesetpointScale
|
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!
- Don't use negative numbers. Many manufacturers will show a value of -1 for some default - this is actually incorrect as the zwave standard uses unsigned values. If you have a value of -1, convert it to it's unsigned equivalent (255 when size is 1, 65535 with size is 2 etc...).
- 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>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.
*** needs updating ***
<?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="commandClass">1:SWITCH_BINARY,BASIC</property>
</properties>
</channel>
<channel id="switch2" typeId="switch">
<label>Switch 2</label>
<properties>
<property name="commandClass">2: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>