Codec for Arrays and Variable-Length Arrays

Scenarios

A smoke detector provides the following functions:

Reporting smoke alarms (fire severity) and temperature simultaneously, or reporting the temperature separately.
Reporting description. The data type of description can be array (array type) or variant (variable-length array type).
NOTE:

This scenario describes how to develop a codec for data in arrays and data in variable-length arrays. The data reporting and command delivery codecs are developed in the same way. Therefore, data reporting is used as an example and command delivery is not described.

Defining the Profile File

Define the profile file in the development space of the smoke sensor.

click to enlarge

Developing a Codec

This section describes only the procedure for developing the codec for reporting the description (other_info). For details on how to develop the codec for reporting the smoke alarms (level) and temperature (temperature), see Codec for Multiple Data Reporting Messages.

In the development space of the smoke sensor, click Codec Development.
Configure a data reporting message to report the fire severity and temperature. For details, see 2.
Configure a data reporting message to report only the temperature. For details, see 3.
Configure a data reporting message to report the description of the array type.

Add the messageId field to indicate the message type. In this scenario, the value 0x0 is used to identify the message that reports the fire severity and temperature, 0x1 is used to identify the message that reports only the temperature, and 0x2 is used to identify the message that reports the description (of the array type).

Add the other_info field to indicate the description of the array type. In this scenario, set Length to 5.
Configure a data reporting message to report the description of the variable-length array type.

Add the messageId field to indicate the message type. In this scenario, the value 0x0 is used to identify the message that reports the fire severity and temperature, 0x1 is used to identify the message that reports only the temperature, and 0x3 is used to identify the message that reports the description (of the variable-length array type).

Add the length field to indicate the length of an array. Data Type is configured based on the length of the variable-length array. If the array contains 255 or fewer characters, set this parameter to int8u.

Add the other_info field to indicate the description of the variable-length array type. Set Length Correlation Field to length. The values of Length Correlation Field Difference and Length are automatically filled.
Drag the property fields in Device Model on the right to set up a mapping with the corresponding fields in the data reporting messages.
Click Save and then Deploy to deploy the codec on the IoT platform.

Testing the Codec

In the development space of the smoke sensor, click Online Testing and add a virtual device to test the codec.

Select No for Is Physical Device Available and click OK.
Use the device simulator to report the description of the array type.

For example, a hexadecimal code stream (0211223344) is reported. In this code stream, 02 indicates the messageId field and specifies that this message reports the description of the array type. 11223344 indicates the description and its length is four bytes.

View the data reporting result ({other_info=null}) in Application Simulator. The length of the description is less than five bytes. Therefore, the codec cannot parse the description.

In the second hexadecimal code stream example (021122334455), 02 indicates the messageId field and specifies that this message reports the description of the array type. 1122334455 indicates the description and its length is five bytes.

View the data reporting result ({other_info=ESIzRF=}) in Application Simulator. The length of the description is five bytes. The description is parsed successfully by the codec.

In the third hexadecimal code stream example (02112233445566), 02 indicates the messageId field and specifies that this message reports the description of the array type. 112233445566 indicates the description and its length is six bytes.

View the data reporting result ({other_info=ESIzRF=}) in Application Simulator. The length of the description exceeds six bytes. Therefore, the first five bytes are intercepted and parsed by the codec.
Use the device simulator to report the description of the variable-length array type.

For example, a hexadecimal code stream (030101) is reported. In this code stream, 03 indicates the messageId field and specifies that this message reports the description of the variable-length array type. The first 01 indicates the length of the description (one byte) and its length is one byte. The second 01 indicates the description and its length is one byte.

View the data reporting result ({other_info=AQ==}) in Application Simulator. AQ== is the encoded value of 01 using the Base64 encoding mode.

In the second hexadecimal code stream example (03020102), 03 indicates the messageId field and specifies that this message reports the description of the variable-length array type. 02 indicates the length of the description (two bytes) and its length is one byte. 0102 indicates the description and its length is two bytes.

View the data reporting result ({other_info=AQI=}) in Application Simulator. AQI= is the encoded value of 01 using the Base64 encoding mode.

In the third hexadecimal code stream example (03030102), 03 indicates the messageId field and specifies that this message reports the description of the variable-length array type. 03 indicates the length of the description (three bytes) and its length is one byte. 0102 indicates the description and its length is two bytes.

View the data reporting result ({other_info=null}) in Application Simulator. The length of the description is less than three bytes. The codec fails to parse the description.

In the fourth hexadecimal code stream example (0303010203), 03 indicates the messageId field and specifies that this message reports the description of the variable-length array type. The second 03 indicates the length of the description (three bytes) and its length is one byte. 010203 indicates the description and its length is three bytes.

View the data reporting result ({other_info=AQID}) in Application Simulator. AQID is the encoded value of 010203 using the Base64 encoding mode.

In the fifth hexadecimal code stream example (030301020304), 03 indicates the messageId field and specifies that this message reports the description of the variable-length array type. The second 03 indicates the length of the description (three bytes) and its length is one byte. 01020304 indicates the description and its length is four bytes.

View the data reporting result ({other_info=AQID}) in Application Simulator. The length of the description exceeds three bytes. Therefore, the first three bytes are intercepted and parsed. AQID is the encoded value of 010203 using the Base64 encoding mode.

Description of Base64 Encoding Modes

In the Base64 encoding modes, three 8-bit bytes (3 x 8 = 24) are converted into four 6-bit bytes (4 x 6 = 24), and 00 are added before each 6-bit byte to form four 8-bit bytes. If the code stream to be encoded contains less than three bytes, fill the code stream with 0. The byte that is filled with 0 is displayed as an equal sign (=) after it is encoded.

Developers can encode hexadecimal code streams as characters or values using the Base64 encoding modes. The encoding results obtained in the two modes are different. The following uses the hexadecimal code stream 01 as an example:

Use 01 as characters. It contains fewer than three characters. Therefore, add one 0 to obtain 010. Query the ASCII code table to convert the characters into an 8-bit binary number, that is, 0 is converted into 00110000 and 1 into 00110001. Therefore, 010 can be converted into 001100000011000100110000 (3 x 8 = 24). The binary number can be split into four 6-bit numbers: 001100, 000011, 000100, and 110000. Then, pad each 6-bit number with 00 to obtain the following numbers: 00001100, 00000011, 00000100, and 00110000. The decimal numbers corresponding to the four 8-bit numbers are 12, 3, 4, and 48, respectively. You can obtain M (12), D (3), and E (4) by querying the Base64 coding table. As the last character of 010 is obtained by adding 0, the fourth 8-bit number is represented by an equal mark (=). Finally, MDE= is obtained by using 01 as characters.
Use 01 as a value (that is, 1). It contains fewer than three characters. Therefore, add 00 to obtain 100. Convert 100 into an 8-bit binary number, that is, 0 is converted into 00000000 and 1 is converted to 00000001. Therefore, 100 can be converted to 000000010000000000000000 (3 x 8 = 24). Then, convert the binary number into four 6-bit numbers: 000000, 010000, 000000, and 000000. Pad each 6-bit number with 00 to obtain 00000000, 00010000, 00000000, and 00000000. The decimal numbers corresponding to the four 8-bit numbers are 0, 16, 0, and 0, respectively. You can obtain A (0) and Q (16) by querying the Base64 coding table. As the last two characters of 100 are obtained by adding 0, the third and fourth 8-bit numbers are represented by two equal marks (==). Finally, AQ== is obtained by using 01 as a value.

Summary

When the data is an array or a variable-length array, the codec encodes and decodes the data using Base64. For data reporting messages, the hexadecimal code streams are encoded using Base64. For example, 01 is encoded into AQ==. For command delivery messages, characters are decoded using Base64. For example, AQ== is decoded to 01.
When the data type of a field is variant(variable-length array type), the field must be associated with the length field. The data type of the length field must be int.
For variable-length arrays, the codecs for command delivery and data reporting are developed in the same way.
When the codecs that are developed online encode data using Base64, hexadecimal code streams are encoded as values.