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
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>Notification Messages and Sequence</title>
<link href="../images+css/OpenZWave.css" rel="stylesheet" type="text/css" />
</head>
<body bgcolor="#FFFFFF">
<div class=Section1>
<div id="Main">
<table width="700" height="100" border=0 cellpadding=0 cellspacing=0>
<tr>
<td class=Heading1 width=250 valign=top><a href="../default.htm"><img src="../images+css/image003.gif" alt=Logo width=134 height=55 border="0"></a> </td>
<td class=Heading1 width=445 valign=top>Notification Messages<br>
and Sequence </td>
</tr>
</table>
<table width="700" border="0" cellpadding="0" cellspacing="0">
<tr>
<td><p class=Heading2>Purpose</p>
<p class="BodyText">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.<br>
<br>
</p></td>
</tr>
</table>
<table width="700" border="0" cellpadding="0" cellspacing="0">
<tr>
<td><p class="Heading2">Important Note </p>
<p class="BodyText">You should be aware that notifications are <u><strong>blocking</strong></u>. 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. </p>
<p class="BodyText">This "feature" may be changed in the future, but for now developers must be aware of this issue. <br />
<br />
<br />
</p>
</td>
</tr>
</table>
<table width="700" border="0" cellpadding="0" cellspacing="0">
<tr>
<td><p class=Heading2>Format</p>
<p class="BodyText">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 <b>always</b> sent (unless there’s a significant error in the network or software) or <b>potentially </b>sent during the execution
sequence.<br>
<br>
<br>
</p></td>
</tr>
</table>
<table width="700" border="0" cellpadding="5px" cellspacing="0" bgcolor="#E6E6E6" >
<tr>
<td><p class=Heading2>Driver Initialization Notification </p>
<p class="BodyText">The notification below is sent when OpenZWave has successfully connected to a physical ZWave controller.<br>
<br>
</p></td>
</tr>
</table>
<table width="700" border=0 cellpadding=0 cellspacing=0>
<tr>
<td width=151 valign=top class="TableText"><b>DriverReady</b><br>
[always sent]</td>
<td width=432 valign=top class="TableText"> 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. <br>
<br>
At the time this notification is sent, only certain information about the controller itself is known:
<ul class="TableBullet">
<li>Controller Z-Wave version </li>
<li>Network HomeID </li>
<li>Controller capabilities </li>
<li>Controller Application Version & Manufacturer/Product ID </li>
<li>Nodes included in the network<br>
<br>
</li>
</ul></td>
</tr>
</table>
<table width="700" border="0" cellpadding="5px" cellspacing="0" bgcolor="#E6E6E6" >
<tr>
<td><p class=Heading2>Node Initialization Notifications </p>
<p class="BodyText">As OpenZWave starts, it identifies and reads information
about each node in the network. The
following notifications may be sent during the initialization process.<br>
<br>
</p></td>
</tr>
</table>
<table width="700" border=0 cellpadding=0 cellspacing=0>
<tr>
<td width=151 valign=top class="TableText"><b>NodeNew</b><br>
[potentially
sent]</td>
<td width=432 valign=top class="TableText"> 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. <br>
<br>
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.</td>
</tr>
<tr>
<td valign=top class="TableText"> </td>
<td valign=top class="TableText"> </td>
</tr>
<tr>
<td width=151 valign=top class="TableText"><b>NodeAdded</b><br>
[always sent (for each node associated with the controller)]</td>
<td width=432 valign=top class="TableText">Sent
when a node has been added to OpenZWaves 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.<br>
<br>
As with NodeNew, very little is known about the node at the time
the notification is sentjust the fact that a new node has been identified
and its assigned NodeID. </td>
</tr>
<tr>
<td valign=top class="TableText"> </td>
<td valign=top class="TableText">
</tr>
<tr>
<td width=151 valign=top class="TableText"><b>NodeProtocolInfo</b><br>
[potentially sent]</td>
<td width=432 valign=top class="TableText">Sent
after a nodes protocol information has been successfully read from the
controller.<br>
<br>
At the time
this notification is sent, only certain information about the node is known:<br>
<ul>
<li>Whether it is a listening or sleeping device</li>
<li>Whether the node is capable of routing messages</li>
<li>Maximum baud rate for communication</li>
<li>Version number</li>
<li>Security byte</li>
</ul>
</tr>
<tr>
<td width=151 valign=top class="TableText"><b>NodeNaming</b><br>
[potentially sent]</td>
<td width=432 valign=top class="TableText">Sent
when a nodes name has been set or changed (although it may be set to or
NULL).</td>
</tr>
<tr>
<td width=151 valign=top class="TableText"><b>ValueAdded</b><br>
[potentially sent]</td>
<td width=432 valign=top class="TableText">Sent
when a new value has been associated with the node.<br>
<br>
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.
</tr>
<tr>
<td width=151 valign=top class="TableText"><b>NodeQueriesComplete</b><br>
[always
sent (for each node associated with the controller that has been successfully
queried)]</td>
<td width=432 valign=top class="TableText">Sent
when a nodes values and attributes have been fully queried.
At the
time this notification is sent, the nodes information has been fully read at
least once. So this notification might
trigger full display of the nodes 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.
</p>
</tr>
</table>
<table width="700" border="0" cellpadding="5px" cellspacing="0" bgcolor="#E6E6E6" >
<tr>
<td><p class=Heading2>Initialization Complete Notifications </p>
<p class="BodyText">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.<br>
<br>
</p></td>
</tr>
</table>
<table width="700" border=0 cellpadding=0 cellspacing=0>
<tr>
<td width=151 valign=top class="TableText"><b>AwakeNodesQueried</b><br>
[always sent]</td>
<td width=432 valign=top class="TableText">Sent
when all listeningalways-ondevices 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.)</td>
</tr>
<tr>
<td width=151 valign=top class="TableText"><b>AllNodesQueried</b><br>
[potentially
sent]</td>
<td width=432 valign=top class="TableText">Sent
when all nodes have been successfully queried.
</p>
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.
</tr>
</table>
<table width="700" border="0" cellpadding="5px" cellspacing="0" bgcolor="#E6E6E6" >
<tr>
<td><p class=Heading2>Other Notifications</p>
<p class="BodyText">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.<br>
<br>
</p></td>
</tr>
</table>
<table width="700" border=0 cellpadding=0 cellspacing=0>
<tr>
<td width=151 valign=top class="TableText"><b>ValueChanged</b></td>
<td width=432 valign=top class="TableText">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.</td>
</tr>
<tr>
<td width=151 valign=top class="TableText"><b>ValueRemoved</b></td>
<td width=432 valign=top class="TableText">Sent
when a value associated with a node has been removed.</td>
</tr>
<tr>
<td width=151 valign=top class="TableText"><b>Group</b></td>
<td width=432 valign=top class="TableText">Sent
when a nodes group association has changed.</td>
</tr>
<tr>
<td width=151 valign=top class="TableText"><b>NodeRemoved</b></td>
<td width=432 valign=top class="TableText">Sent
when a node has been removed from the ZWave network.</td>
</tr>
<tr>
<td width=151 valign=top class="TableText"><b>NodeEvent</b></td>
<td width=432 valign=top class="TableText">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.</td>
</tr>
<tr>
<td width=151 valign=top class="TableText"><b>PollingEnabled</b></td>
<td width=432 valign=top class="TableText">Sent
when node/value polling has been enabled.</td>
</tr>
<tr>
<td width=151 valign=top class="TableText"><b>PollingDisabled</b></td>
<td width=432 valign=top class="TableText">Sent
when node/value polling has been disabled.</td>
</tr>
<tr>
<td width=151 valign=top class="TableText"><b>DriverReset</b></td>
<td width=432 valign=top class="TableText">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.</td>
</tr>
</table>
</div><!--Main -->
<div id="Footer" class="FooterText"><br />
<br />
DRAFT Last updated 2011/02/17
</div><!--footer -->
</div>
</body>
</html>
|
