nRF5 SDK for Thread and Zigbee v4.1.0
Adding dynamic multiprotocol Zigbee support to BLE examples

Table of Contents

This information applies to the following SoCs: nRF52833 and nRF52840.

Applications demonstrating the Bluetooth peripheral functionality can be extended by adding Zigbee protocol support to them, to achieve dynamic multiprotocol functionality. See the sections on this page for the list of required changes.

For reference, see <InstallFolder>\examples\multiprotocol\ble_zigbee\ble_zigbee_dynamic_light_switch_nus, which is a modified version of the ble_app_uart example.

For more information on multiprotocol operation, refer to the Multiprotocol support with BLE/Bluetooth support section.

Restrictions

Zigbee hardware requirements must be met in transformed examples. Refer to the Zigbee memory layout and requirements page.

Modifying sdk_config.h

Modify the sdk_config.h file by implementing the following edits:

Libraries

The nRF5 SDK for Thread and Zigbee provides precompiled Zigbee libraries that must be added to the project.

For a Zigbee router or coordinator devicem, use the following set of libraries:

For the Zigbee end device, use the following set of libraries:

Additionally, add one of the following defines to the compiler options, to indicate the device type:

There is no need to add the additional define for Zigbee coordinator device.

Modifying GCC Makefile

Complete the following edits in the GCC Makefile:

For reference, see the makefile that already supports dynamic Zigbee/BLE: <InstallFolder>\examples\multiprotocol\ble_zigbee\ble_zigbee_dynamic_light_switch_nus\pca10056\s140\armgcc\Makefile.

Modifying IAR project

Complete the following edits in the IAR project:

After the folder path is added, depending on your project location, the following records are visible.

$PROJ_DIR$\..\..\..\..\..\..\..\..\external\zboss\zb_error
$PROJ_DIR$\..\..\..\..\..\..\..\..\external\zboss\osif
$PROJ_DIR$\..\..\..\..\..\..\..\..\external\zboss\include
$PROJ_DIR$\..\..\..\..\..\..\..\..\external\zboss\include\ha
$PROJ_DIR$\..\..\..\..\..\..\..\..\external\zboss\include\osif
$PROJ_DIR$\..\..\..\..\..\..\..\..\external\zboss\include\zcl
$PROJ_DIR$\..\..\..\..\..\..\..\..\external\zboss\include\zll

For reference, see the IAR project that already supports dynamic Zigbee/BLE: <InstallFolder>\examples\multiprotocol\ble_zigbee\ble_zigbee_dynamic_light_switch_nus\ble_zigbee_dynamic_light_switch_nus.eww

Modifying main.c

Complete the following steps in the main.c file:

  1. At the top of the main.c file, add all necessary includes, depending on the Zigbee use case.
    #include "zboss_api.h"
    #include "zb_error_handler.h"
  2. After the section which contains defines and static variables, add the following lines:
    /**< Scan only one, predefined channel to find the coordinator. */
    #define IEEE_CHANNEL_MASK (1l << ZIGBEE_CHANNEL)
    /**< Do not erase NVRAM to save the network parameters after device reboot or power-off. */
    #define ERASE_PERSISTENT_CONFIG ZB_FALSE
    static zb_ieee_addr_t m_ieee_addr;
  3. Define all clusters and endpoints that should be present on your Zigbee device:
    /**< Source endpoint used to control light bulb. */
    #define LIGHT_SWITCH_ENDPOINT 1
    static zb_uint8_t m_attr_zcl_version = ZB_ZCL_VERSION;
    static zb_uint8_t m_attr_power_source = ZB_ZCL_BASIC_POWER_SOURCE_UNKNOWN;
    static zb_uint16_t m_attr_identify_time = 0;
    /* Declare attribute list for Basic cluster. */
    ZB_ZCL_DECLARE_BASIC_ATTRIB_LIST(basic_attr_list, &m_attr_zcl_version, &m_attr_power_source);
    /* Declare attribute list for Identify cluster. */
    ZB_ZCL_DECLARE_IDENTIFY_ATTRIB_LIST(identify_attr_list, &m_attr_identify_time);
    /* Declare cluster list for Dimmer Switch device (Identify, Basic, Scenes, Groups, On Off, Level Control). */
    /* Only clusters Identify and Basic have attributes. */
    ZB_HA_DECLARE_DIMMER_SWITCH_CLUSTER_LIST(dimmer_switch_clusters,
    basic_attr_list,
    identify_attr_list);
    /* Declare endpoint for Dimmer Switch device. */
    ZB_HA_DECLARE_DIMMER_SWITCH_EP(dimmer_switch_ep,
    LIGHT_SWITCH_ENDPOINT,
    dimmer_switch_clusters);
    /* Declare application's device context (list of registered endpoints) for Dimmer Switch device. */
    ZB_HA_DECLARE_DIMMER_SWITCH_CTX(dimmer_switch_ctx, dimmer_switch_ep);
  4. Add the function for initializing the Zigbee protocol. Note that it depends on your use case.
    /***************************************************************************************************
    * @section Initialization of Zigbee.
    */
    /**@brief Function for initializing the Zigbee Stack
    */
    static void zigbee_init(void)
    {
    uint64_t factoryAddress;
    /* Read long address from FICR. */
    factoryAddress = (uint64_t)NRF_FICR->DEVICEID[0] << 32;
    factoryAddress |= NRF_FICR->DEVICEID[1];
    memcpy(m_ieee_addr, &factoryAddress, sizeof(factoryAddress));
    /* Set ZigBee stack logging level and traffic dump subsystem. */
    ZB_SET_TRACE_LEVEL(ZIGBEE_TRACE_LEVEL);
    ZB_SET_TRACE_MASK(ZIGBEE_TRACE_MASK);
    ZB_SET_TRAF_DUMP_OFF();
    /* Initialize ZigBee stack. */
    ZB_INIT("light_switch");
    /* Set up Zigbee protocol main parameters. */
    zb_set_long_address(&m_ieee_addr);
    zb_set_network_ed_role(IEEE_CHANNEL_MASK);
    zb_set_nvram_erase_at_start(ERASE_PERSISTENT_CONFIG);
    ZB_SET_ED_TIMEOUT(ED_AGING_TIMEOUT_64MIN);
    ZB_SET_KEEPALIVE_TIMEOUT(ZB_MILLISECONDS_TO_BEACON_INTERVAL(3000));
    zb_set_rx_on_when_idle(ZB_TRUE);
    /* Initialize application context structure. */
    UNUSED_RETURN_VALUE(ZB_MEMSET(&m_device_ctx, 0, sizeof(light_switch_ctx_t)));
    /* Register dimmer switch device context (endpoints). */
    ZB_AF_REGISTER_DEVICE_CTX(&dimmer_switch_ctx);
    /** Start Zigbee Stack. */
    zb_err_code = zboss_start();
    ZB_ERROR_CHECK(zb_err_code);
    }
    For reference on how to add the dimmable switch functionality (for example) see: <InstallFolder>\examples\multiprotocol\ble_zigbee\ble_zigbee_dynamic_light_switch_nus\main.c
  5. Add the function for handling Zigbee events:
    /**@brief ZigBee stack event handler.
    * @param[in] param Reference to ZigBee stack buffer used to pass arguments (signal).
    */
    void zboss_signal_handler(zb_uint8_t param)
    {
    zb_zdo_app_signal_hdr_t * p_sg_p = NULL;
    zb_zdo_app_signal_type_t sig = zb_get_app_signal(param, &p_sg_p);
    zb_ret_t status = ZB_GET_APP_SIGNAL_STATUS(param);
    switch(sig)
    {
    case ZB_BDB_SIGNAL_DEVICE_FIRST_START:
    case ZB_BDB_SIGNAL_DEVICE_REBOOT:
    if (status == RET_OK)
    {
    NRF_LOG_INFO("Joined network successfully");
    }
    else
    {
    NRF_LOG_ERROR("Failed to join network. Status: %d", status);
    }
    break;
    case ZB_ZDO_SIGNAL_PRODUCTION_CONFIG_READY:
    if (status != RET_OK)
    {
    NRF_LOG_WARNING("Production config is not present or invalid");
    }
    break;
    default:
    /* Unhandled signal. For more information see: zb_zdo_app_signal_type_e and zb_ret_e */
    NRF_LOG_INFO("Unhandled signal %d. Status: %d", sig, status);
    }
    if (param)
    {
    ZB_FREE_BUF_BY_REF(param);
    }
    }
  6. Call the zigbee_init function inside of the application main function.
    Note
    This function must be called after the SoftDevice has been initialized.
  7. Add the following snippet inside the main loop of your application:
    zboss_main_loop_iteration();

For more information about defining and implementing Zigbee device, see Programming principles.

Parameters of Timeslot API

Timeslot API has been tested with a set of default parameters on the nRF52840 Development Kit. These parameters are preset when the 802.15.4 radio driver is initialized.

However, in case your application needs to use a different set of parameters for the Timeslot API, the 802.15.4 radio driver exposes the nrf_raal_softdevice_config() function to change the default Timeslot API parameters.

One of the parameters is the crystal accuracy in PPM units, which by default is set to 25 PPM. The application may use the nrf_raal_softdevice_config() function to change the PPM value of the currently used crystal.

Instructions on how to select other parameters for specific applications will be available in future releases of the nRF5 SDK for Thread and Zigbee.

Documentation feedback | Developer Zone | Subscribe | Updated