【Zigbee】 zigbee设备开发快速入门

[马小勤]

1. 环境安装

1.1 编译工具安装

1.1.1 Keil 下载和安装

前往 Keil 官网 下载 Keil uVision5（5.26.2）。(奉加微平台使用)

1.1.2 IAR 下载和安装

前往 IAR 官网 下载 IAR Embedded Workbench IDE（IAR for Arm）。
注意：必须使用 ARM 8.40.1 或更高版本正版 IAR，强烈建议使用 8.40.1 版本。（芯科平台使用）

1.2. python 下载和安装

前往 python 官网 下载 3.6--3.8 的版本进行默认安装。
注意：windows 下安装完 python 后在安装路径下默认是 python.exe，需要复制一份并重命名为 python3.exe。

1.3. Tuya Wind IDE 安装

前往 Vscode 官网 下载最新的版本，并进行安装。安装完成 Vscode 后在插件栏目搜索 Tuya Wind IDE 并进行安装，安装，安装完成后进行账号登录，如果没有账号，请前往 涂鸦 IoT 平台 进行账号注册。

[马小勤]

2. TuyaOS subdev-zg 开发包介绍

2.1. 框图

2.2. suddev-zg 开发包说明

TuyaOS Zigbee 子设备开发包适用于开发符合 Zigbee 3.0 标准的智能产品。该开发包在芯片原厂 SDK 基础上进行了二次抽象，屏蔽了复杂的 Zigbee 技术细节，融入了涂鸦特色功能，方便您快速入门。主要包含原厂 vendor sdk、涂鸦特色功能 libs 库、硬件接口、网络接口、 组件、工具等部分，并在 APP 下提供若干品类的示例代码，来展示各种接口的使用和 Zigbee 设备接入涂鸦体系的基本开发规范。

2.3. 目录结构

Code: Select all

.
├─ hardware
│  ├─ chip_manual
│  └─ module_manual
├─ pc
│  └─ tools
├─ TuyaOS
│  ├─apps
│  │  └─tuyaos_demo_zg_light2
│  ├─components
│  ├─docs
│  ├─include
│  │  ├─adapter
│  │  ├─base
│  │  └─components
│  ├─libs
│  ├─scripts
│  ├─tools
│  └─vendor
└─ tuya.json

目录名称	作用
hardware	包含硬件模组相关资料
pc	包含原厂 p c工具
apps	包含有 demo 代码，新建项目只需进行新建文件夹并在文件夹下添加相关代码即可
components	包含涂鸦开发的各类开源组件，用户添加组件需要新建目录即可，然后将组件代码放在此文件夹下
doc	包含相关说明文档
include	包含 TuyaOS 子设备开发包各类 API 接口文件
lib	包含 TuyaOS 子设备开发包依赖的库文件
scripts	包含相关脚本文件
tools	包含应用在构建和编译过程中所用到的相关工具和脚本
vendor	包含涂鸦优化过后的芯片原厂 SDK

[马小勤]

3. 开发框架与产品开发包获取

开发框架为涂鸦封装原厂SDK后给业务层框架代码；产品开发包为涂鸦产品demo，包含电工、传感、照明等各品类demo。

3.1 开发框架获取

在 Vscode 下登录 Tuya Wind IDE 账号，然后选择 新建开发框架 进行开发包选择。

根据芯片选择到合适的开发包后点击确认并开始拉取，拉取完成即可进行相关功能的开发。

3.2 产品开发包简介

开发者可以通过以下方式获取产品开发包，拉取产品开发包会直接插入至apps文件下

拉取的demo文件目录如下图所示

目录名称	作用
components	包含涂鸦开发的各类开源组件，如battery电池组件、led blink闪灯组件等
include	包含各种头文件，如配置文件xx_app_config.h
src	包含各种应用回调c文件

[马小勤]

4.编译与烧录

IDE集成了build功能，即开发者通过右击build或者clean即可编译与清理固件。

4.1. 编译注意事项

1.第一次编译的时候必须要使用IDE进行编译，脚本会自动构建编译环境

2.IDE 下的脚本会递归遍历 所有 文件夹，自动添加这些文件下所有的源文件和头文件到编译环境；
a. 在使用 IDE 编译的时请关闭 IAR 或者是 Keil 编译器，否则可能会导致文件占用的问题；
b. 在使用 IAR 或者 Keil 进行调试的时候，禁止手动添加头文件或者是源文件到工程项目中；

4.2.编译生成的固件分类

固件产物位于工程文件夹下的 **output 目录下，QIO** 是生产固件，UG 是全量升级固件 ，DIFF 是用于生成差分的固件。我们在生产时烧录的 QIO 固件即可

4.3.原厂工具烧录

芯科平台：打开 xxx\pc\tools\Simplicity_Commander 目录，找到 commander.exe，通过原厂工具进行快速烧录，烧录产物位于工程文件夹下的 output目录下，然后使用 commander.exe 烧录 QIO 固件即可；

泰林微平台:打开 xxx\pc\tools\TLSR8258 目录，找到 BDT.exe，通过原厂工具进行快速烧录，烧录产物位于工程文件夹下的 output目录下，然后使用 Telink BDT.exe 烧录 QIO 固件即可；

奉加微平台:打开 xxx\pc\tools 目录，PhyPlusKit为原厂合并烧录文件，附有烧录说明；phy62xx_ota_file_generate_v1.1.0为OTA生成工具，用于生成OTA文件。

注意：使用原厂烧录工具烧录的固件仅支持烧录后用于测试，所使用的的固件必须是通过涂鸦烧录工具进行授权烧录的，否则固件只能使用 7 天，7 天之后可能会出现死机等异常情况，涂鸦产测授权请参见《产测说明》文档。

[马小勤]

5. TuyaOS suddev-zg 开发包流程介绍

5.1. 上电初始化流程

上电流程中主要需要关注 tuya_init_first、tuya_init_second、tuya_init_third、tuya_init_last、tuya_main_loop 这几个函数，下面针对这几个函数进行相关介绍。

5.2. 初始化流程说明

tuya_init_first: 在上电后对时钟等必要外设进行初始化之后就会调用此 API，用户可以在此 API 中初始化自己的相关外设。

Code: Select all

#define USER_UART0    0

OPERATE_RET tuya_init_first(VOID_T)
{
    // initialize uart 
    TAL_UART_CFG_T uart_cfg = {
        .rx_buffer_size = 256,
        .open_mode = 0,
        {
            .baudrate = 115200,
            .parity = TUYA_UART_PARITY_TYPE_NONE,
            .databits = TUYA_UART_DATA_LEN_8BIT,
            .stopbits = TUYA_UART_STOP_LEN_1BIT,
            .flowctrl = TUYA_UART_FLOWCTRL_NONE,
        }
    };
    tal_uart_init(USER_UART0, &uart_cfg);

    // initialize gpio interrupt
    TAL_GPIO_IRQ_T irq_cfg = {
        .mode = TAL_GPIO_IRQ_RISE,
        .cb = __hal_pin_irq_handle,
        .arg = NULL,
    };
    tal_gpio_irq_init(TKL_GPIO_PB0, &irq_cfg);
    tal_gpio_irq_init(TKL_GPIO_PB1, &irq_cfg);
    irq_cfg.mode = TAL_GPIO_IRQ_FALL;
    tal_gpio_irq_init(TKL_GPIO_PA3, &irq_cfg);
    tal_gpio_irq_init(TKL_GPIO_PA4, &irq_cfg);

    return OPRT_OK;
}

tuya_init_second: 涂鸦子设备开发框架进行进行内部必要组件初始化完成后调用此 API，用户必须在此函数中注册和初始化 Zigbee 相关功能。

Code: Select all

TAL_ENDPOINT_T dev_endpoint_desc[] ={
    { 1, ZHA_PROFILE_ID, ZG_DEVICE_ID_ON_OFF_LIGHT, SERVER_CLUSTER_NUM, (TAL_CLUSTER_T *)&app_server_cluster_list[0], 0, NULL },
};
OPERATE_RET tuya_init_second(VOID_T)
{
    // app endpoint and cluster register 
    tal_zg_endpoint_register(dev_endpoint_desc, GET_ARRAY_LEN(dev_endpoint_desc));
    
    // node init
    TAL_ZG_NODE_CFG_T node_config = {
        .node_type = ZG_ROUTER,
        .tx_power = 10,
        .scan_interval = 0,
        .scan_duration = ZG_SCAN_DURATION_3,
    };
    tal_zg_node_config(&node_config);
    
    // join config
    TAL_ZG_JOIN_CFG_T join_config = {
        .auto_join_power_on_flag = FALSE,
        .auto_join_remote_leave_flag = 0,
        .join_timeout = 15000,
    };
    tal_zg_join_config(&join_config);
    
    // zll commissiong init if you need
    // tal_zll_target_touchlink_init();
    // tal_zll_target_rssi_threshold_set(-90);
    
    // set time synchronization interval and heartbeat interval  if you need
    // tal_time_sync_period_set(10*1000);
    // tal_heartbeat_period_set(15*1000);

    return OPRT_OK;
}

tuya_init_third: 在原厂 SDK 进行协议栈和相关资源初始化完成后会调用此接口，例如设置 Zigbee 的发射功率，必须要在此函数或者之后的流程中才可以使用，此接口在进入产测模式之前，用户可以在这里设置一些特殊功能，例如进入产测前闪灯等。

Code: Select all

OPERATE_RET tuya_init_third(VOID_T)
{
   // TODO:
    return OPRT_OK;
}

tuya_init_last: 只有不进入产测模式模式才会进入到此 API 中，同时此 API 也是进入 while(1) 前最后的回调函数。

Code: Select all

OPERATE_RET tuya_init_last(VOID_T)
{
    // TODO:
    return OPRT_OK;
}

tuya_main_loop: 此函数是放在 while(1) 主循环中的，用户可以在此 API 中添加更多需要 loop 的函数，但是强烈不建议在此 API 中进行阻塞或者是添加耗时较长的处理函数。

Code: Select all

OPERATE_RET tuya_main_loop(VOID_T)
{
    // TODO:
    return OPRT_OK;
}

[马小勤]

6. Zigbee开发包 关键函数说明

6.1. Zigbee 网络相关函数

Endpoint 注册函数:

Code: Select all

OPERATE_RET tal_zg_endpoint_register(TAL_ENDPOINT_T *ep_desc, UINT8_T sums);

此函数是 Zigbee Endpoint 注册函数，用户把需要的 Endpoint、Cluster、Attribute 通过此函数注册到协议栈内部。TuyaOS Zigbee 开发框架为了开发者更好的专注业务开发，屏蔽了用户无需关心的 Cluster，例如 Server 端 Basic cluster、Client 端 OTA cluster 和 Time cluster，都已经默认注册在了 Endpoint 1 上，用户在开发的时候无需再次注册，此函用户必须手动配置。
注意：此函数注册完成前禁止调用任何 Zigbee 相关 API。

节点配置函数:

Code: Select all

OPERATE_RET tal_zg_join_config(TAL_ZG_JOIN_CFG_T *config);

此函数是用来配置 Zigbee 节点的相关行为，例如节点类型、发射功率、扫描间隔以及 sleep enddevice rejoin 的相关行为，此函用户必须手动配置。

加网扫描配置函数:

Code: Select all

OPERATE_RET tal_zg_join_config(TAL_ZG_JOIN_CFG_T *config);

此函数是用来配置 Zigbee 入网参数，例如是否需要上电自动配网、被网关删除是否自动配网、配网扫描超时时间等，此函用户必须手动配置。

配网扫描函数:

Code: Select all

BOOL_T tal_zg_join_start(UINT_T timeout_ms);

此函数是用来开启 Zigbee 入网扫描的 ，调用后会先进行本地离网，然后动设置的超时时间内进行配网扫描，配网成功或者配网失败后会调用网关状态改变的回调函数，通知用户网络状态变化。如果没有配置关闭网关自恢复功能，在入网超时后会尝试进行网络自恢复，如果成功回到之前的网络，则会自动重启。

离网函数:

Code: Select all

VOID_T tal_zg_leave_start(VOID_T);

此函数是在网设备用来进行离网使用的，离网成功后会调用网关状态改变的回调函数，通知用户网络状态变化。如果没有配置关闭网关自恢复功能，断电重启后且没有设置上电自动配网的情况下，会尝试进行网络自恢复，如果成功回到之前的网络，则会自动重启。

离网函数:

Code: Select all

BOOL_T tal_zg_rejoin_start(TAL_REJOIN_TYPE_E type);

此函数用于 Zigbee End Device 设备类型重回网络使用，当rejoin 成功或者失败的时候会通过网络回调通知用户。

网络状态回调函数:

Code: Select all

VOID_T tal_zg_nwk_status_changed_callback(TAL_ZG_NWK_STATUS_E status);

此函数用于在 Zigbee 网络状态发送改变后通知用户，用户可以根据不同的网络状态进行相关操作，对于网络状态解释如下:

状态	调用时机	作用
TAL_ZG_NWK_POWER_ON_LEAVE	设备上电后没有加入任何网络	指示上电后的网络状态
TAL_ZG_NWK_POWER_ON_ONLINE	设备上电后处于在网状态	指示上电后的网络状态
TAL_ZG_NWK_JOIN_START	在调用配网扫描后用于通知用户配网扫描开启	指示开启配网扫描状态
TAL_ZG_NWK_JOIN_TIMEOUT	在开启配网的指定时间内没有成功入网	指示配网超时
TAL_ZG_NWK_JOIN_OK	在配网开启后成功加入 Zigbee 网络	指示开启配网后成功入网状态
TAL_ZG_NWK_LOST	低功耗设备由于某种原因与父节点失联	指示设备与他的父节点丢失的状态
TAL_ZG_NWK_REJOIN_OK	低功耗设备在丢失父节点后重新回到网络	指示重回网络后的状态
TAL_ZG_NWK_LOCAL_LEAVE	设备本地调用离网函数	指示设备离网是本地调用离网函数
TAL_ZG_NWK_REMOTE_LEAVE	设备接收到网关的离网请求，或者 3.0 Key 交互失败，本地主动离网	指示离网是由于网关请求或者是 Key 交互失败
TAL_ZG_NWK_MF_TEST_LEAVE	设备在进行网关产测后，本产测网关请求离网	指示产测结束导致的离网

恢复出厂设置回调函数:

Code: Select all

VOID_T tal_zg_reset_factory_default_callback(TAL_RESET_TYPE_T type)；

此函数是在收到网关请求恢复出厂设置时用来通知用户进行数据清除的，用户可以根据类型来进行不同业务的实现。

6.2. Zigbee 网络数据接收和发送

写属性前置回调函数:

Code: Select all

TAL_WRITE_RET_E tal_zg_pre_write_attribute_callback(UINT8_T ep_id, UINT16_T cluster_id, TAL_ATTR_REC_T *attr_rec);

此函数是在收到远程设备写属性命令后，但是在真正写本地属性前进行调用的，用户可以检查传入参数，并通过返回值来决定 SDK 内部是否需要将属性写入到本地。

写属性后置回调函数:

Code: Select all

TAL_WRITE_RET_E tal_zg_post_write_attribute_callback(UINT8_T ep_id, UINT16_T cluster_id, TAL_ATTR_REC_T *attr_rec);

此函数是在收到远程设备写属性命令后，但是在本地真正写完属性后进行调用的。

general cmd 命令接收回调函数:

Code: Select all

TAL_MSG_RET_E tal_zcl_general_msg_recv_callback(TAL_ZCL_MSG_T *msg);

此函数是在接收到 ZCL Frame Type 为 command acts across the entire profile 类型的数据时会将数据透传给用户，目前用户无特殊需求，不需要处理此函数所给的数据。

specific cmd 命令接收回调函数:

Code: Select all

TAL_MSG_RET_E tal_zcl_specific_msg_recv_callback(TAL_ZCL_MSG_T *msg);

此函数是在接收到 ZCL Frame Type 为 command is specific to a cluster 类型的数据时会将数据通过此函数透传给用户，用户需要根据结构体指针自行解析和处理 Zigbee 业务数据。

场景保存回调函数:

Code: Select all

VOID_T tal_zg_scene_save_callback(UINT8_T ep_id, UINT8_T scene_id, UINT16_T group_id, TAL_SCENE_DATA_T *data);

此函数是在接收到远程设备给当前设备 Add scene 或者 要求设备 Store scene 时进行回调通知，用户根据场景数据类型，决定是否需要存储当前设备的状态，如果是 TAL_SCENE_DATA_TYPE_YOURSELF 则用户需要把当前设备的状态进行保存便于在 recall 时进行状态还原，如果是 TKL_SCENE_DATA_TYPE_EXT_SERVER 则用户不需要存储场景数据，SDK 内部会把接收到的场景数据进行自动存储。

场景 recall 回调函数:

Code: Select all

VOID_T tal_zg_scene_recall_callback(UINT8_T ep_id, UINT8_T scene_id, UINT16_T group_id, UINT_T time100ms, TAL_SCENE_DATA_T *data);

此函数是在接收到远程设备 recall scene 时给到用户的回调通知函数，用户可以在此函数中获取到之前存储的场景据，并利用此数据进行设备状态的还原。

数据发送函数:

Code: Select all

VOID_T tal_zg_send_data(TAL_ZG_SEND_DATA_T *pdata, TAL_SEND_RESULT_CB callback, UINT_T timeout);

此函数用于发送 Zigbee 数据，底层会把业务数据进行缓存，然后按照顺序进行按需发送，用户可以通过设置回调状态，来确认数据发送是否成功，同时还可以设置远程设备恢复应答的最大超时时间，建议此时间是 200ms 的整数倍。

数据发送队列清除函数:

Code: Select all

VOID_T tal_zg_clear_send_data(TAL_ZG_CLEAR_TYPE_E type, VOID_T *args);

此函数用于清除缓存在 SDK 底层的业务数据，避免因为缓存导致发送了不正确的数据。

6.3. Zigbee 属性读写

写属性函数：

Code: Select all

OPERATE_RET tal_zg_write_attribute(UINT8_T endpoint,
                                UINT16_T cluster,
                                UINT16_T attr_id,
                                VOID_T* data,
                                ZG_ATTR_TYPE_E type);

此函数用于写入 Zigbee 对应的属性值，写入的属性必须是要注册过的，否则写入会失败，如果在注册时标注属性的掩码值为 ATTR_MASK_TOKEN_FAST 则会将在写属性时，同时将属性值存入 NV falsh 中。

读属性函数：

Code: Select all

OPERATE_RET tal_zg_read_attribute(UINT8_T endpoint,
                                UINT16_T cluster,
                                UINT16_T attr_id,
                                VOID_T *data,
                                UINT8_T length);

此函数用于读取 Zigbee 对应的属性值，读取的属性必须是要注册过的，否则读取会失败。

6.4. Zigbee 产测

禁止信标产测函数:

Code: Select all

VOID_T tal_mf_test_disable_beacon_test(VOID_T);

此函数用于禁止 beacon 产测模式。

产测串口配置函数:

Code: Select all

VOID_T tal_mf_test_get_uart_cfg(UINT_T *out_uart_id, TAL_UART_CFG_S *out_cfg);

此函数用于配置产测时使用的串口，但是 uart id 只能返回 MF_TEST_UART_ID，如果不调用次函数则使用默认产测接口进行串口产测。

预产测回调函数:

Code: Select all

VOID_T tal_mf_test_pre_start_callback(VOID_T *args);

此函数仅用户 double dongle 产测模式，在接收到进入预产测模式的广播后会调用此函数，用户可以用一些行为指示进入预产测模式，方便产测人员观察。

产测退出回调函数:

Code: Select all

VOID_T tal_mf_test_end_callback(UINT8_T *data);

此函数仅用户 double dongle 产测模式，产测结束后会调用此函数，并将产测结果通知用户，*data =1 产流程成功结束。

beacon 产测进入回调函数:

Code: Select all

VOID_T tal_beacon_mf_test_callback(VOID_T);

此函数仅用户 beacon 产测模式，在接收到 beacon 广播的进入 beacon 产测的数据帧时，会通过此函数通知用户，用户可以根据自己的需要进行相应的操作，来表明这个设备的功能是完整的。

产测数据处理回调函数:

Code: Select all

TUYA_MF_TEST_RET_T tal_mf_test_handle_callback(TUYA_MF_TEST_CMD_T cmd,
                                              UINT8_T*arg,
                                              UINT16_T arg_len);

此函数用于接收产测数据帧，在串口产测、网关产测、double dongle 产测模式下接收到的产测数据都将通过这个接口通知用户，用户解析数据帧后进行相应的产测行为。

产测结果通知:

Code: Select all

VOID_T tal_mf_test_result_notify(TUYA_MF_TEST_RET_T result);

此函数用于回复产测结果为 true 或者是 false 的产测项。

按键产测结果通知函数:

Code: Select all

VOID_T tal_mf_test_button_test_notify(UINT_T key_id);

此函数用于回复按键产测结果，key_id 是产测按键 id。

电平式传感产测结果通知函数:

Code: Select all

VOID_T tal_mf_test_bool_sensor_notify(UINT8_T sensor_type, UINT8_T index, BOOL_T result);

此函数用于回复高低电平传感器产测结果。

产测结果通用通知函数:

Code: Select all

VOID_T tal_mf_test_general_send(UINT8_T cmd, UINT8_T len, UINT8_T *data);

此函数用于回复按键的产测结果，需要用户自己组装产测命令回复数据。

6.5. OTA 回调

OTA 升级开始回调函数：

Code: Select all

VOID_T tal_zg_ota_start_callback(UINT_T image_size, VOID_T* argv);

此函数用于在 OTA 收到网关 OAT 数据后给到应用层的通知，用户可以在此函数中做一些特殊操作，例如可以把低功耗设备在 OTA 时数据的请求速率提高，来缩短 OTA 时间。

OTA 升级结束回调函数：

Code: Select all

VOID_T tal_zg_ota_end_callback(UINT8_T result);

此函数用于在 OTA 结束后给到应用层通知，并将结果告知应用层。

6.6. 其他 API 接口

其他 API 接口见 《API 接口说明文档》；

注意：在没有特殊需求的情况下，不建议调用 tkl 开头的函数，防止出现异常。

[547176052@qq.com]

怎么让子设备进入配网模式

[马小勤]

怎么让子设备进入配网模式

BOOL_T tal_zg_join_start(UINT_T timeout_ms); 在6.1的函数介绍中有。若设备为上电自配网，上电默认进入配网模式

[freelifewe]

我看SDK也有操作系统的相关tal接口,看给到的流程似乎类似裸机开发循环流程，请教下，目前TUYAOS3.9.0的泰凌平台的SDK，是否是支持实时操作系统的。

[huanghuan]

不支持