Silicon Labs UG391 User manual
UG391: Zigbee Application Framework
Developer’s Guide
The Zigbee application framework is a body of embedded C code
that can be configured by AppBuilder to implement any Zigbee
Cluster Library (ZCL) application. Beginning with version 2.6.0 of
the EmberZNet SDK, the Zigbee application framework replaces
Application Framework V2. This guide covers the structure and
usage of the Zigbee application framework.
KEY POINTS
• Provides a refer ence for all aspects of
the Application Framework, including
callbacks, plugins, t he API, and the CLI.
• Discusses extending the ZCL (Zigbee
Cluster Library).
• Offers guidelines for designing an application in AppBuilder.
silabs.com | Building a more connected world. Rev. 0.2
UG391: Zigbee Application Framework Developer's Guide
Introduction
1 Introduction
1.1 Purpose
The Zigbee application framework (also known as the ZCL application framework) is a body of embedded C code that can be configured
by the AppBuilder tool to implement any Zigbee Cluster Library (ZCL) application. The application framework is located in the app/framework directory.
This guide covers the structure and usage of the Zigbee application framework.
1.2 Building an Application
An application is created in several steps using the Zigbee application framework.
1. Create Zigbee application framework configuration files using Simplicity Studio’s AppBuilder. The configuration files as well as the
project files for your platform of choice are generated by AppBuilder. An overview of using AppBuilder and how it relates to the Zigbee
application framework is provided in UG103.02: Zigbee Fundamentals. More detailed information on how to use AppBuilder can be
found in the AppBuilder Help (Simplicity Studio > Help > Help Contents > Simplicity Studio AppBuilder) in Simplicity Studio 4 and in
the Simplicity Studio 5 User’s Guide.
2. Write the specifics of your application into the callback functions generated along with your configuration files. Use the Zigbee application framework API to do things like interact with attributes, and send, receive, and respond to commands on the Zigbee network.
For more detailed information on the Zigbee application framework API, see section 5 The Application Framework API.
3. Open the generated project file into the IDE of your chosen chip, compile your application, and load it onto your development kit
hardware.
4. Run your application and interact with it using the Simplicity Studio console window and the application’s command line interface.
More information on how to use Simplicity Studio is available in the online help in Simplicity Studio (Help > Help Contents) in Simplicity
Studio 4 and the Simplicity Studio 5 User’s Guide.
1.3 Porting an Application
For information regarding porting an application from Application Framework v2 to the current Zigbee Application Framework in Simplicity
Studio, see the Knowledge Base Article Migrating Projects from Application Framework V2 to the Zigbee Application Framework in Sim-
plicity Studio’s AppBuilder.
silabs.com | Building a more connected world. Rev. 0.2 | 2
UG391: Zigbee Application Framework Developer's Guide
Application Framework Architecture
2 Application Framework Architecture
The Zigbee application framework sits on top of the Zigbee stack, consumes the stack “handler” interfaces, and exposes its own more
highly abstracted and application-specific interface to the developer.
One of the main features of the Zigbee application framework is the separation of user-created and Silicon Labs-created code. While
Silicon Labs provides all of the source code for the Zigbee application framework, user-created code should live outside the framework
and should interact with the framework through the Zigbee application framework API exposed by the framework utilities and callbacks.
The block diagram in the following figure shows a high-level overview of the Zigbee application framework architecture and how the two
code bases are separated.
Figure 2-1. Application Framework Architecture
The “Simple Main” Plugin included in app/framework/plugin consumes the Zigbee Stack handler interface and ties the Zigbee application
framework into the EmberZNet PRO stack. In addition, two main files are located in the app/framework/util directory, one (af-main-soc.c)
for a System-on-Chip (SoC) and the other (af-main-host.c) for a host micro-paired with a Network Co-Processor (NCP).
The af-main-soc and af-main-host files implement the
to the Zigbee application framework for command processing. Once incoming messages are processed they are either passed off to the
appropriate cluster for handling, or passed directly to cluster-specific callbacks generated by AppBuilder. A significant portion of the
command processing code is generated directly from the ZCL XML documents included in app/zcl/.
All of the code and header files generated from the ZCL XML documents are generated into <user workspace directory>/<application
name>/ alongside the application header and callbacks file among others.
emberIncomingMessageHandler() and pass all incoming messages off
silabs.com | Building a more connected world. Rev. 0.2 | 3
UG391: Zigbee Application Framework Developer's Guide
Application Framework Directory Structure
3 Application Framework Directory Structure
When you generate a project, it is generated by default into your workspace directory, in a folder named with the project name. The other
directories named in this section may be found in the Simplicity Studio Zigbee protocol SDK folder (\SiliconLabs\SimplicityStudio\<version>\developer\sdks\gecko_sdk_suite\<version>\protocol\zigbee).
tool/appbuilder: Configuration and template files used by AppBuilder
When you point AppBuilder at a stack installation, it looks into this directory to load XML descriptions of the most current ZCL implementation as of the release of that stack.
You may load your custom cluster .xml files into your project on the “Zigbee Stack” Tab in AppBuilder. For more information about creating
custom clusters, see Simplicity Studio 4 AppBuilder Help at Help | Help Contents | Simplicity Studio AppBuilder | Creating custom clusters
or the Simplicity Studio 5 User’s Guide.
app/framework: All of the Zigbee application framework code is located in app/framework. Major portions of the code have been broken
out into their own directories.
app/framework/cli: Code related to the application framework’s implementation of the Command Line Interface.
Core code for the CLI is included in app/util/serial/command-interpreter2.c. The CLI includes data type checking and command usage
feedback among other things. As a result:
1. All commands require ALL arguments associated with that command. If an argument is missing, the CLI will provide user feedback
as to the particular command’s usage.
2. Arguments passed with the CLI must be in one of the following formats:
<int>: 123(decimal) or 0x1ABC(hex)
<string>: "foo"(string) or {0A 1B 2C}(array of bytes)
app/framework/include: All of the external APIs for the Zigbee application framework.
This directory mirrors the use of the include directory in the stack. It is intended to be the single location for all externally facing application
interfaces.
app/framework/plugin: All Silicon Labs-created ZCL cluster code
This directory contains all of the cluster code created by the Silicon Labs team for handling cluster commands. This code optionally can
be included in an application by selecting the plugin from AppBuilder’s Plugin Tab. If you choose not to include a plugin, you are responsible for implementing the callbacks for all of the required cluster commands.
app/framework/scenarios: All sample application scenarios which use the application framework
These sample scenarios may be opened within AppBuilder by starting a new project, , selecting a framework, and then selecting a sample
application.” AppBuilder requests a new application name for the given scenario instance and copies the sample callback code into a
directory of the same name within app/builder. See QSG106: Zigbee EmberZNet PRO Quick-Start Guide for a detailed description on
building and flashing sample applications.
app/framework/security: All utility code related to Zigbee Security.
Code related to key establishment is located in app/framework/cluster.
app/framework/util: The application's mains, message processing, and any other utility code used by the Zigbee application framework.
This directory contains the guts of the Zigbee application framework. Attribute storage files that manage attributes for multiple endpoint
support are included in this directory. In addition, the API used for accessing, reading, and writing attributes is included in the file attributetable.h, and attribute-storage.h.
silabs.com | Building a more connected world. Rev. 0.2 | 4
UG391: Zigbee Application Framework Developer's Guide
Designing an Application with AppBuilder
4 Designing an Application with AppBuilder
AppBuilder is a tool for generating Zigbee-compliant applications. AppBuilder is made up of two parts: the Zigbee application framework
or other application framework and a graphical tool for configuring the included source code. The AppBuilder graphical tool is both a
stand-alone application and a Simplicity Studio plug-in. AppBuilder gives you an interface for turning on or off embedded clusters and
features in the code compiled into a finished application.
AppBuilder is intended to meet the following goals:
• Quickly create Zigbee-compliant applications for Silicon Labs wireless platforms.
• Enable rapid development and decrease customer time-to-market by providing standard example applications.
4.1 ZCL Concepts
4.1.1 Definitions
Zigbee Application Profiles
Zigbee application profiles specify generic settings (such as security, join parameters, and poll rate) for all devices within an application
group. Application profiles also specify exactly what clusters (protocols) must be supported for each device in the application group.
AppBuilder currently supports six Zigbee application profiles:
• Zigbee 3.0
• Home Automation (HA)
• Smart Energy (SE, formerly AMI or Automated Meter-reading Infrastructure)
• Commercial Building Automation (CBA)
• Zigbee Light Link (ZLL)
• Health Care (HC)
Clusters
Each Zigbee cluster defines an application-level protocol. A set of these protocols (or clusters) defines the functionality of a particular
Zigbee device. Anyone with a networking background can think of a cluster as an application protocol that has been encapsulated within
the Zigbee specification.
The Zigbee Cluster Library (ZCL) is a document that specifies the clusters used by Zigbee devices. The original ZCL document had 30
clusters, most of which were specified as required or optional by at least one device in the Zigbee HA application profile. The SE application profile uses some of the clusters specified in the ZCL but also specifies new clusters that are unique to SE.
Devices
A Zigbee device can be thought of as a collection of clusters. For example, an on/off light switch and an on/off light are two of the 31
devices in the HA profile. All of the devices within a profile must use the same sort of security. There are recommendations on polling
rates, start-up parameters, what kind of ZDO messages should be implemented, and so on, with the idea being that these devices must
interoperate on the same network. If devices have different security settings, they cannot join together. If a user buys an HA device from
company A and buys an HA device from company B, because they use the same application profile one of the devices should be able to
join the other device.
If two Zigbee devices are on a certified Zigbee stack, they can route for each other. In other words, they can exchange messages at the
application level. Interoperability at the application level is not guaranteed until they use an application profile. These standard application
profiles enable AppBuilder to generate compliant Zigbee applications.
The HA on/off light has the following implementations:
• Identify server (required by all)
• Groups server
• Scenes server
• On/Off server
silabs.com | Building a more connected world. Rev. 0.2 | 5
UG391: Zigbee Application Framework Developer's Guide
Designing an Application with AppBuilder
The HA on/off light switch has the following implementations:
• Identify client
• Groups client
• Scenes client
• On/Off client
The on/off light switch can send an on/off or toggle message that the on/off light is required to understand and abide.
4.1.2 More About Clusters and Attributes
Clusters specify two things: attributes and commands. Attributes are well-defined pieces of data that are stored on a device and can be
read (and sometimes written) by external devices. Commands specify over-the-air messages that are exchanged. Each command defined
by the ZCL is unidirectional in the sense that it is sent by one side (either the client or server) and received by the other. A device can
implement only one side of a cluster, or it can implement both sides of a cluster.
For instance, an “HA on/off Light” implements the server side of the “on/off” cluster, while the “HA on/off Light Switch” implements the
client side of the “on/off” cluster. This defines that the Light Switch sends “on”, “off”, and “toggle” commands that the Light can receive
(and understand). It also defines that the Light stores a Boolean attribute called “on/off” representing the current state of the device.
Note: Zigbee often uses the terms “in-cluster-list” and “out-cluster-list” instead of server and client. An “in-cluster-list” is the list of
supported server clusters, and the “out-cluster-list” is the list of supported client clusters.
In most cases, the server side of a cluster contains all the attributes, and the client side is the side that initiates an over-the-air exchange.
For the most part, the client sends a message, and the server answers that message.
4.1.2.1 Example: The Identify Cluster
The client/server interaction defined by the ZCL is illustrated in the Identify example shown in the following figure.
Figure 4-1. Cluster Example: Identify
Like many clusters, the Identify cluster is a fairly simple cluster. The lower right corner shows the single attribute, identify time.
Identify cluster use case:
A user is provisioning a network of 12 lights in one room and must connect 6 of those lights to a single switch. The MAC address of each
light is used to associate it with the switch. The MAC addresses for all 12 lights can be discovered by using a provisioning tool and a low
power broadcast or by using a token (set when they were installed) on each light indicating room or location. The “Identify” functionality
can be used to figure out which six MAC addresses correspond to the six physical lights that the user wants bound to a switch. Using the
Identify cluster, the user can tell each light individually to “identify” itself (for example, blink so that it can be seen).
The Identify cluster defines the protocol for how devices are put into and taken out of identify mode. In the above example, the provisioning
tool implements the client side of the identify cluster, and the light or the device that needs to be identified implements the server side.
silabs.com | Building a more connected world. Rev. 0.2 | 6
UG391: Zigbee Application Framework Developer's Guide
Designing an Application with AppBuilder
When the client wants to tell a device to “start identifying,” it sends the “Identify” command and specifies a period of time in seconds for
which to continue identifying. The device stops identifying when the identify time attributes (decremented each second) reaches 0, or if
the device receives an “Identify” command with identify time value of 0.
The first message in Figure A 1 turns on “identify.” When identify is turned on, a time period is also included in the message. For example,
suppose identify is turned on for 30 seconds. The second message shows the client (provisioning device) querying the server (light) to
find out how much time is left in the identify process.
Because a query message can be sent to a group, it is possible to put a device into a mode where it is identifying, and then use a PC or
provisioning tool and figure out which device in the group is identifying. This is useful if a device supports a physical cue to start identifying.
Then a device can be poked (button press, magnet wand, and so on) to start identifying, and a group message can be sent to map the
MAC address to the physical device.
4.1.2.2 Example: The Temperature Measurement Cluster
The following figure illustrates another example of a cluster. This example shows temperature measurement.
Figure 4-2. Cluster example: Temperature measurement
Notice that this cluster has no commands—it only has attributes. In this case, the device implements measurements of temperature, such
as a thermostat. This example includes a measured value, a minimum measured value, and a maximum measured value. With no commands, this cluster relies on the global commands defined in the ZCL. The global commands define messages for reading, writing,
discovering, and reporting attributes.
Note: Fourteen global commands read attributes, write attributes, configure attribute reporting, discover attributes, and report attribute
values. Clusters that only include attributes are simple to understand and simple to implement, because the global commands
are already implemented.
In order to read the value of an attribute of this cluster, a global read attributes command is used. This message contains the attribute ID
of the attribute to read. In combination, the cluster and the attribute ID provide unique identification. On the embedded side, this makes it
possible to centralize all the attributes in a single table. All of the code for those attributes is generic, shared code.
As a result, for example, when adding four of the temperature-measuring-sensing clusters, the impact on flash is minimal, because there
are no additional commands. The impact on RAM depends on the number of attributes added per cluster.
The application level protocol provided by the Zigbee Cluster Library makes it possible for two companies to develop products separately
and have them work together without having to test them together.
4.2 AppBuilder and the Application Framework Architecture
AppBuilder is a GUI tool which is part of the Simplicity Studio desktop application and is used to configure the Zigbee application framework code. AppBuilder reads configuration data out of the installed stack directory. The .properties and .xml files located in tool/appbuilder
tell AppBuilder everything it needs to know about the associated stack. By interpreting these configuration files within the stack, AppBuilder
is able to generate the appropriate configuration data and project files necessary for a complete Zigbee application.
silabs.com | Building a more connected world. Rev. 0.2 | 7
UG391: Zigbee Application Framework Developer's Guide
Generated Application Configuration Files
5 Generated Application Configuration Files
The Zigbee application framework uses the same preprocessor directives to configure the code to be included and excluded from the
framework. In addition to the main app header file, AppBuilder also generates an "endpoint configuration" header file with the suffix
endpoint_configuration.h.
<DeviceName>_endpoint_configuration.h
The generated file that configures the Zigbee application framework's static data structures. This allows attribute metadata to be shared
across endpoints, and each endpoint to have its own space for attribute storage. The #defines in the <DeviceName>_endpoint_config.h
file are used by the app/framework/util/attribute-storage.c file to configure all of the application’s attribute-related data.
The file must be re-generated each time you modify your application configuration in AppBuilder. Silicon Labs recommends that you do
not edit the <DeviceName>_endpoint_config.h file by hand as each of the macro definitions in the file has a complex relationship.
The role of the endpoint configuration file is described in more detail in section 9.1 ZCL Attribute Configuration.
<DeviceName>.h
The main header file for your application. It includes all of the #defines that turn on the features you require within the framework.
<DeviceName>_callbacks.c
A generated stub callback file containing default implementations of all callbacks you have selected to include in your project. This is
where your code goes. You are not restricted to using this one file for your code. You can include other files provided you add them to
your generated project file so that they can be found by the compiler.
<DeviceName>.hwconf
The generated peripheral configuration file for your part. Simplicity Studio offers a user-friendly interface for modifications to the peripheral
configurations. See AN1115: Configuring Peripherals for 32-Bit Devices in Simplicity Studio for more information.
<DeviceName>_tokens.h
If you are including any attributes in tokens (persistent memory) for a platform that supports tokens, this file is generated by AppBuilder
to configure your token storage.
<DeviceName>.ewp, eww, .xip, .xiw, .mak
Generated project files for your application. AppBuilder only generates the project files that match the platform you have chosen. These
files may be loaded into your IDE and edited to build out the rest of your project.
5.1 Application Framework Files
In addition to device specific files, Application Framework files are also generated by AppBuilder into the <User Workspace>/<DeviceName> directory.
The number of files generated varies based on what plugins are supported and what is required for those plugins. The Zigbee application
framework files that are generated include but are not limited to the following:
af-structs.h: Definitions of structures used by the Zigbee application framework for the parsing of data sent over the air.
att-storage.h: Defines used in the attribute storage mechanism within the Zigbee application framework.
attribute-id.h: All attribute ids defined by the Zigbee Cluster Library specifications for all profiles loaded into the Zigbee application
framework.
attribute-size.h: Size in bytes for attribute types used in the Zigbee Cluster Library specification.
attribute-type.h: Defines to represent over the air values for data types used in the Zigbee Cluster Library specification.
call-command-handler.c: Command handling code for all non-general commands received over the air. This generated code marshals
cluster commands from their over the air format off to the callback interface. It also handles the commands if no callbacks are implemented
for them.
call-command-handler.h: Header file for the call-command-handler c code. This file provides definitions for all of the functions implemented in call-command-handler.c.
silabs.com | Building a more connected world. Rev. 0.2 | 8
UG391: Zigbee Application Framework Developer's Guide
Generated Application Configuration Files
callback-stub.c: Provides stubs for custom callbacks implemented by the Zigbee application framework. The callback stubs are only
compiled in if they are not separately defined by the customer’s application.
callback.h: Provides definitions for ALL callbacks that can possibly be implemented within the Zigbee application framework or the users
application. This defines the ENTIRE callback interface which is the main interface used by the Zigbee application framework when
communicating with the user application.
znet-cli.c: This file provides all the generated handlers for the Command Line Interface.
znet-cli.h: This file is used only by the documentation engine doxygen to document general application framework cli commands; it has
no other purpose.
client-command-macro.h: Macros that are provided as a convenience as part of the Zigbee application framework interface in the filling
of packet buffers that will be sent over the air. Each command supported by the Zigbee Cluster Library as configured in the user’s
Application Configuration is represented here with a macro that will make the appropriate calls into the Zigbee application framework to
fill a packet buffer to send that command over the air.
cluster-id.h: Defines provided for all cluster ids loaded into the Zigbee application framework from the Zigbee Cluster Library.
command-id.h: Defines provided for all command ids loaded into the Zigbee application framework from the Zigbee Cluster Library.
debug-printing-test.h: Defines used to turn on debug printing within the Zigbee application framework.
debug-printing.h: Macros used for debug printing within the Zigbee application framework.
enums.h: Provides definitions for all Zigbee Cluster Library related enums used in the Zigbee application framework.
print-cluster.h: Defines used to turn on printing on a per cluster basis within the Zigbee application framework.
stack-handler-stub.c: Stubs for all stack handlers which are available to be overridden within the Zigbee application framework.
silabs.com | Building a more connected world. Rev. 0.2 | 9
UG391: Zigbee Application Framework Developer's Guide
The Application Framework API
6 The Application Framework API
The Zigbee application framework’s API is provided in app/framework/include/af.h. This interface file is consistent with the way the EmberZNet PRO API is exposed by the stack. The Application Framework API Reference is provided with your installation as well as online
at https://docs.silabs.com/.
Many of the functions in the Zigbee application framework include a passed one-byte endpointId. This is particularly true for functions like
cluster initialization, cluster ticks, and attribute management. For instance, the function zclUtilReadAttribute is located in app/framework/util/attribute-table.c, and the signature of the function takes the endpointId as its first argument.
Some examples of the Zigbee application framework include:
boolean emberAfContainsCluster(int8u endpoint, EmberAfClusterId clusterId);
boolean emberAfContainsServer(int8u endpoint, EmberAfClusterId clusterId);
boolean emberAfContainsClient(int8u endpoint, EmberAfClusterId clusterId);
All of the Zigbee application framework APIs intended to be used by the customer application include the “emberAf” prefix.
APIs for getting information about endpoints and attributes are included in app/framework/util/attribute-storage.h. For instance, to determine if an endpoint contains a certain attribute, use the function emberAfContainsAttribute(int8u endpoint, ClusterId, AttributeId attributeId). It returns a Boolean indicating if the requested attribute and cluster are implemented on the specific endpoint.
Note: The read and write attribute needs an endpoint. If you do not include one, the compiler returns a warning that the function is
declared implicitly, but not a compiler error. Therefore, pay attention to warnings.
silabs.com | Building a more connected world. Rev. 0.2 | 10
UG391: Zigbee Application Framework Developer's Guide
Application Framework Callback Interface
7 Application Framework Callback Interface
The Zigbee application framework callbacks are intended to be used as a means to remove all customer code from the Zigbee application
framework. If any of your application code needs to be put into the Zigbee application framework, Silicon Labs views this as a bug with
the Zigbee application framework, because it means that a callback that would satisfy your application requirement is missing. In this
case, please open a ticket through the Contact Support link at https://www.silabs.com/support.
Generally, when a callback is called the Zigbee application framework is giving the application code a first crack at some incoming
message or requesting some piece of application data. Within the callback API, some callbacks return a Boolean value indicating that
the message has been handled and no further processing should be done. If you are doing something that conflicts with the Zigbee
application framework’s handling of a particular message, return TRUE to indicate that the message was complete. This ensures that the
Zigbee application framework does not interfere with your handling of the message.
7.1 Callback Generation
AppBuilder has the ability to generate a stub callback file for you. By default, AppBuilder chooses not to generate the callback stub file if
it finds that the file already exists in the generation directory. You must specifically tell the application to overwrite an existing file.
When you regenerate files in the future, AppBuilder protects your generated callbacks file from being overwritten by asking if you want to
overwrite it. By default, AppBuilder will not overwrite any previously created callbacks file. If you choose to overwrite the file, AppBuilder
backs up the previous version to the file <appname>_callbacks.bak.
Note: You can implement your callbacks wherever you want; they do not need to be implemented in the generated callbacks file.
However, if you implement them in a different location, clear them out of the generated callback file so that your linker won’t
complain about duplicate definitions for the callback functions.
7.2 Non-Cluster-Related Callbacks
The callback interface is divided up into sections within the AppBuilder GUI for ease of use. The first section, Non-Cluster-Related
Callbacks, is made up of callbacks that are described in the callbacks.xml document located at tool/appbuilder/callbacks.xml. These
callbacks have been manually inserted into the Zigbee application framework code in locations where customers have indicated that they
wish to receive information about the function of the Zigbee application framework.
All global commands fall into this category. The Zigbee application framework contains handling code for global commands. If any global
command callback returns TRUE, this indicates that the command has been handled by the application and no further command handling
should take place. If the callback returns FALSE, then the Zigbee application framework continues to process the command normally.
Example
The pre-command received callback (
boolean isInterpan
framework’s command handling code. The command is parsed into a useful struct
easy way to access relevant data about the command including its
relevant flags for the command. This callback also returns a Boolean value indicating if the command has been handled. If the callback
returns TRUE, then it is assumed that the command has been handled by the application and no further action is taken.
7.3 Cluster-Specific Command Handling Callbacks
The cluster-related callbacks are generated by the Zigbee application framework to allow receipt of a pre-parsed command coming over
the air. Generally, a one-to-one relationship exists between ZCL commands and the cluster-specific callbacks.
The cluster-specific command callbacks all return a Boolean value. This return value allows you to short-circuit command handling included in the application framework. If you implement a cluster-specific command callback and it returns a value of TRUE to the Zigbee
application framework, the framework assumes that the command has been handled outside the framework and that any required command or default response has been sent. If the cluster-specific command returns FALSE, the framework assumes that the application
code did not understand the command and sends a default response with a status of ‘unsupported cluster command’.
) is called after a ZCL command has been received but has not yet been processed by the Zigbee application
emberAfPreCommandReceivedCallback(EmberAfClusterCommand* cmd,
EmberAfClusterCommand, which provides an
EmberApsFrame, message type, source, buffer, length, and any
silabs.com | Building a more connected world. Rev. 0.2 | 11
UG391: Zigbee Application Framework Developer's Guide
Application Framework Callback Interface
7.3.1 Command Callback Context
All command-related callbacks are called from within the context of the emberIncomingMessageHandler. This means that Zigbee APIs
that are available to the application within that context are available within the command handling callbacks as well. These APIs are listed
in the stack API file located at stack/include/message.h. The stack APIs that are available in the command callbacks are listed in the
stack message header located at stack/include/message.h and include:
emberGetLastHopLqi()
emberGetLastHopRssi()
emberGetSender()
emberGetSenderEui64()
emberGetBindingIndex()
emberSendReply() (for incoming APS retried unicasts only)
emberSetReplyBinding()
emberNoteSendersBinding()
7.3.2 Array Handling in Command Callbacks
Any Zigbee message that contains an array of arguments is passed as an int8u* pointer to the beginning of the array. This is done even
when the framework knows that the arguments in the array may be of another type, such as an int16u or int32u, because of byte alignment
issues on the various processors on which the framework may run. Developers implementing the callback must parse the array and cast
its elements appropriately for their hardware.
7.3.3 Global Command Callbacks
Zigbee global commands are also covered in the Zigbee application framework callback interface. These callbacks can be used to receive
responses to global commands. For instance, if your device sends a global read attribute command to another device, it can process the
command response by implementing the emberAfReadAttributesResponseCallback.
7.4 Callback Flow
The following figure shows how a message received by the application framework’s implementation of emberIncomingMessageHandler
is processed and flows through the framework code and out to the application implemented callbacks.
silabs.com | Building a more connected world. Rev. 0.2 | 12
UG391: Zigbee Application Framework Developer's Guide
Application Framework Callback Interface
Figure 6-1. Incoming Message Flow
silabs.com | Building a more connected world. Rev. 0.2 | 13
UG391: Zigbee Application Framework Developer's Guide
Application Framework Callback Interface
Once the incoming message is determined to be an incoming global command, it is passed off to the global command handling for
processing, as shown in the following figure.
Figure 6-2. Global Command Handling
silabs.com | Building a more connected world. Rev. 0.2 | 14
UG391: Zigbee Application Framework Developer's Guide
Application Framework Callback Interface
Otherwise, if it is found to be a cluster specific command, it is passed off to the cluster-specific command processing, as shown in the
following figure.
Figure 6-3. Cluster-Specific Command Processing
silabs.com | Building a more connected world. Rev. 0.2 | 15
UG391: Zigbee Application Framework Developer's Guide
Time Handling
8 Time Handling
The Zigbee application framework provides a single API for accessing the current time on the system (int32u emberAfGetCur-
rentTime()
work/util/time-util.c.:
If the ZCL time cluster server is implemented on the system, then this function retrieves the time from the server through the function call
int32u emberAfTimeClusterServerGetCurrentTime()), in which case the time is read from the time cluster server’s
(
time attribute and returned. If the time cluster server is not implemented, then
rentTimeCallback
If your device needs to know the current time but does not implement the time cluster server plugin, it is responsible for maintaining its
own time somewhere on the system and returning that time through the
This is especially important for SE devices that do not implement the time cluster server, like an in-premise display (IPD). Essentially the
IPD is on its own when it comes to time management. It would be outside the specification (as currently interpreted) for a non-Energy
Service Portal to implement the time cluster server. Therefore, the IPD must maintain its own knowledge of time and provide it to the
framework when requested through the
If your application includes the time cluster server, the time cluster server code always tries to initialize and update the time server’s time
attribute through the
time cluster server increments the stored attribute once per second. Thus you can use the time cluster server to store and maintain real
time on the system without implementing the
another device on the system and written into the time server’s time attribute. For more information on how time is handled by the bundled
implementation of the time cluster server see app/framework/plugin/time-server/time-server.c.
), which is described in app/framework/util/time-util.h. This section describes how the function is implemented in app/frame-
emberAfGetCurrentTime calls emberAfGetCur-
.
emberAfGetCurrentTimeCallback when it is requested.
emberAfGetCurrentTimeCallback.
emberAfGetCurrentTimeCallback. If the emberAfGetCurrentTimeCallback returns 0, then the
emberAfGetCurrentTimeCallback, if the actual time value can be synced from
silabs.com | Building a more connected world. Rev. 0.2 | 16
Loading...