Zwave .things file syntax

Hi all,
I have been searching for the whole afternoon for the syntax of ZWAVE .things OH2 file with no success.
I have tried the following:

Bridge zwave:serial_zstick:controller [ 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"]
Thing zwave:device:controller:node3 (zwave:serial_zstick:controller) [ zwave_nodeid="3" ]

But had no success: meaning that the BRIDGE works, but the THING is discovered but remains in INITIALIZING state forever.
If I add the THING using PAPER UI it works, so it must be something with the syntax of the .things file.

The same configuration was working perfectly with OH1.

Can someone help me please?


If I remember and interpreted @chris’s comments on a different thread correctly, I don’t think the OH 2 Zwave binding supports defining your own Things in a .things file. I could be wrong, I often am when it comes to zwave.

Let’s wait for Chris words then.
I hope you are wrong :wink: as it will be a real reason not to upgrade to OH2

Just be aware that you are not required to use the 2.0 version of the zwave binding in OH 2. You can happily run with the 1.9 SNAPSHOT. You may need to enable the “Include Legacy 1.x Bindings” in Configurations-> System -> Extension Management in PaperUI it to show up in the list if you don’t see it.

Beyond the consistency of being able to use text files for Things, what is the benefit/capability that pushes you to need to define them by hand?

In my admittedly limited experience, if the zwave 2.0 binding can’t autodiscover the Thing and initialize it, it isn’t going to work anyway. Its the same as in OH 1.x when the binding doesn’t produce the node.xml file.

Hi Rick,
I know I could use OH1 Zwave binding, but according to Chris comment ( it’s better to move to the new version.
And also he is saying that is only the device configuration that it’s not supposed to work, not the things text definition.
Also Kay confirmed this at the end of the following post:

The 2.0 binding is discovering the things and they appear in the inbox correctly.

So I would really like to use the new V2 binding, but want to use the text file to configure it.

The only thing that is missing is the syntax of the .things file that is not explained in the Zwave binding documentation ( and it’s impossible to guess.

Can someone who has already configured a .things file for Zwave help me please?

thanks a lot.

You can use the 2.0 Zwave binding without the need for a .things file. Just create the .items file for the z-wave binding like you used to do in OH1 and you are good to go.

Okay… these items do not show up as things in the Paper UI…but maybe you are more comfortable with the basic or classic ui anyway

I am not sure I understand. How do I create the channel links in the items file, if I don’t create the things?
I thought that I should define the things and then the items.

Now I am confused.

Edit: also shouldn’t the devices appear in the Karaf console as things?

In my case I have also decided to keep with a .items file.

However I use HABmin to discover and create the things. This also exposes the channels. Depending on the thing there may be multiple channels.

I then create the items I want in a .item files.

After that I go back to HABmin and then link the item, which will now be visible in HABmin, to a channel which is found in the relevant thing configuration page.

This has been working well for me for over 3 months and I don’t see the need to define the thing and channels in text files.

Hi Mike,
yes, that’s another way. And it works.
But it does not answer the original question. :slight_smile:

In other words, I would like to know what is the syntax for the .things files for the zwave binding.
This could help others to build their system with text files if they want to.
As reported, Kay is confirming that configuring using text files is guaranteed to be working, so it’s just a question of understanding the syntax…


I have seen the syntax for linking items to channels somewhere, but can’t remember where right now, so that allows one more level of control from a text file.

Re: defining things and channels, I think this might be bit more difficult as the core data is from a zwave database that the binding is linked to. So unless you have all the info you need to define the channel etc, then this will be way more work than simply letting the system discover the thing.

@chris has done some work on developing an alternative storage option to mapDB that makes this data easier to look at , maybe edit, and backup. However we are still waiting for this to be added as an option for openHAB 2.

Text files can be used to configure the thing, but you won’t be able to configure the device. This means that you won’t be able to change any device parameters, associations, wakeup period etc. To me, this is quite a large issue, but I leave it to others to decide their individual needs.

The syntax is the same as any other binding - I can’t write this specifically for ZWave.

I need to try and find a way to add channel information into the documentation. I want to automatically generate this from the source otherwise it’s a nightmare to keep them consistent as there are a lot of channels in this binding.

You can however find the information on the channels, and their configuration, in this file. As above, the syntax itself is the standard syntax.

I did see a recent comment from Kai that indicated he was considering this, but yes, at the moment it’s not included. To me, this is a useful solution as I think it provides a good compromise between the utility of the UI configuration, and the ability to see what is in the database, edit it and copy it. Oh, and it’s significantly faster than mapDB as well!

For reference, the PR is here -:

1 Like

Hi Mike,

It’s not the system that discovers the things. It’s the binding.

The alternative storage option is another way of doing it.

But I would like to know the easiest, such as the text file :slight_smile:

Hi Chris,

I understand and I accept this limitation.

Can you give me an example please?
All bindings have different syntax in the things file.

A simple working example will really clarify the issue.

Thanks a lot.

EDIT: If I could find the syntax myself I wouldn’t have asked. If I am asking is because I cound’t find. :slight_smile: Any help would be appreciated.

Using your example, I think you might need curly braces? When trying to do this with another binding (squeezebox), I had to hunt around a lot to find this.

Bridge zwave:serial_zstick:controller [ 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"] {
    Thing zwave:device:controller:node3 (zwave:serial_zstick:controller) [ zwave_nodeid="3" ]
    Thing ....

Without the curly braces, I think it just creates a thing not associated with a bridge…

Thanks Mark.
Will try tonight at home.
Will post result.

Adding some other considerations.
It’s not true that the syntax of the .things file is the same as any other binding.
Every single binding has it’s own syntax.
Infact looking in the documentation section of openHAB2, there are THINGS definitions for many of the bindings (not for Zwave, thou).

So for example for the squeezebox server, it tells you that for the Bridge you should specify the ipaddress and the webport, while for the Thing you should specify the mac address:

Bridge squeezebox:squeezeboxserver:myServer [ ipAddress="", webport=9000, cliport=9090 ]
Thing squeezebox:squeezeboxplayer:myServer:myPlayer[ mac="00:f1:bb:00:00:f1" ]

Homematic example (gatewayAddress, callbackHost, callbackPort, etc):

Bridge homematic:bridge:ccu [ gatewayAddress="...", callbackHost="...", callbackPort=... ]
Thing HG-HM-LC-Dim1T-Pl-2     JEQ0999999

Onkyo example (ipaddress, port)

onkyo:onkyoAV:myOnkyo [ipAddress=””, port=”60128”]

So the question regarding the syntax of the THINGS file is what are the parameters that I should put inside the square brackets for configuring the Bridge and for the Thing?
I assume that only @Chris can answer this, as he’s the developer.

In the meantime I will test the suggestion made by Mark.


Can you give me an example please?
All bindings have different ways of writing the things file.

The overall syntax should be the same for every binding in OH2 - sure - channels and options etc will be different between bindings, but surely the overall syntax is the same?

Unfortunately I can’t give an example as I use the UI to configure the system - I’ve never used items files in OH2. Sorry. There is a thread somewhere on the forum that describes it though, but as I’m travelling I don’t have access.

I assume that only @Chris can answer this, as he’s the developer.

As I said I don’t use this so I can’t provide any concrete examples. I do all my configuration through the UI due to the major limitations of the text files (i.e. not being able to configure devices, so you will need to find other software to do this). I provided the reference to the XML file that defines all the channels used by the system, and the options available. There are literally hundreds of devices, and dozens of channel types - I can’t provide documentation on all of this - sorry - I would spend my whole time writing documentation for devices.

As said earlier, there is a thread on the forum that describes the format from memory.

BTW, that squeezebox example above is incorrect. It needs curly braces. The documentation needs to be fixed.

If implemented as above, the player will never come out of the Initializing state.

Not only considering - if it as as good as you claim, we will use it for sure. It’s just still on my to-do list to be reviewed and merged, sorry…

Not that the contribution guidelines ask for such an example and I think we have it on every binding with the exception of Z-Wave. So even if you are not using it yourself, I would strongly encourage to add textual configuration examples - this might be even helpful for yourself for testing, so that you might notice issues yourself, before the binding users stumble across it. And this thread here seems to indicate that such an example is strongly desired!

No, the syntax should be all the same and it is explained at