How do you make a unknown in openHab2 known?


  • Platform information:
    • Hardware: AMD 64bit
    • OS: LXC-container with Linux 4.15.0-47-generic #50-Ubuntu x86_64 x86_64 x86_64 GNU/Linux
    • Java Runtime Environment: default-jre 2:1.10-63ubuntu1~02
    • openHAB version: 2.4.0-1
  • Issue of the topic: 2 Unknown devices of which 1 is found in the Jackson Database


I have 2 unknown Z-wave devices.

One is found I can find on
the other is a newer version of the same device where only the ID has changed.

So I have now 2 XML files from the Jackson database but I have no clue where to put them.
Of all the information out there is no guide or I cannot find one that explains it step by step.
So what do I do?


What is the step by step approach?

Do I for instance need to save the files where the openhab2 is installed?
If so in which directory and how should the be named?
Can I watch the log (tail -f or log:tail) for something that the file are recognised?

Do I for instance need to compile openhab2 (or just the zwave addon)?
If so where do I put the files in the source tree and how should I name them?

Device 1 XML Excerpt

This one should be found with vendor ID (0214:0002:0001)

      <property name="vendor">Kaipule Technology Co., Ltd.</property>
      <property name="modelId">IM-20</property>
      <property name="manufacturerId">0214</property>
      <property name="manufacturerRef">0002:0001,0003:0001</property>
      <property name="dbReference">633</property>
      <property name="defaultAssociations">1</property>

Device 2 XML Excerpt

Vendor ID (0258:0003:108d) was not found in the Jackson database so I made a change to the predecessor of this device with the same options.

      <property name="vendor">Shenzhen Neo Electronics Co., Ltd</property>
      <property name="modelId">Motion Sensor</property>
      <property name="manufacturerId">0258</property>
      <property name="manufacturerRef">0003:108d</property>
      <property name="dbReference">401</property>
      <property name="defaultAssociations">1</property>

Welcome to the OH community!

If the device is already in the DB, you would not need to change something since it should be in the ZWave binding as well.
If you have a battery powered device, device pairing takes a bit. You might need to wake up the device several times when pairing. It should be detected as the correct device then.

Where did you change that ? In the XML file ?

It does not have any effect to change that XML on your system.
You need to create a new DB entry and supply the XML file from your system.
After the DB entry is created chris needs to sync the database into the next OH build and you need to get and run that before you can expect your addition to take effect.

1 Like

I understand that there is a device database maintained by Jackson and it winds up in the in the openHab2 Z-wave binding add-on also maintained by Jackson.

So the only way to add a Z-wave device description to my openHab installation
is to add it remotely at and wait for the next openhab release?

Personally I will do not believe that that is the only way.
I think you need to be able to test it on my own system before uploading it to the database for the community.

I changed the following line in the downloaded XML

<property name="manufacturerRef">0003:108d</property>`

Since this device is from the same manufacturer and has the same capabilities.


Please read this guide:

Yes. The DB is part of the OH zwave binding code so no believe it or not there is no other way
(assuming we’re talking about you being the first to have/add this type of device).
But you don’t need to wait for the next OH release (i.e. 2.5), it’ll be in the next snapshot as well.

As I said changing the local XML does not have any effect.

First thing I did when I went to that website.
This should be obvious I think.

1 Like

Indeed no effect when you cannot apply the changed file to my installation some how.

This information leads to my next set of questions

  • How do a I get the latest (or update) of my “Z-wave binding” add-on in my openHab2 application ?
  • How can I test a device/thing description XML?

My Investigation of the ‘Z-wave binding’ add-on

In the file /var/lib/openhab2/tmp/kar/openhab-addons-2.4.0/org/openhab/binding/org.openhab.binding.zwave/2.4.0/org.openhab.binding.zwave-2.4.0.jar are the XML-files located which can be downloaded from the jackson’s website.

A jar file is actually a zip-archive which you can edit and add the missing XML-files for my device.
Would that allow me to test a modified XML-file for a new device as an option?

Look at this post from @5iver: Modify a zwave binding jar to add/change a zwave device while waiting for a build

1 Like

Thanks and GREAT!!, this is just what I was looking for.

BTW is this standard for all jar’s in a java applications or is it only specific for this OpenZWave add-on?

Sorry, I don’t know this. Hopefully someone more knowledgeable can step in and answer it.

One of the fixes is found in lots of different posts is a way to manually add Things. I used information from the “OpenZwave” application to find the correct device XML containing the thing type-id and node it is attached to by unzipping the jar file. So no more automatic discovery of devices that are sleeping and then waking them up to still not to be found at all anyway.

What is missing in the Paper-UI is to select a zwave device manually for non click monkeys.

File: /etc/openhab2/things/zwave.things

Bridge zwave:serial_zstick:controller "Aeotec Z-Stick Gen5" @ "Attic" [ 
	//heal_time="<possible values ?>",
	//inclusion_mode="<possible values ?", 
	//controller_wakeupperiod="<usefull values ?>",                                                            
	Thing zwave:serial_zstick:controller "Z-Wave Controller"
	Thing zwave:philio_pan04_00_000:controller:node2 "ZWave Node 2 > Philio Technology Corporation > PAN04-1 Double Relay Switch 2x1.5kW with Power Measurement" (zwave:serial_zstick:controller) @ "Z-Wave" [ node_id=2 ]
	Thing zwave:tkb_tz68_00_000:controller:node3 "ZWave Node 3 > Wenzhou TKB Control System" (zwave:serial_zstick:controller) @ "Z-Wave" [ node_id=3 ]
	Thing zwave:kaipule_im20_00_000:controller:node7 "ZWave Node 7 > Kaipule Technology Co., Ltd. > IM-20 Access Control Sensor" (zwave:serial_zstick:controller) @ "Z-Wave" [ node_id=7 ]
	Thing zwave:shenzhen_motionsensor_00_000:controller:node4 "ZWave Node 4 > Shenzhen Neo Electronics Co., Ltd > Home Security Sensor" (zwave:serial_zstick:controller) @ "Z-Wave" [ node_id=4 ]

Only problem is that OpenHab2 does not do this happily.
When I thought something should work as I configured it only did it after restarting OpenHab2.
As far as I know only the things file is not implemented fully after changing on a running OpenHab2 service. (openhab2 v4.2.1 and binding-zwave v2.4.0)