 |
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:
|
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:
|
| 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. |