dsp.UDPReceiver
Receive UDP packets from the network
Description
The dsp.UDPReceiver
System object™ receives UDP packets over a UDP network from an IP address specified in the
RemoteIPAddress
property. The object then saves the data to its
internal buffer. The amount of data (number of elements) received in each UDP packet can vary.
The maximum number of bytes the object can receive without losing data is set by the
ReceiveBufferSize
property. The
MaximumMessageLength
property specifies the maximum number of samples
each data packet can contain. The LocalIPPort
on which the object
receives the data is tunable in generated code but not tunable during simulation. For an
example, see Tune the UDP Port Number in MATLAB.
Due to the nature of the UDP transmission protocol, the receiver is not guaranteed to
receive all the data packets that you send using the dsp.UDPSender
object.
To receive UDP packets from the network:
Create the
dsp.UDPReceiver
object and set its properties.Call the object with arguments, as if it were a function.
To learn more about how System objects work, see What Are System Objects?
Creation
Properties
Unless otherwise indicated, properties are nontunable, which means you cannot change their
values after calling the object. Objects lock when you call them, and the
release
function unlocks them.
If a property is tunable, you can change its value at any time.
For more information on changing property values, see System Design in MATLAB Using System Objects.
LocalIPPort
— Local port on which to receive data
25000
(default) | [1, 65535]
Port on which to receive the data, specified as a scalar in the range [1, 65535]. This property is tunable in generated code but not tunable during simulation.
Data Types: single
| double
| int8
| int16
| int32
| int64
| uint8
| uint16
| uint32
| uint64
RemoteIPAddress
— Address from which to accept data
'0.0.0.0'
(default) | character vector containing a valid IP address | string scalar
Address from which to accept data, specified as a character vector or a string
scalar containing a valid IP address. Entering a specific IP address blocks UDP packets
from other addresses. The default, '0.0.0.0'
, indicates that the data
can be accepted from any remote IP address.
Data Types: char
ReceiveBufferSize
— Size of internal buffer
8192
bytes (default) | [1, 67108864]
Size of the internal buffer that receives UDP packets, specified in bytes as a
scalar in the range [1, 67108864]
. If the number of bytes received
exceeds this value, the buffer overflows and the contents are truncated.
Data Types: single
| double
| int8
| int16
| int32
| int64
| uint8
| uint16
| uint32
| uint64
MaximumMessageLength
— Maximum size of output message
255
(default) | [1, 65507]
Maximum length of the output message, specified in samples as a positive scalar in the range [1, 65507]. Set this property to a value equal to or greater than the data size of the UDP packet. If you receive more samples than specified in this property, the excess data is truncated.
Data Types: single
| double
| int8
| int16
| int32
| int64
| uint8
| uint16
| uint32
| uint64
MessageDataType
— Data type of the message
'uint8'
(default) | 'double'
| 'single'
| 'int8'
| 'int16'
| 'uint16'
| 'int32'
| 'uint32'
| 'logical'
Data type of the vector elements in the message output, specified as a MATLAB® built-in data type.
Match the data type with the data input used to create the UDP packets.
Data Types: char
IsMessageComplex
— Complexity of message
false
(default) | true
Complexity of the message, specified as either true
or
false
.
Set this property to true
if the received message is complex. Set
the property to false
if the received message is real.
Data Types: logical
Usage
Syntax
Output Arguments
dataR
— Data received
scalar | vector
Data received from the network, returned as one packet. The MaximumMessageLength property specifies the maximum number of bytes each data packet can contain. Length of the data received is the number of bytes received from the network.
The data is received as complex data if the IsMessageComplex
property is set to true
.
If the packet gets dropped during transmission and the receiver does not receive
the packet, the dataR
output is empty.
Data Types: single
| double
| int8
| int16
| int32
| uint8
| uint16
| uint32
| logical
Complex Number Support: Yes
Object Functions
To use an object function, specify the
System object as the first input argument. For
example, to release system resources of a System object named obj
, use
this syntax:
release(obj)
Examples
Byte Transmission Using UDP
Send and receive UDP packets using the dsp.UDPSender
and dsp.UDPReceiver
System objects. Calculate the number of bytes successfully transmitted.
Set the RemoteIPPort
of UDP sender and the LocalIPPort
of the UDP receiver to 31000
. Set the length of the data vector to 128
samples, which is less than the value of the MaximumMessageLength
property of the receiver. To prevent the loss of packets, call the setup
method on the receiver object before the first call to the object algorithm.
udpr = dsp.UDPReceiver('LocalIPPort',31000); udps = dsp.UDPSender('RemoteIPPort',31000); setup(udpr); bytesSent = 0; bytesReceived = 0; dataLength = 128;
In each loop of iteration, send and receive a packet of data. At the end of the loop, use the fprintf
function to print the number of bytes sent by the sender and the number of bytes received by the receiver.
for k = 1:20 dataSent = uint8(255*rand(1,dataLength)); bytesSent = bytesSent + dataLength; udps(dataSent); dataReceived = []; while (isempty(dataReceived)) dataReceived = udpr(); end bytesReceived = bytesReceived + length(dataReceived); end release(udps); release(udpr); fprintf('Bytes sent: %d\n', bytesSent);
Bytes sent: 2560
fprintf('Bytes received: %d\n', bytesReceived);
Bytes received: 2560
Tune the UDP Port Number in MATLAB
The local IP port number of the dsp.UDPReceiver
object and the remote IP port number of the dsp.UDPSender
object are tunable in the generated code. Generate a MEX file from the receiver
function which contains the algorithm to receive sine wave data over a UDP network. Change the remote IP port number of the UDP receiver without regenerating the MEX file. Verify the number of bytes sent and received over the network.
Note: This example runs only in R2017a or later.
The input to the receiver
function is the local IP port number of the dsp.UDPReceiver
System object™. The output of this function is the number of bytes received from the UDP network.
type receiver
function [bytesReceived] = receiver(portnumber) persistent udpRx if isempty(udpRx) udpRx = dsp.UDPReceiver('MessageDataType','double'); end udpRx.LocalIPPort = portnumber; dataReceived = udpRx(); bytesReceived = length(dataReceived);
The dsp.UDPSender
object with remoteIPPort
number set to 65000 sends the data over the UDP network. The dsp.UDPReceiver
object with LocalIPPort
number set to 65000 receives the data from the UDP network. The data is a sine wave containing 250 samples per frame.
portnumber = 65000; udpSend = dsp.UDPSender('RemoteIPPort',portnumber); sine = dsp.SineWave('SamplesPerFrame',250); bytesSent = 0; bytesReceived = 0; dataLength = 250; for i = 1:10 dataSent = sine(); bytesSent = bytesSent + dataLength; udpSend(dataSent); bytesReceived = bytesReceived + receiver(portnumber); end fprintf('Number of bytes sent: %d', bytesSent);
Number of bytes sent: 2500
fprintf('Number of bytes received: %d', bytesReceived);
Number of bytes received: 2250
The data is sent and received successfully over the UDP network. The initial data is dropped due to overhead.
Generate a MEX file from the receiver.m
function.
codegen receiver -args {65000}
Code generation successful.
Release the sender and change the RemotePort
number to 25000. The LocalIPPort
number of the receiver continues to be 65000. Since the port numbers are different, the data is not transmitted successfully.
release(udpSend) portnumberTwo = 25000; udpSend.RemoteIPPort = portnumberTwo; bytesReceived = 0; bytesSent = 0; for i = 1:10 dataSent = sine(); bytesSent = bytesSent + dataLength; udpSend(dataSent); bytesReceived = bytesReceived + receiver_mex(portnumber); end fprintf('Number of bytes sent: %d', bytesSent);
Number of bytes sent: 2500
fprintf('Number of bytes received: %d', bytesReceived);
Number of bytes received: 0
Clear the MEX file and change the local IP port number of the receiver to 25000. Clearing the MEX enables the receiver port number to change without having to regenerate the MEX. The port numbers of the sender and receiver match. Verify if the data is transmitted successfully.
clear mex %#ok bytesReceived = 0; bytesSent = 0; for i = 1:10 dataSent = sine(); bytesSent = bytesSent + dataLength; udpSend(dataSent); bytesReceived = bytesReceived + receiver_mex(portnumberTwo); end fprintf('Number of bytes sent: %d', bytesSent);
Number of bytes sent: 2500
fprintf('Number of bytes received: %d', bytesReceived);
Number of bytes received: 2250
The data is transmitted successfully over the UDP network. The initial data is dropped due to overhead.
Transmit Complex Data over UDP Network
Compute the STFT of a sine wave and transmit the complex STFT data over a UDP network. At the receiver side, compute the ISTFT of the received data. Visualize the data sent and the data received using a time scope.
The dsp.UDPSender
object can send complex data. In order to enable the dsp.UDPReceiver
object to receive complex data, set the IsMessageComplex
property to true
.
udps = dsp.UDPSender('RemoteIPPort',31000); udpr = dsp.UDPReceiver('LocalIPPort',31000,... 'IsMessageComplex',true,... 'MessageDataType','double'); setup(udpr); bytesSent = 0; bytesReceived = 0; dataLength = 128;
Initialize the dsp.STFT
and dsp.ISTFT
System objects with a periodic hann
window of length 120 samples and an overlap length of 60 samples. Set the FFT length to 128.
winLen = 120; overlapLen = 60; frameLen = winLen-overlapLen; stf = dsp.STFT(... 'Window',hann(winLen,'periodic'),... 'OverlapLength',overlapLen,'FFTLength',128); istf = dsp.ISTFT(... 'Window',hann(winLen,'periodic'),... 'OverlapLength',overlapLen,... 'WeightedOverlapAdd',0);
The input is a sinusoidal signal with a frequency of 100 Hz, a sample rate of 1000 Hz, and with 60 samples per each signal frame.
sine = dsp.SineWave(... 'SamplesPerFrame',winLen-overlapLen,... 'Frequency',100);
Initialize a timescope
object with a sample rate of 1000 Hz and a time span of 0.09. The Delay
object corrects the overlap length while comparing the input with the reconstructed output signal.
ts = timescope('SampleRate',1000,... 'ShowLegend',true,... 'YLimits',[-1 1],... 'TimeSpanSource','Property',... 'TimeSpan',.09,... 'ChannelNames',{'Input','Reconstructed'}); dly = dsp.Delay('Length',overlapLen);
Transmit complex STFT data of the sine wave over the UDP network. Due to the undependable nature of the UDP protocol, the data packets can get lost during transmission. The receiver is not guaranteed to receive all the data that you send.
Compute the ISTFT of the received data. Compare the input x
to the reconstructed output y
. Due to the latency introduced by the objects, the reconstructed output is shifted in time compared to the input. Therefore, to compare, take the norm of the difference between the reconstructed output y
and the previous input, xprev
.
Visualize the signals using a time scope. You can see that the reconstructed signal overlaps very closely with the input signal.
n = zeros(1,1e3); xprev = 0; for k = 1:1e3 x = sine(); X = stf(x); bytesSent = bytesSent + length(X); udps(X); dataReceived = []; while (isempty(dataReceived)) dataReceived = udpr(); end if (~isempty(dataReceived)) y = istf(dataReceived); end n(1,k) = norm(y-xprev); xprev = x; bytesReceived = bytesReceived + length(dataReceived); ts([dly(x),y]); end
The norm of the difference is very small, indicating that the output signal is a perfectly reconstructed version of the input signal.
max(abs(n))
ans = 6.1244e-14
Release the UDP objects.
release(udps); release(udpr);
Some of the packets sent can be lost during transmission due to the lossy nature of the UDP protocol. To check for loss, compare the bytes sent to the bytes received.
fprintf('Bytes sent: %d\n', bytesSent);
Bytes sent: 128000
fprintf('Bytes received: %d\n', bytesReceived);
Bytes received: 128000
Extended Capabilities
C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.
Usage notes and limitations:
System Objects in MATLAB Code Generation (MATLAB Coder)
The executable generated from this System object relies on prebuilt dynamic library files (
.dll
files) included with MATLAB. Use thepackNGo
function to package the code generated from this object and all the relevant files in a compressed zip file. Using this zip file, you can relocate, unpack, and rebuild your project in another development environment where MATLAB is not installed. For more details, see How To Run a Generated Executable Outside MATLAB.The
LocalIPPort
property is tunable in generated code but not tunable during simulation.
Version History
Introduced in R2012a
MATLAB Command
You clicked a link that corresponds to this MATLAB command:
Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.
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)