Z Wave Product Database

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.

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.

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.

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.

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. 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 no 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 ```true 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. Note 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 (ie 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.
• <removeClass>true</removeClass> 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.

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>
			<removeClass>true</removeClass>
		</Class>

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>