4 #include "cluster-id.h"
6 #include <lib/support/Span.h>
10 // Cluster Init Functions
11 void emberAfClusterInitCallback(EndpointId endpoint, ClusterId clusterId)
15 {{#all_user_clusters_names}}
16 case ZCL_{{asDelimitedMacro define}}_ID :
17 emberAf{{asCamelCased name false}}ClusterInitCallback(endpoint);
19 {{/all_user_clusters_names}}
21 // Unrecognized cluster ID
26 {{#all_user_clusters_names}}
27 void __attribute__((weak)) emberAf{{asCamelCased name false}}ClusterInitCallback(EndpointId endpoint)
32 {{/all_user_clusters_names}}
35 // Non-Cluster Related Callbacks
38 /** @brief Add To Current App Tasks
40 * This function is only useful to sleepy end devices. This function will note
41 * the passed item as part of a set of tasks the application has outstanding
42 * (e.g. message sent requiring APS acknwoledgement). This will affect how the
43 * application behaves with regard to sleeping and polling. Until the
44 * outstanding task is completed, the device may poll more frequently and sleep
47 * @param tasks Ver.: always
49 void __attribute__((weak)) emberAfAddToCurrentAppTasksCallback(EmberAfApplicationTask tasks) {}
51 /** @brief Remove From Current App Tasks
53 * This function is only useful to sleepy end devices. This function will
54 * remove the passed item from the set of tasks the application has outstanding
55 * (e.g. message sent requiring APS acknwoledgement). This will affect how the
56 * application behaves with regard to sleeping and polling. Removing the item
57 * from the list of outstanding tasks may allow the device to sleep longer and
58 * poll less frequently. If there are other outstanding tasks the system may
59 * still have to stay away and poll more often.
61 * @param tasks Ver.: always
63 void __attribute__((weak)) emberAfRemoveFromCurrentAppTasksCallback(EmberAfApplicationTask tasks) {}
65 /** @brief Allow Network Write Attribute
67 * This function is called by the application framework before it writes an
68 * attribute in response to a write attribute request from an external device.
69 * The value passed into this callback is the value to which the attribute is to
70 * be set by the framework.
71 Example: In mirroring simple metering data
72 * on an Energy Services Interface (ESI) (formerly called Energy Service Portal
73 * (ESP) in SE 1.0).), a mirrored simple meter needs to write read-only
74 * attributes on its mirror. The-meter-mirror sample application, located in
75 * app/framework/sample-apps, uses this callback to allow the mirrored device to
76 * write simple metering attributes on the mirror regardless of the fact that
77 * most simple metering attributes are defined as read-only by the ZigBee
79 Note: The ZCL specification does not (as of this
80 * writing) specify any permission-level security for writing writeable
81 * attributes. As far as the ZCL specification is concerned, if an attribute is
82 * writeable, any device that has a link key for the device should be able to
83 * write that attribute. Furthermore if an attribute is read only, it should not
84 * be written over the air. Thus, if you implement permissions for writing
85 * attributes as a feature, you MAY be operating outside the specification. This
86 * is unlikely to be a problem for writing read-only attributes, but it may be a
87 * problem for attributes that are writeable according to the specification but
88 * restricted by the application implementing this callback.
90 * @param endpoint Ver.: always
91 * @param clusterId Ver.: always
92 * @param attributeId Ver.: always
93 * @param mask Ver.: always
94 * @param manufacturerCode Ver.: always
95 * @param value Ver.: always
96 * @param type Ver.: always
98 EmberAfAttributeWritePermission __attribute__((weak)) emberAfAllowNetworkWriteAttributeCallback(
99 EndpointId endpoint, ClusterId clusterId,
100 AttributeId attributeId, uint8_t mask,
101 uint16_t manufacturerCode, uint8_t * value, uint8_t type)
103 return EMBER_ZCL_ATTRIBUTE_WRITE_PERMISSION_ALLOW_WRITE_NORMAL; // Default
106 /** @brief Attribute Read Access
108 * This function is called whenever the Application Framework needs to check
109 * access permission for an attribute read.
111 * @param endpoint Ver.: always
112 * @param clusterId Ver.: always
113 * @param manufacturerCode Ver.: always
114 * @param attributeId Ver.: always
116 bool __attribute__((weak)) emberAfAttributeReadAccessCallback(
117 EndpointId endpoint, ClusterId clusterId, uint16_t manufacturerCode,
118 AttributeId attributeId)
123 /** @brief Attribute Write Access
125 * This function is called whenever the Application Framework needs to check
126 * access permission for an attribute write.
128 * @param endpoint Ver.: always
129 * @param clusterId Ver.: always
130 * @param manufacturerCode Ver.: always
131 * @param attributeId Ver.: always
133 bool __attribute__((weak)) emberAfAttributeWriteAccessCallback(
134 EndpointId endpoint, ClusterId clusterId, uint16_t manufacturerCode,
135 AttributeId attributeId)
140 /** @brief Default Response
142 * This function is called by the application framework when a Default Response
143 * command is received from an external device. The application should return
144 * true if the message was processed or false if it was not.
146 * @param clusterId The cluster identifier of this response. Ver.: always
147 * @param commandId The command identifier to which this is a response. Ver.:
149 * @param status Specifies either SUCCESS or the nature of the error that was
150 * detected in the received command. Ver.: always
152 bool __attribute__((weak)) emberAfDefaultResponseCallback(
153 ClusterId clusterId, CommandId commandId, EmberAfStatus status)
158 /** @brief Configure Reporting Response
160 * This function is called by the application framework when a Configure
161 * Reporting Response command is received from an external device. The
162 * application should return true if the message was processed or false if it
165 * @param clusterId The cluster identifier of this response. Ver.: always
166 * @param buffer Buffer containing the list of attribute status records. Ver.:
168 * @param bufLen The length in bytes of the list. Ver.: always
170 bool __attribute__((weak)) emberAfConfigureReportingResponseCallback(
171 ClusterId clusterId, uint8_t * buffer, uint16_t bufLen)
176 /** @brief Read Reporting Configuration Response
178 * This function is called by the application framework when a Read Reporting
179 * Configuration Response command is received from an external device. The
180 * application should return true if the message was processed or false if it
183 * @param clusterId The cluster identifier of this response. Ver.: always
184 * @param buffer Buffer containing the list of attribute reporting configuration
185 * records. Ver.: always
186 * @param bufLen The length in bytes of the list. Ver.: always
188 bool __attribute__((weak)) emberAfReadReportingConfigurationResponseCallback(
189 ClusterId clusterId, uint8_t * buffer, uint16_t bufLen)
194 /** @brief Discover Attributes Response
196 * This function is called by the application framework when a Discover
197 * Attributes Response or Discover Attributes Extended Response command is
198 * received from an external device. The Discover Attributes Response command
199 * contains a bool indicating if discovery is complete and a list of zero or
200 * more attribute identifier/type records. The final argument indicates whether
201 * the response is in the extended format or not. The application should return
202 * true if the message was processed or false if it was not.
204 * @param clusterId The cluster identifier of this response. Ver.: always
205 * @param discoveryComplete Indicates whether there are more attributes to be
206 * discovered. true if there are no more attributes to be discovered. Ver.:
208 * @param buffer Buffer containing the list of attribute identifier/type
209 * records. Ver.: always
210 * @param bufLen The length in bytes of the list. Ver.: always
211 * @param extended Indicates whether the response is in the extended format or
214 bool __attribute__((weak)) emberAfDiscoverAttributesResponseCallback(
215 ClusterId clusterId, bool discoveryComplete, uint8_t * buffer,
216 uint16_t bufLen, bool extended)
221 /** @brief Discover Commands Generated Response
223 * This function is called by the framework when Discover Commands Generated
224 * Response is received.
226 * @param clusterId The cluster identifier of this response. Ver.: always
227 * @param manufacturerCode Manufacturer code Ver.: always
228 * @param discoveryComplete Indicates whether there are more commands to be
229 * discovered. Ver.: always
230 * @param commandIds Buffer containing the list of command identifiers. Ver.:
232 * @param commandIdCount The length of bytes of the list, whish is the same as
233 * the number of identifiers. Ver.: always
235 bool __attribute__((weak)) emberAfDiscoverCommandsGeneratedResponseCallback(
236 ClusterId clusterId, uint16_t manufacturerCode, bool discoveryComplete,
237 CommandId * commandIds, uint16_t commandIdCount)
242 /** @brief Discover Commands Received Response
244 * This function is called by the framework when Discover Commands Received
245 * Response is received.
247 * @param clusterId The cluster identifier of this response. Ver.: always
248 * @param manufacturerCode Manufacturer code Ver.: always
249 * @param discoveryComplete Indicates whether there are more commands to be
250 * discovered. Ver.: always
251 * @param commandIds Buffer containing the list of command identifiers. Ver.:
253 * @param commandIdCount The length of bytes of the list, whish is the same as
254 * the number of identifiers. Ver.: always
256 bool __attribute__((weak)) emberAfDiscoverCommandsReceivedResponseCallback(
257 ClusterId clusterId, uint16_t manufacturerCode, bool discoveryComplete,
258 CommandId * commandIds, uint16_t commandIdCount)
263 /** @brief Pre Command Received
265 * This callback is the second in the Application Framework's message processing
266 * chain. At this point in the processing of incoming over-the-air messages, the
267 * application has determined that the incoming message is a ZCL command. It
268 * parses enough of the message to populate an EmberAfClusterCommand struct. The
269 * Application Framework defines this struct value in a local scope to the
270 * command processing but also makes it available through a global pointer
271 * called emberAfCurrentCommand, in app/framework/util/util.c. When command
272 * processing is complete, this pointer is cleared.
274 * @param cmd Ver.: always
276 bool __attribute__((weak)) emberAfPreCommandReceivedCallback(
277 EmberAfClusterCommand * cmd)
282 /** @brief Pre Message Send
284 * This function is called by the framework when it is about to pass a message
285 * to the stack primitives for sending. This message may or may not be ZCL,
286 * ZDO, or some other protocol. This is called prior to
288 * fragmentation that may be done. If the function returns true it is assumed
289 * the callback has consumed and processed the message. The callback must also
290 * set the EmberStatus status code to be passed back to the caller. The
291 * framework will do no further processing on the message.
293 * function returns false then it is assumed that the callback has not processed
294 * the mesasge and the framework will continue to process accordingly.
296 * @param messageStruct The structure containing the parameters of the APS
297 * message to be sent. Ver.: always
298 * @param status A pointer to the status code value that will be returned to the
299 * caller. Ver.: always
301 bool __attribute__((weak)) emberAfPreMessageSendCallback(
302 EmberAfMessageStruct * messageStruct, EmberStatus * status)
307 /** @brief Message Sent
309 * This function is called by the application framework from the message sent
310 * handler, when it is informed by the stack regarding the message sent status.
311 * All of the values passed to the emberMessageSentHandler are passed on to this
312 * callback. This provides an opportunity for the application to verify that its
313 * message has been sent successfully and take the appropriate action. This
314 * callback should return a bool value of true or false. A value of true
315 * indicates that the message sent notification has been handled and should not
316 * be handled by the application framework.
318 * @param type Ver.: always
319 * @param indexOrDestination Ver.: always
320 * @param apsFrame Ver.: always
321 * @param msgLen Ver.: always
322 * @param message Ver.: always
323 * @param status Ver.: always
325 bool __attribute__((weak)) emberAfMessageSentCallback(
326 EmberOutgoingMessageType type, uint64_t indexOrDestination,
327 EmberApsFrame * apsFrame, uint16_t msgLen, uint8_t * message,
333 /** @brief Pre Attribute Change
335 * This function is called by the application framework before it changes an
336 * attribute value. The value passed into this callback is the value to which
337 * the attribute is to be set by the framework. The application should return
338 * ::EMBER_ZCL_STATUS_SUCCESS to permit the change or any other ::EmberAfStatus
341 * @param endpoint Ver.: always
342 * @param clusterId Ver.: always
343 * @param attributeId Ver.: always
344 * @param mask Ver.: always
345 * @param manufacturerCode Ver.: always
346 * @param type Ver.: always
347 * @param size Ver.: always
348 * @param value Ver.: always
350 EmberAfStatus __attribute__((weak)) emberAfPreAttributeChangeCallback(
351 EndpointId endpoint, ClusterId clusterId, AttributeId attributeId,
352 uint8_t mask, uint16_t manufacturerCode, uint8_t type, uint8_t size,
355 return EMBER_ZCL_STATUS_SUCCESS;
358 /** @brief Post Attribute Change
360 * This function is called by the application framework after it changes an
361 * attribute value. The value passed into this callback is the value to which
362 * the attribute was set by the framework.
364 * @param endpoint Ver.: always
365 * @param clusterId Ver.: always
366 * @param attributeId Ver.: always
367 * @param mask Ver.: always
368 * @param manufacturerCode Ver.: always
369 * @param type Ver.: always
370 * @param size Ver.: always
371 * @param value Ver.: always
373 void __attribute__((weak)) emberAfPostAttributeChangeCallback(
374 EndpointId endpoint, ClusterId clusterId, AttributeId attributeId,
375 uint8_t mask, uint16_t manufacturerCode, uint8_t type, uint8_t size,
380 /** @brief Read Attributes Response
382 * This function is called by the application framework when a Read Attributes
383 * Response command is received from an external device. The application should
384 * return true if the message was processed or false if it was not.
386 * @param clusterId The cluster identifier of this response. Ver.: always
387 * @param buffer Buffer containing the list of read attribute status records.
389 * @param bufLen The length in bytes of the list. Ver.: always
391 bool __attribute__((weak)) emberAfReadAttributesResponseCallback(
392 ClusterId clusterId, uint8_t * buffer, uint16_t bufLen)
397 /** @brief External Attribute Read
399 * Like emberAfExternalAttributeWriteCallback above, this function is called
400 * when the framework needs to read an attribute that is not stored within the
401 * Application Framework's data structures.
403 * information about the attribute itself is passed as a pointer to an
404 * EmberAfAttributeMetadata struct, which is stored within the application and
405 * used to manage the attribute. A complete description of the
406 * EmberAfAttributeMetadata struct is provided in
407 * app/framework/include/af-types.h
408 This function assumes that the
409 * application is able to read the attribute, write it into the passed buffer,
410 * and return immediately. Any attributes that require a state machine for
411 * reading and writing are not really candidates for externalization at the
412 * present time. The Application Framework does not currently include a state
413 * machine for reading or writing attributes that must take place across a
414 * series of application ticks. Attributes that cannot be read in a timely
415 * manner should be stored within the Application Framework and updated
416 * occasionally by the application code from within the
417 * emberAfMainTickCallback.
418 If the application was successfully able to
419 * read the attribute and write it into the passed buffer, it should return a
420 * value of EMBER_ZCL_STATUS_SUCCESS. Ensure that the size of the externally
421 * managed attribute value is smaller than what the buffer can hold. In the case
422 * of a buffer overflow throw an appropriate error such as
423 * EMBER_ZCL_STATUS_INSUFFICIENT_SPACE. Any other return value indicates the
424 * application was not able to read the attribute.
426 * @param endpoint Ver.: always
427 * @param clusterId Ver.: always
428 * @param attributeMetadata Ver.: always
429 * @param manufacturerCode Ver.: always
430 * @param buffer Ver.: always
431 * @param maxReadLength Ver.: always
433 EmberAfStatus __attribute__((weak)) emberAfExternalAttributeReadCallback(
434 EndpointId endpoint, ClusterId clusterId,
435 EmberAfAttributeMetadata * attributeMetadata, uint16_t manufacturerCode,
436 uint8_t * buffer, uint16_t maxReadLength)
438 return EMBER_ZCL_STATUS_FAILURE;
441 /** @brief Write Attributes Response
443 * This function is called by the application framework when a Write Attributes
444 * Response command is received from an external device. The application should
445 * return true if the message was processed or false if it was not.
447 * @param clusterId The cluster identifier of this response. Ver.: always
448 * @param buffer Buffer containing the list of write attribute status records.
450 * @param bufLen The length in bytes of the list. Ver.: always
452 bool __attribute__((weak)) emberAfWriteAttributesResponseCallback(
453 ClusterId clusterId, uint8_t * buffer, uint16_t bufLen)
458 /** @brief External Attribute Write
460 * This function is called whenever the Application Framework needs to write an
461 * attribute which is not stored within the data structures of the Application
462 * Framework itself. One of the new features in Version 2 is the ability to
463 * store attributes outside the Framework. This is particularly useful for
464 * attributes that do not need to be stored because they can be read off the
465 * hardware when they are needed, or are stored in some central location used by
466 * many modules within the system. In this case, you can indicate that the
467 * attribute is stored externally. When the framework needs to write an external
468 * attribute, it makes a call to this callback.
469 This callback is very
470 * useful for host micros which need to store attributes in persistent memory.
471 * Because each host micro (used with an Ember NCP) has its own type of
472 * persistent memory storage, the Application Framework does not include the
473 * ability to mark attributes as stored in flash the way that it does for Ember
474 * SoCs like the EM35x. On a host micro, any attributes that need to be stored
475 * in persistent memory should be marked as external and accessed through the
476 * external read and write callbacks. Any host code associated with the
477 * persistent storage should be implemented within this callback.
479 * the important information about the attribute itself is passed as a pointer
480 * to an EmberAfAttributeMetadata struct, which is stored within the application
481 * and used to manage the attribute. A complete description of the
482 * EmberAfAttributeMetadata struct is provided in
483 * app/framework/include/af-types.h.
484 This function assumes that the
485 * application is able to write the attribute and return immediately. Any
486 * attributes that require a state machine for reading and writing are not
487 * candidates for externalization at the present time. The Application Framework
488 * does not currently include a state machine for reading or writing attributes
489 * that must take place across a series of application ticks. Attributes that
490 * cannot be written immediately should be stored within the Application
491 * Framework and updated occasionally by the application code from within the
492 * emberAfMainTickCallback.
493 If the application was successfully able to
494 * write the attribute, it returns a value of EMBER_ZCL_STATUS_SUCCESS. Any
495 * other return value indicates the application was not able to write the
498 * @param endpoint Ver.: always
499 * @param clusterId Ver.: always
500 * @param attributeMetadata Ver.: always
501 * @param manufacturerCode Ver.: always
502 * @param buffer Ver.: always
504 EmberAfStatus __attribute__((weak)) emberAfExternalAttributeWriteCallback(
505 EndpointId endpoint, ClusterId clusterId,
506 EmberAfAttributeMetadata * attributeMetadata, uint16_t manufacturerCode,
509 return EMBER_ZCL_STATUS_FAILURE;
512 /** @brief Report Attributes
514 * This function is called by the application framework when a Report Attributes
515 * command is received from an external device. The application should return
516 * true if the message was processed or false if it was not.
518 * @param clusterId The cluster identifier of this command. Ver.: always
519 * @param buffer Buffer containing the list of attribute report records. Ver.:
521 * @param bufLen The length in bytes of the list. Ver.: always
523 bool __attribute__((weak)) emberAfReportAttributesCallback(
524 ClusterId clusterId, uint8_t * buffer, uint16_t bufLen)
529 /** @brief Get Current Time
531 * This callback is called when device attempts to get current time from the
532 * hardware. If this device has means to retrieve exact time, then this method
533 * should implement it. If the callback can't provide the exact time it should
534 * return 0 to indicate failure. Default action is to return 0, which indicates
535 * that device does not have access to real time.
538 uint32_t __attribute__((weak)) emberAfGetCurrentTimeCallback()
543 /** @brief Get Endpoint Info
545 * This function is a callback to an application implemented endpoint that
546 * operates outside the normal application framework. When the framework wishes
547 * to perform operations with that endpoint it uses this callback to retrieve
548 * the endpoint's information. If the endpoint exists and the application can
549 * provide data then true shall be returned. Otherwise the callback must return
552 * @param endpoint The endpoint to retrieve data for. Ver.: always
553 * @param returnNetworkIndex The index corresponding to the ZigBee network the
554 * endpoint belongs to. If not using a multi-network device, 0 must be
555 * returned. Otherwise on a multi-network device the stack will switch to this
556 * network before sending the message. Ver.: always
557 * @param returnEndpointInfo A pointer to a data struct that will be written
558 * with information about the endpoint. Ver.: always
560 bool __attribute__((weak)) emberAfGetEndpointInfoCallback(
561 EndpointId endpoint, uint8_t * returnNetworkIndex,
562 EmberAfEndpointInfoStruct * returnEndpointInfo)
567 /** @brief Get Source Route Overhead
569 * This function is called by the framework to determine the overhead required
570 * in the network frame for source routing to a particular destination.
572 * @param destination The node id of the destination Ver.: always
574 uint8_t __attribute__((weak)) emberAfGetSourceRouteOverheadCallback(chip::NodeId destination)
579 /** @brief Registration Abort
581 * This callback is called when the device should abort the registration
585 void __attribute__((weak)) emberAfRegistrationAbortCallback() {}
587 /** @brief Interpan Send Message
589 * This function will send a raw MAC message with interpan frame format using
590 * the passed parameters.
592 * @param header Interpan header info Ver.: always
593 * @param messageLength The length of the message received or to send Ver.:
595 * @param message The message data received or to send. Ver.: always
597 EmberStatus __attribute__((weak)) emberAfInterpanSendMessageCallback(
598 EmberAfInterpanHeader * header, uint16_t messageLength, uint8_t * message)
600 return EMBER_LIBRARY_NOT_PRESENT;
603 /** @brief Start Move
605 * This function is called to initiate the process for a device to move (rejoin)
609 bool __attribute__((weak)) emberAfStartMoveCallback()