Z Wave Product Database

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 in OpenHAB1. 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.

It is worth understanding that the database is not required for the binding to work with a particular device. The database allows the system to identify a device, and to provide configuration information about a device. Additionally, it allows modification of functionality that in an ideal world would be automatically provided by the device, but many devices have bugs or quirks that we need to work around.

Adding devices to the database

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. Note that you can probably start by copying an existing file - possibly from the same manufacturer, as often the configuration is similar.

With Eclipse

Within Eclipse, the database is shown in the zwave binding in the Project Explorer under a folder called database (see the image below). Within here, there is the products.xml file, which is the master device file, and a number of directories that contain the specific configuration for devices.

Without Eclipse

If you don't have Eclipse IDE installed with the source code of openhab, you can still help generate the XML required. If you browse the database in the zwave binding repository you can see the existing XML files for other devices. The easiest thing to do is to find a similar device and edit it to contain the correct information for the new device, then past it into an issue in the openhab issue tracker so that it can be added to the binding.

Database Structure

Two types of file are used - the products file, and the device files. Note that HABmin provides a Product Explorer to allow viewing of the database which allows database file content to be checked even without the device. The Product Explorer lists all the configuration parameters, association groups and command classes. Command classes that are not currently supported within openHAB are indicated by a yellow warning indicator.

Product File

There is a single product file. This provides the top level manufacturer information and links to the individual device files.

Part of the file is shown below. There is a section for each manufacturer, and within this, a section for each product. New products need to be added into the exiting manufacturer. Products are referenced using the Type and Id, and this is specified within the Reference tag. Multiple references are allowed for a single product, and this is shown in the Fibaro section. Note that the Type and Id must be specified as hexadecimal values.

Products with multiple versions can be handled in two possible ways. Some manufacturers will keep the Type and Id the same for different versions, and just increment the application version within the device - others will change the Type and Id and may or may not change the application version. If the application version is updated, then this can be handled with the VersionMin and VersionMax parameters in the ConfigFile tag - thus allowing multiple configuration files to be specified dependant on the version of the device. So long as the application version is updated, then it is probably best to use this method. If the application version remains constant, and the Type and Id are modified, then a completely new device needs to be generated. VersionMin and VersionMax are decimal values specified as a double with one decimal place.

<?xml version="1.0" encoding="utf-8"?>
<Manufacturers>
	<Manufacturer>
		<Id>0086</Id>
		<Name>Aeon Labs</Name>
		<Product>
			<Reference>
				<Type>0002</Type>
				<Id>0001</Id>
			</Reference>
			<Model>Z-Stick S2</Model>
			<Label lang="en">USB Controller</Label>
			<ConfigFile></ConfigFile>
		</Product>
	</Manufacturer>
	<Manufacturer>
		<Id>010F</Id>
		<Name>Fibaro System</Name>
		<Product>
			<Reference>
				<Type>0100</Type>
				<Id>0104</Id>
			</Reference>
			<Reference>
				<Type>0100</Type>
				<Id>0106</Id>
			</Reference>
			<Reference>
				<Type>0100</Type>
				<Id>0107</Id>
			</Reference>
			<Reference>
				<Type>0100</Type>
				<Id>0109</Id>
			</Reference>
			<Model>FGD211</Model>
			<Label lang="en">Universal Dimmer 500W</Label>
			<ConfigFile VersionMax=“1.8">fibaro/fgd211-18.xml</ConfigFile>
			<ConfigFile VersionMin=“2.1” VersionMax="2.3">fibaro/fgd211-21.xml</ConfigFile>
		</Product>

Device File

Individual device files are required for each device. These are linked from the product file using the ConfigFile tag.

The device file consists of a few sections.

• General information
• Command classes supported
• Configuration parameters
• Association configuration

General Information

<?xml version="1.0" encoding="utf-8"?>
<Product>
	<Model>FGD211</Model>
	<Label lang="en">Universal Dimmer 500W</Label>

Configuration Parameters

This provides a list of configuration parameters that the device supports. This information is generally provided in the device manual, or in the pepper1 database.

	<Configuration>
		<Parameter>
			<Index>1</Index>
			<Type>list</Type>
			<Default>255</Default>
			<Size>1</Size>
			<Label lang="en">Enable/Disable ALL ON/OFF</Label>
			<Item>
				<Value>0</Value>
				<Label lang="en">ALL ON disabled/ ALL OFF disabled</Label>
			</Item>
			<Item>
				<Value>1</Value>
				<Label lang="en">ALL ON disabled/ ALL OFF active</Label>
			</Item>
			<Item>
				<Value>2</Value>
				<Label lang="en">ALL ON active / ALL OFF disabled</Label>
			</Item>
			<Item>
				<Value>255</Value>
				<Label lang="en">ALL ON active / ALL OFF active</Label>
			</Item>
			<Help lang="en">Activate/Deactive ALL ON/OFF</Help>
		</Parameter>
		<Parameter>
			<Index>112</Index>
			<Type>int</Type>
			<Minimum>1</Minimum>
			<Maximum>2678400</Maximum>
			<WriteOnly>true</WriteOnly>
			<Default>720</Default>
			<Size>4</Size>
			<Label lang="en">Interval to send out reports of group 2</Label>
		</Parameter>

<Type> field

The field allows the file to specify how the interface can interpret the data. The following values are allowed.

• list. Only values from the <Item> list may be selected.
• multilist. Only values from the <Item> list may be selected, however multiple values can be selected at once. The system will add together all the values - this allows bit masks to be specified.
• freelist. Values from the <Item> list may be selected, or another value can be manually typed in so long as it is between the <Minimum> and <Maximum> specified values.
• Any other name in the <Type> field will be treated as a decimal value and must be between the <Minimum> and <Maximum> specified values.

<WriteOnly> field

The <WriteOnly>true</WriteOnly> tag identifies the configuration parameter as one that can not be read-back. Some devices have such parameters, and attempting to read them will result in a timeout. This slows down the binding communications in general, and needs to be avoided. It is especially problematic during the initialisation phase where configuration information is updated. Configuration parameters that do not respond to requests need to be identified and the <WriteOnly>true</WriteOnly> tag added.

<ReadOnly> field

The <ReadOnly>true</ReadOnly> tag identifies the configuration parameter as one that can not be written to. Some devices have such parameters, and attempting to write to them will result in a timeout. This slows down the binding communications in general, and needs to be avoided. It is especially problematic during the initialisation phase where configuration information is updated. Configuration parameters that do not respond to write requests need to be identified and the <ReadOnly>true</ReadOnly> tag added.

Association Configuration

This section lists all the association groups supported by the device. This information is generally provided in the device manual, or in the pepper1 database.

The <SetToController>true</SetToController> tag is intended to tell the system that this should automatically be set to provide reports to the controller.

	<Associations>
		<Group>
			<Index>1</Index>
			<Maximum>5</Maximum>
			<Label lang="en">Switch 1</Label>
		</Group>
		<Group>
			<Index>2</Index>
			<Maximum>5</Maximum>
			<Label lang="en">Switch 2</Label>
		</Group>
		<Group>
			<Index>3</Index>
			<Maximum>1</Maximum>
			<Label lang="en">Controller Updates</Label>
			<SetToController>true</SetToController>
		</Group>
	</Associations>

Command Classes

This section lists all the command classes supported by the device. This is mostly for information, and if you're unsure, it does not hurt to leave classes out of the file (or even to add classes into the file). Where this information is required is where we need to add command class options to modify the way the binding interacts with a device.

	<CommandClasses>
		<Class><id>0x20</id></Class>
		<Class><id>0x26</id></Class>
		<Class><id>0x27</id></Class>
		<Class><id>0x70</id></Class>
		<Class><id>0x72</id></Class>
		<Class><id>0x73</id></Class>
		<Class><id>0x85</id></Class>
		<Class><id>0x86</id></Class>
		<Class><id>0x8e</id></Class>
	</CommandClasses>

The database allows for device specific modifications to the way command classes work. This allows us to work around bugs in devices that would otherwise cause the binding to timeout requests, or request information that the device will not correctly support. While we don't want to remove classes or requests from a device when it really is supported, timed out requests also slow down the binding (for up to 15 seconds) and need to be avoided.

• <endpoint>1</endpoint> specifies the endpoint for this class. By default, endpoint 0 (i.e. root node) will be used, but if you want to set configuration for a specific endpoint, then the <Class> can be duplicated with the same <id> and a different <endpoint>.
• <isGetSupported>false</isGetSupported> stops the binding requesting updates for this command class (ie GET requests). Some devices will not respond to these requests for some command classes when polled (ie they will only send a notification to an association group following an alarm, or periodic update). This option stops the binding making these requests which will time out. This defaults to true.
• <remove>true</remove> will remove the command class from the device. Some devices may report that they support a command class, but they actually don't. Removing the class stops the binding requesting information that will then fail.
• <add>true</add> will add the command class to the device. Some devices may not report that they support a command class, but they actually do. This allows classes that aren't notified to be added.

The example below shows where these options are inserted into the database

	<CommandClasses>
		<Class><id>0x30</id></Class>
		<Class>
			<id>0x31</id>
			<isGetSupported>false</isGetSupported>
		</Class>
		<Class>
			<id>0x84</id>
			<remove>true</remove>
		</Class>

Command Class Specific Configuration

Some devices may report incorrect information when queried, or the functionality they report may not work as expected, and we might want to modify it. Some command classes therefore support class specific configuration as detailed below.

Command Class	Option	Description
METER	meterCanReset	set to true to specify that the meter can be reset
	meterType	ELECTRIC GAS WATER
	meterScale	E_KWh E_KVAh E_W E_Pulses E_V E_A E_Power_Factor G_Cubic_Meters G_Cubic_Feet G_Pulses W_Cubic_Meters W_Cubic_Feet W_Gallons W_Pulses

Multi Language Support

The files support multiple languages. Each label, or help message can be duplicated with a language attribute. This is shown below.

<Label lang="en">Universal Dimmer 500W</Label>
<Label lang="de">Universal Dimmer 500W in German</Label>