What Is a Sub-Device Configuration File?

This topic describes the sub-device configuration file that is used to connect sub-devices to Tuya-enabled gateways. The configuration file allows for the conversion between IoT protocols and Tuya-defined data point (DP) protocol. By setting parameters in the JSON configuration file, you can connect sub-devices to Tuya-enabled gateways.

File format

The configuration file is in JSON format, as shown below.

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

It contains the following content:

Requirements

• All the sub-device configuration files must have a conversion rule defined. Otherwise, they cannot work.

• The following table provides a list of the required and optional fields in the configuration file for different protocols.

  File type	Required	Optional
  Matter configuration file	SList	MTRT
  Zigbee configuration file	None	proData and MTDes
  Matter bridge configuration file	MTDes	None

First-level parameters

The following table lists the parameters in the first level of the JSON configuration file.

Parameter	Description	Data type
VID	The vendor ID, a unique number assigned by the Connectivity Standards Alliance (CSA), identifies the manufacturer that owns the configuration file.	Number (16-bit)
MPID	The product ID (PID) of a Matter device. The PID, a unique number assigned by the manufacturer, identifies the product type. Multiple products can share the same PID.	Number (16-bit)
TPID	The PID, a unique identifier assigned by Tuya, identifies the product.	String (16-byte)
FVer	The version of the configuration file, identifying the version of the conversion rule defined by the configuration file. For example, 1.0.1.	String (16-byte)
EVer	The version of the DP Engine. It can only be specified in the solution parameters and cannot be modified in the product definition.	String (16-byte)
ClusterDP	An array of cluster-DP conversions, including the rules for conversion between all DPs of a product and Matter or Zigbee commands. For more information, see ClusterDP.	Array
MTDes	The device information displayed when a Zigbee device is bridged to a Matter network. For more information, see MTDes.	Array
SList	The sub-device subscription table. This field is intended for the Matter configuration file. The controller sends the subscribe command to the sub-device based on the elements in the table. For more information, see SList.	Array
ProData	The protocol data. For more information, see ProData.	String (JSON)

Second-level parameter: ClusterDP

ClusterDP represents an array of cluster-DP conversions. It includes the rules for conversion between all DPs of a product and Matter commands.

Example

{
  "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

dir indicates the direction of protocol conversion, either upstream or downstream.

Take the on/off feature as an example. In the upstream direction, convert the Matter OnOff attribute reported by a device into DP data. In the downstream direction, convert the DP data received from the cloud into the Matter OnOff command.

dir	Protocol	Direction	Description
1	Thread	Downstream	DP to Matter
2	Thread	Upstream	Matter to DP
1	WoM (Wi-Fi over Matter)	Downstream	DP to Matter
2	WoM (Wi-Fi over Matter)	Upstream	Matter to DP
1	Zigbee	Downstream	DP to Zigbee
2	Zigbee	Upstream	Zigbee to DP
1	Zigbee bridge	Downstream	Matter to DP
2	Zigbee bridge	Upstream	DP to Matter

Cluster

The cluster command that corresponds to a DP.

Parameter	Description
EPID	The endpoint ID of a device, a 2-byte unsigned number. For example, 0x0001.
CID	The cluster ID, a 4-byte unsigned number. For example, 0x00000006 for the On/Off cluster.
SType	The subtype: 1: Command 2: Attribute 3: Event
SID	The subtype_id, a 4-byte unsigned number, indicating the ID of a cluster’s subtype. If Sub_type is attribute, SID is the attribute ID. If Sub_type is command, SID is the command ID. If Sub_type is event, SID is the event number. Note: When SType is command, to send the value of a DP as the command ID, set SID to 0xFF(255). Currently, only 1-byte commands are supported. For example, if the valid values of SID are the commands for the On/Off cluster, and the value of dp_payload is either 0 or 1 (0 for Off and 1 for On), set SID to 255. Then, the DP’s payload will be used as the command to send to the device. When SID is 0xFF, the MFmt is fixed as {\"T\":4,\"L\":1,\"F\":1}.
Act	action, an enum type, indicates the operation of a Sub_type. When Sub_type is attribute, the attribute can be read, write, report, or subscribe. When Sub_type is event, the event can be subscribe or report. When Sub_type is command, the command can be client to server (C2S) or server to client (S2C). Currently, the configuration file does not support: Conversion between the DP and the read attribute. Conversion between the DP and the subscribe event. SType SID Act 1 (command) xx (command ID) 1 (C2S) 2 (S2C) 2 (attribute) xx (attribute ID) 3 (read) 4 (write) 5 (report) 3 (event) xx (event ID) 6 (subscribe) 7 (report)
MType	The method_type, indicating the algorithm of conversion between Matter command values and DP command values. 1: C library
MName	The method_name, the name of the function that processes the conversion. The functions are listed in enum values in the JSON configuration file. See the dp_engine conversion function mapping table for details. The conversion functions are used to translate the payload of the DP protocol into the payload of the local protocol.
MFmt	The message_format, indicating the format of the Msg parameter in the Matter command packet. Unsigned Integers are represented in bitmap format. T: The type of the character. When the type of the payload is Boolean, set T to 8 or 9. When the type of the payload is bitmap, set T to 4. When the type of the payload is string, set T to 0x0c and L to 0. When the type of the payload is raw, set T to 16 and L to -1. L: The length of the parameter T. F: The flag, populated with Matter data converted from the DP value. When this field is set to 1, it is populated with the converted value. When this field is null, it is populated with the default value.

The valid values for the T field:

Value	Description
-1	Unspecified
0x00	Int8
0x01	Int16
0x02	Int32
0x03	Int64
0x04	UInt8
0x05	UInt16
0x06	UInt32
0x07	UInt64
0x08	Boolean False
0x09	Boolean True
0x0a	Floating Point Number 32
0x0b	Floating Point Number 65
0x0c	UTF-8 String_1ByteLength
0x0d	UTF-8 String_2ByteLength
0x0e	UTF-8 String_4ByteLength
0x0f	UTF-8 String_8ByteLength
0x10	Byte String_1ByteLength
0x11	Byte String_2ByteLength
0x12	Byte String_4ByteLength
0x13	Byte String_8ByteLength
0x14	NULL

Take the brightness adjustment command as an example.

• The payload:

  Description	1st parameter	2nd parameter	3rd parameter	4th parameter
  Bytes	1	2	0 or 1	0 or 1
  Data type	uint8	uint16	map8	map8
  Parameter	Level	Transition time	OptionsMark	OptionsOverride

• JSON example

  [
      {//level
          "T": 4,//uint8
          "L": 1, //1byte
          "F": 1// Populated with the value converted from the DP value.
      },
      {//transition time
          "T": 5,// uint6
          "L": 2// 2byte
      },
      {//optionsMask
          "T": 4,// map8 == uint8
          "L": 1// 1byte
      },
      {//optionoverride
          "T": 4,// map8 == uint8
          "L": 1// 1byte
          }
      ]
  

  The F field is populated with the converted DP value, and all other fields are set to the default value of 0.

Data point (DP)

An array of Tuya-defined DP commands. An attribute might correspond to more than one DPs.

Parameter	Description
DPID	The ID of a DP, two bytes.
DPType	The data type of a DP. Bool: 0 Value: 1 String: 2 Enum: 3 Bitmap: 4 Raw: 5
MType	The method_type, indicating the algorithm of conversion between Matter command values and DP command values. 1: C library
MName	The method_name, the name of the function that processes the conversion. The functions are listed in enum values in the JSON configuration file. See the dp_engine conversion function mapping table for details. The conversion functions are used to translate the payload of the local protocol into the payload of the DP protocol.

Exp

Exp indicates an optional extension field. To use this field, set the MName field in the respective array to 0.

• EType: expand_typde

  EType	Description
  1	EnumMap enum mapping table
  2	BitMap bit table
  3	DefaultValue table
  4	Math formula conversion, for example, *(num/360.0)254 + 0.5. Only unary operators are supported currently.

• Data: JSON string.

  • When EType is 1, the format is "{"map":[{"dpV":0,"mtV":2},{"dpV":1,"mtV":0}]}". mtV of -1 indicates that NULL is sent.
  • When EType is 2, the format is "{"byte":1,"bit":1}", indicating that the value of DP is derived from the first bit of the first byte, which is used for parsing the data reported by intruder alarm system (IAS) zone devices.
  • When EType is 3, the format is "{\"dp\":[{\"i\":1,\"t\":1,\"v\":2}]}", indicating that data is converted into the default value for reporting, without parsing the payload but directly using the specified DP content. i is for DpID, t for DPType, and v for dpValue.
  • When EType is 4, the format is "{\"1\":\"num+1\",\"2\":\"num-1\"}", indicating that a specified function is used for numeric conversions. When jsonKey is set to 1, the content of jsonValue is the function used to convert the local protocol into the DP protocol. When jsonKey is set to 2, the content of jsonValue is the function used to convert the DP protocol into the local protocol. The name of the unknown number must be num.

Second-level parameter: MTDes

MTDes describes the device information displayed when a non-Matter device is bridged to a Matter network.

Example

{
  "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

The Basic field, containing the default values of attributes, describes the basic attributes of a product to the Matter network. Its content follows the cluster definition in the Matter specification. This field is in JSON format, as shown below.

[
    {
        "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"}
        ]
    }
]

Example of the Basic field:

[
    {
        "57":[ //clusterid=57, indicating basic informaton cluster
            {
                "1":"tuya"//attributeid=1, indiating VendorName is tuya
            },
            {
                "2":4821 //attributeid=4821(0x125D), indicating VendorId is 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 indicates additional information, with the following sub-parameters.

• CType: The cluster type, with valid values as shown below.

  Value	Description
  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: The cluster ID.

• FMap: The feature map. Its values correspond to the attributes and commands supported by the cluster.

• ICmds: In cluster. The payload format for each command must be specified.

• OCmds: Out cluster. The payload format for each command must be specified.

Second-level parameter: SList

SList is the sub-device subscription table, applying to Matter sub-devices. The controller sends the subscribe command to the sub-device based on the elements in the table.

{
"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
                }
            ]
        }
    ],
}

Second-level parameter: ProData

ProData specifies protocol information in string format, applying to the Zigbee configuration file. After Zigbee sub-devices join the network and are bound with the Tuya service, the controller will send Zigbee standard commands to the sub-devices based on RTbale, WTable, and CTable.

  {
    "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
        }]
    }]}

Example of complete configuration

Bridged Zigbee switch

Sample sub-device configuration file for a bridged Zigbee switch:

{
    "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 switch

Sample sub-device configuration file for a Thread switch:

{
    "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}]}"
            }
        }
    ]
}