* 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. *
* 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. *
* 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. *
* 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. *
* 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 *
* \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. *
* 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. * *
* 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. *
* 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. *
* You should have received a copy of the GNU Lesser General Public License
* along with OpenZWave. If not, see
*/