Zigbee SDK Guide

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

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 Developer Platform 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