mirror of
https://github.com/Fishwaldo/open-zwave.git
synced 2025-03-15 19:41:36 +00:00
Update README.md and DoxygenMain.h (#1964)
Should fix "Outdated info in readme.md and on website?" #1961
This commit is contained in:
Peter Gebruers
parent
ceda0e678a
commit
814090c74a
2 changed files with 69 additions and 69 deletions
86
README.md
86
README.md
|
|
@ -1,62 +1,92 @@
|
|||
|
||||
==================
|
||||
|
||||
Our goal is to create free software library that interfaces with selected Z-Wave PC controllers, allowing anyone to create applications that manipulate and respond to devices on a Z-Wave network, without requiring in-depth knowledge of the Z-Wave protocol.
|
||||
*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 Page is located at https://github.com/OpenZWave/. If you wish to participate on our Mailing List, please visit https://groups.google.com/forum/#!forum/openzwave
|
||||
Our Homepage is at [http://www.openzwave.net](http://www.openzwave.net/) and our Github Organization is located at [https://github.com/OpenZWave/](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](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](https://github.com/OpenZWave/open-zwave/wiki/OpenZWave-1.6-Release-Notes) summarizes changes.
|
||||
|
||||
## Getting Started
|
||||
There is a example application on how to interface with the library called MinOZW. This currently offers a minimal example on how to monitor for changes and enable Polling of values. There are also plenty of other examples on the Internet that you can research.
|
||||
|
||||
There is an example application based on the library, it is called MinOZW and it is part of the [open-zwave repository](https://github.com/OpenZWave/open-zwave). 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](http://www.openzwave.com/dev/) 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 that uses OZW, you should first check with the Application Developers for support. As OZW is a library used by dozens of large opensource home automation applications, we can not support application related issues here. If your application developer indicates the problem may be with OZW, please follow the guidelines below.
|
||||
|
||||
First thing you should do if you are running into troubles is search our [mailing list](https://groups.google.com/forum/#!forum/openzwave). There is a high chance that your problem may have already been discussed on the list.
|
||||
If you're still having problems, you should Generate a Log file and upload your Log to the [Log Analyzer on our homepage](http://www.openzwave.com/log-analyzer), 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 are using a Application based on OpenZWave, and you have an issue, you should check:
|
||||
|
||||
If you think you have found a bug, please see the next section.
|
||||
1. 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.
|
||||
2. The [OpenZWave Mailing List](https://groups.google.com/forum/#!forum/openzwave) for general discussion of issues and contacting peers and developers.
|
||||
3. The [OpenZWave Wiki](https://github.com/OpenZWave/open-zwave/wiki) for main library information.
|
||||
4. The Issue Tracker of the sub-project, for example the [Zwave2Mqtt Issue Tracker](https://github.com/OpenZWave/Zwave2Mqtt/issues)
|
||||
5. The [OpenZWave Issue Tracker](https://github.com/OpenZWave/open-zwave/issues) 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.
|
||||
|
||||
For General Questions/How Do I etc, please post a message to our [mailing list](https://groups.google.com/forum/#!forum/openzwave)
|
||||
## 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](http://www.openzwave.com/log-analyzer), 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 Organisation page at https://github.com/OpenZWave
|
||||
|
||||
If you have developed a wrapper for another language, and would like to publish it under the OpenZWave organisation (and gain access to things like CI, Distribution Build Servers etc) please contact Fishwaldo on our mailing list.
|
||||
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](https://github.com/OpenZWave)
|
||||
|
||||
## Opening or Contributing to a Issue on Github
|
||||
Z-Wave is a reasonably complex protocol, and thus, it almost always necessary for us to review a OZW Log file to determine what’s going on. As GitHub does not support attachments on Issues, please upload a [LogFile](http://www.openzwave.com/log-analyzer) and then create a issue on [GitHub](https://github.com/OpenZWave/open-zwave/issues). Please include a link to the LogFile Scan results (check the "Public Results" button on the results page and copy the URL it links to).
|
||||
Not uploading a Log file will often mean that we are unable to provide any further help without seeing what’s going on, so please ensure you do this.
|
||||
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.
|
||||
|
||||
## Supporting New Devices
|
||||
If your device is not recognized by OZW, it should still work as long as its compliant with the Z-Wave specifications. Our Device database is mainly community contributions, so please consult [this page](https://github.com/OpenZWave/open-zwave/wiki/Adding-Devices) on how to add the Device to the manufacturer_specific.xml file and generate a Configuration file for it.
|
||||
## 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](https://github.com/OpenZWave/open-zwave/wiki/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](https://github.com/OpenZWave/open-zwave/wiki/Config-Options)
|
||||
|
||||
You can have a look at the current device database for OpenZWave 1.6 by browsing to the [Online Device Database](http://openzwave.com/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](https://github.com/OpenZWave/open-zwave/tree/1.4/config)
|
||||
|
||||
## Contributing to OpenZWave
|
||||
|
||||
## Contributing to OZW
|
||||
We are happy to accept Pull Requests via GitHub. A few things to follow when preparing a Pull Request.
|
||||
|
||||
1. 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.
|
||||
1. 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.
|
||||
2. Please add a entry to the ChangeLog describing the change you made.
|
||||
3. If you are changing some internal code paths in OZW, please discuss on the mailing list 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 overcomplicated, it most likely is there for a reason.
|
||||
4. Finally, if you have signed a NDA with Sigma Designs, we are unable to accept your changes. OZW is developed by reverse engineering and consulting publically available information. We have not signed a NDA with Sigma, and do not want users to infringe upon their agreement with Sigma either.
|
||||
3. 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.
|
||||
4. 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.
|
||||
5. Parts of the spec have been released as the [Public Z-Wave Specification](https://www.silabs.com/products/wireless/mesh-networking/z-wave/specification), and the radio protocol is know as [G.9959](https://www.itu.int/rec/T-REC-G.9959-201501-I/en). 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"
|
||||
|
||||
## Final Words
|
||||
As of Sept, 2016, Sigma has released a large portion (not all) of the Z-Wave Protocol Specifications into the public domain. Prior to Sept, 2016, OpenZWave was developed by mainly reverse engineering the protocol as well as consulting various public information on the Internet.
|
||||
## Trivia
|
||||
|
||||
The Z-Wave Specifications can now be found at http://zwavepublic.com/ and we welcome contributions or
|
||||
reviews of the specifications against our code base.
|
||||
Prior to Sept, 2016, OpenZWave was developed by mainly reverse engineering the protocol as well as consulting various public information on the Internet.
|
||||
|
||||
OpenZWave is a opensource program that is LGPL licensed. This does allow commercial applications to utilize the openzwave libary, 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 Sigma, or the Z-Wave Alliance for further info)
|
||||
In September 2016, Sigma Designs released a large portion (not all) of the Z-Wave Protocol Specifications into the public domain.
|
||||
|
||||
Of course, for Open Source applications, as long as you abide by our License (LGPL) we would love to welcome you the OZW community!
|
||||
On April 18, 2018, [Silabs acquired Sigma Design's Z-Wave business](https://news.silabs.com/2018-04-18-Silicon-Labs-Completes-Acquisition-of-Sigma-Designs-Z-Wave-Business), they now host the official [Z-Wave Support Resources](https://www.silabs.com/support/z-wave)
|
||||
|
||||
And for those that are wondering, you cannot use OZW to create Z-Wave Nodes. This is not the goal of the library. We allow applications to talk to Z-Wave nodes on the network via a Z-Wave Controller.
|
||||
In 2005 the [Z-Wave Alliance](https://z-wavealliance.org) was established. OpenZWave is an Affiliate Member of the Z-Wave Alliance.
|
||||
|
||||
<p align="center">
|
||||
<img src="https://github.com/OpenZWave/open-zwave/raw/master/docs/images%2Bcss/zwalliance_250x100.jpg"><br>
|
||||
OpenZWave is a Affiliate Member of the Z-Wave Alliance
|
||||
<img src="https://github.com/OpenZWave/open-zwave/raw/master/docs/images%2Bcss/zwalliance_250x100.jpg">
|
||||
</p>
|
||||
|
||||
## 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](https://z-wavealliance.org) and [Z-Wave Support Resources](https://www.silabs.com/support/z-wave) 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
|
||||
|
|
|
|||
|
|
@ -6,29 +6,12 @@
|
|||
* applications, without requiring any in depth knowledge of the Z-Wave
|
||||
* protocol.
|
||||
* <p>
|
||||
* The Majority of the Z-Wave Protocol has been released into the public domain
|
||||
* on Sept, 2016. Prior to Sept, 2016, OpenZWave had reverse engineered the
|
||||
* protocol to allow applications to be created to interact with Z-Wave devices.
|
||||
* There is now ongoing work to update OpenZWave to be compliant with the Z-Wave
|
||||
* Specifications that are now released at http://zwavepublic.com
|
||||
* <p>
|
||||
* There is one part of the protocol that has not been released into the Public
|
||||
* Domain, namely, the "SerialAPI" protocol that specifies how to talk to
|
||||
* a USB Stick via a Serial COM Port. This portion of OpenZWave will continue to
|
||||
* be reverse engineered if needed in the future.
|
||||
* <p>
|
||||
* The goal of the project is to make a positive contribution to the Z-Wave
|
||||
* community by creating a library that supports as much of the Z-Wave
|
||||
* specification as possible, and that can be used as a "black-box"
|
||||
* solution by anyone wanting to add Z-Wave to their application.
|
||||
* <p>
|
||||
* @image html zwalliance_250x100.jpg
|
||||
* <center>OpenZWave is a affiliate member of the Z-Wave Alliance (http://zwavealliance.org/)</center>
|
||||
|
||||
* For more information about the OpenZWave project: see README.md in the
|
||||
* root of the OpenZWave repository.
|
||||
* \section ZWave Z-Wave Concepts
|
||||
* Z-Wave is a proprietary wireless communications protocol employing mesh
|
||||
* networking technology. A mesh network allows low power devices to
|
||||
* communicate over long ranges, and around radio blackspots by passing
|
||||
* communicate over long ranges, and around radio black spots by passing
|
||||
* messages from one node to another. It is important to note that not all
|
||||
* Z-Wave devices are active all the time, especially those that are battery
|
||||
* powered. These nodes cannot take part in the forwarding of messages
|
||||
|
|
@ -36,10 +19,10 @@
|
|||
* <p>
|
||||
* Each Z-Wave device is known as "Node" in the network. A Z-Wave network
|
||||
* can contain up to 232 nodes. If more devices are required, then
|
||||
* multiple networks need to be set up using separate Z-Wave controller.
|
||||
* multiple networks need to be set up using separate Z-Wave controllers.
|
||||
* OpenZWave supports multiple controllers, but on its own does not bridge
|
||||
* the networks allowing a device on one to directly control a device on
|
||||
* another. This functionality would have to be supplied by the application.
|
||||
* the networks, allowing a device on one to directly control a device on
|
||||
* another. This functionality would have to be supplied by the application.
|
||||
* <p>
|
||||
* Z-Wave nodes can be divided into two types: Controllers and Slaves. The
|
||||
* controllers are usually in the form of hand-held remote controls, or PC
|
||||
|
|
@ -48,7 +31,6 @@
|
|||
* Replication
|
||||
* Command Classes
|
||||
* Values
|
||||
|
||||
* <hr>
|
||||
* \section Library The OpenZWave Library
|
||||
* \subsection Overview Overview
|
||||
|
|
@ -92,7 +74,7 @@
|
|||
* to be reliable. Do not rely on receiving a response to any request.
|
||||
*
|
||||
* - A Z-Wave network may change at any time. The application's notification
|
||||
* callback handler must deal woth all notifications, and any representation
|
||||
* callback handler must deal with all notifications, and any representation
|
||||
* of the state of the Z-Wave network held by the application must be
|
||||
* modified to match. User interfaces should be built dynamically from the
|
||||
* information reported in the notification callbacks, and must be able to cope
|
||||
|
|
@ -111,23 +93,11 @@
|
|||
|
||||
* <hr>
|
||||
* \section Licensing Licensing
|
||||
* OpenZWave is free software: you can redistribute it and/or modify
|
||||
* it under the terms of the GNU Lesser General Public License as published
|
||||
* by the Free Software Foundation, either version 3 of the License,
|
||||
* or (at your option) any later version.
|
||||
* <p>
|
||||
* OpenZWave is distributed in the hope that it will be useful,
|
||||
* but WITHOUT ANY WARRANTY; without even the implied warranty of
|
||||
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
||||
* GNU Lesser General Public License for more details.
|
||||
* <p>
|
||||
* You should have received a copy of the GNU Lesser General Public License
|
||||
* along with OpenZWave. If not, see <http://www.gnu.org/licenses/>.
|
||||
* See README.md in the root of the OpenZWave project.
|
||||
|
||||
* <hr>
|
||||
* \section Support Support
|
||||
* Assistance with all OpenZWave issues can be obtained by posting a message
|
||||
* to the OpenZWave Google Group (http://groups.google.com/group/openzwave)
|
||||
* See README.md in the root of the OpenZWave project.
|
||||
* <p>
|
||||
*/
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue