[HowTo] create a correct device description (xml, ZDDX)

Tips, Tricks and Scripts to enhance your home automation and workaround known device bugs, limitations and incompatibilities
Post Reply
piet66
Posts: 266
Joined: 04 Feb 2017 17:00

[HowTo] create a correct device description (xml, ZDDX)

Post by piet66 »

The status of the device descriptions is deplorable. Reason I think is, because nobody really knows how to create a correct description. And no manual seems to exist in the Web. Therefore, I have decided to gather my knowledge on this topic here. If anything is not correct, please tell me.

Device descriptions are defined as xml files and stored on the server computer in folder /opt/z-way-server/ZDDX.

Steps to a new device description:

1. In ExpertUI select your device and invoke ZDDX Code Creator

2. Store the resulting data into a file named nnnn-aaaa-bbbb-cccc-dd-ee-ff-gg-hh.xml with:
- nnnn = any number
- aaaa-bbbb-cccc-dd-ee-ff-gg-hh = so called 'Strong Hash', combined from the 8 first parameters of the data from manufacturerId till appSubVersion. Take the parameters from the data exactly as shown as hexa. Although the file name doesn't matter for ExpertUI, it's always a good idea to follow the standard.
I'm using to add an additional character between hash and dot. This has the only purpose to avoid, that the file is deleted at next update of the device descriptions: nnnn-aaaa-bbbb-cccc-dd-ee-ff-gg-hhX.xml

3. With a text editor add the remaining parts to the file.
Required respectively recommended are following tags (in this order):

Code: Select all

<ZWaveDevice xmlns="http://www.pepper1.net/zwavedb/xml-schemata/z-wave" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="z-wave_v2.xsd" 
schemaVersion="2">
    <deviceData>
        <rfFrequency></rfFrequency>
        <certNumber>ZCxx-xxxxxxxx</certNumber>
    </deviceData>
   <deviceDescription>
        <description></description>
        <productName></productName>
        <brandName></brandName>
        <productCode></productCode>
    </deviceDescription>       
    <assocGroups></assocGroups> (add descriptions)
    <configParams>
    </configParams>
    <resourceLinks>
        <deviceImage url="http://....png"/>
    </resourceLinks>
ExpertUI uses the certNumber for a link to the manual, deviceImage url to display an image.

configParams is only necessary, if the device supports parameters. Please note that all parameter values must be in hexa (xx = 1 byte, xxxx = 2 bytes, xxxxxxxx = 4 bytes). ExpertUI doesn't complain decimals, but it won't work properly.

3. Validate your file:
There is an xsd schema file 'z-wave_v2.xsd' in the ZDDX folder. An xsd schema describes the required structure of an xml document. You can use this to validate your xml file. There are websites where you can do this online like for example: https://www.freeformatter.com/xml-validator-xsd.html.

Of course, if you are using an xml editor with xsd support instead of a text editor, this step is not necessary.

4. Add the new description to server:
- store the file into folder /opt/z-way-server/ZDDX
- open a terminal window on the server and rebuild the index for ExpertUI:

Code: Select all

  cd /opt/z-way-server/ZDDX
  sudo python ./MakeIndex.py
Don't care about the error messages. They are caused by buggy xml files.

Now you can select the new device description in ExpertUI

5. Would be fine if you could make your file available to the public. But I don't know how to do that.
Raspberry Pi 3 Model B Rev 1.2
Raspbian GNU/Linux 10 (buster, 32bit)
RaZberry by Z-Wave.Me ZW0700 7.20.00 07.38/1766938484 1025/257
Z-Way version v3.2.3 from 2022-04-06 04:56:23 +0300
rossjulie
Posts: 1
Joined: 09 Sep 2021 16:48

Re: [HowTo] create a correct device description (xml, ZDDX)

Post by rossjulie »

Copied the code on my text editor Visual studio code.To make the code available to public you can save it in GitHub in your account.
Post Reply