1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
/**
* \mainpage OpenZWave
* \section Introduction Introduction to OpenZWave
* OpenZWave is an open-source, cross-platform library designed to enable
* anyone to add support for Z-Wave home-automation devices to their
* applications, without requiring any in depth knowledge of the Z-Wave
* protocol.
* <p>
* Z-Wave employs a proprietary protocol which the owners, Sigma Designs,
* have chosen not to release into the public domain. There is also no
* official free or low-cost SDK that can be used to develop applications
* (The ControlThink SDK is now tied exclusively to their own Z-Wave PC
* interface). The only way to obtain the protocol documentation and sample
* code is to purchase an expensive development kit, and sign a non-disclosure
* agreement (NDA) preventing the release of that knowledge.
* <p>
* OpenZWave was created to fill that gap. We do not have the official
* documentation, have signed no NDA, and are free to develop the library as
* we see fit. Our knowledge comes from existing bodies of open-source code
* (principally the Z-Wave parts of LinuxMCE), and through examining the
* messages sent by Z-Wave devices.
* <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. It is NOT
* our aim to publish alternative documentation of the Z-Wave protocol, or
* to attempt to "punish" Sigma Designs for their decision to keep the
* protocol closed.
* \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
* 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
* across the mesh.
* <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.
* 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.
* <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
* interfaces. The switches, dimmers, movement sensors etc are all slaves.
* Controllers and Devices
* Replication
* Command Classes
* Values
* <hr>
* \section Library The OpenZWave Library
* \subsection Overview Overview
* \subsection Manager The Manager
* All Z-Wave functionality is accessed via the Manager class. While this
* does not make for the most efficient code structure, it does enable
* the library to handle potentially complex and hard-to-debug issues
* such as multi-threading and object lifespans behind the scenes.
* Application development is therefore simplified and less prone to bugs.
* <p>
* \subsection Notifications Notifications
* Communication between the PC and devices on the the Z-Wave network occurs
* asynchronously. Some devices, notably movement sensors, sleep most of the
* time to save battery power, and can only receive commands when awake.
* Therefore a command to change a value in a device may not occur immediately.
* It may take several seconds or minutes, or even never arrive at all.
* For this reason, many OpenZWave methods, even those that request
* information, do not return that information directly. A request will be
* sent to the network, and the response sent to the application some time
* later via a system of notification callbacks. The notification handler
* will be at the core of any application using OpenZWave. It is here that
* all information regarding device configurations and states will be reported.
* <p>
* A Z-Wave network is a dynamic entity. Controllers and devices can be
* added or removed at any time. Once a network has been set up, this
* probably won't happen very often, but OpenZWave, and any application
* built upon it, must cope all the same. The notification callback system
* is used to inform the application of any changes to the structure of the
* network.
* \subsection Values Working with Values
*
* \subsection Guidelines Application Development Guidelines
* The main considerations when designing an application based upon
* OpenZWave are:
*
* - Communication with Z-Wave devices is asynchronous and not guaranteed
* 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
* 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
* with the addition and removal of devices.
*
* Some users will have more than one Z-Wave controller, to allow for remote
* locations or to work around the 232 device limit. OpenZWave is designed
* for use with multiple controllers, and all applications should be written
* to support this.
*
* - There is no need to save the state of the network and restore it on
* the next run. OpenZWave does this automatically, and is designed to cope
* with any changes that occur to the network while the application is not
* running.
*
* <hr>
* \section Structure Source Code Structure
*
* <hr>
* \section Samples Samples
* The SDK package includes skeleton code for creating xPL-enabled
* applications. Code is provided for three types of application - a Windows
* service, a Windowed application, and a console application. The Windows
* service is quite flexible - it will run as a console application if no
* command line parameters are passed to it. This makes it possible to
* ship one application that will run on all versions of Windows, whether or
* not there is support for services. It is also useful for debugging.
* <p>
* The full source code for the W800RF32 service is also provided as a real
* life example of using the SDK to build a complete xPL application.
* <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/>.
* <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)
* <p>
*/