English
English
简体中文
Contact Us
Register
Log In
layoutIndex

Zigbee SDK Guide

Last Updated on : 2022-02-23 06:44:20download

Tuya Zigbee EFR32 SDK applies to the development of smart products that comply with the Zigbee 3.0 standard. The SDK is developed on the basis of Silicon Labs SDK, simplifying the complex Zigbee technical details. You can get started quickly.

Tuya Zigbee SDK provides three interfaces, hardware interface, network interface, and tool interface. It also includes many sample codes for several categories. These samples demonstrate how to use different interfaces and give the basic development specifications for Zigbee devices to connect to Tuya system.

SDK directory structure

After you download the SDK project, its directory structure is as follows:

├── app
│   ├── build-all.py
│   ├── light
│   ├── sensor
│   ├── smart_plug
│   └── switch
├── doc
│   ├── datasheet
│   ├── SPEC
│   ├── connection standard 
│   └── development guide 
├── include
│      ├── hal_adc.h
│      ├── hal_battery.h
│      ├── hal_flash.h
│      ├── hal_gpio.h
│      ├── hal_i2c.h
│      ├── hal_pwm.h
│      ├── hal_spi.h
│      ├── hal_systick_timer.h
│      ├── hal_timer.h
│      ├── hal_uart.h
│      ├── tuya_app_timer.h
│      ├── tuya_mcu_os.h
│      ├── tuya_mf_test.h
│      ├── tuya_oem_kit.h
│      ├── tuya_tools.h
│      ├── tuya_zigbee_modules.h
│      ├── tuya_zigbee_sdk.h
│      ├── tuya_zigbee_stack.h
│      ├── type_def.h
│      ├── zigbee_attr.h
│      ├── zigbee_cmd.h
│      ├── zigbee_dev_template.h
│      ├── zigbee_modules.h
│      └── zigbee_raw_cmd_api.h
├── lib
│   ├── gcc_lib
│   └── iar_lib
├── sdk
│   ├── platform
│   └── tool
└── tools
    ├── gcc-arm-none-eabi-9-2019-q4-major
    ├── gcc-arm-none-eabi-9-2019-q4-major.tar.bz2
    ├── gcc_boot
    └── iar_tools

The description of the main directory is shown in the following table:

Directory Description
app The entry path of the application project, including sample code of different categories
doc Zigbee related documentation
include SDK interface files
lib SDK library files are divided into IAR library and GCC library
sdk Tools and link scripts used in tools
tools Tools and scripts used for compilation

SDK usage procedure

Zigbee SDK Guide

User-implemented function interface

This section describes the function interfaces that are implemented by yourself.

dev_power_on_init()

/**
 * @note (MUST) This is the first function after the hardware starts.
 * The CPU and base clock are initialized before calling this function.
 * You need to implement the creation of Zigbee devices and 
 * determine the parameters of Zigbee device behavior.
 * Include device roles(router, end device), device networking(join), 
 * rejoin parameters, and more. Refer to the TUYA Zigbee SDK demo for details.
 * @param none
 * @return none
 */
void dev_power_on_init(void);

Implementation description

The Zigbee SDK will call this function according to the system flow chart. You need to create a Zigbee device and configure networking parameters.

Sample code snippet

void dev_power_on_init(void)
{
    join_config_t cfg;
    zg_dev_config_t zg_dev_config;
    /**
    Register the basic type of Zigbee, including endpoint, cluster, attributes, and other information.
    */
    dev_register_zg_ep_infor((dev_description_t *)g_dev_des, EP_SUMS);
    memset(&zg_dev_config, 0, sizeof(zg_dev_config_t));
    zg_dev_config.dev_type = ZG_ROUTER;
    dev_register_zg_dev_config(&zg_dev_config);
    memset(&cfg, 0, sizeof(cfg));
    cfg.auto_join_power_on_flag = TRUE;
    cfg.auto_join_remote_leave_flag = TRUE;
    cfg.join_timeout = ZIGBEE_JOIN_MAX_TIMEOUT;
    dev_zg_join_config(&cfg);
    //TODO: others task
    return;
}

dev_system_on_init()

/**
 * @note (MUST) This is the first function after system startup. 
 * Before calling this function, Zigbee stack and some basic 
 * components have been started. You can use all API except individual ones. 
 * API limits refer to the API limits description table
 * @param none
 * @return none
 */
void dev_system_on_init(void);

Implementation description

The Zigbee SDK calls this function according to the system flow chart. You can implement Zigbee attribute operation, hardware initialization, software timing processing, and other initializations.

Sample code snippet

static void __uart_rx_callback(uint8_t *data, uint16_t len)
{
    //TODO: Process data received in serial port
}
static void __dev_evt_callback(uint8_t evt)
{
    switch(evt) {
        case EVT_LOCK_CANCEL: {
            //TODO: Process custom events
            break;
        }
        default: {
            break;
        }
    }
}
void dev_system_on_init(void)
{
    user_uart_config_t *p_default_cfg = mf_test_uart_config();
    user_uart_config_t uart_cfg;
    memcpy(&uart_cfg, p_default_cfg, sizeof(user_uart_config_t));
    uart_cfg.func = __uart_rx_callback;
    user_uart_init(&uart_cfg);
    dev_timer_start_with_callback(EVT_LOCK_CANCEL, 1000, __dev_evt_callback);
    dev_change_power(11, 19);
    return;
}

nwk_state_changed_callback()

/**
 * @note (MUST) This function is invoked when the network state changes.
 * Handling network-related matters at this function is recommended.
 * @param[in] {state} Refer to NET_EVT_T for more detal.
 * @return none
 */
void nwk_state_changed_callback(NET_EVT_T state);

Implementation description

The Zigbee SDK will call this function according to the system flow chart. You can process the Zigbee network status.

Sample code snippet

void nwk_state_changed_callback(NET_EVT_T state) 
{ 
switch(state) { 
case NET_POWER_ON_LEAVE: { 
            //TODO: No network access when powered on 
            break;
} 
case NET_JOIN_START: { 
            //TODO: Networking starts 
            break;
} 
case NET_JOIN_TIMEOUT: { 
            //TODO: Networking fails 
break; 
} 
case NET_POWER_ON_ONLINE: { 
            //TODO: Have network access when powered on 
            break;
} 
case NET_JOIN_OK: { 
            //TODO: Networking succeeds 
break; 
} 
case NET_REJOIN_OK: { 
            //TODO: Reconnecting succeeds 
break; 
} 
case NET_LOST: { 
            //TODO: Lose connection to parent node 
            break;
} 
case NET_REMOTE_LEAVE: { 
            //TODO: Remote disconnection notification 
break; 
} 
case NET_LOCAL_LEAVE: { 
            //TODO: Local disconnection notification 
break; 
} 
case NET_MF_TEST_LEAVE: { 
            //TODO: Production test disconnection notification 
      break;
        }
        default: {
            break;
        }
    }
}

Sample code and documentation

The SDK includes documentation and sample code. The best practice for a quick start is to use the sample code of attribute. It is recommended that you use the sample code to directly compile, run, and connect to the network. Then you can try to modify the code to implement custom functions.

  • Sample description

    Sample directory Description
    light Zigbee light project includes light switch and brightness adjustment function
    sensor Zigbee contact sensor project includes contact sensor switch and battery level report
    smart_plug Zigbee socket project includes socket switch function
    switch Zigbee relay project includes relay switch function
  • Documentation description

    Documentation directory Description
    datasheet Zigbee chip datasheet
    SPEC Zigbee Alliance standard reference guide
    Development guide All documentation used in development

API reference

Hardware

API Functions Limits
user_uart_init Single serial port configuration includes serial port hardware parameters and callback function of receiving serial port data.
The receiving function is already a function after receiving queue processing, and is the non-interrupt environment.
Call it during or after dev_system_on_init. You must not call it during dev_power_on_init.
Otherwise, it will conflict with the serial port production test.
gpio_raw_init gpio original initialization If it is multiplexed with serial port I/O, it must be called during or after dev_system_on_init. There is no calling limit without multiplexing.
gpio_int_register gpio interrupt initialization

If it is multiplexed with serial port I/O, it must be called during or after dev_system_on_init. There is no calling limit without multiplexing.

Software delay event

API Functions Limits
dev_timer_stop Stop a delayed execution event early Call it during or after dev_system_on_init. You must not call it during dev_power_on_init.
Early calling may cause exception since the initialization of event architecture is not completed. If it is called during interrupts,
the interrupts must occur after dev_system_on_init.
dev_timer_start_with_callback Start a delayed execution event and set the event processing function
dev_timer_start Start a delayed execution event. If an event has been set with an event processing function,
this function will apply to the subsequent calling.
dev_timer_get_valid_flag Determine whether an event is valid, that is, the event has not occurred yet
dev_timer_get_remaining_time Obtain how many milliseconds left until an event is executed

Zigbee device creation and basic configuration

API Functions Limits
dev_register_zg_ep_infor Register a complete Zigbee device, including endpoint,
cluster, and attributes.
It can only be called during dev_power_on_init
dev_register_zg_dev_config Configure the device role (router or end device) and the parameter of join and rejoin. It can only be called during dev_power_on_init
dev_zg_join_config Configure networking policies for power-on and remote deletion It can only be called during dev_power_on_init

Networking operation

API Functions Limits
dev_zigbee_join_start Exit the network and enter networking Call it during or after dev_system_on_init, which involves the processing of event and network status
dev_zigbee_join_stop Stop networking early Call it during or after dev_system_on_init, which involves the processing of event and network status

Zigbee 3.0

API Functions Limits
zg_report_table_init Configure the default report table It can only be called during dev_power_on_init or after dev_register_zg_ep_infor.
ext_plugin_identify_client_enable Use Zigbee 3.0, and enable identify client service It can only be called during dev_power_on_init or after dev_register_zg_ep_infor.
ext_plugin_identify_server_enable Use Zigbee 3.0, and enable identify server service It can only be called during dev_power_on_init or after dev_register_zg_ep_infor.
ext_plugin_green_power_client_enable Use Zigbee 3.0, and enable green power client service It can only be called during dev_power_on_init or after dev_register_zg_ep_infor.
ext_plugin_reporting_enable Use Zigbee 3.0, and enable reporting service It can only be called during dev_power_on_init or after dev_register_zg_ep_infor.
ext_plugin_register_cmd_handle Register the command processing of cluster It can only be called during dev_power_on_init.

Battery collection

API Functions Limits
hal_battery_config Configuration of battery collection function Call it during or after dev_system_on_init
hal_battery_set_battery_type Dynamic configuration of the battery type and whether the device is frequently woken up.
SDK will adopt collection policies based on these parameters
Call it after hal_battery_config
hal_battery_report_policy_config Configuration of special battery policies Call it after hal_battery_config

Flash

API Functions Limits
flash_block_raw_write Write flash in blocks, and one block is 250 bytes Currently, only the library of big flash version can use this function, and only the door lock uses this function.
flash_block_raw_read Read flash in blocks, and one block is 250 bytes
flash_addr_raw_write Write flash according to the virtual address
flash_addr_raw_read Read flash according to the virtual address
user_flash_data_write Write application flash, leaving 250 bytes of underlying flash for app development Call it during or after dev_system_on_init
user_flash_data_read Read application flash, leaving 250 bytes of underlying flash for app development

Self-healing network when losing access

API Functions Limits
nwk_disable_self_recovery_once Disable the self-healing function once Call it during or after dev_system_on_init
nwk_enable_self_recovery_once Enable the self-healing function
nwk_self_recovery_manual Immediately restore

Information query

API Functions Limits
zigbee_get_net_info Obtain device networking parameter info Call it during or after dev_system_on_init
zg_get_join_type Obtain the networking mode: centralized, distributed, and non-networking Call it during or after dev_system_on_init
zg_get_join_gw_type Obtain the networking gateway: Tuya gateway, gateways of other brands, and non-gateway (non-networking/distributed) Call it during or after dev_system_on_init
zg_is_zll_net Check whether it is ZLL networking Call it during or after dev_system_on_init, dedicated to zll lib

General configuration

API Functions Limits
dev_heartbeat_set Heartbeat configuration Call it during or after dev_system_on_init
dev_change_power Configure transmission power Call it during or after dev_system_on_init
disable_gw_change_power Disable the gateway to change the transmit power It is called during dev_power_on_init

Polling

API Functions Limits
zg_poll_interval_change Change the polling interval It is called during dev_register_zg_dev_config
zg_poll_start Keep polling when this call is made
zg_poll_end Stop generating new polls, and the calling ends after sending the left polls
zg_poll_clear Stop polling immediately

Endpoint

API Functions Limits
dev_set_endpoint_alias Set an alias for an endpoint to solve compatibility problems with the endpoint processing when connecting to other gateways and
Tuya gateways
Call it after dev_register_zg_ep_infor
dev_endpint_enable_disable Dynamically disable and enable an endpoint. After an endpoint is disabled,
the endpoint cannot be accessed remotely and locally
Call it during or after dev_system_on_init, which involves the processing of event
dev_attr_recovery You cannot call this API for now, since it will restore the PID to the default value, instead of the PID value for production test
N/A

Appendix 1: Glossary

Noun Description
Attribute Attribute is a data value reflecting the physical quantity or status
Cluster Cluster contains one or more attributes
Device ID The serial number defined for each device in Zigbee
ELV (extra-low voltage) device Refers to a battery-powered device, which is called a sleep end device in the Zigbee protocol
Electrical device Refers to a device powered by mains electricity or stabilized voltage supply from mains electricity, which is called a router device in the Zigbee protocol
PID It represents product ID. Each product created in the Tuya IoT Console will generate a unique product identifier. This ID is associated with specific data points of the product, app control panel, shipping information, and other information related to the product

For more information, see Glossary.

Version history

Version Description Date
1.0.0 The first release. March 26, 2020