Page 1 of 1

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

Posted: 07 Sep 2020 10:57
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):
<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>
<description>
</description>
<productName></productName>
<brandName></brandName>
<productCode></productCode>
</deviceData>
<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:
In ZDDX folder there is a xsd schema file 'z-wave_v2.xsd'. A xsd schema describes
the required structure of a 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.

If you are using a 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.