open-zwave: A C++ repository from rdoorn

Last Updated: 4 October 2019

Our goal is to create free software library that interfaces with Z-Wave controllers, allowing anyone to create applications to control devices on a Z-Wave network, without requiring in-depth knowledge of the Z-Wave protocol. OpenZWave is not about creating Z-Wave devices (nodes). The project consists of the main library, written in C++ and wrappers and supporting projects, to interface different languages and protocol(s).

This software is currently aimed at Application Developers who wish to incorporate Z-Wave functionality into their applications.

Our Homepage is at http://www.openzwave.net and our Github Organization is located at https://github.com/OpenZWave/. There are several repositories at that location. This is the README of the main project (often called "the library" or "OpenZWave" or "open-zwave"), located at https://github.com/OpenZWave/open-zwave.

The current version of the main library is called OpenZWave 1.6, it is the master branch of the open-zwave repository and tagged "1.6". The previous version was 1.4 (same branch name and tag), and 1.5 was a development branch. The older versions are no longer maintained. The Dev branch is experimental and is not recommend unless someone specifically asks you to try it.

OpenZWave 1.6 was released on March the 5th, 2019, when the Dev branch was merged into master and the 1.6 tag was created. The OpenZWave Wiki 1.6 Release Notes summarizes changes.

Getting Started

There is an example application based on the library, it is called MinOZW and it is part of the open-zwave repository. This currently offers a minimal example. There are also plenty of other examples on the Internet that you can research.

On Linux, macOS, BSD run "make" to build the library and MinOZW. Optionally, run "make install" to install the library, header and config files system-wide. Run "BUILD=DEBUG make" to make a debug build.

Online Developers documentation is generated from source comments by Doxygen. If you do "make install" and have Doxygen on your system, a description of the api will be in open-zwave/docs/api/html/index.html

On Windows, install "Visual Studio" then open "open-zwave/cpp/build/windows/vs2010/OpenZWave.sln" to build the library or "open-zwave/cpp/examples/windows/MinOZW/vs2010/MinOZW.sln" to build both library and sample application.

Getting Help

If you are using a Application based on OpenZWave, and you have an issue, you should check:

If you are an end user, check the Forum and Issue Tracker of your product based on OpenZWave. As this is a library used by dozens of large open source home automation applications, we can not support application related issues here.
The OpenZWave Mailing List for general discussion of issues and contacting peers and developers.
The OpenZWave Wiki for main library information.
The Issue Tracker of the sub-project, for example the Zwave2Mqtt Issue Tracker
The OpenZWave Issue Tracker for main library issues and "things being worked on". See "Opening or Contributing to an Issue on Github" if you think the problem is related to the OpenZWave main library.

Opening or Contributing to an Issue on Github

Please check both closed and open Issues before reporting. If you're still having problems, you should generate a (debug) log file and upload that to the OpenZWave Log Analyzer on our homepage, which will check for common issues, and provide some basic recommendations. Please follow the instructions on that page to ensure your log file contains the relevant information.

If you think you have found a bug, ZIP the OZW_log.txt and your ozwcache*xml file and "drag and drop" the resulting archive on the github issue or comment you create on GitHub. Please do not paste as text.

Please always provide an OZW_Log.txt file. Z-Wave is a reasonably complex protocol, and thus, it is almost always necessary for us to review that log file to understand what is going on.

Language Wrappers

A number of members of the community have developed wrappers for OpenZWave for other languages. Those actively maintained wrappers can be found at the OpenZWave Github Organization

If you have developed a wrapper for another language, and would like to publish it under the OpenZWave Organization (and gain access to things like CI, Distribution Build Servers etc) please contact Fishwaldo on our mailing list.

Device Database and Supporting New Devices

If your device is not recognized by OpenZWave, it should still work as long as its compliant with the Z-Wave specifications. Our Device database is mainly based on community contributions, so please consult the wiki page on Adding Devices on how to add the Device to the manufacturer_specific.xml file and generate a Configuration xml file for it.

When OpenZWave 1.6 starts, it checks the version of several related files configuration files and downloads the latest revision. This behavior can be changed by changing the AutoUpdateConfigFile configuration in options.xml. Config options are explained on the wiki page on Config-Options

You can have a look at the current device database for OpenZWave 1.6 by browsing to the Online Device Database

Please note device configuration files for 1.6 and 1.4 are different. If your application is based on OpenZWave version 1.4, the older database is still available but unmaintained at: OpenZWave 1.4 branch, config folder

Contributing to OpenZWave

We are happy to accept Pull Requests via GitHub. A few things to follow when preparing a Pull Request.

If you have added or changed any of the configuration files (eg, adding a new device) please run "make xmltest" from the root directory to ensure your XML is well formed. Also run "make dist-update" if you have added files.
Please add a entry to the ChangeLog describing the change you made.
If you want to change OpenZWave code, please discuss your plan through the Mailing List or on Github prior to starting your work. Z-Wave is complex and there are lots of corner cases as far as proper support of the various (non-standard) devices out there. While it might sometimes seem (overly) complicated, it most likely is there for a reason.
Finally, if you have signed a NDA with Sigma Designs, and your proposed changes are covered by that NDA, we are unable to accept your changes. OZW is developed by reverse engineering and consulting publicly available information. We do not want users to infringe upon their agreements. The OpenZWave organization has not signed a NDA with Sigma.
Parts of the spec have been released as the Public Z-Wave Specification, and the radio protocol is know as G.9959. There may be more public resources, but please do check the terms and conditions of every part before posting for compatibility with "Open Source Software"

Trivia

Prior to Sept, 2016, OpenZWave was developed by mainly reverse engineering the protocol as well as consulting various public information on the Internet.

In September 2016, Sigma Designs released a large portion (not all) of the Z-Wave Protocol Specifications into the public domain.

On April 18, 2018, Silabs acquired Sigma Design's Z-Wave business, they now host the official Z-Wave Support Resources

In 2005 the Z-Wave Alliance was established. OpenZWave is an Affiliate Member of the Z-Wave Alliance.

License

OpenZWave is an open source program that is LGPL licensed. This does allow commercial applications to utilize the OpenZWave library, but we ask that you support us by either contributing any changes back to the community, or consider a donation of Z-Wave hardware to the developers so we can continue to ensure openzwave works well with the z-wave ecosystem. (You should also be aware that of the Z-Wave restrictions about selling software that implements this public standard. Please consult the Z-Wave Alliance and Z-Wave Support Resources for further info.

Of course, for Open Source applications, as long as you abide by our License (LGPL) we would love to welcome you the OpenZWave community!

Contributors

Code Contributors

This project exists thanks to all the people who contribute. [Contribute].

Financial Contributors

Become a financial contributor and help us sustain our community. [Contribute]

Individuals

(We also have many users that support us via Github Sponsors program!)

Organizations

Support this project with your organization. Your logo will show up here with a link to your website. [Contribute]

rdoorn/open-zwave