Z-wave device template; adding new device

Intro (less important)
Not being a programmer I have struggled to configure OpenHAB2 on RaspberryPi3 with z-wave.me USB Stick.
It seems there are plenty of files in different locations, but I didn’t find an explanation in one place.
Until now I’ve managed to find my way through the documentation (as a side note: it’s been a difficult task, though, and the lack of information whether the documentation is about OpenHAB1 or OpenHAB2 in many tutorials, on many pages, hasn’t made it easier tbh.)

I bought the cheapest contact sensor (door/window) available from “Kaipule Technology Co., Ltd”. It seems to be the IM-20. It doesn’t show any channels; The info in database is incomplete. I can’t get it to work.

What I am asking
How to create a template for a new device (the one mentioned above in my case, but my question is more general), so I could test it and upload to the database on chris’s site once it’s working?
I’m not interested in uploading something before I’m really sure it’s working, I hope you get the point :wink:

What I already tried (to no avail)
I found the information about how to upload (create an account, ask access etc.) but I have literally no idea how to create the template (some file? xml? json?), where to put it and how to test it.

It seems there is this json file containing all the needed info (the xml files are re-created if needed according to chris).
So I have edited this json file according to the info I have about my device… and all is gone, cause OpenHAB has overwritten the file with what it’s found in the database, I suppose, which is incomplete (see above).

To sum up
Assuming a new z-wave device, good documentation on paper, but not in database for OpenHAB - what to do? how to create an entry? where is it stored? Can it be tested? edited?

If there is someone who can explain (or point to a good source) how the binding actually works, its structure, files etc. that would be appreciated. I’ve started to read how to create a new binding, but honestly it’s way too complicated for a beginner, so I gave up.

Documentation is not the strongest point of OpenHAB, but considering its potential, I’m really glad there are people actively explaining things on this forum. (I’d love to contribute as well, but I know nothing :wink: )


You’ve already found all needed docs: :grinning:

Go to your /userdata/zwave folder and find the xml created during inclusion, upload that file to the database, wait for the changes to get approved, wait for the changes to get merged to the zwave binding, wait for the new compiled zwave binding, upgrade to that new zwave binding (if you are using the snapshot runtime, just uninstall the binding and reinstall it again).

If you don’t have an xml the entries in the database need to be edited manually according to your device manual.

No need to compile your own zwave binding, you just need a little bit of patience until new versions are available (normally it takes around two weeks, depending on the spare time of the maintainer)

There is no need to edit those files, you can easily screw up your system …

Thanks for your answer

Ha! That’s what I thought for the most part of last night :wink: The thing is I don’t want to submit to database on chris’ site, unless I know what I am doing. There is enough of wrong information on the Internet already :stuck_out_tongue_winking_eye:
I want to get it working with my system first. Is it even possible?

Although it may be indeed the right way, I’m not being optimistic for three reasons:

1 - I checked on this file and there was no useful information in it. The json file on the other hand is supposed to contain some info about available channels, isn’t it?
2 - my device is not working correctly - it seems to communicate with the controller, but there is no channel I could connect to.
3 - there is an entry in chris’ database, but it’s incomplete. One of possible reasons IMO is that someone has uploaded an incomplete entry based on xml file which was not working. (Please feel free to explain how and why am I mistaken).

You’re right, and it was not my intention :wink: - I just wanted to understand how it works and where to search for more info.

In other words: To do it my way I need

  • to translate what I got (on paper and in the Internet) to something useful,
  • put it at the right place in OpenHAB2,
  • check if it works and
  • upload to global database.

If that’s the wrong way, what is the right one?

As @sihui mentioned, unless you edit your local copy of the database (undocumented so you are mostly in your own) and recompile the binding, you have to update the DB online, wait for it to be approved and gets compiled into a snapshot. Chris is usually much faster than two weeks for this sort of thing unless he is traveling.

Yepp, sorry, was referring to updates to the development version of the zwave binding which takes usually two weeks :sunglasses:

It looks like no XML has been uploaded as there are no endpoints defined, and this is what the XML does. Someone has created the entry, but basically not added any information. If you have an XML, then please feel free to upload it…

Thanks, it’s getting clearer now :slight_smile:

so you’re basically saying there is no need for a user to test it beforehand.

All a user has to do in case of an unknown device is:

  • to take the automatically created xml file
  • add the file to global database
  • it will be automatically adjusted,
  • revised by Chris and then
  • made available for the binding.

Am I right? If yes, I will accept this post as a solution.

Sorry for being so inquisitive, but I thought it is better to ask than mess up with the global database without understanding what is going on. Please also note, that although the Database Guide explains how to do it, I was not able to find any information, that it is what should be done. It seemed to me I was missing something in between.

Yes - thats correct.

No problem at all :slight_smile: .

Yes, you’re right, and this is partly due to the fact that the database was not 100% dedicated to openHAB - it’s also used by other products so I wanted to avoid writing too much OH specifics there… I know that probably leads to some confusion - sorry for that.


I have a problem with my Hauppauge-sensors. A lot of 4in1 door-sensor, a smoke-sensor and a 3in1 flood sensor.
I think they are nearly the same like the philio or devolo.
When I include them, I get the message unknown device. I google and read in the forum and the jackson page, but I don’t find a really good solution.
In the Z-Wave folder is no builded xml. I search in the forum and find node.xml from philio and add it to the folder and edit the xml-tag node. When I delete the node and include them again. Openhab find the the sensor and add a thing with the items. I get values, but more random. For example the contact items is every time open or close.

What can I do? I found a topic to the same problem, but no answers. Hauppauge mySmarthome 4 in 1 sensors


That’s a battery device, I suppose, isn’t it?
Not being an expert I would try to remove the xml node file you’ve copied from somewhere, then let OpenHAB find and include the device and then - and this may be really important - wake the device up few times until a xml node file is created automatically (if not :thinking: - scream for help :stuck_out_tongue_winking_eye: )
Then you should do what I marked as a solution.
Anyway, please keep us updated.

These z-wave sensors are crazy.
I have actually 7 sensors here. 1 devolo door sensor, 4 Hauppauge 4in1 door sensors and 2 3in1 Hauppauge flood sensors.
I removed the xmls, but so really nothing happened. Then I delete the binding and the things. Then I install the binding. Put all devices near the raspi with usb-stick. Now he found all sensors with a name. For 5 of 7 he generated a xml.
One for the devolo, 3 of 4 for the hauppauge door sensors and 1 of 2 for the flood sensors.
For the devolo I get values and openhab shows me, then the door is open or closed. For the door sensors with xml I get no values. I touch the trigger of the sensors, i set off and on the battery, nothing happened. In the logs also nothing happened. I also kicked a thing and add it. No values.

The flood sensors are crazier. The flood sensor without a xml send me the temperature and the battery. The flood sensor with a xml has no values.

What can I do?

edit: the devolo also do nothing. I open and close the door, nothing happened. coolio :frowning:

Crazy they are :wink: Did you try to wake them up several times? That way every device should end up having its own xml file. At least that’s what I suppose.

If you see some reports, there has to be at least one channel defined for the devolo sensor. Did you do it? or was it the “autolink” from PaperUI?
I, for instance, don’t use the PaperUI, cause it’s getting too messy with autolinking any possible channel.

How about other devices? I suppose no Hauppauge has any channels, because they seem not to be in the database - they won’t work at the moment. Not until you take the xml files and update the database (like in the post marked as solution).
Then you’ll have to switch to the snapshot binding in order to use the updated database.

I know - it is complicated. So many times I wanted to give up already :roll_eyes:
But once it’s working it’s so much fun :wink: