Zwave .things file syntax

It would be great if someone can provide some examples and I can add them to the docs. There are now around 300 things in the database, and many different channels etc, so it can only ever be an example.

What I want to do is auto generate the channels/config parameters from the XML since I have a single XML that defines all the channels (as I linked above). I haven’t quite worked out how to do that yet but I’d like to add to the markdown directly from the XML if possible as keeping two copies (one in XML and one in MD will no doubt end up with errors). If you have any ideas, it would be good ;).

An XSLT transformation from the thing XML into markdown, using something like this for an example. It could also be applied to all bindings’ thing XML files to automate creation of the “Thing Dictionary”.

@kai if we went down this route is it worth adding a separate file for descriptions (things/channels) that is outside the readme? The current Zwave readme is getting quite big already and if we want d to auto generate channel lists and keep it in the current readme we would need a way to combine the files as well - not impossible but I wonder if we’re better to split them?

Hi all,
I consider myself quite an experienced user.
I am contributing to enhance some existing bindings (added several hundred commands to the xbmc binding, etc), so I know how to write and read Java code.

But, really, I tried hard, but I couldn’t find any way to configure the Zwave Things file.

@Kai, I appreciate your interest in this matter.
While the general syntax is defined, the items inside the [] square brackets aren’t.
So this is what I mean when I say that the syntax is not the same.
Maybe I am using the wrong words, but the concept is that.

So for the Bridge and for the Thing we need some example to start with.
For example, for a Bridge, do I need to use all these settings?:
[port="/dev/ttyACM0", controller_softreset="false", controller_master="true", security_networkkey="00 11 22 33 44 55 66 77 88 99 AA BB CC DD EE FF"]
And for the Thing, in some examples I saw users using [zwave_nodeid="5"], in others [NodeID="5"] or even [zwave_nodeid="5", config_1_1="0"].
What is the correct one?

Because all combination that I tested do not work.

And there are other users asking for help with no answers:

So what I am asking is just one working configuration, then for sure we will be able to populate the wiki by ourselves like it has been done with the OH1 zwave configuration examples.

BTW, thanks for all the efforts put in the project.

1 Like

Hi Chris,

in the linked file, there is only the configuration of the channels. Not of the things configuration.
If you could point me to the file in the source code where there is the things configuration, I think I can find by myself the answers.


As mentioned earlier, there are over 300 things so it’s not so easy to document. I suggest that you refer to the online database. Alternatively, if you look in the same folder as I referenced earlier, you will find all the files there as well.

It shouldn’t be difficult for you to provide ONE working example.
Just one working example… please.


1 Like

I created a small gist to show a rough start on converting a .thing XML file to a .md Markdown file (the repeated “Overview” headings are in the XML source of this particular example; you could paste the .xsl and some .thing file here to see it produce different output.) If a proper, completed version of the XSLT file were incorporated into the build of openhab-docs, it might help with the documentation effort.

1 Like

Cool! :slight_smile:

For me, it’s not so much about the thing files - there are too many to incorporate into the documentation (I think anyway - currently there are 314 and growing!). I would tend to point people at the database for the things - at least this is my thought for ZWave - other bindings could be different. (and of course others might think differently :wink: ).

At the moment at least I think the channels are the big issue since this is the building blocks that everything is based on. In the thing definitions we list the channels, but you still need to see what the data type is, and the options, and for me, this is what I’d like to incorporate first…

I’m sure that it would be possible to add this into a maven build though and autogenerate some of this doc, and it would be a huge benefit - at least for larger bindings…

There already is a PR for this:
As it is interesting for Z-Wave, maybe you are interested in checking it out? I didn’t yet find the time to have a closer look at it…

Quick look looks interesting so I’ll try and find some time to play (2 hours on a plane tomorrow night might do).

Hi @Chris,

I have been digging into your code for the last 4 days and I think that the reason why the .things file does not work is because there is a problem in the code that prevents the nodeID to be assigned correctly to the THING. Maybe it’s because you have never tested the binding with a real .things text file.

1st possible problem:
Inside ZWaveThingsHandler:initialize() (line 115) your code tries to read the node ID using this piece of code:
String nodeParm = this.getThing().getProperties().get(ZWaveBindingConstants.PROPERTY_NODEID);

but getThing().getProperties() does not contain any reference to the zwave_nodeid parameter.

Here is the result of getThing().getProperties() for 2 different fibaro zWave devices:

getProperties()= {modelId=FGS222, vendor=Fibaro System, defaultAssociations=3, manufacturerId=010F, manufacturerRef=0202:1002, dbReference=124}
getProperties()= {versionMin=2.1, modelId=FGD211, vendor=Fibaro System, defaultAssociations=3, manufacturerId=010F, manufacturerRef=0100:0107,0100:0109,0100:300A,0100:100A,0100:0104,0100:0106, dbReference=119}

As you can see you can retrieve many information, but not the zwave_nodeid, so your initialize() method does not proceed and we get the error in the log:
NodeID is not set in zwave:fibaro_fgs222_00_000:node3

2nd possible problem:
Another point of failure is inside ZWaveConfigProvider:getConfigDescription and ZWaveConfigProvider:getParameterOption where there is this piece of code:

        if ("thing".equals(uri.getScheme()) == false) {
            return null;

Because all the Things from the .things file have uri.getScheme() == 'thing-type', the mehod returns and the following code that should set the nodeID is never executed:

        // And make sure this is a node because we want to get the id off the end...
        if (!thingUID.getId().startsWith("node")) {
            return null;

Here is the .things file that I have used:
Bridge zwave:serial_zstick:controller [ port="/dev/ttyACM0"] { Thing fibaro_fgs222_00_000 node3 [] Thing fibaro_fgd211_02_001 node8 [] }

And in order to avoid auto_approve of the things discovered in the inbox, I have set in conf/services/runtime.cfg:
set autoapprove:enabled=false

I hope I have contributed to find the problem that prevents the .things file to load correctly

3rd possible problem:
in the .xml files of the zwave devices (…/ESH-INF/thing/) there is no definition of the parameter “zwave_nodeid” that is used in the code.

Possibly, but since the binding doesn’t know about things files, it shouldn’t matter. The framework takes care of the things files so it should be exactly the same as if handled through the UI.

Why not? You need to add the properties or is this not possible in the things file?

You are responsible for setting the information correctly if you use the things files. You must set all the information that the binding needs.

I believe that other people are using the things files so I think that you just need to configure the information.

I will try and take a quick look to see if properties are passed in through the things file.

Correct - as above YOU need to set this.

that’s the point: if you add the [zwave_nodeid=3] in the Things file, it does not appear in the getProperties() method.

I tried this .things file too and I can confirm that in the getProperties() the zwave_nodeid does not appear:
Bridge zwave:serial_zstick:controller [ port="/dev/ttyACM0"] { Thing fibaro_fgs222_00_000 node3 [zwave_nodeid=3] Thing fibaro_fgd211_02_001 node8 [zwave_nodeid=8] }

I will try to make myself clearer: what I meant is that, in the zwave xml files there is the list of the possible parameters that you can configure into the .things file between square brackets:
i.e. config_1_1, config_3_1, config_39_2, etc.

In this list there is no “zwave_nodeid” so I assume that you cannot define the zwave_nodeid from the things file inside the two [ ].

thanks :slight_smile:

No - this is the list of configuration parameters - not properties. They are different - the nodeID is not configurable - it is a one time setting.

Also, not all configuration is done in the XML file anyway.

Ok, so the zwave_nodeid is “correctly” passed by the framework. However, it ends up as a config parameter, and not a property. I believe that this is a bug in the framework (although Kai might disagree ;)).

@kai, shouldn’t properties and configuration be treated the same when created through the DSL and the Inbox? I believe when we add properties to a thing in the inbox, when the thing is created the framework checks to see if there is a config description, and if there is it adds it to the configuration, and if it isn’t, it adds it to properties. Shouldn’t the same be true when creating things through the DSL?

Sorry, I didn’t see this thread earlier. See my comment here.