Protocol Decoder

Decode a uint8 byte stream by specifying the packet structure

Since R2021b

Add-On Required: This feature requires the Simulink Support Package for Arduino Hardware add-on.

• 

Libraries:
Simulink Support Package for Raspberry Pi Hardware / Utilities
Simulink Support Package for Arduino Hardware / Common
C2000 Microcontroller Blockset / Target Communication

Description

The Protocol Decoder block decodes a uint8 byte stream as per the specified packet structure based on the communication protocol. You can use this block to decode packet into separate fields, by specifying the header, terminator, name of packet fields in sequence and their size. You can also validate the packet using the checksum logic that you specify.

Ports

Input

Data — uint8 byte stream packet

vector

The uint8 byte stream packet that contains the encoded data from multiple signals as specified in the packet structure.

The input packet can be partially received over multiple sample times. The Protocol Decoder block has the capability to buffer such partial data until the complete packet is received.

Data Types: uint8

Length — Length of data stream packet at Data input port

numeric scalar

Optional input port to include the exact length of valid data stream. Use this option when you know the exact length of the valid data in the input data stream

This option is useful when you have a communication channel receive peripheral that outputs partially received data that contains trailing zeros. Such peripherals also output the length of the actual number of valid data bytes received. You can connect the length output of the peripheral directly with the Length input port of Protocol Decoder block, so that trailing zeros in the input byte stream do not affect the decoding logic.

Dependencies

This input port appears only if you select the Is input data stream length available parameter.

Data Types: uint16

Output

Field1 — First field decoded by the block

scalar

Name of the first field decoded by the block. The name of the output port is defined using the block parameter, Field name. Each subsequent field that you create while defining the packet structure results in a new output port, with the Field name value appearing as the name of output port.

The block can have from 1 to N output ports. N is the number of fields in the packet structure that you specify in the Specify packet fields sequentially pane.

Data Types: string

IsNew — New data indicator

0 | 1

New data indicator returned as a logical. A value of 1 indicates that a new data is available since the last sample was received by the block. This output can be used to trigger subsystems to process new data received from the Protocol Decoder block.

If IsNew = 0, the block outputs decoded fields from the last complete packet decoded by the block. If no last sample is available, the block outputs zeros.

Data Types: Boolean

IsValid — Checksum validation indicator

0 | 1

Checksum validation indicator returned as a logical. A value of 1 indicates that the input packet received by the block is valid when validated using the checksum logic that you specified. If IsValid = 0, the block outputs zeros.

Dependencies

This output port appears only if you select the Specify logic for checksum validation parameter.

Data Types: Boolean

Variable field length — Actual data length of the last field that is variable-size

numeric scalar

Actual data length of the last field that is variable-size. The maximum size of the variable size field can be specified using Specify maximum length if last field has variable size parameter. The block outputs the variable-size data as a fixed size data with size that is equal to the maximum length specified. The output contains actual data followed by trailing zeros. The size of actual data can be determined using this Variable Field Length output.

Dependencies

This output port appears only if you select the Specify maximum length if last field has variable size parameter. For more details, see Decode Variable-size Packet.

Data Types: double

Variable field lengths — Actual data lengths of comma separated variables

array

Actual data lengths of comma separated variables that are decoded from the input stream.

This output value (1-by-N array) corresponds to the actual data length of the fields in the packet, where N is the number of comma separated variables in the packet.

When Parse comma separated variables is selected, the Output field length parameter value corresponds to the maximum size of the field. The actual size of the field is available as the Variable field lengths output.

If the actual field length of n^th field is less than the specified Output field length parameter value on the block, the output corresponding to the field is actual data followed by trailing zeros. The n^th element of the Variable field lengths output provides the actual length corresponding to that variable in that array.

If the actual field length of n^th field is greater than the specified Output field length parameter value on the block, the output corresponding to the field is truncated and outputted, given the actual packet size does not exceed maximum packet size. The n^th element of the Variable field lengths output provides the actual length corresponding to that variable in that array.

Dependencies

This output port appears only if you select the Parse comma separated variables parameter. For more details, see Decode Comma-separated Variable.

Data Types: double

Parameters

Parse comma separated variables — Parse input data that contains comma separated variables

array

Specify that the input data to be parsed contains comma separated variables.

Data Types: uint8

Header — Header of the packet

character array | array of numeric values less than 255

Specify the header that indicates the beginning of the data. The simulation disregards data that occurs before the header. The header data is not sent to the output port.

The numeric array specified in this parameter is the uint8 integer representation of the corresponding ASCII characters.

Few examples of header values are: ‘START’, '$’, 36, [36,37].

Specify packet fields sequentially

Field name — Name of the field in the packet structure

Field1 (default) | string

Specify the name of the field included in the packet structure. This name appears as the name of the output port.

To add a new packet field and specify its properties, click Add. After adding a field, click Move Up or Move Down to change its sequence in the structure.

To delete a field and its properties, select the row and click Delete.

Output field length — Length of the field in the packet structure as per the data type

1 (default) | numeric scalar

Length of the field in the packet structure as per the data type that you enter in the next column (Output field data type). For example, if the Output field data type of a field is uint16 and the length is 1, the decoder reads two bytes from the packet as per the packet structure and combine these bytes to output a uint16 value.

If you select Parse comma separated variables parameter, the Output field length value corresponds to the maximum length that the field can have.

Data Types: double

Output field data type — Data type of the field

uint8 (default) | int8 | int16 | uint16 | int32 | uint32 | int64 | uint64 | single | double

Select the output data type of the field.

Note

double is considered as 8 bytes. If your hardware does not support 8 bytes double, selecting this data type might give incorrect results.

Note

If you select the Parse comma separated variables parameter, you cannot edit this parameter (the Output field data type is set to uint8 always).

Byte order — Endianess of the field in the packet

Little endian (default) | Big endian

Select the endianess of the packet field to describe the order in which bytes are transmitted.

Note

If you select the Parse comma separated variables parameter, you cannot edit this parameter (the Byte order is set to Little endian always).

Specify maximum length if last field has variable size — Enable last field to output variable-size data and specify maximum length of the field

numeric scalar

Enable last field of the packet to output variable-size data and specify the maximum length of the variable length field, which is present as the last field in the packet. For more details, see Decode Variable-size Packet.

Specify logic for checksum validation — Enable the logic for checksum validation and select the logic

XOR of bytes | 2's complement of sum of bytes | Custom algorithm

Specify the logic to generate checksum for validation using standard algorithms or a custom algorithm.

If you select Custom algorithm, the additional parameters – Checksum size and File path – are enabled.

Checksum bytes are expected to be in the last in the packet (before terminator, if terminator is available).

If you select the logic as XOR of bytes, checksum byte is expected to be the last byte before terminator. The logic calculates the XOR of all bytes excluding header, terminator and checksum byte, and compare it with the checksum byte.

If you select the logic as 2's complement of sum of bytes, checksum byte is expected to be the last byte before terminator. The logic calculates the 2's complement of sum off all bytes excluding header, terminator and checksum byte, and compare it with the checksum byte.

If you select Custom algorithm, you can provide your own custom logic to validate packet. In this case, checksum bytes are extracted as per the size specified in the Checksum size field. For more information, see Function Template for Custom Checksum Logic in Protocol Decoder Block.

Checksum size — Number of bytes of checksum data

numeric scalar

Specify the number of bytes of checksum data. The blocks extracts the checksum bytes as per the specified size and passes it to the function used for custom algorithm, for validating the packet. For more details, see Function Template for Custom Checksum Logic in Protocol Decoder Block. Checksum bytes are expected to be in the last in the packet (before terminator, if terminator is available).

Dependencies

This parameter is enabled only if you select Custom algorithm option under Specify logic for checksum validation parameter.

Data Types: uint8

File path — Path of the function (.m) used for custom checksum logic

MATLAB path

Specify the path of the function (.m) in which you defined the custom algorithm for checksum logic. The file must be saved in a directory in the MATLAB^® path. For more details, see Function Template for Custom Checksum Logic in Protocol Decoder Block.

Dependencies

This parameter is enabled only if you select Custom algorithm option under Specify logic for checksum validation parameter.

Data Types: uint8

Terminator — Terminator of the packet

<none> (default) | CR ('\r') | LF ('\n') | CR/LF ('\r\n') | NULL ('\0') | Custom Terminator

Specify the terminator that indicates the end of the data. The terminator data is not sent to the output port.

If you select Custom Terminator, you can specify your own terminator value.

Data Types: uint8

Custom terminator — Custom terminator of the packet

character array

Custom terminator that indicates the end of the data. The terminator data is not sent to the output port.

The numeric array specified in this parameter is the uint8 integer representation of the corresponding ASCII characters.

Few examples of custom terminator values are: ‘END’, '#’

Is input data stream length available — Enable additional input for data stream length

off (default) | on

Enable optional input port to include the exact length of valid data stream.

More About

Decode Fixed-Sized Packet

The Protocol Decoder block can be used to decode fixed size input packet (uint8) into separate fields.

The block extracts the separate fields as per the packet structure specified, and convert them to output data of the data type specified in the Output field data type parameter as per the Byte order.

The input packet can be partially received in over multiple sample times. The Protocol Decoder block has the capability to buffer such partial data until the complete packet is received.

The general structure of a fixed size packet look like this, with optional checksum and terminator fields:

For example, suppose that you need to decode input packet as specified in this structure:

In this case, you specify the block parameters as shown in the below figure. The output displayed when you simulate the model conforms to the packet structure:

The block follows this sequence for decoding the data:

1. Extract packet based on header, packet size and terminator (if applicable). The packet size is determined by adding these:

   Sum of values specified using Output field length parameter (in bytes) + Value of Checksum size parameter (if applicable).

   The block waits for the header, to start decoding. Once it receives the header, it reads the fixed data fields as per the packet size. If the terminator is specified, the blocks checks if the subsequent bytes following the fixed size bytes are terminator bytes. If the subsequent bytes are not terminator bytes, the packet will be discarded.

2. Validate the data received from the previous step using the checksum logic specified (if applicable).

3. Split the fields in the packet as per the length, datatype, and endianness specified, and provide them as output.

Decode Variable-size Packet

If the last field in the packet is variable-size, you select the parameter Specify maximum length if last field has variable size.

The input packet can be partially received in over multiple sample times. The Protocol Decoder block has the capability to buffer such partial data until the complete packet is received.

The general structure of a packet containing variable-size field may look like this, with optional checksum and terminator fields:

For example, NMEA (National Marine Electronics Association) sentences given by a GPS device can be considered as a packet that contains both fixed size fields and variable size field. The general structure of these sentences looks like this:

Here:

• Header ($): Start of the packet

• Talker ID: Identify the talker (GP, GN, and so on)

• MessageID: Type of message (RMC, GGA, and so on)

• Variable size data: Data fields depending on the Message ID

• Checksum: Checksum bytes are followed after asterisk *. The checksum is a two-digit hexadecimal number calculated by the bit-wise exclusive OR of ASCII codes of all characters between $ and *, not inclusive.

• Terminator: CR LF, indicating end of the message

This figure shows the corresponding entries for the various parameters in the block and the output in the Simulink^® model. The Checksum size in the block mask is specified as 3, which includes asterisk * and the 2-digit checksum value. The last row, GPSData, denotes the variable sized data with default values for its Output field length, Output field data type, and Byte order parameters, which cannot be edited. The variable size output (GPSData in the block) contains actual data appended with zeros. The additional output port that gets enabled, Variable field length, can be used to determine the actual size of the field.

The custom algorithm required for checksum validation is saved in another file, validateData.m, and it is called using the File path field in the block. The logic defined for the above case, in validateData.m, looks like this:

function isValid = validateData(packet, checksumBytes)
%#codegen
isValid = false;
calculated_checksum = uint8(0);
% Checksum bytes from NMEA starts with '*', followed by 2 bytes which is
% XOR of all bytes in hexadecimal format.
if ~checksumBytes(1) == uint8('*')
    return;
end
for i = 1:numel(packet)
    calculated_checksum = bitxor(calculated_checksum ,packet(i));
end
if checksumBytes(2:3) == dec2hex(calculated_checksum)
    isValid = true;
end
end

Note

If you specify that the data contains variable-size field, the Terminator selection is mandatory (select a value except none).

Decode Comma-separated Variable

To decode comma-separated variable, you enable the Parse comma separated variables parameter.

The input packet can be partially received in over multiple sample times. The Protocol Decoder block has the capability to buffer such partial data until the complete packet is received.

The fields in the packet can be variable sized. In the Output field length column, ensure that the maximum possible length of the field is given. The block outputs fixed size fields based on this length.

For example, consider the packet below:

This figure shows the corresponding entries for the various parameters in the Protocol Decoder block and the output in the Simulink model.

The block follows this sequence for decoding the data:

1. Check for a packet which has the specified header and terminator and does not exceed the maximum packet size.

   The maximum packet size is determined by adding these:

   Sum of Output field length + Checksum size (if applicable) + number of fields -1.

2. Validate the packet once the packet satisfying above condition is obtained, using the checksum logic (if applicable).

3. Parse the individual fields considering comma as the separator. The additional output port that gets enabled, Variable field lengths, can be used to determine the actual size of the fields​.

   1. If the n^th field has a length that is the same as specified in Output field length in the block, the block outputs the value as it is. In this case, the n^th element of the Variable field lengths is equal to the field length specified.

   2. If the n^th field has a length that is less than its specified Output field length in the block, the block outputs the actual value appended with zeros. In this case, the n^th element of the Variable field lengths is equal to the actual field length obtained.

   3. If the n^th field has a length that is greater than specified output data length, the block outputs truncated value as per the specified length. In this case, the n^th element of the Variable field lengths is equal to the actual field length obtained.

Note

If you want to parse comma-separated variable, the Terminator selection is mandatory (select a value except none).

Function Template for Custom Checksum Logic in Protocol Decoder Block

function isValid  = validateChecksumByte(payload,checksumByte)
%#codegen
end

Create the function as specified above to validate packet using checksum. The function returns a boolean, isValid, which determines if the packet is valid. If the isValid is false, output field values given by the block will be 0's. Payload contains all the data bytes excluding header, terminator, and checksum bytes, in uint8 data type. The checksum bytes (checksumByte) are uint8 bytes whose size is specified in the Checksum size field available in the block mask.

Save the function and specify the path of the function in the File path field in the block mask. Ensure that the file is in the MATLAB path.

Example

Consider the NMEA packet with the following structure:

You define the block parameters for this case like this:

Checksum bytes are followed after asterisk *. The checksum is a two-digit hexadecimal number calculated by the bit-wise exclusive OR of ASCII codes of all characters between the $ and *, not inclusive. The Checksum size in the block mask is specified as 3, which includes asterisk * and 2-digit checksum value.

Consider the following input (obtained from a GPS receiver) to the Protocol Decoder:

[uint8(['$GPVTG,77.52,T,,M,0.004,N,0.008,K,A*06']),uint8([13,10])]

The first input to validate the logic is the packet excluding header($), terminator (CR(ASCII-13)( LF -ASCII-10) ), and checksum bytes:

uint8(['GPVTG,77.52,T,,M,0.004,N,0.008,K,A'])

The second input is the checksum bytes *06, which are the last 3 bytes before terminator. In this case, the validation logic can be created like this:

function isValid = validateData(packet, checksumBytes)
%#codegen
isValid = false;
calculated_checksum = uint8(0);
% Checksum bytes from NMEA starts with '*', followed by 2 bytes which is
% XOR of all bytes in hexadecimal format.
if ~checksumBytes(1) == uint8('*')
    return;
end
for i = 1:numel(packet)
    calculated_checksum = bitxor(calculated_checksum ,packet(i));
end
if checksumBytes(2:3) == dec2hex(calculated_checksum)
    isValid = true;
end
end

Monitor Signals and Tune Parameters

The Protocol Decoder block is available with Simulink Support Package for Arduino^® Hardware and Embedded Coder^® Support Package for Texas Instruments^® C2000™ Processors. However, to monitor signals and tune parameters for protocol decoding in Simulink models to be run on TI’s C2000™-based targets, use the Universal Measurement and Calibration Protocol (XCP)-based External mode simulation.

Version History

Introduced in R2021b