Technical Overview
Below is a quick overview of Z-Wave that will help to make sense of the WZWave source code. This information has been obtained from various web sites on the Internet.
Please keep in mind that this is by no means exhaustive and may contain inaccuracies as the official documentation for Z-Wave is only available for purchase under NDA.
The Z-Wave Network
A Z-Wave network is comprised of one or more nodes (up to 232). Since the radios on Z-Wave devices are fairly low power, the nodes are organized as a mesh so that each node knows about other nodes that it can reach nearby. This allows nodes to help route messages through the network when necessary.
For example, say your network has 3 nodes as shown below:
In the above diagram, A is in range of B, B is in range of C but A is NOT in range of C. The Z-Wave protocol still allows A to talk to C by using B as a router. Fortunately, the details of all of this is encapsulated in the Z-Wave chip itself so application code doesn't have to worry about the gory details of routing.
From a WZWave standpoint, there is always a controller node (typically node 1) that serves as the gateway between a device running WZWave and the Z-Wave network itself. An example of a controller is the Aeotech Z-Stick 2.
WZWave interacts with the controller node using a proprietary serial protocol that was defined by the creators of Z-Wave.
Note: The terms device and node are used interchangeably throughout this document.
Z-Wave Nodes
When you get a new device, you have to explicitly add it to your Z-Wave network. This inclusion process can happen in a couple of ways: the controller hardware may have a button on it to toggle inclusion mode or you can use WZWave to put the controller in inclusion mode. Adding a device typically involves putting the controller in inclusion mode and then doing something on the device such as pressing a button. The device-specific details of the inclusion process are usually documented by the device manufacturer.
Nodes on a Z-Wave network are broken into two rough categories: controllers and slaves. Slaves are broken down into two additional categories: standard and routing.
Device Classes
Each node on the Z-Wave network is also associated with three device classes: basic, generic and specific. These help to identify the type of device and provides some details about what the device can do.
The basic device class is very high level and indicates whether the device is a controller, a slave or a routing slave as mentioned above.
The generic device class provides a bit more detail about the device. Examples of generic device classes include binary switch, alarm sensor and meter.
The specific device class builds on the information provided by the generic device class. Although I've read it's possible for a device not to have a specific device class, I haven't yet seen an example of one. Examples of specific device classes include binary power switch, routing smoke sensor and simple meter.
Command Classes
All interaction with Z-Wave nodes is done via command classes. These command classes define commands that can be sent to devices as well as responses or notifications that can be received from those devices.
The device classes mentioned in the previous section define certain command classes that are mandatory for a device of that type to implement. However, it may choose to implement others.
All devices are required to implement the Basic Command Class. This defines a way to get and set a generic value from the device. This is useful so that even if you know nothing about the device, you can still do something with it. The meaning of this value is going to be device-specific and so the Basic Command Class is often mapped to a more specific command class.
For example, a Binary Switch (generic device type) will implement both the Basic and Binary Switch command classes. The Binary Switch command class defines a way to get and set the switch value (0x00 for off and 0xFF for on). The Basic command class is mapped to the Binary Switch command class so sending a Basic command is equivalent to sending a Binary Switch command.
Command classes are versioned (e.g. v1, v2, etc.) and a device may support more than one version of a command class.
Sleeping Nodes
It would be extremely inconvenient to have to replace the battery in battery-powered Z-Wave devices frequently. Therefore, most battery-powered devices will spend the majority of their time sleeping to conserve power. Effectively, the device is inaccessible when it is sleeping and won't respond to any requests. There are typically two ways a device will wake from sleep: the device being triggered or via a recurring interval.
The device being trigged is exactly as it sounds. For example, a smoke detector will sleep most of the time (from a Z-Wave network perspective) but will wake up when it senses smoke and send out a notification.
Some devices may also wake up briefly at recurring intervals to check in with the network. When it does this, it sends a notification to the network (using the Wake Up Command Class) indicating it is now awake. WZWave will queue up requests made to a sleeping node, and when it receives this "wake up" notification, will send out those commands. The wake-up interval is often a configurable property of the device.
WZWave Startup
When WZWave is started and finds a controller to talk to, it begins an "interview" or "interrogation" process. This involves asking the controller for information about itself and what it knows about nodes on the Z-Wave network. The controller only retains limited information about nodes (e.g. its device classes), so once WZWave learns what it can from the controller, it will interrogate each node to get more detail including the precise command classes it supports.
Note that this interrogation process takes some time and that time increases in relation to the number of nodes on the network.
References
Understanding Z-Wave Networks, Nodes & Devices
How Z-Wave Controllers & Devices Work