udpport
Description
The udpport
object allows you to perform byte-type and
datagram-type UDP communication using a UDP socket on the local host.
Creation
Syntax
Description
u = udpport
or u = udpport("byte")
constructs a byte-type udpport
object u
, with an IP
address version set to IPV4, bound to a UDP socket.
u = udpport(
or
IPv
)u = udpport("byte",
constructs a byte-type
IPv
)udpport
object with an IP address version specified by
IPv
, which can be either "IPV4"
or
"IPV6"
.
u = udpport("datagram")
constructs a datagram-type
udpport
object u
, with an IP address version set
to IPV4.
u = udpport("datagram",
constructs a
datagram-type IPv
)udpport
object with an IP address version specified by
IPv
, which can be either "IPV4"
or
"IPV6"
.
u = udpport(___,
constructs a Name,Value
)udpport
object and sets specified object properties using
name-value pair arguments. If you specify an invalid property name or value, the function
does not create the object. udpport
properties that can be set using
name-value pair arguments are LocalHost
,
LocalPort
, Timeout
,
ByteOrder
, OutputDatagramSize
, and
EnablePortSharing
.
Input Arguments
IPv
— IP address version
"IPV4"
(default) | "IPV6"
IP address version, specified as "IPV4"
or
"IPV6"
.
Note
The IP address version must be consistent across your setup. You cannot communicate between an IPV4 socket and IPV6 address, or vice versa.
Specify optional pairs of arguments as
Name1=Value1,...,NameN=ValueN
, where Name
is
the argument name and Value
is the corresponding value.
Name-value arguments must appear after other arguments, but the order of the
pairs does not matter.
Before R2021a, use commas to separate each name and value, and enclose
Name
in quotes.
Properties that support Name-Value arguments are LocalHost
,
LocalPort
, Timeout
,
ByteOrder
, OutputDatagramSize
, and
EnablePortSharing
. Of these, LocalHost
,
LocalPort
, and EnablePortSharing
become
read-only after the udpport
object is created.
Example: "Timeout",60
Properties
Properties Common to Byte and Datagram udpport
Objects
IPAddressVersion
— Version type for IP address
"IPV4"
(default) | "IPV6"
This property is read-only.
Version type for IP address, specified as "IPV4"
or
"IPV6"
.
Example:
"IPV6"
Data Types: char
| string
LocalHost
— Local host name or IP address
string | character vector
This property is read-only.
Local host name or dotted-decimal IP address, specified as a character vector or
string. If you do not specify a value for LocalHost
when you
create the udpport
object, the default value is
"0.0.0.0"
for IPV4, or "::"
for IPV6.
Example:
"144.133.0.0"
Data Types: char
| string
LocalPort
— Port of local host for binding
numeric
This property is read-only.
Port of local host for binding for UDP, specified as a numeric value from 0 to
65535. If you do not specify a value for LocalPort
when you
create the udpport
object, a value is automatically
assigned.
Example:
50791
Data Types: single
| double
| int8
| int16
| int32
| int64
| uint8
| uint16
| uint32
| uint64
ByteOrder
— Sequential arrangement of bytes
"little-endian"
(default) | "big-endian"
Sequential order in which bytes are arranged into larger numerical values,
specified as "little-endian"
or
"big-endian"
.
Example:
"big-endian"
Data Types: char
| string
Timeout
— Time allowed for read and write operations
10 (default) | double
Time allowed for read and write operations in seconds, specified as a double.
Example:
20
Data Types: double
OutputDatagramSize
— Maximum number of bytes written in datagram packet
512 (default) | double
Maximum number of bytes of data to be written in a datagram packet, specified as a double value from 1 to 65507.
Example:
512
Data Types: single
| double
| int8
| int16
| int32
| int64
| uint8
| uint16
| uint32
| uint64
Tag
— Label for identifying connection
""
(default) | string
Since R2024a
Label for identifying the connection, specified as a string. Use
Tag
to apply a label to a connection that you can use later to
access the connection using udpportfind
. Doing so can be useful when you open a socket in one
function and use a different function to communicate with the socket. It is also
useful for locating and accessing connections in app callbacks.
Example: "Sender"
Data Types: string
EnablePortSharing
— Allow other UDP sockets to bind to same local port
false
(0
) (default) | true
(1
)
This property is read-only.
Setting to allow other UDP sockets to bind to the same local port as this socket,
specified as logical true
(1
) or
false
(0
).
Example: true
Data Types: logical
EnableBroadcast
— Allow broadcasting
false
(0
) (default) | true
(1
)
Setting to allow broadcasting, specified as logical true
(1
) or false
(0
).
Example:
true
Data Types: logical
EnableMulticast
— Allow multicast
false
(0
) (default) | true
(1
)
This property is read-only.
Setting to allow multicast, specified as logical true
(1
) or false
(0
).
Example: true
Data Types: logical
MulticastGroup
— IP address group to receive multicast data
string
This property is read-only.
IP address group to subscribe to for receiving multicast data. Set this property
with the configureMulticast
function.
Example:
"226.0.0.1"
Data Types: char
| string
EnableMulticastLoopback
— Allow looping back if sender is in multicast group
true
(1
) (default) | false
(0
)
This property is read-only.
Indicate looping back of data in udpport
multicast if the
sender is subscribed to the same multicast group, specified as a logical. Set this
property with the configureMulticast
function.
Example: false
Data Types: logical
ErrorOccurredFcn
— Function to call when error event occurs
function handle
Function to call when an error event occurs, specified as a function handle.
Example: @myErrorFun
Data Types: function_handle
UserData
— Application-specific data
any type
Application-specific data for this udpport
instance. This is a
general purpose property for user data, specified as any MATLAB® data type. For example, you can use this property to store data when an
event is triggered from a callback function.
Example: datetime()
Data Types: single
| double
| int8
| int16
| int32
| int64
| uint8
| uint16
| uint32
| uint64
| logical
| char
| string
| struct
| table
| cell
| function_handle
| categorical
| datetime
| duration
| calendarDuration
| fi
Byte udpport
Object Properties
NumBytesAvailable
— Number of bytes available to be read
double
This property is read-only.
Number of bytes available to be read, returned as a double.
Example: 512
Data Types: double
NumBytesWritten
— Number of bytes written to udpport
socket
double
This property is read-only.
Number of bytes written to udpport
socket, returned as a
double.
Example:
48
Data Types: double
Terminator
— Terminator for ASCII string communication
"LF"
(default) | "CR"
| "CR/LF"
| numeric
This property is read-only.
Terminator for ASCII-terminated string communication, returned as a string or
numeric value. If the read and write operations have different terminators, the values
are returned as a cell array. To set this property value, use the configureTerminator
function.
Example:
"CR/LF"
Data Types: single
| double
| int8
| int16
| int32
| int64
| uint8
| uint16
| uint32
| uint64
| string
| cell
BytesAvailableFcn
— Function called when bytes-available event occurs
function handle
This property is read-only.
Function called when a bytes-available event occurs, specified as a function
handle. To set this property value, use the configureCallback
function.
Example: @myAvailFun
Data Types: function_handle
BytesAvailableFcnCount
— Number of available bytes to trigger event
numeric
This property is read-only.
Number of bytes required in the input buffer to trigger a bytes-available event,
returned as a numeric value. This property applies only when
BytesAvailableFcnMode
is "byte"
. To set this
property value, use the configureCallback
function.
Example: 64
Data Types: single
| double
| int8
| int16
| int32
| int64
| uint8
| uint16
| uint32
| uint64
BytesAvailableFcnMode
— Condition for triggering BytesAvailableFcn
callback
"off"
(default) | "byte"
| "terminator"
This property is read-only.
Condition for triggering BytesAvailableFcn
callback, returned
as "off"
, "byte"
, or
"terminator"
. To set this property value, use the configureCallback
function.
Example:
"byte"
Data Types: string
Datagram udpport
Object Properties
NumDatagramsAvailable
— Number of datagrams available to be read
double
This property is read-only.
Number of datagrams available to be read, returned as a double.
Example: 64
Data Types: double
NumDatagramsWritten
— Number of datagrams written to udpport
socket
double
This property is read-only.
Number of datagrams written to udpport
socket, returned as a
double.
Example:
8
Data Types: double
DatagramsAvailableFcn
— Function called when datagrams-available event occurs
function handle
This property is read-only.
Function called when a datagrams-available event occurs, returned as a function
handle. To set this property value, use the configureCallback
function.
Example: @myAvailFcn
Data Types: function_handle
DatagramsAvailableFcnCount
— Number of available datagrams to trigger event
numeric
This property is read-only.
Number of available datagrams to trigger a datagrams-available event, returned as
a numeric value. This property applies only when
BytesAvailableFcnMode
is "datagram"
. To set
this property value, use the configureCallback
function.
Example: 16
Data Types: single
| double
| int8
| int16
| int32
| int64
| uint8
| uint16
| uint32
| uint64
DatagramsAvailableFcnMode
— Condition for triggering DatagramsAvailableFcn
callback
"off"
(default) | "datagram"
This property is read-only.
Condition for triggering a DatagramsAvailableFcn
callback,
returned as "off"
or "datagram"
. To set this
property value, use the configureCallback
function.
Example:
"datagram"
Data Types: string
Object Functions
Functions for byte-type and datagram-type udpport
interfaces:
read | Read data from UDP socket |
write | Write data to UDP socket |
configureCallback | Set callback function and trigger condition for communication with UDP socket |
configureMulticast | Set multicast properties for communication with UDP socket |
flush | Clear UDP socket buffers |
Functions for a byte-type udpport
interface only:
readline | Read line of ASCII string data from UDP socket |
writeline | Write line of ASCII data to UDP socket |
configureTerminator | Set terminator for ASCII string communication with UDP socket |
Examples
Send and Receive UDP Bytes
This example shows common tasks of byte-type UDP communication.
Construct a byte-type udpport
object.
u = udpport("IPV4")
u = UDPPort with properties: IPAddressVersion: "IPV4" LocalHost: "0.0.0.0" LocalPort: 60825 NumBytesAvailable: 0
Write a vector of uint8
data via the udpport
socket to a specified address and port.
write(u,1:5,"uint8","125.0.1.4",2020);
Read 10 values of uint16
data from the udpport
socket.
data = read(u,10,"uint16");
Define the terminator, and send a string via the udpport
socket
to a specified address and port.
configureTerminator(u,"CR/LF"); writeline(u,"hello","125.0.1.4",2020);
Read an ASCII-terminated string from the udpport
socket.
data = readline(u);
Subscribe to a multicast address group.
configureMulticast(u,"226.0.0.1");
Configure a callback to trigger when 50 bytes are available.
configureCallback(u,"byte",50,@myCallbackFcn);
Flush the output buffer, then disconnect and clear the udpport
connection.
flush(u,"output"); clear u
Send and Receive UDP Datagrams
This example shows common tasks of datagram-type UDP communication.
Construct a datagram-type udpport
object.
u = udpport("datagram","IPV4")
u = UDPPort with properties: IPAddressVersion: "IPV4" LocalHost: "0.0.0.0" LocalPort: 53465 NumDatagramsAvailable: 0
Write a vector of uint8
data via the udpport
socket to a specified address and port.
write(u,1:5,"uint8","125.0.1.4",2020);
Read one datagram packet as uint16
data.
data = read(u,1,"uint16");
Subscribe to a multicast address group.
configureMulticast(u,"226.0.0.1");
Configure a callback to trigger when 5 datagrams are available.
configureCallback(u,"datagram",5,@myCallbackFcn);
Flush the output buffer, then disconnect and clear the udpport
connection.
flush(u,"output"); clear u
Control Datagram Size
This example shows how datagram size affects data segmentation.
Turn echoudp
on at port 3030, then create a datagram-type
udpport
object with an OutputDatagramSize
of
5.
echoudp("on",3030); u = udpport("datagram","OutputDatagramSize",5);
Send 20 bytes of uint8
data to the echoudp
port.
write(u,1:20,"uint8","127.0.0.1",3030);
Because OutputDatagramSize
is set to 5, the 20 bytes are sent
as 4 datagram packets, each containing 5 bytes of data.
Verify that 4 datagrams were received from the echo server.
u.NumDatagramsAvailable
ans = 4
Read the 4 datagrams received from the echo server.
data = read(u,u.NumDatagramsAvailable,"uint8")
data = 1×4 Datagram array with properties: Data SenderAddress SenderPort
The first datagram contains the values 1-5 (5 bytes), the second 6-10, the third 11-15, and the fourth 16-20.
View the third datagram.
data(3)
ans = Datagram with properties: Data: [11 12 13 14 15] SenderAddress: "127.0.0.1" SenderPort: 3030
Allow UDP Port Sharing
Allow multiple udpport
objects to share the same
local port.
Create a udpport
object bound to LocalPort
3030.
u1 = udpport("LocalPort",3030,"EnablePortSharing",true);
Create a separate udpport
object using the same port.
u2 = udpport("LocalPort",3030,"EnablePortSharing",true);
EnablePortSharing
must be true
for both
udpport
objects.
Disconnect Single UDP Socket Connection
When you use udpport
in a script or at the
MATLAB command line, the result is a connection represented by an object in the
MATLAB workspace.
U = udpport("datagram",LocalPort=3030,Tag="Receiver");
U = UDPPort with properties: IPAddressVersion: "IPV4" LocalHost: "0.0.0.0" LocalPort: 3030 Tag: "Receiver" NumDatagramsAvailable: 0
When no references to the same connection exist in other variables, you can disconnect the UDP port by clearing the workspace variable.
clear(U)
Use udpportfind
to confirm that the connection is closed.
udpportfind
ans = []
Disconnect UDP Socket Connections in Functions or App Callbacks
When you have a udpport
connection that exists in the
MATLAB workspace or is saved as a class property or app property, the
udpport
object might not be accessible in a different function or app
callback. In this case, you can use udpportfind
to find and delete the
connection.
U = udpportfind
U = UDPPort with properties: IPAddressVersion: "IPV4" LocalHost: "0.0.0.0" LocalPort: 3030 Tag: "Receiver" NumDatagramsAvailable: 0
To close this connection, delete U
.
delete(U)
This command deletes the udpport
object and disconnects the device. If
you want to reconnect to the device, you must create a new connection with
udpport
.
After the deletion, calling udpportfind
confirms that there are no
existing connections.
udpportfind
ans = []
Note that the variable U
is still present in the workspace, but it is
now an invalid handle.
U
U = handle to deleted UDPPort
The variable persists after deletion of the interface because udpport
is a handle object. (For more information about this type of object,
see Handle Object Behavior.) You can use clear
to remove the invalid handle from the
workspace.
clear U
Version History
Introduced in R2020bR2024a: New Tag
Property
Use the new Tag
property to apply a label to a UDP socket connection
that you can use later to access the connection using udpportfind
.
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)