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 linked using the Type and Id, as well as the VersionMin and VersionMax, 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. VersionMin and VersionMax are decimal values. With these specifiers, different config files may be specified for different versions of the device if needed.

<?xml version="1.0" encoding="utf-8"?>
<Manufacturers>
	<Manufacturer>
		<Id>0086</Id>
		<Name>Aeon Labs</Name>
		<Product>
			<Reference>
				<Type>0002</Type>
				<Id>0001</Id>
				<VersionMin>0001</VersionMax>
				<VersionMan>0001</VersionMax>
			</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>fibaro/fgd211.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>

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.

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

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>

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.

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>

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>