WiFi UDP Receive

R2026b

Receive data from UDP host on wireless network

Libraries:
Simulink Support Package for Arduino Hardware / WiFi

Description

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

The WiFi UDP Receive block receives data from a UDP host on a wireless network. At each sample time, the block outputs data as a vector of the size specified in the Data size (N) parameter. The block receives data on the port number specified in the Local IP Port parameter. Match the port number specified in the Local IP Port parameter with the remote port number on the sending host.

The block supports reception of both fixed and variable-length UDP packets. The block also supports blocking mode, allowing you to wait for incoming UDP data up to a specified timeout.

Note

If you are having trouble using UDP to communicate with a computer, antivirus or firewall software might be blocking UDP traffic. If so, configure the software to allow the traffic for a specific IP port number.

You can run a model containing WiFi UDP Receive block in connected IO mode on Arduino^® boards.

For more information about the fixed ports and the allocated pins for the block, see Pin Mapping for Arduino Timer-Independent Blocks.

Supported Hardware

You can use the WiFi UDP Receive block only with the following hardware:

ESP8266
WiFi Shield
MKR1000
MKR WIFI 1010
Nano 33 IoT
ESP32–S3 series (Arduino compatible)
ESP32–WROOM (Arduino compatible)
ESP32–WROVER (Arduino compatible)

Limitations

When using ESP8266 hardware, a model can have only one of these blocks: WiFi TCP/IP Receive, WiFi TCP/IP Send, WiFi UDP Send, WiFi UDP Receive block.
The maximum number of connections allowed for different ports on WiFi UDP Receive and WiFi TCP/IP Send blocks in a model is two for WiFi shield, four for boards with on-board Wi-Fi^®, and one for ESP8266. If the model uses external mode over Wi-Fi or includes a WiFi ThingSpeak Read or WiFi ThingSpeak Write block, one UDP port is reserved for each from the maximum allowed connections.

Ports

Output

expand all

Data — Output data
vector

In fixed-length mode, the block outputs a vector of the size as you define in the Data size (N) parameter.

In the variable-length mode, the block outputs the received bytes up to Maximum data size and the Size port outputs the actual number of bytes the block receives.

The port receives the in the little-endian format. To convert it to a big-endian format, do any of the following:

Place a Byte Reversal block immediately after the WiFi UDP Receive block.
Apply the swapbytes function in a MATLAB Function block and place the block immediately after the WiFi UDP Receive block.

For more information, see Block Outputs for Fixed Length of Received Data.

Size — Number of data bytes received
scalar

At each sample time, the port outputs the number of bytes in the received data. For more information, see Block Outputs for Fixed Length of Received Data.

Data Types: uint16

Status — Receiver operation status
scalar

The port outputs the status of the most recent receiver operation.

1 — Packet received (both, blocking and non-blocking modes)
0 — No packet available (non-blocking mode)
-1 — Timeout (blocking mode)

Data Types: int8

Parameters

expand all

Local IP Port — IP port on receiving host from which data is received
`50001` (default) | [1 to 65,535]

Port number of the application on which you want to receive data.

Match the local port number with the remote port number on the sending host.

Data type — Data type of received data
`uint8` (default) | `double` | `single` | `int8` | `int16` | `uint16` | `int32` | `uint32` | `boolean`

Type of the block receives from the sending host.

The size of each element depends on its data type.

Enable variable length data — Enable variable length packet reception
`off` (default) | `on`

Allow the block to process variable-length UDP data instead of a fixed-length payload. The block adjusts to the actual number of bytes available during the current read operation.

Enabling this parameter on the receiver side allows the block to output only the actual bytes in the UDP receiver packet.

To use variable-length UDP transmission and reception in a model, you must enable this parameter on both the WiFi UDP Receive and WiFi UDP Send blocks.

Data size (N) — Number of bytes in received data
`1` (default) | any positive integer

Number of bytes received at each sample time.

The maximum number of bytes the block receives at each sample time is shown in the table.

Target Hardware	ESP8266	WiFi Shield	Arduino On-board Wi-Fi Boards
Maximum Number of Received Bytes	40	64	1400

Dependencies

To enable this parameter, clear Enable variable length data.

Maximum data size (N) — Upper limit on number of bytes in received data
`1` (default) | positive integer ≥ `1`

Maximum number of bytes the block stores and outputs in the variable-length mode.

For the variable-length mode, the incoming UDP packet may contain a different number of bytes at each time step. The block allocates a buffer of the size you specify in the Maximum data size (N) parameter. The Size port outputs the actual number of bytes received during that step up to the maximum data size limit.

Dependencies

To enable this parameter, select Enable variable length data.

Enable blocking mode — Make receiver wait until a UDP packet is available on port or timeout elapses
`off` (default) | `on`

Make the receiver operation block execution until at least one UDP message is available on the block input port or till the timeout elapses while waiting for a packet.

Timeout (ms) — Maximum wait time before a blocked receive operation times out
`2` (default) | non-negative integer

Time limit on how long the block must wait for data on the input port when blocking mode is enabled.

Dependencies

To enable this parameter, select Enable blocking mode.

Sample time — Interval at which block reads data from sending host
`0.1` (default) | `-1` | any nonnegative value

When you set this parameter to -1, Simulink^® determines the best sample time for the block based on the block context within the model. When the hardware is ESP8266, the minimum sample time allowed is 0.01 seconds. Otherwise, it is 0.000001 seconds (1 microsecond).

More About

expand all

Blocking and Non-Blocking Behavior

The WiFi UDP Receive block can operate in either blocking mode or non-blocking mode, depending on whether Enable blocking mode is selected.

This flow chart summarized how the block decides when to output data, when to hold the previous data values, and how the Status port reflects packet availability at the Data port.

Flow chart for Blocking and Non-Blocking Mode

Non-Blocking Mode — The block does not wait for UDP data. At each time step, it immediately checks if a packet is available.
- If a packet is available, the block outputs the new packet and sets Status to 1.
- If no packet is available, the block holds the previous data and sets Status to 0.
Blocking Mode — The block waits for a packet to arrive for up to the duration specified in Timeout (ms).
- If a packet arrives before the timeout, the block outputs data and sets Status to 1.
- If no packet arrives before the timeout, the block holds the previous data, sets Status to -1, completes the step.

Block Outputs for Fixed Length of Received Data

This section explains the values at the output ports, with the following block parameters specified as:

Block Parameter	Value
Data type	`uint8`
Enable variable length data	`off`
Data size (N)	`4`

The values at the output ports vary depending on whether the length of the data received is less than, greater than, or equal to the length of requested data.

Length of UDP message received = Data size (N)
The Data port outputs data as a vector of the size specified in the Data size (N) parameter. The Size port outputs the number of data bytes received.
Suppose that the length of the data received is 4. In this case, the Data port outputs a data vector of size 4. The Size port outputs 4.
Length of UDP message received < Data size (N)
The Data port outputs data as a vector of the size specified in the Data size (N) parameter. All the empty spaces in the vector are filled with zeros. The Size port outputs the number of data bytes received (excluding zeros added to fill the vector).
Suppose that the length of data received is 3. In this case, the Data port outputs a data vector of size 4. The first three values in the vector are the bytes from the received data. The remaining space is filled with zero. The Size port outputs 4.
Length of UDP message received > Data size (N)
The Data port outputs a data vector of the size specified in the Data size (N) parameter. The vector contains only the first N bytes from the received data. The remaining data bytes are dropped. The Size port outputs the number of data bytes received (including the output data bytes and the dropped data bytes).
Suppose that the length of data received is 5. In this case, the Data port outputs a data vector of size 4. The vector contains only the first 4 bytes from the received data. The remaining data byte is dropped. The Size port outputs 4.

Block Outputs for Variable Length of Received Data

This section explains the values at the output ports, with the following block parameters specified as:

Block Parameter	Value
Data type	`uint8`
Enable variable length data	`on`
Maximum data size (N)	`4`

For the variable data length mode, the block outputs only the actual bytes it receives in the current UDP packet up to the maximum data size. The Size port outputs the number of valid bytes received at that time step. The Status port outputs the status of whether the block received a new packet (1), no packet available in the non-blocking mode (0), or the read operation timed-out in the blocking mode (-1).

Length of UDP message received ≤ Maximum data size (N)
The Data port outputs a vector whose length equals the actual number of bytes received in the current packet. The Size port outputs the same number of bytes (actual count). In the non-blocking mode, the status is 1 when a packet is available in the current time step, otherwise the status is 0. In the blocking mode, the status is 1 if a packet arrives before timeout, otherwise the status is -1.
Suppose that the length of the data received is 4 (equal to Maximum data size).
- The Data port outputs a vector of size 4 containing the 4 received bytes.
- The Size port outputs 4.
- Status is 1 if the packet arrived in the current time step. Otherwise, it is either 0 in the non-blocking mode or -1 in the blocking mode.
Suppose that the length of data received is 3.
- The Data port outputs a vector of size 3 (no zero padding).
- The Size port outputs 3.
- Status is 1 if the packet arrived in the current time step. Otherwise, it is either 0 in the non-blocking mode or -1 in the blocking mode.
Length of UDP message received > Maximum data size (N)
The Data port outputs a vector of Maximum data size (N) containing the first 4 bytes of the received packet while, the remaining bytes are dropped at the output. The Size port outputs the total number of bytes received in the packet, including the dropped bytes. In the non-blocking mode, the status is 1 when a packet is available in the current time step, otherwise the status is 0. In the blocking mode, the status is 1 if a packet arrives before timeout, otherwise the status is -1.
Suppose that the length of the data received is 5.
- The Data port outputs a vector of size 4 containing the 4 received bytes. The fifth byte is dropped at the output.
- The Size port outputs 4.
- Status is 1 if the packet arrived in the current time step. Otherwise, it is either 0 in the non-blocking mode or -1 in the blocking mode.

Version History

Introduced in R2014a

expand all

R2026b: Add support for variable length UDP payloads and blocking mode

The block receives both fixed and variable length UDP packets. The block also supports blocking and non-blocking modes allowing you to either wait for incoming data up to a specified timeout or do not wait when no packet is available.

WiFi UDP Receive