快速入门

本文介绍如何通过涂鸦在 Visual Studio Code 里的插件 Tuya Wind IDE，来获取涂鸦 Matter Over Thread 开发包，以及相关的 Tuya Wind IDE 操作步骤。另外，概述了开发包的使用及关键函数的说明。

环境安装

Python 下载和安装

前往 Python 官网 下载 3.6~3.8 的版本进行默认安装。

Tuya Wind IDE 安装

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

TuyaOS subdev-thread 开发包介绍

框图

subdev-thread 开发包说明

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

目录结构

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

目录描述

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

TuyaOS subdev-thread 开发包获取

1. 创建子设备开发包。在 Visual Studio Code 下登录 Tuya Wind IDE 账号，然后选择 Create New Framework 进行开发包选择。

   

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

   

TuyaOS subdev-thread 开发包初始化流程

VOID_T tal_dev_power_on_init(VOID_T)：上电后回调接口，在该函数中初始化设备的信息。

1. 使用 tal_device_info_config 初始化设备配置信息。
2. 使用 tal_device_network_config 初始化网络信息。
3. 使用 tal_matter_init_identify 初始化 Identify Cluster 需要使用的回调接口。
4. 使用 tal_matter_attribute_change_handler_register 注册属性改变回调接口，当属性状态改变时，会调用注册的回调函数。
5. 使用 tal_matter_event_notification_register 注册网络状态改变接口，当网络状态改变时，会调用注册的回调函数。
6. tal_matter_device_init 初始化设备包含的 Endpoint，Cluster，Attribute 以及 Attribute 默认值，您可以参考模板文件 zcl_attr_template.h 和 zcl_cluster_template.h 来实现自己的初始化。

VOID_T tal_dev_power_on_init(VOID_T)
{
    TUYA_LOG("register_device_info ");
    TUYA_LOG("firmware_version  = 0x%x ", FIRMWARE_VERSION);
    /***************config device basic infomation************/   //step 1
    DEVICE_INFO_T  device_info = {
        TUYA_PID,
        FIRMWARE_NAME,
        FIRMWARE_VERSION,
        FIRMWARE_OTA_ID
    };
    tal_device_info_config(&device_info);

    /***************config device network information*********/  // step 2
    NETWORK_CONFIG_T network_data;
    network_data.power_on_start_pairing = TRUE;//FALSE;
    network_data.node_type = ROUTER;//SLEEP_END_DEVICE;
    network_data.network_pairing_timeout =  3 * 60; //min value of 3 * 60 seconds: max value of 15 * 60 seconds
    tal_device_network_config(&network_data);
    /**************config device cluster infomation************/  //step 3
    tal_matter_init_identify(app_ep_info[0].endpoint,
                            MATTER_ZCL_IDENTIFY_TYPE_VISIBLE_LED,
                            identify_start_callback,
                            identify_stop_callback,
                            identify_effect_callback);  //init identity callback
    tal_matter_attribute_change_handler_register(attribute_change_callback); //register attribute change callback

    tal_matter_event_notification_register(network_change_callback); //register network state change callback

    tal_matter_device_init(&app_ep_info[0], get_array_len(app_ep_info)); //init device endpoint infomation
}

在 tal_dev_system_on_init 中可以初始化一些硬件相关接口，例如按键输入和 LED 灯输出。

VOID_T tal_dev_system_on_init(VOID_T)
{
    ty_key_init(0, 1, 0, 5000, key_event_callback);
    ty_key_init(1, 2, 0, 5000, key_event_callback);
    ty_led_init(0, 21, TUYA_GPIO_LEVEL_LOW, 1);
    ty_led_init(1, 20, TUYA_GPIO_LEVEL_LOW, 1);
}

Matter Over Thread 关键函数

Matter 信息配置相关函数

设备信息配置接口

VOID_T tal_device_info_config(DEVICE_INFO_T *device_info_p);

此函数是用来配置 Matter 节点的基础信息，例如涂鸦 PID（涂鸦开发者平台产生）、固件名称标识、固件版本和固件标识。

Endpoint 注册函数

OPERATE_RET tal_matter_device_init(MATTER_ENDPOINT_S endpoint_info[],
                                   UINT16_T endpoint_info_sums);

此函数是 Matter Endpoint 注册函数，您把需要的 Endpoint、Cluster、Attribute 通过此函数注册到协议栈内部。TuyaOS Matter 开发框架为了您更好地专注业务开发，将要使用的 Cluster 和 Attribute 写好属性模板，您可以选取其中的一部分对自己开发的应用初始化，或者参考模板实现自己设备需要的 Cluster 和 Attribute 来初始化，其中 Endpoint 0 协议栈底层已经做好初始化，您可以不用关心。

节点网络配置函数

VOID_T tal_device_network_config(NETWORK_CONFIG_T* network_data);

此函数是用来配置 Matter 节点的相关行为，例如节点类型、配网超时时间、上电是否开始配网的相关行为，此函数必须手动配置。

Matter 网络相关函数

开始配网函数

OPERATE_RET tal_matter_commission_start(UINT32_T timeout);

此函数是用来开启 Matter 配网，开启后设备开始蓝牙广播，等待配网。如果设备已经配网，调用后会先离网，然后重启。如果设备没有配网或者没有等待配网，调用后设备开始配网。参数 timeout 是配置的配网超时时间，单位是秒（s），设备也可以通过 tal_device_network_config 来配置配网超时时间。

停止配网函数

OPERATE_RET tal_matter_commission_stop(VOID_T);

此函数是用来停止 Matter 设备配网，如果设备正在等待配网中，可以通过该函数停止配网。

离网函数

OPERATE_RET tal_matter_reset_factory_new(VOID_T);

此函数是在网设备用来进行离网的。离网后设备会清除 Thread 网络信息和 Fabric 信息，并重启。

网络状态回调注册函数

OPERATE_RET tal_matter_event_notification_register(EVENT_FUNC_CB event_callback);

此函数用于注册 Matter 网络状态回调函数，需要在 tal_dev_power_on_init 函数中完成注册。注册后的网络回调函数，在 Matter 网络状态发生改变后通知您，您可以根据不同的网络状态进行相关操作。网络状态的解释如下：

状态	调用时机	作用
MATTER_EVT_POWER_ON	设备上电后进入	指示设备上电
MATTER_EVT_COMMISSION_START	设备开启配网后通知您开始配网	指示开启配网状态
MATTER_EVT_COMMISSION_OK	在配网开启后成功加入 Matter 网络	指示开启配网后成功入网状态
MATTER_EVT_COMMISSION_FAILED	在开启配网的指定时间内没有成功入网	指示配网超时
MATTER_EVT_RESET_FACTORY_NEW	在离网恢复出厂设置成功后	指示离网恢复出厂设置状态

获取 Matter 网络状态

MATTER_STATUS_E tal_matter_status_get(VOID_T);

此函数是获取设备当前的 Matter 网络状态。

状态	说明
MATTER_ST_POWER_ON_CONNECTED	指示设备上电已连接上 Matter 网络
MATTER_ST_POWER_ON_UNCONNECTED	指示设备上电后未连接 Matter 网络
MATTER_ST_CONNECTED	指示设备已连接 Matter 网络，上电连接成功后，配网成功后指示
MATTER_ST_UNCONNECTED	指示设备未连接网络，配网失败后指示

获取 Matter 当前产生网络事件

MATTER_EVT_E tal_matter_event_get(VOID_T);

此函数获取的网络事件和 tal_matter_event_notification_register 函数注册的回调函数的事件对应。

Matter 属性和命令相关接口

写属性函数

OPERATE_RET tal_matter_attribute_write(UINT16_T endpoint,
                                       UINT32_T cluster_id,
                                       UINT32_T attr_id,
                                       UINT8_T *attr_data,
                                       UINT8_T attr_type);

此函数用于写入 Matter 对应的属性值，写入的属性必须是注册过的，否则写入会失败。如果在注册时标注属性的掩码值为 TY_ATTRIBUTE_MASK_NONVOLATILE 或者 TY_ATTRIBUTE_MASK_TOKENIZE，则会将在写属性时，同时将属性值存入 NV flash 中。

读属性函数

OPERATE_RET tal_matter_attribute_read(UINT16_T endpoint,
                                      UINT32_T cluster_id,
                                      UINT32_T attr_id,
                                      UINT8_T *attr_data,
                                      UINT16_T data_len);

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

注册属性值改变回调函数

OPERATE_RET tal_matter_attribute_change_handler_register(ATTR_CHANGE_CB attr_change_callback);

此函数用于注册属性改变的回调函数。当属性值发生改变时（远程写属性，本地写属性，控制命令修改属性时），回调函数将被调用。

属性更新函数

OPERATE_RET tal_matter_attribute_config_update(UINT16_T endpoint,
                                               UINT32_T cluster_id,
                                               CONST MATTER_ATTR_S *attr);

此函数用于更新属性的初始化参数。

属性本地读写回调注册函数

OPERATE_RET tal_matter_ext_attribute_handler_register(EXT_ATTR_WRITE_CB ext_attr_write_cb,
                                                      EXT_ATTR_READ_CB ext_attr_read_cb);

此函数用于注册本地写属性、本地读属性操作回调接口，对应 tal_matter_attribute_write（本地写属性）和 tal_matter_attribute_read（本地读函数）。

注册 Identify Cluster 命令回调函数

OPERATE_RET tal_matter_init_identify(UINT16_T endpoint,
                                     MATTER_ZCL_IDENTIFY_E type,
                                     MATTER_INDENTIFY_CB start_cb,
                                     MATTER_INDENTIFY_CB stop_cb,
                                     MATTER_INDENTIFY_CB effect_cb);

此函数用于初始化 Identify Cluster 接收到指令的回调函数。需要初始化 start 回调、stop 回调 和 effect 回调。

命令接收回调函数

VOID_T tal_dev_cmd_recv_callback(UINT16_T endpoint, UINT32_T cluster, UINT32_T cmd_id, UINT8_T * cmd_buffer, UINT16_T cmd_len)

此函数用于设备接收到 Matter Cluster 命令的回调函数。

Matter 产测

禁止信标产测函数

VOID_T tal_mf_test_disable_beacon_test(VOID_T);

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

产测串口配置函数

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

此函数用于配置产测时使用的串口。如果不调用此函数，则 SDK 使用默认产测接口进行串口产测。

产测开始回调函数

VOID_T tal_mf_test_pre_start_callback(VOID_T *args);

此函数仅用于 Double Dongle 产测模式，进入 Double Dongle 产测流程时会调用此函数。您可以用一些行为指示进入产测模式，方便产测人员观察。

产测退出回调函数

VOID_T tal_mf_test_end_callback(UINT8_T *data);

此函数仅用于 Double Dongle 产测模式，产测结束后会调用此函数，并将产测结果通知您。*data 为 1，产测流程成功结束。

产测结果通知

VOID_T tal_mf_test_result_notify(TUYA_MF_TEST_RET_T result);

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

按键产测结果通知函数

VOID_T tal_mf_test_button_test_notify(UINT_T key_id);

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

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

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

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

模拟式传感产测结果通知函数

VOID_T tal_mf_test_analog_sensor_notify(CHAR_T* sensor_type, UINT8_T index, FLOAT_T* value,BOOL_T result);

此函数用于回复模拟式传感器产测结果。

产测结果通用通知函数

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

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

Matter 应用开发说明

新建应用工程

在 apps 目录下新建工程文件夹，并在工程文件夹下增加头文件和源文件即可，头文件和源文件需要存放在不同的文件夹，需要分别命名为 include 和 src。

修改 JSON 配置文件

{
    "firmwareInfo": {
        "description": "this is a matter demon project",
        "TUYA_PID":"ueoxczuav3sln***",
        "MODULE_TYPE":"TS24_U",
        "FIRMWARE_NAME": "app_thread_light",
        "FIRMWARE_VERSION": "65536",
        "SOFTWARE_VERSION": "1.0.6",
        "FIRMWARE_OTA_ID": "light",
        "VID": "0x125D",
        "PID": "0x002C"
    }
}

根据产品，修改 appconfig.json 中的相关内容。

名称	作用
description	工程描述。
TUYA_PID	涂鸦开发者平台生成的设备 PID，用于区分产品类型和 App 面板界面，具体请咨询相关产品经理。
MODULE_TYPE	工程使用模组的类型，可选 “TS24_U”、“TS24_2S”、“TS24_LC5”。
FIRMWARE_NAME	固件的名称，就是固件标识名。如果填写错误，会导致指纹校验产测项失败。
FIRMWARE_VERSION	固件版本号，十进制 65545 转换成十六进制 0X00010009，最高两字节表示高版本号，中间一字节表示中间版本号，最后一字节表示最低版本号。
SOFTWARE_VERSION	软件版本号字符串，和固件版本号同步。
FIRMWARE_OTA_ID	固件 OTA 识别 ID，OTA 升级会判断该字段。如果校验不通过，就不会升级。
VID	Matter Vendor ID，CSA 联盟分配给公司的 VendorID。
PID	Matter Product ID，根据公司产品进行设置，涂鸦产品的 PID 在涂鸦开发者平台获取。

{
    "_libs": {
        "lib_symblos":[
            "libs/libapploader.a",
            "libs/libbluetooth.a",
            "libs/librail_multiprotocol_efr32xg24_gcc_release.a",
            "libs/libnvm3_CM33_gcc.a",
            "libs/sl_rail_phy_overrides.o",
            "libs/libMatterRouterDebug.a"
        ]
    }
}

工程需要用到的库文件：

• libs/libMatterRouterDebug.a（Router 节点用）带日志库，可以编译带日志固件，方便调试使用。日志打印端口可以通过函数配置，波特率推荐使用 921600。
• libs/libMatterRouterRelease.a（Router 节点用）库编译的固件不带日志，方便生产使用。

Build & Clean

在 Visual Studio Code 下找到需要编译的工程文件夹，右击后找到相关选项进行 Build 和 Clean。

原厂工具烧录

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

固件分类说明

固件产物位于工程文件夹的 output 目录下，QIO 是生产固件，UG 是全量升级固件。涂鸦在生产时烧录 QIO 固件即可。

支持与帮助

在开发过程遇到问题，您可以登录 TuyaOS 开发者论坛 TuyaOS-Matter 开发 版块进行沟通咨询。