| Notification Messages and Sequence

Purpose

Several questions from developers using the OpenZWave library have suggested confusion about the meaning of notifications sent by the library. This document is intended to clarify and document the notifications sent by the library and to indicate what information is “known” at the time the notifications are sent. This will, hopefully, assist developers in designing the actions to take upon receipt of each notification.

Important Note

You should be aware that notifications are blocking. That is, when a notification is sent to an application, the OpenZWave library will wait until the callback function returns. So, for example, if you put a modal dialog box (for Windows users) in the notification handler in your application, OpenZWave will essentially stop communicating with the Z-Wave controller until the dialog box is dismissed and the notification handler returns.

This "feature" may be changed in the future, but for now developers must be aware of this issue.

Format

The table presented below lists notifications in the order they might typically be received, and grouped into a few logically related categories. Of course, given the variety of ZWave controllers, devices and network configurations the actual sequence will vary (somewhat). The descriptions below the notification name (in square brackets) identify whether the notification is always sent (unless there’s a significant error in the network or software) or potentially sent during the execution sequence.

Driver Initialization Notification The notification below is sent when OpenZWave has successfully connected to a physical ZWave controller.

DriverReady
[always sent]

Sent when the driver (representing a connection between OpenZWave and a Z-Wave controller attached to the specified serial (or HID) port) has been initialized.
At the time this notification is sent, only certain information about the controller itself is known:

- Controller Z-Wave version
- Network HomeID
- Controller capabilities
- Controller Application Version & Manufacturer/Product ID
- Nodes included in the network

Node Initialization Notifications As OpenZWave starts, it identifies and reads information about each node in the network. The following notifications may be sent during the initialization process.

NodeNew [potentially sent] | Sent when a new node has been identified as part of the Z-Wave network. It is not sent if the node was identified in a prior execution of the OpenZWave library and stored in the zwcfg*.xml file. At the time this notification is sent, very little is known about the node itself...only that it is new to OpenZWave. This message is sent once for each new node identified.

NodeAdded
[always sent (for each node associated with the controller)]

Sent when a node has been added to OpenZWave’s list of nodes. It can be triggered either as the zwcfg*.xml file is being read, when a new node is found on startup (see NodeNew notification above), or if a new node is included in the network while OpenZWave is running.
As with NodeNew, very little is known about the node at the time the notification is sent…just the fact that a new node has been identified and its assigned NodeID.

NodeProtocolInfo
[potentially sent]

Sent after a node’s protocol information has been successfully read from the controller.
At the time this notification is sent, only certain information about the node is known:

- Whether it is a “listening” or “sleeping” device
- Whether the node is capable of routing messages
- Maximum baud rate for communication
- Version number
- Security byte

NodeNaming [potentially sent] | Sent when a node’s name has been set or changed (although it may be “set” to “” or NULL).
ValueAdded [potentially sent] | Sent when a new value has been associated with the node. At the time this notification is sent, the new value may or may not have “live” data associated with it. It may be populated, but it may alternatively just be a placeholder for a value that has not been read at the time the notification is sent.

NodeQueriesComplete
[always sent (for each node associated with the controller that has been successfully queried)]

Sent when a node’s values and attributes have been fully queried. At the time this notification is sent, the node’s information has been fully read at least once. So this notification might trigger “full” display of the node’s information, values, etc. If this notification is not sent, it indicates that there has been a problem initializing the device. The most common issue is that the node is a “sleeping” device. The NodeQueriesComplete notification will be sent when the node wakes up and the query process completes.

Initialization Complete Notifications As indicated above, when OpenZWave starts it reads certain information from a file, from the controller and from the network. The following notifications identify when this initialization/querying process is complete.

AwakeNodesQueried
[always sent]

Sent when all “listening”—always-on—devices have been queried successfully. It also indicates, by implication, that there are some “sleeping” nodes that will not complete their queries until they wake up. This notification should be sent relatively quickly after start-up. (Of course, it depends on the number of devices on the ZWave network and whether there are any messages that “time out” without a proper response.)

AllNodesQueried [potentially sent] | Sent when all nodes have been successfully queried. This notification should be sent relatively quickly if there are no “sleeping” nodes. But it might be sent quite a while after start-up if there are sleeping nodes and at least one of these nodes has a long “wake-up” interval.

Other Notifications In addition to the notifications described above, which are primarily “initialization” notifications that are sent during program start-up, the following notifications may be sent as a result of user actions, external program control, etc.

ValueChanged | Sent when a value associated with a node has changed. Receipt of this notification indicates that it may be a good time to read the new value and display or otherwise process it accordingly.
ValueRemoved | Sent when a value associated with a node has been removed.
Group | Sent when a node’s group association has changed.
NodeRemoved | Sent when a node has been removed from the ZWave network.
NodeEvent | Sent when a node sends a Basic_Set command to the controller. This notification can be generated by certain sensors, for example, motion detectors, to indicate that an event has been sensed.
PollingEnabled | Sent when node/value polling has been enabled.
PollingDisabled | Sent when node/value polling has been disabled.
DriverReset | Sent to indicate when a controller has been reset. This notification is intended to replace the potentially hundreds of notifications representing each value and node removed from the network.