Z-Wave Device Database Usage Guidance

The database is designed for manual entry of some data, and automatic entry of more detailed device specific data. Manual entry is required for configuration parameters,  associations, device names etc, where such information is not provided by a scan of the device itself. Automatic entry of data is performed by uploading the node XML files that are automatically produced by openHAB directly to the database system. These files are generated by openHAB when it performs device discovery and contains all the information on supported command classes and their configuration.

Automatic entry, and update of references (eg the deviceType and deviceId) is preferred to avoid mis-entry of the information.

To use the database you must first register on the site, then email, or open a ticket to have your access updated to allow you to edit the information. Please avoid adding comments to this page or other pages to request access or discuss issues. The comments section is to help provide a record of changes, or device issues and shouldn't be used as a forum as it is not read routinely.

Each database has a comments section - this should be used to provide information to other users, or make a comment that may help understand why changes are made at a later time. If you have an issue with a device, please discuss this on the openHAB community forum and not in the comments section of the device database page as this is not monitored.

Please remember that the database is used by everyone, so when entering data, please consider others. Think about usability in the User Interface and use the features the database provides to enhance the way data will be presented to others. By spending a little more time to improve the data, everyone will benefit.

 

Device Identification

Devices are identified in the database by 4 pieces of information that are provided by the device during the initial discovery process. These are -:

  • Manufacturer ID
  • Device Type
  • Device ID
  • Firmware version

The primary identification is performed using the Manufacturer ID, Device Type and Device ID and it is important that when entering data into the database, these are correctly identified. Many devices use multiple deviceType and deviceId sets to identify different regions, or other minor differences.

Often a manufacturer will have a different model number, and possibly different Type and ID for the same device in different regions (eg ZE32EU, ZE32UK and ZE32US) - unless these are known to be different devices with different configuration, then it is best to simply call them by the model number without the regional part (eg ZE32) and use a single database entry.

Most devices don’t use the firmware version, but some devices have different firmware versions with different features in the same device. The database handles this by introducing a new device and using a minimum and maximum version numbers that is applicable to the device. By default, a device should be configured with the maximum version to detect all new versions (ie set to 255.255). This means that new devices will work, even if new features are not supported without a database update. When a new device is made available, the existing device should be set to a max version lower than the new device, and the new device min version set appropriately.

NOTE: If you find that there is already a device in the database with the same Type and ID as the one you want to add, don't just change them or add duplicates. Please flag this to me on the openHAB forum and we'll try and work out how best to handle it - for example, the device might be a newer (or older!) version of a similar device with different firmware.

 

Updating Existing Devices

If you have looked through the database and found your device, but the information is out of date then there are two possible updates the database can perform. Firstly, when the database was created it may not have contained all the detailed information for the device. If this is the case, there will be a message printed across the top of the device summary page. Secondly, many devices use multiple sets of deviceType and deviceId as explained above in the device identification section. Again, uploading a new XML file will allow this to be resolved. When you upload a new file, the database will perform some consistency checks to make sure the device is the same - it checks the manufacturer, and the device class - the checks are not foolproof, so please try to ensure the device is really the one you have!

To upload an XML, select the Update Device option from the tools menu in the top right of the device summary page.

Currently the database allows manual editing of most data, but it is preferable to upload the XML files rather than manually editing the fields as this will be less error prone.  There are some instances where manual editing is the only way of doing something, but please be careful editing things other than text fields (labels etc).

The database does not allow users to delete data. If you need to remove something, then mark the label with "** DELETE **" or something similarly identifiable.

 

Adding a new version of an existing device

If you have a different version of a device in the database, before adding another entry to the database, check that the association group configuration, parameters, and channels are the same. If they are, then it is only needed to update the device IDs of the existing device. If there is a new version required because the above data has changed, then first edit the exiting devices versions so that it does not conflict with the new device, then you can add the new device.

 

Adding New Devices

First, start by checking that the device is not already in the database by doing a search in the Device List. Some manufacturers use multiple sets of Device Type and Device ID for the same device to represent different regions etc, so don’t create a new device if it exists, just add the extra references into the existing device.

Once you’ve clearly established that the device doesn’t exist, you need to create a new device. There are two ways to create a new device - either by uploading an openHAB node XML file, or manually. The recommended approach is to upload an XML file since much of the information about the device will be filled in automatically, and errors will be minimised, however if you don't have the device, then you need to create is manually.

 

Creating a device from an XML file

This allows creating of a device from the XML file that openHAB generates once it has initialised a device and this is the recommended way to create a device. Go to the Device List and click on the tools button in the top right of the page - this will provide you with the two options listed above. If you are uploading an XML file, you should enter the device name and label. Below this information is a box that allows you to paste in an XML file. Open the XML file for the node you want to add (in the /etc/zwave folder for OH1, and the {userdata}/zwave folder for OH2) and paste the data into this box and press the Submit button.  This will perform some sanity checks on the XML file to ensure that it has all the information required, and that it is consistent with the information you manually entered, and that another device with these identifiers doesn’t already exist in the database.

If all is well, the device should be created, and you will receive a report stating what was performed. You will then be transferred to the device summary page. This lists all the information about the device – the information you’ve manually entered, and the data extracted from the XML. Scroll down this page and edit the relevant sections as required.

No information will have been added for configuration or association groups. These will need to be entered manually, using the device manufacturers manual as a reference. 

If the device supports multiple endpoints, then you should rename the default names that were added during the device generation. Ideally, provide a name associated with the function of the endpoint, so for a switch that supports two switches, one on endpoint 1, and the other on endpoint 2, you could rename the endpoints to “Switch 1” and “Switch 2”.

 

Creating a device manually

If you don't have an XML file, then you need to create the device manually. Really, the only time that this should be needed is if you don't yet have the device - in this case, the best approach is to create a new device, and fill in the minimum information only - this is the manufacturer, device name, and the device type and id. This will allow a database file to be created, and you can add configuration parameters and association groups from here. It is not recommended to manually enter the detailed device information as this is prone to error. Once you have the device running, and it creates an XML, please return to the device summary page and update the information by uploading the XML file.

If the warning above is displayed, this means that only basic information is available for the device - this provides the configuration and association information required for configuration, but not the detailed information required for use in OH2. If you have this device, and have an XML file, then please upload it.

 

Updating endpoints

An endpoint in the database is the same as an endpoint within the device - this isn't a command class. An endpoint is effectively a virtual device within the device and (typically) supports multiple command classes. Each command class may have multiple 'channels' (to use an OH2 term) or information that the user may be interested in - most don't, but where multiple alarms, or sensors are supported within a class, this is how it's done...

This is endpoint 0, which normally contains a lot of 'service' classes - eg all the associations, configuration, wakeup, version, manufacturer information etc - basically stuff that users don't care about. Of course endpoint 0 also has some user classes, but you'll see that the other endpoints don't have this device level information, so there are more classes in endpoint 0… 

Now to look at endpoint 1 (if there are multiple endpoints). Here we only see the more user oriented command classes - in this case the switch and the meter. You can also see what I mentioned about channels - the meter class supports two channels -the current power (watts) and the power consumed to date (kWh). These can be associated with items (in OH1) and channels (in OH2). 

From here, you can go through and rename the channels - eg the "Electric meter (watts) 1" might be better labelled "Plug 1 power" or something, so you can click on the edit button and change the label (remember though that this is a generic database, so don't call it "Master bedroom" or something specific to your house - you can set this later in OH2 when items are defined, and this just becomes the default). If there are duplicated channels between endpoints, or the same data on multiple command classes, this should be consolidated. There are also some other fields you can set - these are kind of like the options that we might have in OH1 items). There's also the 'Overview' input where we can provide a description using a nice editor - this is later used to create the device instruction information (it's not currently included at the moment though)...

 

Copying Configuration From Another Device

The database allows copying of configuration information (configuration parameters and association groups only) from one device to another. Firstly, the device must be included into the database, so you need to follow the steps above to add a device by loading the XML file. Once this is complete, you can go to the device summary page, and click on the tools button in the top right of the page. Here you will find an option to copy the configuration - select this option, and you'll be presented with a list of devices in the database - select the device and the system will copy all the configuration parameters and association groups into the original device.

Note that if you start adding parameters or groups to the device manually, then the option to copy from another device will not be available. This is to avoid conflicts, so you should copy the configuration from another device first, then tailor it to the new device.

 

Configuration Parameters

Configuration parameters are needed to allow the device to be configured as different users want to use their device. The database provides a flexible system for configuration of parameters that is mostly straight forward and self explanatory, but there are a few fields that require explaining.

Most of the information required when filling in the parameter configuration is provided in the manufacturers manuals.

  • Parameter ID: This is the identifier of the parameter. It is a number between 0 and 255.
  • Bitmask: This allows separation of a configuration parameter into individual 'sub-parameters'. Ideally, each component of a devices configuration would be defined separately in individual parameters, but this isn't always the case. In some cases, a manufacturer might use a single parameter to configure (for example) the volume, and style of an alarm By setting the bitmask, we can separate these two fields out and allow the user to control them individually. The bitmask is (currently) defined as a hexadecimal value - the bits must be continuous.
  • Label: The label should be able to fit in a single line and should not contain any HTML markup.
  • Units:
  • Description: The description should be able to fit in a single line and should not contain any HTML markup. If you need to add extended information about the configuration, then you should use the Overview box which can use HTML.
  • Size: This is the size of the parameter (in bytes). If this is a logical sub-parameter, this should be set to the physical size of the parameter - ie all sub-parameters will have the same size. The size must be consistent with the device.
  • Minimum: This should be set to the minimum value when the user is manually entering data. When parameter options are provided, and the Allow free entry option is ticked, then the minimum value should be set to the minimum that the user can enter manually - ie options can use values outside of the minimum and maximum value.
  • MaximumThis should be set to the maximum value when the user is manually entering data. When parameter options are provided, and the Allow free entry option is ticked, then the maximum value should be set to the maximum that the user can enter manually - ie options can use values outside of the minimum and maximum value.
  • Default: This should be set to the manufacturers default value.
  • Read Only: Tick this if the parameter can not be written to.
  • Write Only: Tick this if the parameter can not be read from.
  • Allow free entry: If the parameter has some options defined, these will be presented in a list in the UI. By enabling 'allow free entry', you allow the user to type in any other value as well as these options. Sometimes the manufacturer might set an allowable range, but specific values might have special meaning. For example, a parameter might be used to set the position volume of an alarm between 0 and 100%, but a value of 255 might be used to set a special function. In this case, 'Allow free entry' can be set, and an option can be added for the special function. The user can still type in any value they like, but they get the option of the special value as well.
  • Advanced: Advanced options are initially hidden in the UI unless advanced mode is selected. This allows users to focus on important configuration settings. Please consider setting the advanced flag on parameters that are either not used often, or potentially have unwanted side effects.
  • Overview: This allows entry of extended information about the parameter. It should be formatted using HTML and the database provides data entry in a WYSIWYG editor. Please ensure that lines are not terminated with a line feed except at the end of paragraphs. This allows the information to be nicely presented in the browser.

When entering labels, keep it short. Avoid things like "This sets the notification number" - just use "Notification number", or in associations "Nodes to receive the thermostat update" - just use "Thermostat update".

 

Options

Options can be provided for a parameter to provide the user with a textual input. Note that if the Allow free entry box is ticked for the parameter, then the user can also enter data manually so long as it is inside the minimum and maximum value for the parameter. Option labels should be kept short so that they fit nicely in a single line in the browser. Longer information about the option should be entered in the Overview box which can support basic HTML markup.

 

Sub Parameters

The Z-Wave binding supports a concept of 'sub-parameters'. This allows elements of a parameter to be processed as if it were an individual parameter. in order to do this, we introduce the concept of a bitmask to the parameter - this allows us to separate out the relevant parts of a parameter, and the configuration will process it as though it was a parameter in its own right. The bitmask is a hexadecimal value used to mask out contiguous bits in the value.

To explain this further, let's look at an example. A parameter might have two elements - volume and style of an alarm. The lower 8 bits might be the volume, and the next 3 bits might specify a different sound type. Let's assume this is parameter 20, it would then be specified as follows -:

Two parameters would be added to the database -:

The first parameter would be specified as parameter number 20, with a bitmask FF (to mask out the first byte). The minimum and maximum would be 0 and 100 (to make this a percentage)

The second parameter would also be specified as parameter number 20, but with a bitmask of 700 - this is masking out the first 3 bits in the second byte. In this case we would have a minimum of 0, and a maximum of 7. In this case, if we're specifying different sounds, we might add options to set the siren sounds - again these would be set between 0 and 7 - the binding handles the bitmask, so to take these values and put them in the correct part of the configuration parameter.

  

Changing parameters in openHAB rules

To use a configuration parameter in a rule, or display it in the UI, a channel must be add. This should be added to the Configuration command class in the endpoints list. It should be given the type config_decimal and there should be an option parameter=XX where XX is the relevant parameter ID.

 

Associations

ZWave uses associations to configure devices to send commands to other devices, and the controller, when certain events occur. In openHAB, the binding will automatically configure the ZWave Plus Lifeline group, but other groups may be configured to be automatically set if needed. This is not normally required for sending reports to the controller however, and configuring additional groups can cause duplicate commands to be sent to the controller.

  

Entering textual information

The database has been designed with multiple text fields to describe a device. Some of these are text only, while others allow basic HTML elements. Please use the fields appropriately – don’t just add everything into the Overview box for example, or add the device manufacturer or model into the device name, and then also put it at the beginning of the description. By doing this, we can ensure a consistent format for all devices as the export tool can appropriately combine the information so that everything is presented in a similar way no matter who entered the data.

Keep text labels short and concise. For example, instead of writing "Threshold of current for the Load Caution", use "Load caution current threshold".

If adding information as bullet points, or numbered lists, please use the editor buttons to format the data rather than manually adding the numbers or bullets. This ensures consistency and allows UIs to present the data more appropriately.

Avoid reiterating the title - eg in the inclusion section, just write the steps required to include the device, don't write things like "the following steps are required to include the device".

It should be noted that when the editor saves the text, it will filter out any HTML tags that are not permitted, and any CSS styling. This shouldn't affect the text, but is designed to make it more portable across UIs.

 

Reference Material

We can't add all information into the database, so to ensure reference material is available, it's possible to upload manuals etc and associate this with the device. At the bottom of the device summary page is where this can be found.

 

Errors and Warnings

The database software will perform a number of checks to try and detect data entry errors, to suggest things that might be wrong with the database entry, and to try and enforce consistency across entries. These are listed at the top of the device database page - errors are listed in red, and these must be removed before the device can be approved. Warnings are in yellow, and information messages are in blue - these don't need to be removed before approval.

  • Endpoint 0 has no command class linked to the basic class: Many devices will report changes using the BASIC class, and the binding needs to know how to handle these messages. Nearly always, the BASIC class is mapped to a specific class, and this link needs to be made in the database. If you have a binary light, then this will likely be SWITCH_BINARY and to remove this information message you need to tick the "Treat as BASIC" box in the appropriate command class.
  • There are 1 association groups but none are linked to the controller. Is this correct?: This means that the device supports association groups which are used to report state changes or sensor updates, however no groups are configured to report to the controller. Therefore, the controller will not receive these state updates if it is not added to the appropriate group. Often there is a Lifeline group, or other group that is specifically designed for sending reports to the controller - this should be identified from the device manual, and then the "Controller" box should be ticked for this group.
  • Device supports configuration, but no parameters are defined: The CONFIGURATION command class is supported by this device. This likely means that the device has configuration parameters, however these are not defined in the database so they will not be available in the user interface.
  • Device supports associations, but no groups are defined: The ASSOCIATION command class is supported by this device. This likely means that the device has association groups, however these are not defined in the database and this may mean that reports can not be sent from the device to the controller.

Many warnings aim to improve consistency by enforcing label lengths, capitalisation, naming conventions etc. Please don't ignore these - they are there to provide a consistent database in order to provide the best possible user experience.

 

The Review Process

Changes to the database are logged so that we can review the updates before they are made available for use. Once you have finished making changes, then you will need to request a review - this will email the reviewers, and someone can check the updates and accept them.

The image above shows what you will expect to see once you have made changes, and once you've requested a review of the device. It's worth noting that you will only the see list of changes that you have made - changes made by other people won't be visible, and the 'Request Review' button is only displayed when you have made changes to this device.

Before requesting a review, please ensure that all errors and warnings are removed. Many warnings are designed to ensure consistency between different devices within the database so please try to make update as per the warnings.

Once the device is reviewed and approved, files are exported in various formats for different products. For openHAB, the XML files are automatically produced and made available for a Pull Request into the binding repository in Github.

 

Edit Locking

A device may be locked from general editing. This is aimed at preventing changes to devices that are considered stable, and have achieved the required level of quality. A user can request that a device is locked once all data is entered, all warnings removed, and they believe that the quality of data is high and well formatted. A critical review will be made to ensure this is correct, and if so, the device will be locked from general editing.

Once locked, a user may request it is unlocked for them to edit. They will be given a period of time to make changes before it is locked again. Ideally, any changes should have been discussed with other users on the community forum before requesting the database is updated.

The image above shows a device that is locked, with a button to allow users to request it is unlocked for them to edit.

 

For a device to be considered for edit locking, it must be complete and high quality. Some issues to check before requesting a device is locked -:

  • All errors and warnings at the top of the page are removed. Sometimes a warning may not be applicable, so this can be ignored in some minor cases.
  • All overview fields are filled in with the detailed information. This is required for device level data, as well as configuration parameters where applicable.
  • Labels and options are properly capitalised. They should start with a capital letter, and should not be all upper case or lower case.

 

Documentation Generation

The database is used to generate documentation for the openHAB binding. You can view this by clicking the Export button, and selecting MD Documentation. You are encouraged to do this prior to submitting the device for approval so you can see the result of your changes.  By careful use of the label, description and overview fields in the various parts of the database, high quality products should be achieved for the user interface and the documentation.

 

Comments

Each database entry contains a comments section at the bottom of the page. This is intended so you can report observations with a device, configuration that you found useful, updates that you made to the database etc. It is not intended as a discussion forum!

If you have problems, or want to discuss something about the device, please open a thread on the openHAB community forum