Protocol Decoder
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 nth 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
nth element of the Variable field
lengths output provides the actual length corresponding to that variable
in that array.
If the actual field length of nth 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 nth 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].
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:
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 ofChecksum 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.
Validate the data received from the previous step using the checksum logic specified (if applicable).
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:
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.Validate the packet once the packet satisfying above condition is obtained, using the checksum logic (if applicable).
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.
If the nth 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 nth element of the Variable field lengths is equal to the field length specified.
If the nth 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 nth element of the Variable field lengths is equal to the actual field length obtained.If the nth 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 nth 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.
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
MATLAB 命令
您点击的链接对应于以下 MATLAB 命令:
请在 MATLAB 命令行窗口中直接输入以执行命令。Web 浏览器不支持 MATLAB 命令。
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list:
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)