open-zwave

a C++ library to control Z-Wave Networks via a USB Z-Wave Controller.

1,048

916

1,048

165

View on GitHub

Top Related Projects

domoticz

3,468

Open source Home Automation System

Quick Overview

OpenZWave is an open-source project that provides a C++ library for controlling Z-Wave home automation networks. It aims to make Z-Wave device control and management accessible to developers, allowing them to create applications that can interact with a wide range of Z-Wave devices.

Pros

Supports a wide range of Z-Wave devices and controllers
Cross-platform compatibility (Windows, Linux, macOS)
Active community and ongoing development
Provides a high-level API for easier integration

Cons

Documentation can be sparse or outdated in some areas
Learning curve can be steep for beginners
Limited support for some advanced Z-Wave features
Dependency on specific Z-Wave controller hardware

Code Examples

Initializing the OpenZWave Manager:

#include <Options.h>
#include <Manager.h>

OpenZWave::Options::Create(".", "", "");
OpenZWave::Options::Get()->AddOptionInt("SaveLogLevel", OpenZWave::LogLevel_Detail);
OpenZWave::Options::Get()->AddOptionInt("QueueLogLevel", OpenZWave::LogLevel_Debug);
OpenZWave::Options::Get()->AddOptionInt("DumpTrigger", OpenZWave::LogLevel_Error);
OpenZWave::Options::Get()->AddOptionInt("PollInterval", 500);
OpenZWave::Options::Get()->AddOptionBool("IntervalBetweenPolls", true);
OpenZWave::Options::Get()->AddOptionBool("ValidateValueChanges", true);
OpenZWave::Options::Get()->Lock();

OpenZWave::Manager::Create();

Adding a Z-Wave controller:

uint32 homeId;
OpenZWave::Manager::Get()->AddDriver("/dev/ttyUSB0");
// Wait for the driver to become ready
while (!OpenZWave::Manager::Get()->GetControllerNodeId(homeId)) {
    sleep(1);
}

Controlling a Z-Wave device:

uint8 nodeId = 3; // Example node ID
uint8 instance = 1;
uint8 commandClass = 0x25; // COMMAND_CLASS_SWITCH_BINARY
uint8 index = 0;
bool value = true; // Turn on

OpenZWave::Manager::Get()->SetValue(nodeId, commandClass, instance, index, value);

Getting Started

Install OpenZWave dependencies:
```
sudo apt-get install libudev-dev
```

Clone the repository:

git clone https://github.com/OpenZWave/open-zwave.git

Build and install:
```
cd open-zwave
make
sudo make install
```

Include the library in your C++ project:

#include <openzwave/Options.h>
#include <openzwave/Manager.h>

Link against the OpenZWave library when compiling:

g++ -I/usr/local/include/openzwave -lopenzwave your_program.cpp -o your_program

Competitor Comparisons

domoticz

3,468

Open source Home Automation System

Pros of Domoticz

Comprehensive home automation solution with a user-friendly web interface
Supports a wide range of devices and protocols beyond Z-Wave
Active community and regular updates

Cons of Domoticz

Steeper learning curve due to its extensive features
Heavier resource usage compared to Open-ZWave
May be overkill for users only interested in Z-Wave functionality

Code Comparison

Domoticz (C++)

bool CDomoticzHardwareBase::WriteToHardware(const char *pdata, const unsigned char length)
{
    return false;
}

Open-ZWave (C++)

bool Driver::WriteMsg( Msg* _msg )
{
    return m_controller->Write( _msg );
}

Summary

Domoticz is a full-featured home automation platform that includes Z-Wave support, while Open-ZWave focuses specifically on Z-Wave integration. Domoticz offers a more comprehensive solution but may be more complex for users only interested in Z-Wave. Open-ZWave provides a lighter, more focused approach to Z-Wave integration, making it potentially easier to implement in custom projects.

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

README

Last Updated: 17 November 2022

NOTICE: This project is no longer being maintained. :warning:

openzwave has no more maintainers, are there any motivated to continue the development of the library?

Introduction

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!