Zigbee SDK 说明

涂鸦 Zigbee EFR32 SDK 适用于开发符合 Zigbee 3.0 标准的智能产品。该 SDK 基于 Silicon Labs SDK 进行了二次抽象，屏蔽了复杂的 Zigbee 技术细节，方便您快速入门。

涂鸦 Zigbee SDK 主要包含硬件接口、网络接口、工具接口三个部分，并提供若干品类的示例代码来展示各种接口的使用和 Zigbee 设备接入涂鸦体系的基本开发规范。

SDK 目录结构

下载 SDK 项目后，其目录结构如下所示：

├── app
│   ├── build-all.py
│   ├── light
│   ├── sensor
│   ├── smart_plug
│   └── switch
├── doc
│   ├── datasheet
│   ├── SPEC
│   ├── 对接标准
│   └── 开发手册
├── 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

其中，主目录的说明如下表所示：

目录	说明
app	应用工程的入口路径，里面含有各种品类的实例代码
doc	Zigbee 相关文档资料
include	SDK 的接口文件
lib	SDK 的库文件，分为 IAR 版本的库和 GCC 版本的库
sdk	tools 里面用到的一些工具和链接脚本
tools	编译使用到的相关工具和脚本

SDK 使用流程

需要自定义实现的函数接口

本小节介绍需要您自行实现的函数接口。

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);

实现说明

Zigbee SDK 根据系统流程图会调用该函数，您至少需要实现 Zigbee 设备的创建，组网参数的设定。

示例代码片段

void dev_power_on_init(void)
{
    join_config_t cfg;
    zg_dev_config_t zg_dev_config;
    
    /**
    注册Zigbee的基本型，包括endpoint，cluster，attributes等信息。
    */
    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);

实现说明

Zigbee SDK 根据系统流程图会调用该函数，您可以实现 Zigbee 属性操作，硬件初始化，软件定时处理等初始化。

示例代码片段

static void __uart_rx_callback(uint8_t *data, uint16_t len)
{
    //TODO: 串口接收处理
}

static void __dev_evt_callback(uint8_t evt)
{
    switch(evt) {
        case EVT_LOCK_CANCEL: {
            //TODO: 自定义事件处理
            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);

实现说明

Zigbee SDK 根据系统流程图会调用该函数，您可以实现 Zigbee 网络状态处理。

示例代码片段

void nwk_state_changed_callback(NET_EVT_T state)
{
    switch(state) {
        case NET_POWER_ON_LEAVE: {
            //TODO: 上电无网络状态
            break;
        }
        case NET_JOIN_START: {
            //TODO: 组网开始
            break;
        }
        case NET_JOIN_TIMEOUT: {
            //TODO: 组网失败
            break;
        }
        case NET_POWER_ON_ONLINE: {
            //TODO: 上电有网络状态
            break;
        }
        case NET_JOIN_OK: {
            //TODO: 组网成功
            break;
        }
        case NET_REJOIN_OK: {
            //TODO: 重连成功
            break;
        }
        case NET_LOST: {
            //TODO: 和父节点丢失
            break;
        }
        case NET_REMOTE_LEAVE: {
            //TODO: 远程离网通知
            break;
        }
        case NET_LOCAL_LEAVE: {
            //TODO: 本地离网通知
            break;
        }
        case NET_MF_TEST_LEAVE: {
            //TODO: 产测离网通知
            break;
        }
        default: {
            break;
        }
    }
}

示例与文档

SDK 包含了文档和示例，通过使用和属性示例代码是快速入门的最佳实践。建议您先使用示例代码直接编译，运行，组网后，再尝试修改代码来实现自定义的功能。

• 示例说明：

  示例目录	说明
  light	包含 Zigbee 灯的工程，包括灯的开关和亮度调节功能
  sensor	包含 Zigbee 门磁的工程，包含门磁开、关、电池电量上报功能
  smart_plug	包含 Zigbee 插座的工程，包含插座的开，关功能
  switch	包含 Zigbee 继电器开关工程，包含继电器开，关功能

• 文档说明 ：

  文档目录	说明
  datasheet	Zigbee 芯片数据手册
  SPEC	包含 Zigbee 联盟标准参考手册
  开发手册	开发用到的所有文档

API 参考

硬件相关

API	功能	限制
user_uart_init	单个串口配置，包含串口硬件参数和串口数据接收回调函数， 接收函数已经是接收队列处理后的函数，非中断环境	dev_system_on_init 和之后调用，不要在 dev_power_on_init 里面调用， 会被和串口产测冲突
gpio_raw_init	gpio 原始初始化	如果和串口 IO 复用，需要在 dev_system_on_init 和之后调用，没有复用时，无调用限制
gpio_int_register	gpio 中断初始化	如果和串口 IO 复用，需要在 dev_system_on_init 和之后调用，没有复用时，无调用限制

软件延时事件相关

API	功能	限制
dev_timer_stop	提前停止某个延时执行事件	dev_system_on_init 和之后调用，不要在 dev_power_on_init 里面调用， 太早调用会有异常，事件框架还未初始化。如果在中断里面调用， 至少要保证中断在 dev_system_on_init 之后产生
dev_timer_start_with_callback	启动某个延时执行事件并设置事件处理函数
dev_timer_start	启动某个延时执行事件，如果该事件曾经设置过事件处理函数后， 后面的调用不需要每次设置事件处理函数
dev_timer_get_valid_flag	判断某个事件是否有效（也就是事件还没有达到）
dev_timer_get_remaining_time	获取某个事件还剩下多少 ms 后执行

Zigbee 设备创建和基础配置相关

API	功能	限制
dev_register_zg_ep_infor	注册一个完整的 Zigbee 设备，包含描述 Zigbee 设备的 endpoint， cluster，attributes等	只能在 dev_power_on_init 里面调用
dev_register_zg_dev_config	配置 Zigbee 的设备角色，是路由还是 end device 和 join，rejoin 的参数	只能在 dev_power_on_init 里面调用
dev_zg_join_config	配置上电和远程删除的组网策略	只能在 dev_power_on_init 里面调用

组网操作相关

API	功能	限制
dev_zigbee_join_start	退网并组网	dev_system_on_init 和之后调用，里面会涉及到事件和网络状态的处理
dev_zigbee_join_stop	提前停止组网	dev_system_on_init 和之后调用，里面会涉及到事件和网络状态的处理

Zigbee 3.0 相关

API	功能	限制
zg_report_table_init	配置默认 report 表	只能在 dev_power_on_init 里面调用, 在 dev_register_zg_ep_infor 后调用
ext_plugin_identify_client_enable	Zigbee 3.0 使用，开启 identify client 服务	只能在 dev_power_on_init 里面调用, 在 dev_register_zg_ep_infor 后调用
ext_plugin_identify_server_enable	Zigbee 3.0 使用，开启 identify server 服务	只能在 dev_power_on_init 里面调用, 在 dev_register_zg_ep_infor 后调用
ext_plugin_green_power_client_enable	Zigbee 3.0 使用，开启 green power client 服务	只能在 dev_power_on_init 里面调用, 在 dev_register_zg_ep_infor 后调用
ext_plugin_reporting_enable	Zigbee 3.0 使用，开启 reporting 上报服务	只能在 dev_power_on_init 里面调用, 在 dev_register_zg_ep_infor 后调用
ext_plugin_register_cmd_handle	注册 cluster 的命令处理	只能在 dev_power_on_init 里面调用

电池采集相关

API	功能	限制
hal_battery_config	电池采集功能的配置	需要在 dev_system_on_init 和之后调用
hal_battery_set_battery_type	动态配置电池类型和设备是否经常唤醒， SDK 内部会根据这些参数做对应的采集策略	hal_battery_config 之后调用
hal_battery_report_policy_config	电池特殊策略配置	hal_battery_config 之后调用

Flash 操作相关

API	功能	限制
flash_block_raw_write	按照块来写 flash，一块是 250 字节	目前只有 big flash 版本的 lib 才能用该函数，目前只有门锁在用
flash_block_raw_read	按照块来读 flash，一块是 250 字节
flash_addr_raw_write	按照虚拟地址来写 flash
flash_addr_raw_read	按照虚拟地址来读 flash
user_flash_data_write	应用 flash 写，给 APP 开发留了 250 字节的底层 flash 区域	dev_system_on_init 和之后调用
user_flash_data_read	应用 flash 读，给 APP 开发留了 250 字节的底层 flash 区域

离网自恢复网络相关

API	功能	限制
nwk_disable_self_recovery_once	禁用一次自恢复功能	dev_system_on_init 和之后调用
nwk_enable_self_recovery_once	启用自恢复功能
nwk_self_recovery_manual	立即自恢复

查询信息相关

API	功能	限制
zigbee_get_net_info	获取设备组网参数信息	dev_system_on_init 和之后调用
zg_get_join_type	获取组网方式：集中式，分布式，未组网	dev_system_on_init 和之后调用
zg_get_join_gw_type	获取组网的网关：涂鸦网关，其他网关，非网关（未组网/分布式）	dev_system_on_init 和之后调用
zg_is_zll_net	查询是否是ZLL组网	dev_system_on_init 和之后调用， zll lib专用

常规配置相关

API	功能	限制
dev_heartbeat_set	心跳配置	dev_system_on_init 和之后调用
dev_change_power	配置发送功率	dev_system_on_init 和之后调用
disable_gw_change_power	禁用网关来改变发送功率	在 dev_power_on_init 里面调用

轮询相关

API	功能	限制
zg_poll_interval_change	改变 poll 间隔	在 dev_register_zg_dev_config 调用
zg_poll_start	调用会一直 poll
zg_poll_end	停止产生新的 poll，发送完剩余的 poll 后停止
zg_poll_clear	立即停止 poll ，

Endpoint 相关

API	功能	限制
dev_set_endpoint_alias	给某个 endpoint 附加一个别名 endpoint ，主要解决对接其他网关和 涂鸦网关对于 endpoint 处理的兼容性问题	在 dev_register_zg_ep_infor 后调用
dev_endpint_enable_disable	动态禁用和启用某个 endpoint，禁用某个 endpoint 后， 远程和本地无法访问该endpoint	dev_system_on_init 和之后调用，里面会涉及到事件的处理
dev_attr_recovery	暂时不要用，会把 PID 恢复成默认值，而不是产测的 PID 值	N/A

附录一：名词解释

名词	说明
Attribute	Attribute （属性）是一个反映物理数量或状态的数据值
Cluster	Cluster （群集）是包含一个或多个属性（attribute）的群集
Device ID	Zigbee 中为每一种设备定义的序号
弱电设备	是指使用电池供电的设备，在 Zigbee 协议中被称为 sleep end device 的设备
强电设备	是指使用市电或者从市电稳压后的电源供电的设备，在 Zigbee 协议中被称为 router 的设备
PID	product ID，在涂鸦 IoT 平台创建的每一个产品都会产生一个唯一的产品编号，关联了产品具体的功能点、APP 控制面板、出货信息等所有跟这个产品相关的信息

更多详情，请参考 名词解释。

文档版本

版本	编写/修订说明	修订日期
1.0.0	创建文档	2020-03-26