Callbacks#

Connect-based applications include the Stack Common and Application Framework Common components, which not only provide the required initialization actions but also implement the stack handlers and dispatch them to every dependent component callback. While Silicon Labs provides all the source code for the Connect Application Framework (the stack and RAIL are provided as pre-compiled libraries), user-created code should live outside the framework and should interact with the framework through the Connect Application Framework API exposed by the framework utilities and callbacks.

GSDK v3 projects include a main.c file (Connect-based applications should leave this unaltered) that initializes the stack and runs its main loop. The stack will call emberAfInitCallback() (in app_init.c) at the end of its initialization and emberAfTickCallback() (in app_process.c) from the main loop. Using these functions for init and main loop actions empowers the Connect stack to prioritize operations critical to the timely execution of stack and radio tasks.

Stack callbacks are routed through and distributed by the Application Framework. This can be observed by noting the prefix on relevant API function names (ember being associated with the stack API and emberAf associated with the Application framework API). For example, when the receipt of an incoming message causes the stack to raise emberIncomingMessageHandler, the message is both passed to emberAfIncomingMessageCallback (for processing by the application) and emberAfIncomingMessage (to be consumed by components), as dictated below in app_framework_stack-cb.c (from gecko_sdk_3*/protocol/flex/app-framework-common/).

void emberIncomingMessageHandler(EmberIncomingMessage *message)
{
  emberAfIncomingMessage(message);
  emberAfIncomingMessageCallback(message);
}

When installing a component, note the callback(s) prototype code provided to the right of the component list in the Project Configurator. Use these reference examples to implement the necessary callbacks in a .c file, typically app_process.c for your installed components, as illustrated in the following example.

Implementing Callbacks to Support Installed Components#

As an example, when installing the Mailbox Client component in the Software Configurator, a number of changes are automatically generated within the project to support the new component. These include:

  • A configuration file (mailbox-client-config.h) is copied into the /config directory.

  • The /mailbox SDK directory is copied or linked into /gecko_sdk_3.0.0/protocol/flex.

  • Necessary include directories are added to the project settings.

  • Files under /autogen are modified where necessary to support the functionality introduced by the component.

Although they are weakly defined in the SDK (in this case, /gecko_sdk_3.0.0/protocol/flex/mailbox/mailbox-client/mailbox-client-cb.c), before you can make use of a newly-installed component the application often must implement the associated callbacks. To facilitate this task, prototypes are provided where necessary in the embedded documentation displayed in the Project Configurator:

v3x callback prototypev3x callback prototype

The figure shows three callbacks available to the application when Mailbox Client is installed:

  • emberAfPluginMailboxClientMessageSubmitCallback,

  • emberAfPluginMailboxClientMessageDeliveredCallback, and

  • emberAfPluginMailboxClientCheckInboxCallback.

To complete the installation of the Mailbox Client component, copy these prototypes into app_process.c and implement the callback code required by your application.