Description of Complex Protocol

This topic describes how a complex data point (DP) of raw or string type is parsed.

Applicability

The complex protocol applies to standard DPs of string or raw type for electrical and lighting products and door locks.

The parsing rules can help address the compatibility issues that might occur when you reuse DP data across product categories, control panels, cloud projects, and data analytics. We recommend you choose standard functions for product development to enable compatibility with more development options.

Procedure

1. Log in to the Tuya Developer Platform.

2. On the page of Product Development, select an applicable product, and click Develop.

3. Click the Function Definition tab. In the Standard Function section, find a DP of string or raw type, and click Protocol parsing specification.

   

4. On the page that appears, you can check the protocol preview.

   

Protocol preview

• F is used to represent the length of a field. One F denotes one byte.

• The number below the F represents the sequence number of a field.

• Three types of loops are supported: loop an unknown number of times, loop a known number of times, and dependency loop. More than one field can form a loop, which is combined with other general fields to implement the complex protocol.

  • Loop an unknown number of times: The positions of fields are fixed but their length is dynamically changed. The loop runs a dynamic number of times based on the length of the received fields.
  • Loop a known number of times: The positions and length of fields are fixed. The loop runs a fixed number of times.
  • Dependency loop: The value of a specific field determines the number of times the loop runs. The position and length of this field are fixed.

• Principle of loop parsing: Considering the possibility of nested loops, data is parsed from the inner loop to the outer loop.

• Definition of data length: Data of raw type is expressed in hexadecimal format. By default, the length of raw data is defined as the base for data parsing. The base multiplied by 2 bit by bit is the parsing of string data.

Field description

• S/N: the sequence number of a field. It determines the position of a field in the sequence.

• Name: the name of a field.

• Byte(s): the length of a field.

• Data Type: the type of field. It can be Boolean, value, enum, string, week, and bit. The property values vary depending on data types.

• Field Properties: the property values of a field.

• Field Description: the detailed description of a field.

  Type	Parameter	Description	Example
  Boolean	boolean	Represent a binary variable value that is either true or false.	On/off control. Turn a device on or off.
  Value	value	Apply to the data that can be linearly adjusted.	Adjust the temperature, ranging from 20°C to 40°C.
  Enum	enum	A custom finite set of values.	Change the working level in terms of high, medium, and low.
  Weekly data	week	Transmit data in a raw binary format.	Specify the day(s) of the week on which a task will be run.
  String	string	Transmit the data as a string.	-
  Bit	bit	Transmit data in a raw binary format.	Indicate which bit is valid from bit 0 to bit 7.

Example of parsing

The following sample parses a JSON object. The key of a JSON object is an identifier of a field and a group. The value of a field is a JSON object. The value of a group is an array. The langKey that is used for multilingual text is parsed by using the Dubbo API.

{
    "bs2":[
        {
            "bs22":{
                "langKey":"30d7e1f1",
                "type":"string",
                "value":[
                    17
                ]
            }
        },
        {
            "bs22":{
                "langKey":"30d7e1f1",
                "type":"string",
                "value":[
                    34
                ]
            }
        }
    ],
    "bs1":{
        "langKey":"5165502",
        "type":"enum",
        "value":{
            "value":[
                2
            ]
        }
    },
    "bs4":[
        {
            "bs44":{
                "langKey":"731d3b7e",
                "type":"string",
                "value":[
                    85
                ]
            }
        },
        {
            "bs44":{
                "langKey":"731d3b7e",
                "type":"string",
                "value":[
                    17
                ]
            }
        },
        {
            "bs44":{
                "langKey":"731d3b7e",
                "type":"string",
                "value":[
                    17
                ]
            }
        },
        {
            "bs44":{
                "langKey":"731d3b7e",
                "type":"string",
                "value":[
                    17
                ]
            }
        }
    ],
    "bs3":[
        {
            "bs33":{
                "langKey":"d372e06a",
                "type":"string",
                "value":[
                    51
                ]
            }
        },
        {
            "bs33":{
                "langKey":"d372e06a",
                "type":"string",
                "value":[
                    68
                ]
            }
        }
    ]
}

String and value

{
    "langKey":"d372e06a",
    "type":"string",
    "value":[
        51
    ]
}

• langKey: the language identifier, used for multilingual texts.
• type: the data type, which can be string or number.
• value: an int array.

Week

{
    "langKey":"d372e06a",
    "type":"week",
    "value":[
        1,0,0,0,0,0,0
    ]
}

• langKey: the language identifier, used for multilingual texts.
• type: the data type is week.
• value: an int array from bit 0 to bit 6, representing Monday to Sunday. In the example above, 1,0,0,0,0,0,0 means a task is scheduled to be run on Monday.

Enum and Boolean

{
    "langKey":"5165502",
    "type":"enum",
    "value":{
        "langKey":"d372e06a",
        "value":[
            2
        ]
    }
}

• langKey: the language identifier, used for multilingual texts.
• type: the data type can be enum or boolean.
• value: a JSON object.
• langKey: the language identifier, used for multilingual texts. If value is not populated with a predefined value, it will be empty.
• value: an int array.

Bit

{
    "langKey":"2ecbe5e2",
    "type":"bit",
    "value":{
        "bit7":{
            "langKey":"8ebb4416",
            "index":7,
            "type":"boolean",
            "value":{
                "langKey":"2d3975fd",
                "value":[
                    0
                ]
            }
        },
        "bit5":{
            "langKey":"d0cc3145",
            "index":5,
            "type":"boolean",
            "value":{
                "langKey":"2d3975fd",
                "value":[
                    0
                ]
            }
        },
        "bit6":{
            "langKey":"fc9a8919",
            "index":6,
            "type":"boolean",
            "value":{
                "langKey":"2d3975fd",
                "value":[
                    0
                ]
            }
        },
        "bit3":{
            "langKey":"c978dd00",
            "index":3,
            "type":"boolean",
            "value":{
                "langKey":"7f18c924",
                "value":[
                    1
                ]
            }
        },
        "bit4":{
            "langKey":"15d5ee1e",
            "index":4,
            "type":"boolean",
            "value":{
                "langKey":"7f18c924",
                "value":[
                    1
                ]
            }
        },
        "bit1":{
            "langKey":"50b1a328",
            "index":1,
            "type":"boolean",
            "value":{
                "langKey":"7f18c924",
                "value":[
                    1
                ]
            }
        },
        "bit2":{
            "langKey":"18d3937b",
            "index":2,
            "type":"boolean",
            "value":{
                "langKey":"2d3975fd",
                "value":[
                    0
                ]
            }
        },
        "bit0":{
            "langKey":"801acde4",
            "index":0,
            "type":"boolean",
            "value":{
                "langKey":"2d3975fd",
                "value":[
                    0
                ]
            }
        }
    }
}

• langKey: the language identifier, used for multilingual texts.

• type: the data type is bit.

• value: the value of a field, in JSON. The bit field is a composite field with eight sub-fields included. The key of a JSON object is an identifier of a sub-field.

  Sub-field:

  • langKey: the language identifier of a sub-field, used for multilingual texts.
  • index: the sequence number.
  • type: the data type of a sub-field, which is boolean.
  • value: the value of a sub-field (multi-language supported).
  • langKey: the language identifier of the value of a sub-field.
  • value: the value of a sub-field, an int array. The valid value can be either 0 or 1.

Group

[
    {
        "a":{
            "langKey":"266edefb",
            "type":"string",
            "value":[
                12
            ]
        },
        "d":{
            "langKey":"01f1e022",
            "type":"string",
            "value":[
                18
            ]
        }
    },
    {
        "a":{
            "langKey":"266edefb",
            "type":"string",
            "value":[
                12
            ]
        },
        "d":{
            "langKey":"01f1e022",
            "type":"string",
            "value":[
                18
            ]
        }
    }
]

• A JSON array. The same field definitions are repeated.
• A group that is not looped. An array of one byte in length.