子设备配置文件接入

子设备配置文件接入 是一个简化海量子设备接入网关的配置文件功能，它依赖于涂鸦自研的 DP 引擎功能实现。

功能背景

物联网（IoT）网关是连接 IoT，感知网络与传统通信网络的中间纽带，同时实现不同类型感知网络之间的协议转换。这类网关既可以实现云端广域互联，也可以实现局域互联。例如 IoT 感知网络内的 Zigbee 或 Thread 等设备终端，需要通过网关来连接云端服务器或其它互联网进行通信。

常规的挑战是，在实现 IoT 设备与云端之间的数据通信的过程中，由于 IoT 设备的种类或型号的不同，其所需要的 IoT 网关的配置也不同。为了支持 IoT 设备可以与云端进行数据通信，需要开发 IoT 网关与 IoT 设备的类型相对应的程序，以完成 IoT 协议数据与云端协议数据之间的转换。并且 IoT 网关还需要频繁进行更新，才可以使得其支持 IoT 设备的拓展和使用。

为了能够兼容涂鸦庞大的设备生态，涂鸦提供了 子设备配置文件接入 功能。

功能优势

优势	使用 子设备配置文件接入 之前	使用 子设备配置文件接入 之后	特殊情况
三方设备接入更便捷	您在接入自有子设备到涂鸦生态时，需要进行网关开发。	您在接入自有子设备时，在云端为子设备创建自定义方案并为自己设备编辑 转换文件 ，再使用支持 子设备配置文件接入 功能的网关就能正常用涂鸦生态使用自己的子设备。	子设备配置文件接入功能只开放基础转换，若需要定制功能还是必须网关定制固件开发。
生态支持更完整	会出现涂鸦的某款网关 A 已经支持了新接入的子设备，但是某款网关 B 还是无法正常使用这款新接入子设备的情况。这是因为涂鸦生态的网关品类众多，历史子设备接入的过程中由于每款网关的迭代周期不同。	只要您发布了新接入子设备的配置文件，支持 子设备配置文件接入 功能且支持这款子设备配置文件版本的网关，都能正常管理这款子设备。	子设备配置文件接入 功能也存在版本概念，版本向下兼容且不会经常迭代。
设备迭代更快速	接入的子设备若需要更新固件，必须通过网关更新程序并 OTA 子设备的方式保证设备新功能可用。	使用 子设备配置文件接入 功能接入的子设备，只需要在云端更新 转换文件 配置并直接 OTA 子设备。	特殊情况更新网关代码。

什么是 DP 引擎？

DP（Data Point，设备功能）引擎是涂鸦开发应用于 IoT 网关或者其它控制器的工具。DP 引擎可以将涂鸦平台 DP 类型的数据与其它 IoT 协议格式的数据进行转换。

DP 引擎由 转换引擎 与 转换文件 两部分组成。转换引擎部分为代码实现，转换文件为 JSON 格式文件。

转换引擎功能

• 解析转换文件

  支持 子设备配置文件接入 的网关，本身内置了转换引擎的功能。转换文件 是某款子设备进入网关时从云端拉取，并将 JSON 格式的 转换文件 加载到网关内存中，提高执行效率。

• 匹配转换规则

  当需要转换数据时，根据 转换文件 中的转换关系匹配到对应数据。涂鸦把 IoT 协议数据分为 Header 和 Payload 两部分，转换规则中包含：

  • 局域网协议格式 Header
  • 云端协议格式 Header
  • Payload 转换函数

  数据上行时，为局域网协议转为云端协议。涂鸦用上行数据的 Header 与转换规则内的局域网协议格式 Header 比较匹配到转换规则，从而获取到对应的云端协议格式 Header。以 Zigbee 转换数据为例：

  • ZCL（Zigbee Cluster Library）数据上行时是以 Header 中的 epID、clusterID、subID 组成的字符串作为匹配键值，格式为 endpointId_clusterId_subId，涂鸦称之为 zclKey。

  • 在应用中，当收到 ZCL 数据后组成 zclKey，再与 转换文件 的节点中的 zclKey 匹配。若匹配成功，则使用这个转换节点进行数值转换。

    例如，在一个调光灯的转换关系中，亮度改变会上报 1_8_0 即 endpointId = 1，clusterId = 8，subId = 0。涂鸦根据 1_8_0 的上报 zclKey 与 转换文件 节点中的 zclKey 匹配，就能找到需要对应到的 DP 格式的 Header 为 3。

  数据下行时，为云端协议转为局域网协议。涂鸦用下行数据的 Header 与转换规则内的云端协议格式 Header 比较，匹配到转换规则从而获取到对应的局域网协议格式 Header。以 Zigbee 转换数据为例：

  • 下行控制数据 DP 数据转 ZCL 数据时，以 dpID 作为匹配键值，涂鸦称之为 dpKey。

  • 在应用中，当收到 DP 数据时，用 dpKey 与 转换文件 的节点中的 dpKey 匹配。若匹配成功，则使用这个转换节点进行数值转换。

    例如，在一个调光灯的转换关系中，调整亮度会下发一个 DP 数据{"3":1000}。此时 dpKey 为 3，涂鸦用 3 与 转换文件 节点中的 dpKey 匹配，就能找到需要对应到的 ZCL 格式的 Header 为1_8_1。

• 转换 Payload 数值

  上述 匹配转换规则 中，已经根据协议的 Header 找到对应的转换关系。但是不同协议的 Payload 可能需要进行数值的转换。

  例如，在一个调光灯的转换中，ZCL 格式的 Payload 的数值范围为 0-255，涂鸦平台的 DP 格式 Payload 为 0-1000。涂鸦需要进行一次精度转换，完成转换规则匹配后，可以找到本次转换使用的转换节点，涂鸦使用转换节点中的转换函数进行数值转换。

• 更新文件

  网关内存在 子设备配置文件接入 的方式加入的设备时，每次重启网关或者每 12 小时会向云端校验当前子设备的 转换文件 是否为最新的文件。当子设备通过 子设备配置文件接入 的方式加入网关后，若您需要更新产品形态增删功能时，可以重启网关或者等到 12 小时保证网关的 转换文件 为最新。

转换文件说明

更多详情，请参考 子设备配置文件格式说明。

Zigbee 转换文件

更多详情，请参考 Zigbee 配置指导

Matter 转换文件

更多详情，请参考 Matter 配置指导

开发指导

初始化

子设备配置文件接入功能使用需要调用以下接口进行初始化。

/**
* @brief    start DP engine.
*
* @param[in] cfg service configuration.
*                 {
*                     "storage_path": "./trans_file",            // DP trans file storage path
*                     "file_max_count": 100,                     // max DP trans file count
*                     "pidTable_max_count": 100,                 // max pid_table element count
*                     "enable_zigbee_trans": 1,                  // 0 or 1 If the value is 0, it is disabled
*                     "enable_matter_trans": 1,                  //If the value is 1, it is enabled
*                 }
*
* @return OPRT_OK on success. Others on error, please refer to tuya_error_code.h
*/
 OPERATE_RET dp_engine_init_inf(ty_cJSON *cfg);

参数说明

字段	描述
storage_path	转换文件 的存储目录，需要是可读的
file_max_count	支持的最大 转换文件 数量，建议值 100
pidTable_max_count	pid 映射表最大支持数量，建议值 100
enable_zigbee_trans	是否开启 Zigbee 转换文件 接入，填 1 表示开启，填 0 表示不开启
enable_matter_trans	是否开启 Matter 转换文件 接入，填 1 表示开启，填 0 表示不开启

使用示例

#include "dp_engine_inf.h"

int main(int argc, char **argv)
{
    // ...
    ty_cJSON *eng_cfg = ty_cJSON_CreateObject();
    if (zb_cfg == NULL) {
        return OPRT_CJSON_GET_ERR;
    }
    ty_cJSON_AddStringToObject(eng_cfg, "storage_path", "./trans_files");
    ty_cJSON_AddNumberToObject(eng_cfg, "file_max_count", 100);
    ty_cJSON_AddNumberToObject(eng_cfg, "pidTable_max_count", 100);
    ty_cJSON_AddNumberToObject(eng_cfg, "enable_zigbee_trans", 1);
    ty_cJSON_AddNumberToObject(eng_cfg, "enable_matter_trans", 0);

    // 初始化 子设备配置文件接入 业务
    TUYA_CALL_ERR_RETURN(dp_engine_init_inf(eng_cfg));

    // ...

    return 0;
}