What Is a Sub-Device Configuration File?

Last Updated on : 2023-09-15 06:29:56download

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:

What Is a Sub-Device Configuration File?

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

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

For the Zigbee to Matter bridge configuration file, in the downstream direction, convert Matter protocol into DP protocol. In the upstream direction, convert DP protocol into Matter protocol.

`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)
1 (command)	xx (command ID)	2 (S2C)
2 (attribute)	xx (attribute ID)	3 (read)
		4 (write)
		5 (report)
3 (event)	xx (event ID)	6 (subscribe)
3 (event)	xx (event ID)	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

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

Prev DocIntegration by Sub-Device Config Files

Next DocZigbee Sub-Device Config File