Line data Source code
1 : /*
2 : *
3 : * Copyright (c) 2020 Project CHIP Authors
4 : * Copyright (c) 2018 Nest Labs, Inc.
5 : *
6 : * Licensed under the Apache License, Version 2.0 (the "License");
7 : * you may not use this file except in compliance with the License.
8 : * You may obtain a copy of the License at
9 : *
10 : * http://www.apache.org/licenses/LICENSE-2.0
11 : *
12 : * Unless required by applicable law or agreed to in writing, software
13 : * distributed under the License is distributed on an "AS IS" BASIS,
14 : * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15 : * See the License for the specific language governing permissions and
16 : * limitations under the License.
17 : */
18 :
19 : /**
20 : * @file
21 : * Defines events used by the chip Device Layer to signal actions
22 : * or changes in device state.
23 : */
24 :
25 : #pragma once
26 : #include <stdint.h>
27 :
28 : #include <inet/IPAddress.h>
29 : #include <lib/core/DataModelTypes.h>
30 :
31 : namespace chip {
32 : namespace DeviceLayer {
33 : namespace DeviceEventType {
34 :
35 : enum
36 : {
37 : kFlag_IsPublic = 0x8000,
38 : kFlag_IsPlatformSpecific = 0x4000,
39 : kFlag_Reserved1 = 0x2000,
40 : kFlag_Reserved2 = 0x1000,
41 : kMaxEventNum = 0x0FFF,
42 : };
43 :
44 : /**
45 : * Event Type Ranges
46 : *
47 : * Defines numeric ranges for event types based on their visibility to the application,
48 : * an whether or not they are specific to a particular platform adaptation.
49 : */
50 : enum EventTypeRanges
51 : {
52 : /**
53 : * Public Event Range
54 : *
55 : * Denotes a range of event types that are publicly visible to applications. Events in this
56 : * range a generic to all platforms.
57 : */
58 : kRange_Public = kFlag_IsPublic,
59 :
60 : /**
61 : * Public, Platform-specific Event Range
62 : *
63 : * Denotes a range of platform-specific event types that are publicly visible to applications.
64 : */
65 : kRange_PublicPlatformSpecific = kFlag_IsPublic | kFlag_IsPlatformSpecific,
66 :
67 : /**
68 : * Internal Event Range
69 : *
70 : * Denotes a range of event types that are internal to the chip Device Layer. Events in this
71 : * range a generic to all platforms.
72 : */
73 : kRange_Internal = 0,
74 :
75 : /**
76 : * Internal, Platform-specific Event Range
77 : *
78 : * Denotes a range of platform-specific event types that are internal to the chip Device Layer.
79 : */
80 : kRange_InternalPlatformSpecific = kFlag_IsPlatformSpecific,
81 : };
82 :
83 : inline bool IsPublic(uint16_t eventType)
84 : {
85 : return (eventType & kFlag_IsPublic) != 0;
86 : }
87 19 : inline bool IsInternal(uint16_t eventType)
88 : {
89 19 : return (eventType & kFlag_IsPublic) == 0;
90 : }
91 : inline bool IsPlatformSpecific(uint16_t eventType)
92 : {
93 : return (eventType & kFlag_IsPlatformSpecific) != 0;
94 : }
95 : inline bool IsPlatformGeneric(uint16_t eventType)
96 : {
97 : return (eventType & kFlag_IsPlatformSpecific) == 0;
98 : }
99 :
100 : /**
101 : * Public Event Types
102 : *
103 : * Enumerates event types that are visible to the application and common across
104 : * all platforms.
105 : */
106 : enum PublicEventTypes
107 : {
108 : /**
109 : * WiFi Connectivity Change
110 : *
111 : * Signals a change in connectivity of the device's WiFi station interface.
112 : */
113 : kWiFiConnectivityChange = kRange_Public,
114 :
115 : /**
116 : * Thread Connectivity Change
117 : *
118 : * Signals a change in connectivity of the device's Thread interface.
119 : */
120 : kThreadConnectivityChange,
121 :
122 : /**
123 : * Internet Connectivity Change
124 : *
125 : * Signals a change in the device's ability to communicate via the Internet.
126 : */
127 : kInternetConnectivityChange,
128 :
129 : /**
130 : * Service Connectivity Change
131 : *
132 : * Signals a change in the device's ability to communicate with a chip-enabled service.
133 : */
134 : kServiceConnectivityChange,
135 :
136 : /**
137 : * Service Provisioning Change
138 : *
139 : * Signals a change to the device's service provisioning state.
140 : */
141 : kServiceProvisioningChange,
142 :
143 : /**
144 : * Time Sync Change
145 : *
146 : * Signals a change to the device's real time clock synchronization state.
147 : */
148 : kTimeSyncChange,
149 :
150 : /**
151 : * CHIPoBLE Connection Established
152 : *
153 : * Signals that an external entity has established a new CHIPoBLE connection with the device.
154 : */
155 : kCHIPoBLEConnectionEstablished,
156 :
157 : /**
158 : * CHIPoBLE Connection Closed
159 : *
160 : * Signals that an external entity has closed existing CHIPoBLE connection with the device.
161 : */
162 : kCHIPoBLEConnectionClosed,
163 :
164 : /**
165 : * Request BLE connections to be closed.
166 : * This is used in the supportsConcurrentConnection = False case.
167 : */
168 : kCloseAllBleConnections,
169 :
170 : /**
171 : * When supportsConcurrentConnection = False, the ConnectNetwork command cannot start until
172 : * the BLE device is closed and the Operation Network device (e.g. WiFi) has been started.
173 : */
174 : kWiFiDeviceAvailable,
175 : kOperationalNetworkStarted,
176 :
177 : /**
178 : * Thread State Change
179 : *
180 : * Signals that a state change has occurred in the Thread stack.
181 : */
182 : kThreadStateChange,
183 :
184 : /**
185 : * Thread Interface State Change
186 : *
187 : * Signals that the state of the Thread network interface has changed.
188 : */
189 : kThreadInterfaceStateChange,
190 :
191 : /**
192 : * chip-over-BLE (CHIPoBLE) Advertising Change
193 : *
194 : * Signals that the state of CHIPoBLE advertising has changed.
195 : */
196 : kCHIPoBLEAdvertisingChange,
197 :
198 : /**
199 : * IP address availability - either ipv4 or ipv6 addresses assigned to the underlying
200 : * wifi/ethernet interface.
201 : */
202 : kInterfaceIpAddressChanged,
203 :
204 : /**
205 : * Commissioning has completed by a call to the general commissioning cluster command.
206 : */
207 : kCommissioningComplete,
208 :
209 : /**
210 : * Signals that the fail-safe timer expired before the CommissioningComplete command was
211 : * successfully invoked.
212 : */
213 : kFailSafeTimerExpired,
214 :
215 : /**
216 : *
217 : */
218 : kOperationalNetworkEnabled,
219 :
220 : /**
221 : * Signals that DNS-SD has been initialized and is ready to operate.
222 : */
223 : kDnssdInitialized,
224 :
225 : /**
226 : * Signals that DNS-SD backend was restarted and services must be published again.
227 : */
228 : kDnssdRestartNeeded,
229 :
230 : /**
231 : * Signals that bindings were updated.
232 : */
233 : kBindingsChangedViaCluster,
234 :
235 : /**
236 : * Signals that the state of the OTA engine changed.
237 : */
238 : kOtaStateChanged,
239 :
240 : /**
241 : * Server initialization has completed.
242 : *
243 : * Signals that all server components have been initialized and the node is ready to establish
244 : * connections with other nodes. This event can be used to trigger on-boot actions that require
245 : * sending messages to other nodes.
246 : */
247 : kServerReady,
248 :
249 : /**
250 : * Signals that BLE is deinitialized.
251 : */
252 : kBLEDeinitialized,
253 :
254 : /**
255 : * Signals that secure session is established.
256 : */
257 : kSecureSessionEstablished,
258 :
259 : /**
260 : * Signals that factory reset has started.
261 : */
262 : kFactoryReset,
263 : };
264 :
265 : /**
266 : * Internal Event Types
267 : *
268 : * Enumerates event types that are internal to the chip Device Layer, but common across
269 : * all platforms.
270 : */
271 : enum InternalEventTypes
272 : {
273 : kEventTypeNotSet = kRange_Internal,
274 : kNoOp,
275 : kCallWorkFunct,
276 : kChipLambdaEvent,
277 : kChipSystemLayerEvent,
278 : kCHIPoBLESubscribe,
279 : kCHIPoBLEUnsubscribe,
280 : kCHIPoBLEWriteReceived,
281 : kCHIPoBLEIndicateConfirm,
282 :
283 : /**
284 : * Post this event in case of a BLE connection error. This event should be posted
285 : * if the BLE central disconnects without unsubscribing from the BLE characteristic.
286 : * This event should populate CHIPoBLEConnectionError structure.
287 : */
288 : kCHIPoBLEConnectionError,
289 : kCHIPoBLENotifyConfirm,
290 : kCHIPoWiFiPAFReceived,
291 : kCHIPoWiFiPAFConnected,
292 : kCHIPoWiFiPAFCancelConnect,
293 : kCHIPoWiFiPAFWriteDone,
294 : };
295 :
296 : static_assert(kEventTypeNotSet == 0, "kEventTypeNotSet must be defined as 0");
297 :
298 : } // namespace DeviceEventType
299 :
300 : /**
301 : * Connectivity Change
302 : *
303 : * Describes a change in some aspect of connectivity associated with a chip device.
304 : */
305 : enum ConnectivityChange
306 : {
307 : kConnectivity_NoChange = 0,
308 : kConnectivity_Established = 1,
309 : kConnectivity_Lost = -1
310 : };
311 :
312 : enum class InterfaceIpChangeType
313 : {
314 : kIpV4_Assigned,
315 : kIpV4_Lost,
316 : kIpV6_Assigned,
317 : kIpV6_Lost,
318 : };
319 :
320 : /**
321 : * Activity Change
322 : *
323 : * Describes a change in some activity associated with a chip device.
324 : */
325 : enum ActivityChange
326 : {
327 : kActivity_NoChange = 0,
328 : kActivity_Started = 1,
329 : kActivity_Stopped = -1,
330 : };
331 :
332 : enum OtaState
333 : {
334 : kOtaSpaceAvailable = 0,
335 : /**
336 : * This state indicates that Node is currently downloading a software update.
337 : */
338 : kOtaDownloadInProgress,
339 : /**
340 : * This state indicates that Node has successfully downloaded a software update.
341 : */
342 : kOtaDownloadComplete,
343 : /**
344 : * This state indicates that Node has failed to download a software update.
345 : */
346 : kOtaDownloadFailed,
347 : /**
348 : * This state indicates that Node has aborted the download of a software update.
349 : */
350 : kOtaDownloadAborted,
351 : /**
352 : * This state indicate that Node is currently in the process of verifying and applying a software update.
353 : */
354 : kOtaApplyInProgress,
355 : /**
356 : * This state indicates that Node has successfully applied a software update.
357 : */
358 : kOtaApplyComplete,
359 : /**
360 : * This state indicates that Node has failed to apply a software update.
361 : */
362 : kOtaApplyFailed,
363 : };
364 :
365 : inline ConnectivityChange GetConnectivityChange(bool prevState, bool newState)
366 : {
367 : if (prevState == newState)
368 : return kConnectivity_NoChange;
369 : if (newState)
370 : return kConnectivity_Established;
371 : return kConnectivity_Lost;
372 : }
373 :
374 : /**
375 : * A pointer to a function that performs work asynchronously.
376 : */
377 : typedef void (*AsyncWorkFunct)(intptr_t arg);
378 :
379 : } // namespace DeviceLayer
380 : } // namespace chip
381 :
382 : /* Include a header file containing platform-specific event definitions.
383 : */
384 : #ifdef EXTERNAL_CHIPDEVICEPLATFORMEVENT_HEADER
385 : #include EXTERNAL_CHIPDEVICEPLATFORMEVENT_HEADER
386 : #elif defined(CHIP_DEVICE_LAYER_TARGET)
387 : #define CHIPDEVICEPLATFORMEVENT_HEADER <platform/CHIP_DEVICE_LAYER_TARGET/CHIPDevicePlatformEvent.h>
388 : #include CHIPDEVICEPLATFORMEVENT_HEADER
389 : #endif // defined(CHIP_DEVICE_LAYER_TARGET)
390 :
391 : #if CONFIG_NETWORK_LAYER_BLE
392 : #include <ble/Ble.h>
393 : #endif
394 :
395 : #include <inet/InetInterface.h>
396 : #include <lib/support/LambdaBridge.h>
397 : #include <system/SystemEvent.h>
398 : #include <system/SystemLayer.h>
399 : #include <system/SystemPacketBuffer.h>
400 :
401 : #if CHIP_DEVICE_CONFIG_ENABLE_WIFIPAF
402 : #include <wifipaf/WiFiPAFRole.h>
403 : #endif // CHIP_DEVICE_CONFIG_ENABLE_WIFIPAF
404 :
405 : namespace chip {
406 : namespace DeviceLayer {
407 :
408 : /**
409 : * Represents a chip Device Layer event.
410 : */
411 : struct ChipDeviceEvent final
412 : {
413 : uint16_t Type;
414 :
415 : union
416 : {
417 : ChipDevicePlatformEvent Platform;
418 : LambdaBridge LambdaEvent;
419 : struct
420 : {
421 : AsyncWorkFunct WorkFunct;
422 : intptr_t Arg;
423 : } CallWorkFunct;
424 : struct
425 : {
426 : ConnectivityChange Result;
427 : } WiFiConnectivityChange;
428 : struct
429 : {
430 : ConnectivityChange Result;
431 : } ThreadConnectivityChange;
432 : struct
433 : {
434 : ConnectivityChange IPv4;
435 : ConnectivityChange IPv6;
436 : // WARNING: There used to be `char address[INET6_ADDRSTRLEN]` here and it is
437 : // deprecated/removed since it was too large and only used for logging.
438 : // Consider not relying on ipAddress field either since the platform
439 : // layer *does not actually validate* that the actual internet is reachable
440 : // before issuing this event *and* there may be multiple addresses
441 : // (especially IPv6) so it's recommended to use `ChipDevicePlatformEvent`
442 : // instead and do something that is better for your platform.
443 : chip::Inet::IPAddress ipAddress;
444 : } InternetConnectivityChange;
445 : struct
446 : {
447 : struct
448 : {
449 : ConnectivityChange Result;
450 : } Overall;
451 : struct
452 : {
453 : ConnectivityChange Result;
454 : } ViaThread;
455 : } ServiceConnectivityChange;
456 : struct
457 : {
458 : ConnectivityChange Result;
459 : } ServiceSubscriptionStateChange;
460 : struct
461 : {
462 : bool IsMemberOfFabric;
463 : } FabricMembershipChange;
464 : struct
465 : {
466 : bool IsServiceProvisioned;
467 : bool ServiceConfigUpdated;
468 : } ServiceProvisioningChange;
469 : struct
470 : {
471 : bool IsPairedToAccount;
472 : } AccountPairingChange;
473 : struct
474 : {
475 : bool IsTimeSynchronized;
476 : } TimeSyncChange;
477 : struct
478 : {
479 : uint64_t PeerNodeId;
480 : uint16_t SessionKeyId;
481 : uint8_t SessionType;
482 : bool IsCommissioner;
483 : } SessionEstablished;
484 : #if CONFIG_NETWORK_LAYER_BLE && BLE_USES_DEVICE_EVENTS
485 : struct
486 : {
487 : BLE_CONNECTION_OBJECT ConId;
488 : } CHIPoBLESubscribe;
489 : struct
490 : {
491 : BLE_CONNECTION_OBJECT ConId;
492 : } CHIPoBLEUnsubscribe;
493 : struct
494 : {
495 : BLE_CONNECTION_OBJECT ConId;
496 : chip::System::PacketBuffer * Data;
497 : } CHIPoBLEWriteReceived;
498 : struct
499 : {
500 : BLE_CONNECTION_OBJECT ConId;
501 : } CHIPoBLEIndicateConfirm;
502 : struct
503 : {
504 : BLE_CONNECTION_OBJECT ConId;
505 : CHIP_ERROR Reason;
506 : } CHIPoBLEConnectionError;
507 : struct
508 : {
509 : BLE_CONNECTION_OBJECT ConId;
510 : } CHIPoBLENotifyConfirm;
511 : #endif // CONFIG_NETWORK_LAYER_BLE && BLE_USES_DEVICE_EVENTS
512 : #if CHIP_DEVICE_CONFIG_ENABLE_WIFIPAF
513 : struct
514 : {
515 : chip::System::PacketBuffer * Data;
516 : chip::WiFiPAF::WiFiPAFSession SessionInfo;
517 : bool result;
518 : } CHIPoWiFiPAFReceived;
519 : #endif
520 : struct
521 : {
522 : bool RoleChanged : 1;
523 : bool AddressChanged : 1;
524 : bool NetDataChanged : 1;
525 : bool ChildNodesChanged : 1;
526 : struct
527 : {
528 : uint32_t Flags;
529 : } OpenThread;
530 : } ThreadStateChange;
531 : struct
532 : {
533 : ActivityChange Result;
534 : } CHIPoBLEAdvertisingChange;
535 : struct
536 : {
537 : InterfaceIpChangeType Type;
538 : } InterfaceIpAddressChanged;
539 :
540 : struct
541 : {
542 : uint64_t nodeId;
543 : FabricIndex fabricIndex;
544 : } CommissioningComplete;
545 : struct
546 : {
547 : FabricIndex fabricIndex;
548 : } BindingsChanged;
549 :
550 : struct
551 : {
552 : FabricIndex fabricIndex;
553 : bool addNocCommandHasBeenInvoked;
554 : bool updateNocCommandHasBeenInvoked;
555 : bool updateTermsAndConditionsHasBeenInvoked;
556 : bool setVidVerificationStatementHasBeenInvoked;
557 : } FailSafeTimerExpired;
558 :
559 : struct
560 : {
561 : // TODO(cecille): This should just specify wifi or thread since we assume at most 1.
562 : int network;
563 : } OperationalNetwork;
564 :
565 : struct
566 : {
567 : OtaState newState;
568 : } OtaStateChanged;
569 :
570 : struct
571 : {
572 : uint64_t PeerNodeId;
573 : uint8_t FabricIndex;
574 : uint8_t SecureSessionType;
575 : uint8_t TransportType;
576 : uint16_t LocalSessionId;
577 : } SecureSessionEstablished;
578 : };
579 :
580 : bool IsPublic() const { return DeviceEventType::IsPublic(Type); }
581 19 : bool IsInternal() const { return DeviceEventType::IsInternal(Type); }
582 : bool IsPlatformSpecific() const { return DeviceEventType::IsPlatformSpecific(Type); }
583 : bool IsPlatformGeneric() const { return DeviceEventType::IsPlatformGeneric(Type); }
584 : };
585 :
586 : } // namespace DeviceLayer
587 : } // namespace chip
|
