Documentation for the CHIP Zigbee Cluster Library (ZCL) implementation also called the CHIP ZCL Application Framework. This document provides information on how the different parts of the CHIP Application layer implementation of the Zigbee Cluster Library fit together.
THIS DOCUMENT IS A WORK IN PROGRESS AS THE DESIGN OF THE CHIP APPLICATION FRAMEWORK IS STILL IN FLUX
This directory provides the external interface for the CHIP ZCL Application Framework. In here you will find APIs and declarations needed to interact with the CHIP ZCL implementation.
This directory contains all the documentation for the CHIP ZCL Application Framework including the file you are reading right now.
This directory contains an example of generated code used by the CHIP ZCL Application Framework. This is not all the generated code used by a given application. It is merely the code used by the test framework within the CHIP ZCL Application Framework. Under orderinary circumstances, code would be generated into the gen directory associated with a given application target or project. The application target's gen directory would live with the given application and not with the core CHIP ZCL Application Framework. In this way there can be many application configurations each with its own gen directory.
This directory contains all of the plugins or sets of functionality included in the CHIP ZCL Application Framework. For more information on the plugin directory see the design document below.
The CHIP ZCL implementation is broken down into “plugins”. Plugins are located in the plugin directory located at src/app/plugin. A plugin represents a discrete piece of functionality implemented within the CHIP ZCL. Everything in the CHIP ZCL Application Framework is encapsulated in a plugin.
There are two types of functions called from within the CHIP ZCL Application Framework, there are command “handlers” and “callbacks”. These two types of functions are distinguished by the last word in their function signature.
The command handler literally handles ZCL commands as they arrive over the air. the command handler has a very specific signature containing just two arguments, a pointer to the incoming ChipZclCommandContext_t and a pointer to the handlers associated command struct. The ChipZclCommandContext_t contains all of the raw information about the incoming command such as its endpointId, clusterId and commandId among other things. The command handler's command struct contains all of the arguments associated with a given command.
Command handler can be implemented anywhere in the application code, but generally they are implemented by the plugin associated with the ZCL Cluster to which the given command belongs. For example the chipZclClusterOnOffServerCommandOnRequestHandler is implemented by the cluster-server-on-off plugin. This way whenever an “on” command is received over the air by the device, it will be handed off to the cluster-server-on-off plugin which will in turn decide what to do with it.
Callbacks are called when one portion of the CHIP ZCL Application Framework needs to interact with another. They are used to tie different pieces of functionality within the CHIP ZCL Application Framework together. For instance the core-data-model calls the postAttributeChangeCallback when an attribute's value changes within the data model. By implementing the postAttributeChangeCallback the application is able to listen for, and react to changes in the core-data-model.
Any plugin may define a callback for its own purposes. The core-data-model defines callbacks associated with the data model. The cluster-server-identify plugin defines two callbacks, the chipZclIdentifyServerStartIdentifyingCallback and the chipZclIdentifyServerStopIdentifyingCallback. By implementing these callbacks, the application can be informed when it should start or stop identifying itself. In this manner, the “normative behavior” of the application can be encapsulated inside the cluster-server-identify plugin and the application logic implemented by the developer need only implement a callback so that it knows when to start and stop interaction with the hardware needed to identify itself (toggling a gpio).
Callbacks provide a nice separation between the application logic (interaction with the hardware) and normative logic encapsulated within the CHIP ZCL Applicaton Framework.
Not all plugins within in the CHIP ZCL Application Framework are documented here. This is merely documentation for the critical plugins associated with the framework such as core-message-dispatch and core-data-model.
Messages enter into and are handled by the CHIP ZCL Application Framework through the core-message-dispatch plugin. The core-message-dispatch plugin is responsible for handling incoming messages and dispatching them off for processing by various other plugins. core-message-dispatch is also responsible for transmitting any synchronous response to an incoming message if one is required. For instance if a message arrives and it requires a ZCL Default Response, the core-message-dispatch plugin is responsible for generating any response value ZCL_ERROR or ZCL_SUCCESS based on how the incoming message is handled by the application framework and putting the response into the CHIP outgoing message queue.
Messages arriving in the core-message-dispatch are assumed to have had their ZCL Header Data (APS Header in Zigbee Pro) decoded completely such that they arrive in the form of a pointer to a ChipZclCommandContext_t which is defined in src/app/api/chip-zcl.h. Values that are normally part of the ZCL Header Data such as endpointId, clusterId and commandId are used by the core-message-dispatch to determine how to process the incoming message.
core-message-dispatch uses information parsed from the ZCL Header to retrieve a “request spec” and command handler pointer from the core-data-model. The “request spec” contains all the information necessary to decode the incoming request. The “request spec” and a pointer to the appropriate “request struct” are passed by the core-message-dispatch to the appropriate struct parser which is tied to the codec. The codec understands how data is encoded Over the Air (OTA) The struct parser and codec decode the incoming message payload and populate the associated “request struct” which can then be passed on throughout the system for actual command processing and device actuation etc...
This design gives the CHIP Application Framework the flexibilty to swap out or call a different codec if the OTA format of the message changes. It also insulates the command processing “normative behavior” or “business logic” from other logic in the system such as the OTA encode/decode.
For more information and an example on the handling of incoming On/Off Command messages by the core-message-dispatch and other plugins please see the diagram below:
The core-data-model plugin is responsible for the storage and interaction with the data model associated with a device. This includes all ZCL attributes and command handlers. For instance, when an attribute needs to be updated, the application interacts with the core-data-model. The data is a generated piece of code located in the gen directory associated with a given project. There is a gen directory located at /src/app/gen. This is not the gen directory for an application. It is merely an example of generated code used for unit testing the CHIP ZCL Application Framework.
When a ZCL attribute is updated in the data model, the core-data-model will call the postAttributeChangeCallback, if this callback is implemented by the device it will be informed of the attribute change. The device may react to the attribute change. For instance, if the on/off attribute in the On-Off Cluster changes, the application which implements the postAttributeChangeCallback may reflect this by toggling the actual pin tied to an LED.
