ZWave binding migration to development version

Setup, Configuration and Use News & Important Changes
1

Important message first - upcoming changes to the ZWave binding will require that existing things are deleted, and re-added so that the binding picks up the latest thing definitions. You don’t need to exclude and re-include the devices from the network, and in most cases the devices should look the same to the user so channels should be the same (the database is the same for all versions).

For some time now, most features and fixes in the ZWave binding have been added to a development branch of the binding with only major issues being fixed in the master branch - and of course database updates have been maintained. I think the time has now (finally!) come to merge this branch into master - it brings with it some new features, and works a little differently in some areas, so users may see some noticable changes…

Firstly - the major enhancements -:

  • Security has been added using the S0 security class. This should allow all devices supporting security to be included into the binding securely.
  • Transaction code has been rewritten to hopefully improve the way transactions are managed.
  • The way associations work has been updated. This is a very messy area in ZWave as there are 2 overlapping command classes, each with multiple versions that all work very differently. This fluidity in the specification means that there are many devices that don’t work exactly as expected - hopefully this will improve the situation for most devices at least.
  • The notification (alarm) command class has been improved to reduce reliance on the database to define all supported events.
  • Color command class has been improved.
  • UoM (Units of Measure) has been added to some reports - eg temperature units are now handled automatically depending on your unit/location preferences.

There are probably a lot of other smaller changes, and while this has been quite well tested now, with many people using this version for some time, I’m sure there will be some issues as more people migrate. The association changes mentioned above may cause some devices to send reports in a different way, which may mean some channels could change on some devices (note the excessive use of words like “could” and “may” - there are over 800 devices now supported by the binding, so it’s hard to be sure that nothing will change :roll_eyes:).

So, to reiterate, this binding will require that existing things are deleted, and re-added so that the binding picks up the latest thing definitions. You don’t need to exclude and re-include the devices from the network, and in most cases the devices should look the same to the user so channels should be the same (the database is the same for all versions). If you don’t do this because you’re reading this message after I merge the binding, it’s not the end of the world, but the binding won’t work until you do this.

I don’t intend to merge this immediately - probably it will be merged in early September to allow people a week or so to prepare and ask any questions etc…

For those wanting some background or reference material, feel free to read the following thread (it’s not really recommended unless you can’t sleep at night :slight_smile: ).

15 Likes
2

Great news :smiley:

Thanks to all contributors, testers and YOU @chris

2 Likes
3

I think the thread ought to be obligatory reading. All of it! :laughing:

4

This is great news @chris ! My OpenHAB install and zwave binding have been running well enough that I have largely forgotten about it and just used it for a while, but am digging back in again!

1 Like
5

By all the Things I assume you also mean the Serial Thing for the Controller as well? If so does it make sense to caution users that when they create the new Controller Thing to make the ID the same as the old one. Then the new Things won’t need to be relinked to the Items because they will come back into OH with the same Thing ID.

Of course, if the Serial Thing doesn’t need to be recreated then it’s all good and the Thing IDs will match by default.

Great work!

1 Like
6

No - this isn’t necessary. The thing definition for the stick hasn’t changed so it doesn’t need to be updated.

2 Likes
7

Does this mean there will be a new openhab version 2.3.1 with the stable version of the binding as normally the bindings have the same version as openhab or do I have to manually install the new master version of binding or how would I know that the new binding is available in master and how to update it in paperui?

And by delething the things I guess we also need to delete the xml right?

8

I think it means that the version in snapshot will soon be replaced with the new version, so if you’re running snapshot versions of OH you will soon be affected. If you’re on stable, it won’t affect you until you upgrade to 2.4.0.

9

No - it will not impact 2.3 versions - only 2.4 (it’s as @DanielMalmgren said).

This isn’t necessary, but it’s probably a good idea to clear the {userdata}/zwave folder. The xml files actually have a different name in the new binding - the network name is added to the filename as well to allow the binding to work with multiple sticks.

10

Thanks for the update. But you pointed out to user @rlkoshak that we can leave the thing definition for stick. But if I would clear that zwave folder wouldn’t that mess up the thing for the stick?

11

Removing the xml file doesn’t mean removing the Thing. And all xml files (including the one for the controller) is recreated using the new name standard anyway.

12

Not to forget the nightly network heal which is also an important feature.
Thank you very much for all the great work!

2 Likes
13

I’m just bumping this back into peoples visibility - please take note as I will be looking at doing this in the coming days…

3 Likes
14

thanks, Chris. Will there be anything to do for those of us already using the development binding? Or simply delete the JAR from the addons folder, add the binding into addons.cfg and update?

15

No - it should just be a case of deleting the JAR and changing to the snapshot version…

I still haven’t worked out how to “merge” this - I can’t do a standard merge as the changes are too great, and I’ll need to work out how to “transfer” the dev branch to the master and sort of deprecate the current master…

Something to look at tonight :slight_smile:

16

OH will cache the binding, so deleting the jar is not enough. I’ve seen bindings stay cached after an OH restart too. The only way to be sure is to delete the jar and uninstall it through Karaf…

bundle:uninstall org.openhab.binding.zwave
1 Like
17

While you’re right here, part of the (automatically executed, post-)installation scripts in Linux packages (or instructions when there’s no packages) always is to delete the cache contents, too. I guess by the time the new binding gets released, @chris will make an appropriate posting here and include that information again, too.

1 Like
18

There won’t be an installation script etc. This will just be seen as another nightly snapshot update, so for most people who have not used the dev binding before, it should just be a case of uninstall the binding, and reinstall the binding (and of course deleting all their things etc…). For those that have manually installed the binding, then @5iver is right that there is always the possibility that this will be cached and the safe thing to do is to uninstall it (although IMHO it should be removed when the JAR is removed - I know that it doesn’t always work :roll_eyes:).

1 Like
19

Just for the record, this has never been needed for me. As soon as I delete a jar, the bundle is automatically uninstalled. However I guess it wouldn’t hurt if the official recommendation includes a bundle:uninstall just in case.

1 Like
20

Just to jump start the instructions, the steps as I’m understanding them based on the discussion here for those of us who have only ever used the release or snapshot version of the binding would be something like:

NOTE: These are instructions for those who have only ever used paperui/karaf installed zwave binding and will continue to do so.

  1. Backup.
  2. If on the release or testing version of OH and on an apt/yum based install, change to the snapshot release repo as the source.
  3. Upgrade OH using the procedure for your platform.
  4. Remove all Zwave Things except for the thing representing the Controller.
  5. Uninstall the Zwave binding though PaperUI or the Karaf console.
  6. Install the Zwave binding through PaperUI or the Karaf console.
  7. Go to the Inbox and scan for Zwave devices.
  8. Accept the nodes as they appear.
  9. If necessary, perform whatever wake up steps that are necessary for battery powered devices so the binding can figure out what it is.
  10. Perform the steps for secure inclusion for those devices that require the security command class.

Did I get anything backwards or miss a step?

Edit1: Added suggestions from Mark

Edit2: Added suggestions from Scott

1 Like