zz Using the MergeAllianceProduct Script
The MergeAllianceProduct script is a perl script that we have written to import the Device from the Z-Wave Alliance Product Database to the OZW Device Database.
The script is written in perl and is available in the OZW Source distribution under the tools directory or you can download it here
The Perl Script depends upon XML::Twig which should be available via your distribution repository manager (Please send us the RPM and apt commands to install so we can update this documentation!)
Please navigate to the Z-Wave Alliance Product Database and locate your product. At the bottom of the page, you should find a link "Download Product Data in XML Format". Please copy the link it points to (it should be something like https://products.z-wavealliance.org/Products/3257/XML)
From the directory where the mergeallianceproduct.pl script is located, execute the following command:
./mergeallianceproduct.pl -c <OZW Config Directory> -a <path to the product url>
- The "OZW Config Directory" is the full path to where the manufacturer_specific.xml file is located with the manufacturer specific directories.
- The "Path to the Product URL" is the URL to the Z-Wave Alliance Product Entry.
During the execution, you may be prompted several times, especially relating to Configuration Values. This is because the Alliance Database does not contain enough information for us to make a automated conversion. The types of questions and how to determine the right choice is detailed below.
After the script has completed, please review the configuration file created (the script will output the path to the config file it created). Please ensure that the Configuration Options it created are accurate as per the Product Manual. (as we are not sure how often or how accurate this information is updated on the Z-Wave Alliance Product Database.
You should also test the new configuration file with your Home Automation software. Please consult for guidelines on testing.
Once you have confirmed the configuration works with your device, please open a Pull Request and Submit your the changes so others in the community may benefit from the new device support.
The Following is a list of possible prompts the script may ask you for input
This is to generate a ChangeLog entry in the configuration file that credits yourself with adding the device.
Some configuration values are a list of possible options, where only one option can be enabled at a single time. In this case, you would Select "List" as the Configuration Type
Other cases, Vendors will use a large integer field to control a large number of individual features. These individual features are usually "enabled" or "disabled" and are represented by single bits in the integer. An Example from a devices documentation below demonstrates this.
In this case, we can see bits 1-4 control what is sent when a sensor reaches a low threshold and bits 5-8 control the what his sent when a high threshold is set. Typically the vendor would expect the end user to calculate the integer value of what thresholds he wants to enable and use that decimal value as the config value. In OZW, we can represent that configuration as individual bits displayed to the user, and the calculation is done internally. When you encounter Configurations that match this pattern, you should select BitSet.
Some options are often just on/off configuration values. If the script can not determine if it should use a Boolean (on/off) or List (2 options) it will prompt you. As long as the values of each option are equal to 0 and 1 respectively, you should select Bool.
The Alliance Database does not include any names for Association Groups. It does include a Description field, but this field is often long. Please enter a short name that describes the group..
Some devices, such as switches or sensors, often have more than one actual switch or sensor. These additional switches mean the Device Supports a CommandClass called MultiInstance. For example, you may have a 4 way switch (meaning it can control the power to 4 different lights) or a Sensor that reports both a "internal state" as well as external state (indoor versus outdoor temperature for example). Each one of these switches or sensors are represented by a "Instance ID" In order to help identify what Instance relates to what switch or sensor we ask for a short name to help identify what it is actually controlling or representing. These should be names that are generic and not specific to your environment (eg, we would reject "Living Room" as a name). On a 4 way switch, Label Names such as "Top Left", "Top Right", "Bottom Left", and "Bottom Right" would be acceptable. Often the Product Manual will help you name these, so its good to consult the manual.
If you enter 0 for the number of instances, or hit enter for the names, then a Generic name will be used.
In Some cases, the product you are adding may already exist for a different region (thus different type and id values) but are identical apart from frequency. In this case, the Script will prompt you if you wish to use the use the same configuration file for both product entries. If they are the same product, please select Y, otherwise N. Note: We will not accept changes where the same product already exists and you are attempting to add a new configuration file.