udpport

Connect to UDP socket

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

u = udpport

u = udpport("byte")

u = udpport(IPv)

u = udpport("byte",IPv)

u = udpport("datagram")

u = udpport("datagram",IPv)

u = udpport(___,Name,Value)

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(IPv) or u = udpport("byte",IPv) constructs a byte-type 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",IPv) constructs a datagram-type udpport object with an IP address version specified by IPv, which can be either "IPV4" or "IPV6".

u = udpport(___,Name,Value) constructs a 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.

Name-Value Arguments

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

Read-only: "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

Read-only: 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

Read-only: 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

Read-only: 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

Read-only: 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

Read-only: 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

Read-only: 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

Read-only: 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

Read-only: 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

Read-only: "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

Read-only: 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

Read-only: 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

Read-only: "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

Read-only: 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

Read-only: 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

Read-only: 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

Read-only: 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

Read-only: "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 R2020b

R2024a: 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.