Tuya.com
简体中文
English
注册
登录开发者平台
简体中文
English
注册
登录开发者平台
网关接入开发
search
根据文档目录筛选
网关接入开发子设备接入网关子设备配置文件接入子设备配置文件说明

子设备配置文件说明

更新时间：2024-07-19 03:09:56下载pdf

本文描述网关接入开发中，子设备配置文件 接入方式使用的配置文件的格式。该文件支持多种物联网协议格式与涂鸦的 DP（Data Point）协议格式转换，核心配置为一个 JSON 文件，通过设置 JSON 文件中的参数值实现子设备接入。

文件格式

子设备配置文件为 JSON 格式的文本：

{
    "VID": 1,
    "MPID": 2,
    "TPID": "xx",
    "FVer": "xx",
    "EVer": "xx",
    "MTDes": [{ "key": "value" }],
    "SList": [{ "key": "value" }],
    "proData": [{ "key": "value" }],
    "ClusterDP": [{ "key": "value" }]
}

主要包含下图中的内容：

子设备配置文件说明

限制条件

  • 所有子设备配置文件必须拥有一个 转换关系，否则无法使用。

  • 不同子设备配置文件的必须字段和可选字段如下表所示：

    文件类型 必选字段 可选字段
    Matter 转换文件 SList MTRT
    Zigbee 转换文件 无 proData、MTDes
    桥接转换文件 MTDes 无

一级参数配置

一级参数配置表示 JSON 格式的第一层参数的设置情况：

参数 说明 数据类型
VID 即厂商（Vendor）ID，表示转换表所属的设备厂商。CSA 联盟分配给厂商 ID。 数字（16 bit）
MPID 即 Matter 设备的产品 ID（PID）。PID 是厂商分配给自己产品型号的标识符，标识产品的类型，多种产品可以使用同一个 PID。 数字（16 bit）
TPID 即涂鸦（Tuya）分配的设备独有的 PID，标识同一款产品的 ID 信息。 字符串（16 bytes）
FVer 转换文件的版本，标识当前转换表的转换规则的版本。例如 1.0.1。 字符串（16 bytes）
EVer DP 引擎的版本。只能在方案中填入，不能从产品维度修改。 字符串（16 bytes）
ClusterDP 设备集群（Cluster）和 DP 转换的数组，包含该产品的所有的 DP 和 Matter、Zigbee 等指令之间的转化关系。更多详情，请参考下文 ClusterDP。 数组
MTDes 用于描述一个 Zigbee 设备桥接在 Matter 网络时，显示的设备信息。更多详情，请参考下文 MTDes。 数组
SList 子设备订阅表。Matter 协议类型子设备的配置文件使用该字段。控制端会根据表内的元素向子设备发送订阅指令。更多详情，请参考下文 SList。 数组
ProData 协议信息字符串。更多详情，请参考下文 ProData。 字符串（JSON）

二级参数配置：ClusterDP

ClusterDP 表示 Cluster 和 DP 转换的数组。包含该产品的所有的 DP 和 Matter 指令之间的转化关系。

配置示例

{
  "ClusterDP": [
    {
      "Direct": 1,
      "Cluster": [
        {
          "EPID": 1,
          "CID": 6,
          "SType": 2,
          "SID": 255,
          "Act": 1,
          "MFmt": "xxxx",
          "MType": 1,
          "MName": 1
        }
      ],
      "DP": [
        {
          "DPID": 1,
          "DPType": 0,
          "MType": 1,
          "MName": 1
        }
      ],
      "Exp": [
        {
          "EType": 1,
          "Data": "xxxx"
        }
      ]
    }
  ]
}

Dir

DP 的转换方向（上行或下行）。

例如开关的上行 DP 对应的 Matter 指令，是 Report OnOff 属性，下行 DP 是 OnOff 的控制命令。

dir 协议转换 转换关系上下行 描述
1 Thread 下行 DP 格式 > Matter 格式
2 Thread 上行 Matter 格式 > DP 格式
1 WoM（Wi-Fi over Matter） 下行 DP 格式 > Matter 格式
2 WoM（Wi-Fi over Matter） 上行 Matter 格式 > DP 格式
1 Zigbee 下行 DP 格式 > Zigbee 格式
2 Zigbee 上行 Zigbee 格式 > DP 格式
1 Zigbee 桥接 下行 Matter 格式 > DP 格式
2 Zigbee 桥接 上行 DP 格式 > Matter 格式

请注意，对于 Zigbee 桥接于 Matter 的转换文件，下行是 Matter 协议转 DP 协议。上行是 DP 协议转 Matter 协议。

Cluster

DP 对应的 Cluster 指令。

参数 说明
EPID 即设备的端点号（endpoint_id），2 个字节无符号数。例如，0x0001。
CID 即 Cluster 的标识 ID，4 字节无符号数，例如：0x00000006 （On/Off）;
SType 即 subtype：
  • 1：Command
  • 2：Attribute
  • 3：Event
SID 即 subtype_id，Cluster 子选项的 ID，四字节无符号数。
  • 如果 Sub_type 是 Attribute 时，SID 就是 Attribute ID。
  • 如果 Sub_type 是 Command 时，SID 就是 Command ID。
  • 如果 Sub_type 是 Event 时，SID 就是 Event Number。
说明：当 SType 为 Command 时，如果需要将 DP 的 value 作为 Command ID 发送时，SID 填 0xFF(255)。暂时只支持 commad 为一个字节的情况。例如，SID 可选的内容为 ON/OFF Cluster 中的command相关内容时，dp_payload 的值可选为 0 和 1(0 代表 OFF 命令，1 代表 ON 命令)，此时转换关系的 SID 填 255，转换时就会用 DP 的 payload 作为 command 下发。当 SID 为 0xFF 时，MFmt 填的内容固定为 {\"T\":4,\"L\":1,\"F\":1}。
Act 即 action 标识对应的 Sub_type 的操作方式，枚举类型。
  • 当 Sub_type 是 Attribute 时，属性可能是读（Read），写（Write），上报（Report），或者订阅（Subscribe）。
  • 当 Sub_type 是 Event 时，事件可能是订阅（Subscribe）或者上报（Report）。
  • 当 Sub_type 是 Command 时，命令可能是 Client to Server（C2S）或者 Server To Client（S2C）。
转换文件暂时不支持：
  • DP 和读的转换
  • DP 与订阅事件
STypeSIDAct
1(command)xx(command Id)1(c2s)
2(s2c)
2(Attribute)xx(Attribute Id)3(Read)
4(Write)
5(Report)
3(Event)xx(Enent Id)6(Subscribe)
7(Report)
MType 即 method_type，Matter 指令值和 DP 指令值的转换算法的类型：
  • 1：C 库函数
MName 即 method_name，处理这个转换的函数名。JSON 文件内使用枚举值表示，实际对照关系见 dp_engine 转换函数对应表。指是 DP 协议的 payload，转换到局域网协议的 payload，需要使用的转换函数。
MFmt 即 message_format，代表了这条 Matter 指令包的 Msg 参数的格式。Unsigned Integer 格式以 Bitmap 格式表示。
  • T：即 Type，表示字符的类型。
    • payload 类型为 bool 时，T 填 8 或者 9 都可以
    • payload 类型为 bitmap 时，T 填 4
    • payload 类型为 String 时，T 填 0x0c、L 填 0
    • payload 类型为 Raw 时，T 填 16、L 填 -1
  • L：即 Length，与上一个参数 T 对应，标识数据长度。
  • F：即 Flag，表示 dpValue 转成 Matter 数据时，存放的位置。
    • 有这个字段表示且为 1 时，表示 dpValue 转换后会作为这个参数存储。
    • 没有这个字段，表示 null，会以默认值填充。

由于 MFmt 参数的配置较为复杂，因此本小节后续详细讲解。

T 字段的可选值如下表：

数值 说明
-1 未指定
0x00 Int8
0x01 Int16
0x02 Int32
0x03 Int64
0x04 UInt8
0x05 UInt16
0x06 UInt32
0x07 UInt64
0x08 Boolean Flase
0x09 Boolean True
0x0a Floating Point Number 32
0x0b Floating Point Number 65
0x0c UTF8 String_1ByteLength
0x0d UTF8 String_2ByteLength
0x0e UTF8 String_4ByteLength
0x0f UTF8 String_8ByteLength
0x10 Byte String_1ByteLength
0x11 Byte String_2ByteLength
0x12 Byte String_4ByteLength
0x13 Byte String_8ByteLength
0x14 NULL

例如，下发光源亮度调节时：

  • payload 要求如下：

    描述 第一个参数 第二个参数 第三个参数 第四个参数
    字节数 1 2 0 或 1 0 或 1
    数据类型 uint8 uint16 map8 map8
    参数 Level Transition time OptionsMark OptionsOverride

  • JSON 示例如下：

    [
    {//level
        "T": 4,//uint8
        "L": 1, //1byte
        "F": 1//DP 转换完成的值，填充在这个位置
    },
    {//transition time
        "T": 5,// uint6
        "L": 2// 2byte
    },
    {//optionsMask
        "T": 4,// map8 == uint8
        "L": 1// 1byte
    },
    {//optionoverride
        "T": 4,// map8 == uint8
        "L": 1// 1byte
        }
    ]

    F 所在的位置，会被填充为 DP 的转换值，其它位置为默认填充值 0。

DP

涂鸦系统的 DP 指令数组。会有一个属性对应多个 DP 的情况。

参数 说明
DPID DP 的 ID 标识。2 个字节。
DPType DP 的数据类型
  • bool：0
  • Value：1
  • String：2
  • enum：3
  • bitmap：4
  • raw：5
MType 即 method_type，Matter 指令值和 DP 指令值的转换算法的类型：
  • 1：C 库函数
MName 即 method_name，处理这个转换的函数名，JSON 文件内使用枚举值表示，实际对照关系见 dp_engine 转换函数对应表。这里指局域网协议的 payload，转换到 DP 协议的 payload 需要使用的转换函数。

Exp

表示拓展字段（expand）。该字段可以不存在，使用拓展字段时前面的 MName 都填 0。

  • EType：expand_typde

    EType 描述
    1 EnumMap 枚举对照表
    2 BitMap 位表
    3 defaultValue 表
    4 数学公式转换 例子：*(num/360.0)254 + 0.5 现在只支持单目运算符

  • Data：JSON 格式字符串

    • 当 EType 为 1 时，格式为："{"map":[{"dpV":0,"mtV":2},{"dpV":1,"mtV":0}]}"。mtV 为 -1 表示下发的值为 NULL。
    • 当 EType 为 2 时，格式："{"byte":1,"bit":1}" 表示取第一个字节的第一位作为 DP 的值，对用与传感器 iasZone 设备的上报解析。
    • 当 EType 为 3 时，格式："{\"dp\":[{\"i\":1,\"t\":1,\"v\":2}]}" 表示转换成默认值上报，不用解析 payload，直接使用指定的 DP 内容上报，i表示 dpId，t表示 dpType,"v"表示 dpValue。
    • 当 EType 4 时，格式："{\"1\":\"num+1\",\"2\":\"num-1\"}" 表示数据转换时使用指定的函数公式进行数值转换，jsonKey 为"1"的 jsonValue 的内容为 DP 转局域网协议时使用的函数。jsonKey 为"2"的 jsonValue 的内容为 DP 转局域网协议时使用的函数。未知数的名字必须为"num"。

二级参数配置：MTDes

MTDes 用于描述一个非 Matter 设备桥接在 Matter 网络时，显示的设备信息。

配置示例

{
  "MTDes": {
    "Basic": "[{\"57\":\"{\\\"1\\\":\\\"tuya\\\"}\"},{\"47\":\"{\\\"2\\\":\\\"Bat\\\"}\"},{\\\"ManuN\\\":\\\"aaa\\\"},{\\\"ModelID\\\":\\\"aaa\\\"}]",
    "EPs": [
      {
        "EPID": 1,
        "MTDevID": 2,
        "CIDs": [
          {
            "CType": 1,
            "CID": 6,
            "FMap": 1,
            "AIDs": [
              {
                "AID": 0
              }
            ],
            "ICmds": [
              {
                "CmdID": 0,
                "MFmt": "[{\"L\":0,\"T\":20}]"
              }
            ],
            "OCmds": [
              {
                "CmdID": 0,
                "MFmt": "[{\"L\":0,\"T\":20}]"
              }
            ]
          }
        ]
      },
      {
        "EPID": 2,
        "MTDevID": 2,
        "CIDs": [
          {
            "CType": 1,
            "CID": 8,
            "FMap": 1,
            "AIDs": [
              {
                "AID": 0,
                "AID": 1
              }
            ],
            "ICmds": [
              {
                "CmdID": 0,
                "CmdID": 1
              }
            ],
            "OCmds": [
              {
                "CmdID": 0,
                "MFmt": "[{\"L\":0,\"T\":20}]"
              }
            ]
          },
          {
            "CType": 1,
            "CID": 768,
            "FMap": 1,
            "AIDs": [
              {
                "AID": 0,
                "AID": 1
              }
            ],
            "ICmds": [
              {
                "CmdID": 0,
                "MFmt": "[{\"L\":0,\"T\":20}]"
              }
            ],
            "OCmds": [
              {
                "CmdID": 0,
                "MFmt": "[{\"L\":0,\"T\":20}]"
              }
            ]
          }
        ]
      }
    ]
  }
}

Basic

Basic 的内容为属性默认值，用来向 Matter 描述产品的基本属性，内容与 Matter 规范文档中的相关 Cluster 描述章节保持一致。该字段为 JSON 字符串形式，如下所示：

[
    {
        "clusterid1_dec_str":[
          {"attributeid1_dec_str":"attribute_value"},
           {"attributeid2_dec_str":"attribute_value"}
        ]
    },
    {
        "clusterid2_dec_str":[
          {"attributeid1_dec_str":"attribute_value"},
           { "attributeid2_dec_str":"attribute_value"}
        ]
    }
]

Basic 字段示例：

[
    {
        "57":[ //clusterid=57 为 basic informaton cluster
            {
                "1":"tuya"//attributeid=1 表示 VendorName 为 tuya
            },
            {
                "2":4821 //attributeid=4821(0x125D)表示 VendorId 为 tuya
            },
            {
                "3":"KA Extended Color Light"
            },
            {
                "4":49
            },
            {
                "7":100
            },
            {
                "8":"1.0"
            },
            {
                "9":100
            },
            {
                "10":"1.0"
            },
            {
                "11":"20221103"
            }
        ]
    },
    {
        "47":[
            {
                "17":true
            }
        ]
    }
]

EPs

EPs 为额外说明，其子参数如下：

  • CType：Cluster 的类型，取值范围：
    数值 说明
    0x01 CLUSTER_MASK_INIT_FUNCTION
    0x02 CLUSTER_MASK_ATTRIBUTE_CHANGED_FUNCTION
    0x04 CLUSTER_MASK_DEFAULT_RESPONSE_FUNCTION
    0x08 CLUSTER_MASK_MESSAGE_SENT_FUNCTION
    0x10 CLUSTER_MASK_MANUFACTURER_SPECIFIC_ATTRIBUTE_CHANGED_FUNCTION
    0x20 CLUSTER_MASK_PRE_ATTRIBUTE_CHANGED_FUNCTION
    0x40 CLUSTER_MASK_SERVER
    0x80 CLUSTER_MASK_CLIENT
  • CID：Cluster ID。
  • FMap：功能地图（feature map），值对应了这个 Cluster 内支持的属性（attribute）和命令（command）。
  • ICmds：代表 in Cluster。必须填入每个命令的 payload 格式。
  • OCmds：代表 out Cluster。必须填入每个命令的 payload 格式。

二级参数配置：SList

SList 为子设备订阅表，适用于 Matter 协议类型子设备。控制端会根据表内的元素，向子设备发送订阅指令。

{
"SList": [
        {
            "Cnt": 1,
            "Min": 0,
            "Max": 360,
            "SType": 2,
            "Member": [
                {
                    "EPID": 1,
                    "CID": 6,
                    "SID": 0
                }
            ]
        },
        {
            "Cnt": 1,
            "Min": 0,
            "Max": 360,
            "SType": 2,
            "Member": [
                {
                    "EPID": 1,
                    "CID": 8,
                    "SID": 0
                }
            ]
        },
        {
            "Cnt": 2,
            "Min": 0,
            "Max": 360,
            "SType": 2,
            "Member": [
                {
                    "EPID": 1,
                    "CID": 768,
                    "SID": 3
                },
                {
                    "EPID": 1,
                    "CID": 768,
                    "SID": 4
                }
            ]
        },
        {
            "Cnt": 1,
            "Min": 0,
            "Max": 360,
            "SType": 2,
            "Member": [
                {
                    "EPID": 1,
                    "CID": 768,
                    "SID": 7
                }
            ]
        },
        {
            "Cnt": 1,
            "Min": 0,
            "Max": 360,
            "SType": 2,
            "Member": [
                {
                    "EPID": 1,
                    "CID": 768,
                    "SID": 8
                }
            ]
        }
    ],
}

二级参数配置：ProData

ProData 为协议信息字符串。该字段的内容适用于 Zigbee 转换文件。控制端在 Zigbee 子设备入网并向涂鸦绑定成功后，会按照 RTbale、WTable、CTable 中的内容，给入网的子设备下发标准 Zigbee 指令。

  {
    "RTable": [{
        "EPID": 1,
        "CID": 6,
        "AIDs": [0, 1],
        "Num": 2
    }],
    "WTable": [{
        "EPID": 1,
        "CID": 6,
        "AID": 0,
        "AType": 1,
        "Val": "hex_string"
    }],
    "CTable": [{
        "EPID": 1,
        "CID": 6,
        "AID": 0,
        "Min": 0,
        "Max": 12,
        "Type": 0,
        "Val": "hex_string"
    }],
    "EPs": [{
        "EPID": 1,
        "GIndx": 0,
        "DPIDs    ": [{
            "ID": 1
        }]
    }]}

完整配置示例

Zigbee 桥接开关设备

以下为一个 Zigbee 桥接开关的子设备配置文件示例：

{
    "VID":4701,
    "MPID":1,
    "TPID":"n8zvuh****",
    "FVer":"1.0.1",
    "EVer":"0.0.4",
    "MTDes":{
        "Basic":"[{"57":[{"1":"tuya"},{"2":4821},{"3":"1 Gang Switch"},{"4":49},{"7":100},{"8":"1.0"},{"9":100},{"10":"1.0"},{"11":"20230301"}]},{"47":[{"17":true}]},{"6":[{"65533":4}]},{"8":[{"65533":5}]},{"768":[{"65533":5}]}]",
        "EPs":[
            {
                "EPID":1,
                "CIDs":[
                    {
                        "CType":64,
                        "FMap":0,
                        "ICmds":[
                            {
                                "MFmt":"[{"L":0,"T":20}]",
                                "CmdID":0
                            },
                            {
                                "MFmt":"[{"L":0,"T":20}]",
                                "CmdID":1
                            },
                            {
                                "MFmt":"[{"L":0,"T":20}]",
                                "CmdID":2
                            }
                        ],
                        "AIDs":[
                            {
                                "AID":0
                            }
                        ],
                        "CID":6
                    }
                ],
                "MTDevID":259
            }
        ]
    },
    "ClusterDP":[
        {
            "Cluster":{
                "MType":1,
                "Act":1,
                "SType":1,
                "MFmt":"[{"L":1,"F":1,"T":4}]",
                "EPID":1,
                "MName":1,
                "CID":6,
                "SID":255
            },
            "DP":{
                "MType":1,
                "DpID":1,
                "MName":1,
                "DPType":0
            },
            "Direct":1
        },
        {
            "Cluster":{
                "MType":1,
                "Act":5,
                "SType":2,
                "MFmt":"[{"L":1,"F":1,"T":4}]",
                "EPID":1,
                "MName":1,
                "CID":6,
                "SID":0
            },
            "DP":{
                "MType":1,
                "DpID":1,
                "MName":1,
                "DPType":0
            },
            "Direct":2
        }
    ]
}

Thread 开关设备

以下为一个 Thread 开关的子设备配置文件示例：

{
    "VID": 4701,
    "MPID": 21324,
    "TPID": "tuya_pid",
    "FVer": "0.0.1",
    "EVer": "0.0.4",
    "SList": [
        {
            "Cnt": 2,
            "Min": 0,
            "Max": 65535,
            "SType": 2,
            "Member": [
                {
                    "EPID": 1,
                    "CID": 6,
                    "SID": 0
                },
                {
                    "EPID": 1,
                    "CID": 6,
                    "SID": 16387
                }
            ]
        },
        {
            "Cnt": 1,
            "Min": 0,
            "Max": 65535,
            "SType": 3,
            "Member": [
                {
                    "EPID": 0,
                    "CID": 40,
                    "SID": 2
                }
            ]
        }
    ],
    "ClusterDP": [
        {
            "Direct": 1,
            "Cluster": {
                "EPID": 1,
                "CID": 6,
                "SType": 1,
                "SID": 255,
                "Act": 1,
                "MFmt": "[{\"L\":1,\"F\":1,\"T\":4}]",
                "MType": 1,
                "MName": 1
            },
            "DP": {
                "DpID": 1,
                "DPType": 0,
                "MType": 1,
                "MName": 1
            }
        },
        {
            "Direct": 2,
            "Cluster": {
                "EPID": 1,
                "CID": 6,
                "SType": 2,
                "SID": 0,
                "Act": 5,
                "MFmt": "[{\"L\":1,\"F\":1,\"T\":4}]",
                "MType": 1,
                "MName": 1
            },
            "DP": {
                "DpID": 1,
                "DPType": 0,
                "MType": 1,
                "MName": 1
            }
        },
        {
            "Direct": 1,
            "Cluster": {
                "EPID": 1,
                "CID": 6,
                "SType": 2,
                "SID": 16387,
                "Act": 4,
                "MFmt": "[{\"L\":1,\"F\":1,\"T\":4}]",
                "MType": 1,
                "MName": 0
            },
            "DP": {
                "DpID": 29,
                "DPType": 3,
                "MType": 1,
                "MName": 0
            },
            "Exp": {
                "EType": 1,
                "Data": "{\"map\":[{\"dpV\":0,\"mtV\":0},{\"dpV\":1,\"mtV\":1},{\"dpV\":2,\"mtV\":-1}]}"
            }
        },
        {
            "Direct": 2,
            "Cluster": {
                "EPID": 1,
                "CID": 6,
                "SType": 2,
                "SID": 16387,
                "Act": 5,
                "MFmt": "[{\"L\":1,\"F\":1,\"T\":4}]",
                "MType": 1,
                "MName": 0
            },
            "DP": {
                "DpID": 29,
                "DPType": 3,
                "MType": 1,
                "MName": 0
            },
            "Exp": {
                "EType": 1,
                "Data": "{\"map\":[{\"dpV\":0,\"mtV\":0},{\"dpV\":1,\"mtV\":1},{\"dpV\":2,\"mtV\":-1}]}"
            }
        }
    ]
}
上一篇子设备配置文件接入
下一篇Zigbee 子设备配置文件
语言
简体中文
简体中文
English
400-881-8611
7×24小时服务热线
市场合作
marketing@tuya.com
业务合作
service@tuya.com
媒体联络
pr@tuya.com
关注“涂鸦智能”
涂鸦服务尽在掌握
关注“全球智能商业”
第一时间获取物联网资讯
联系我们加入我们TuyaExpoApp 商城TuyaGoTuyaGo服务商查询
法律声明隐私协议加州隐私权利声明服务条款廉正合规安全应急响应中心
©2014-2024 杭州涂鸦信息技术有限公司 版权
浙ICP备14011795号
浙B2-20210233号
浙公网安备33010602004238号
简体中文
简体中文
English