Skip to content

Telink Zigbee/BLE Concurrent SDK Guide

Overview

The Telink Zigbee-BLE Concurrent SDK is a dual-mode SDK developed based on the Telink Zigbee SDK and BLE SDK, enabling Zigbee and BLE to operate simultaneously.

This document introducts the features specific to the dual-mode SDK. For details on Zigbee and BLE features and interfaces, please refer to their respective detailed documentation.

Device Types

(1) Device types supported by Zigbee

  • Router: ZR

  • Coordinator：ZC

  • End Device: ZED

(2) Device types supported by BLE

  • BLE Slave device

  • BLE Master device

  • BLE controller (only TL321x and TL721x support)

Network Types

Network types supported by Zigbee:

  • Central Network: ZC forms the network, with ZED and ZR joining

  • Distributed Network: ZR forms the network, with ZED and ZR joining

Hardware Platforms

The Telink Zigbee-BLE Concurrent SDK supports multiple hardware platforms, such as TLSR8258, TLSR921x, TL321x, TL721x, and more.

BLE Supported Connections and Quantity

For TLSR8258 and TLSR921x, BLE operates on a single-connection platform. The role of Slave or Master must be selected via the app_cfg.h file, resulting in the compilation of different firmware:

##define    BLE_SLAVE_ROLE_ENABLE                       1
##define BLE_MASTER_ROLE_ENABLE                     0

For TL321x and TL721x, BLE operates on a multi-connection platform, supporting both Slave and Master roles within the same firmware. The number of supported connections can be configured in the app_cfg.h file.

##define ACL_CENTRAL_MAX_NUM                            0 
##define ACL_PERIPHR_MAX_NUM                            1

Flash Space Allocation

The current SDK defaults to a 1 MB flash configuration across all platforms. If using a 512 KB flash, ensure the firmware size is less than 208 KB.

512 KB Flash

Only supports ZED devices and does not support the software bootloader method.

512 KB Flash Space Allocation in Hardware Bootload Mode

1 MB Flash

Supports two bootloader methods: hardware bootloader and software bootloader.

1 MB Flash Space Allocation in Hardware Bootload Mode

1 MB Flash Space Allocation in Software Bootload Mode

SDK Architecture

Protocol Architecture

Zigbee-BLE Dual-Mode

Zigbee-BLE Dual-Mode Scheduling Mechanism

The Zigbee/BLE functionality is implemented using a time-division multiplexing (TDM) approach.

BLE communication uses a time-synchronized mechanism, while Zigbee operates in an asynchronous communication mode. Due to this characteristic, mode-switch scheduling is based on BLE's timing requirements. BLE tasks are given priority, and Zigbee mode is activated during BLE's idle periods. When BLE synchronization time is reached, the system quickly switches back to BLE mode.

Zigbee-BLE Dual-Mode Timing Diagram

For low-power operation, the Zigbee stack's state is registered with the BLE stack. The BLE stack determines whether to enter a low-power mode and which type of low-power mode to use, based on both Zigbee's and BLE's states. When BLE is idle, the Zigbee stack manages the device's low-power state.

For TLSR8258 and TLSR921x, the BLE stack supports only the suspend sleep mode. For TL321x and TL721x, both suspend and deepsleep retention modes are supported. When the BLE stack stops working, all platforms default to having the Zigbee stack enter the deepsleep retention sleep mode.

SDK Directory

The Telink Zigbee-BLE Dual-Mode SDK architecture is based on the Telink Zigbee SDK, as detailed in the document AN-19052900-E_Telink Zigbee SDK Developer Manual.pdf.

Building upon the Telink Zigbee SDK, a new "\stack" directory has been added to house the Zigbee and BLE protocol stack code: \stack\zigbee, \statck\ble

Zigbee-BLE Dual-Mode Code Directory

Application Layer Directory

We provide three application demos for the three Zigbee device types.

  • common: directory for shared application-layer code.

  • sampleGW：example for a Zigbee gateway and BLE application (Zigbee device type: Coordinator).

  • sampleLight：example for a Zigbee light and BLE application (Zigbee device type: Router).

  • sampleSwitch：example for a Zigbee switch and BLE application (Zigbee device type: ZED).

Unlike the Zigbee SDK, the main function entry for each example in the dual-mode SDK is located in the concurrent_main.c file under the respective example's directory.

Application Layer Directory

Common File Directory

Common File Directory

The following files are universal across all platforms:

  • zigbee_ble_switch.c: Handles the condition checks and switching between Zigbee and BLE modes.

  • comm_cfg.h: Manages code version and mode configurations.

  • factory_reset.c/h: Enables device reset via powering down.

  • module_test.c: A module testing file used exclusively for development testing and verification.

Files specific to the TL321x and TL721x BLE multi-connection platforms:

  • hci_transport: Initializes the HCI interface of the BLE controller and processes data transmission and reception.

  • device_manage.c/h: Manages BLE-connected devices.

  • tlkapi_debug.c/h: Prints debugging information.

App File Directory

The file contents across the three example directories are essentially the same. We use sampleGW as an example for explanation:

sampleGW Directory

  • app_ble2zigbee.c: Interface file for configuring the Zigbee network using BLE data.

  • app_cfg.h: Application configuration file.

  • app_ui.c/h: Interface file for button and LED control.

  • board_xxxx.h: Configuration files for different hardware platforms.

  • concurrent_main.c: Main entry point for the app, including platform initialization.

  • sampleGateway.c/h: Zigbee initialization and main application processing function files.

  • sampleGatewayEpCfg.c: File for endpoint and cluster registration supported by the GW application.

  • sampleGatewayMultiBLE.c: Multi-connection BLE configuration and initialization file (supported by TL321x and TL721x).

  • sampleGatewayMultiBLEController.c: Multi-connection BLE controller configuration and initialization file (supported by TL321x and TL721x).

  • sampleGwBLESlave_8258.c: BLE slave role configuration and initialization file for the TLSR8258 platform.

  • sampleGwBLESlave_b91.c: BLE slave role configuration and initialization file for the TLSR921x platform.

  • stack_cfg.h: Zigbee protocol stack configuration file.

  • version_cfg.h: Zigbee protocol stack version configuration file, mainly used for Zigbee OTA upgrade version checks.

  • zb_appCb.c: Zigbee protocol stack event callback function processing file.

  • zcl_sampleGatewayCb.c: File for Zigbee ZCL application data processing.

Application Configuration

This section introduces the configurations unique to the dual-mode SDK.

General configurations:

(1) ZBHCI_BLE

Configures whether BLE handles Zigbee HCI data, enabling the GW to control Zigbee nodes via BLE.

(2) TLKAPI_DEBUG_ENABLE

Configures whether to enable debug logging. By default, it uses GPIO analog serial port for logging. The macro DEBUG_INFO_TX_PIN can be used to set the GPIO pin for this purpose.

(3) APP_SECURITY_ENABLE

Applicable to the BLE single-connection examples on TLSR8258 and TLSR921x platforms. When enabled, BLE supports pairing and bonding during the connection process.

(4) APP_DIRECT_ADV_ENABLE

Applicable to the BLE single-connection examples on TLSR8258 and TLSR921x platforms. When enabled, and if APP_SECURITY_ENABLE is also enabled, the device will send directed advertisements to bonded devices when detected.

(5) PM_ENABLE and BLE_APP_PM_ENABLE

Configures whether the device supports entering low-power mode.

(6) BLE_ACTIVE_BY_UI

In the default configuration, BLE operates for a period, completes its configuration tasks, and then stops the BLE protocol stack, causing the device to enter deep-sleep retention mode. When BLE_ACTIVE_BY_UI is enabled, pressing a button will wake the device and reactivate BLE functionality.

Multi-Connection BLE example configurations:

(1) ACL_CENTRAL_MAX_NUM and ACL_PERIPHR_MAX_NUM

Configures the maximum number of supported slave and master connections. Both values can be set up to a maximum of 4.

(2) ACL_PERIPHR_SMP_ENABLE and ACL_CENTRAL_SMP_ENABLE

Configures whether pairing is supported for different roles.

(3) BLE_OTA_SERVER_ENABLE

Configures whether BLE supports its built-in OTA process. In the examples, OTA and BLE application data share the same service, so both cannot be supported simultaneously. To enable both, users can modify the code.

(4) PM_DEEPSLEEP_RETENTION_ENABLE

Configures whether the device supports entering deep-sleep retention mode.

Main Function Interface

Initialization Functions

(1) void drv_platform_init(void)

Initializes the platform, including memory, system clock, GPIO, random number generator, and RF module.

(2) void os_init()

Initializes buffers and queues designed within the Zigbee protocol stack. This function does not need to be called when the system wakes from retention sleep.

(3) void user_zb_init(bool isRetention)

Performs Zigbee-related initialization, including the protocol stack, ZCL, application layer ports, and user parameters.

(4) void ble_radio_init(void)

Initializes the BLE RF module. The default setting is BLE 1M mode.

(5) void user_ble_init();

Performs BLE-related initialization, including the protocol stack and user parameters.

Main Task Functions

(1) void concurrent_mode_main_loop(void)

Main function for Zigbee/BLE mode scheduling.

(2) void zb_task(void)

Function for processing Zigbee-related tasks.

(3) void blt_sdk_main_loop(void)

Function for processing BLE-related tasks.

Dual-Mode Switching Functions

(1) void restore_zigbee_rf_context(unsigned char *rxBuf)

Restarts the RF baseband, clears RF interrupts and interrupt buffers, and configures Zigbee RF parameters.

(2) void restore_ble_rf_context(void)

Restarts the RF baseband, clears RF interrupts and interrupt buffers, and configures BLE RF parameters.

(3) void switch_to_zb_context(void)

Switches from BLE mode to Zigbee mode, configuring the RF for Zigbee.

(4) void switch_to_ble_context(void)

Switches from Zigbee mode to BLE mode, configuring the RF for BLE.

(5) APP_BLE_STATE_IDLE()

Checks whether BLE is in an IDLE state. If in IDLE, there is no need to switch to BLE mode.

(6) u32 get_ble_event_state(void)

Get the current BLE RF state:

  • 1: BLE event processing is complete, and the system is in an inactive state.

  • 0: BLE is in an active state.

(7) bool zb_rfTxDoing(void)

Checks if Zigbee is in a transmission state. To ensure the integrity of the Zigbee stack's transmission state machine, switching to BLE mode is not allowed during transmission.

(8) int is_switch_to_ble(void)

Determines whether a switch to BLE mode is required based on the next BLE event time, with a 4 ms lead time.

(9) switch_to_ble

Used in the sampleSwitch example. When in Zigbee mode and Zigbee events are processed, this function switches directly to BLE mode without waiting for the next BLE event. In BLE mode, it enables the device to enter low-power mode.

(10) int is_switch_to_zigbee(void)

Determines whether switching to Zigbee mode is allowed based on the next BLE event time, with a 4 ms lead time.

(11) void ble_task_stop(void)

Disables BLE functionality. The application layer can disable BLE based on specific use cases.

(12) void ble_task_restart(void)

Re-enables BLE functionality. The application layer can restart BLE based on specific use cases.