Overview

Application callbacks serve as the interface between your code and the Zigbee framework, enabling your application to respond to framework events and customize behavior. These callbacks allow you to build intelligent IoT products that react appropriately to network conditions, device commands, and system events.

Purpose and Types

Callbacks within the SDK fulfill diverse functions:

Notify your application about events in the Zigbee framework, such as when an identify command is received with a specific duration.
Allow your application to examine incoming data, modify values before framework processing completes, or even bypass standard framework handling altogether.

The Trident IoT plugin ecosystem includes extensive callback support, but implementation is entirely optional. You have complete flexibility to choose which callbacks best suit your product requirements.

Implementation

Adding callbacks to your project is straightforward - simply define the desired callback functions in your application source files. No complex registration process is required. See the examples below for more details.

Note: Application callbacks associated with Trident IoT plugins require the plugin to be added to the project first. See Plugin Configuration Guide for instructions on how to do that.

Callback Reference

For a complete reference of available callbacks, see:

Common Application Callbacks - callbacks that exist regardless of what plugins are enabled
Services Plugins Application Callbacks - callbacks associated with services plugins (Plugins - Services)
ZCL Plugins Application Callbacks - callbacks associated with ZCL plugins (Plugins - ZCL)

Example - Connection State

One of the Common Application Callbacks is the tr_connection_state_cb. This callback fires whenever the network state changes and is a very useful tool for controlling how a device searches for a network, providing user feedback, and adding any other device specific behavior that depends on the state of the network.

To implement this callback in your application, simply define the function in your application source code and handle the incoming tr_conn_state_e states according to your application. Below is an example of what this might look like to illustrate searching for a network to join.

void tr_connection_state_cb(tr_conn_state_e conn_state)
{
    switch (conn_state)
    {
        case TR_CONN_STATE_NO_NETWORK:
            // no network, found start searching for one 
            tr_led_blink(GPIO_LED_BLUE, 250, 250, 3);
            start_nwk_search(5);
            break;
 
        case TR_CONN_STATE_NWK_STEERING_ATTEMPT_FAILURE:
            // NWK steering attempt failed
            if (--g_search_attempts != 0)
            {
                tr_app_printf("NWK Search Fail! Attempts Remaining: %d\n", g_search_attempts);
                tr_led_blink(GPIO_LED_BLUE, 250, 250, 3);
                bdb_start_top_level_commissioning(ZB_BDB_NETWORK_STEERING);
            }
            else
            {
                // Ran out of search attempts, show failure LED status
                tr_led_blink(GPIO_LED_RED, 2000, 1, 1);
            }
            break;
 
        case TR_CONN_STATE_UNKNOWN:
        default:
            // unknown network state
            break;
    }
}

Example - ZCL Identify

Another example is using application callbacks for triggering application specific behavior when ZCL commands are received over the air. In this case, we will show how to utilize the tr_identify_server_identify_start_cb and tr_identify_server_identify_stop_cb to provide application specific LED feedback on the receipt of the respective identify commands.

Again, all that is needed to implement these callbacks to to enable the Identify Server and to define the callback functions in your application source code.

Note: The tr_identify_server_identify_stop_cb fires when the identify time expires so it is not necessary to set the identify feedback duration from the tr_identify_server_identify_start_cb.

void tr_identify_server_identify_start_cb(zb_uint8_t  endpoint,
                                          zb_uint16_t timeout_sec)
{
    tr_app_printf("Identifying for %d seconds on endpoint %d\n", timeout_sec, endpoint);
    gpio_pin_write(GPIO_LED_BLUE, LED_ON);
}
 
void tr_identify_server_identify_stop_cb(zb_uint8_t endpoint)
{
    gpio_pin_write(GPIO_LED_BLUE, LED_OFF);
}

Example - EUI64 Override

This example describes how you would modify the behavior of the device by passing back data and a return code from an application callback. Here, we will demonstrate how to use the tr_eui64_user_override_cb to set the EUI64 that the device will use at runtime. To implement this, just define the callback function in your application source code.

zb_bool_t tr_eui64_user_override_cb(zb_uint8_t *eui64)
{
    // pass the desired EUI64 value back using the *eui64 pointer
    zb_uint8_t eui64_override[8] = { 0x4F, 0x56, 0x45, 0x52, 0x52, 0x49, 0x44, 0x45 };
    ZB_MEMCPY(eui64, eui64_override, sizeof(eui64_override));
 
    // return ZB_TRUE to tell the framework to use this EUI64 value instead of the default
    return ZB_TRUE;
}

Table of Contents