udpport

Connect to UDP socket

Since R2020b

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

example

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".

example

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".

example

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

expand all

`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

expand all

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

`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

`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()

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 retuned as a cell array. To set this property value, use the configureTerminator function.

Example: "CR/LF"

`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

`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

`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

collapse all

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.

Version History

Introduced in R2020b

udpport

Description

Creation

Syntax

Description

Input Arguments

IPv — IP address version "IPV4" (default) | "IPV6"

Properties

Properties Common to Byte and Datagram udpport Objects

IPAddressVersion — Version type for IP address "IPV4" (default) | "IPV6"

LocalHost — Local host name or IP address string | character vector

LocalPort — Port of local host for binding numeric

ByteOrder — Sequential arrangement of bytes "little-endian" (default) | "big-endian"

Timeout — Time allowed for read and write operations 10 (default) | double

OutputDatagramSize — Maximum number of bytes written in datagram packet 512 (default) | double

EnablePortSharing — Allow other UDP sockets to bind to same local port false (0) (default) | true (1)

EnableBroadcast — Allow broadcasting false (0) (default) | true (1)

EnableMulticast — Allow multicast false (0) (default) | true (1)

MulticastGroup — IP address group to receive multicast data string

EnableMulticastLoopback — Allow looping back if sender is in multicast group true (1) (default) | false (0)

ErrorOccurredFcn — Function to call when error event occurs function handle

UserData — Application-specific data any type

Byte udpport Object Properties

NumBytesAvailable — Number of bytes available to be read double

NumBytesWritten — Number of bytes written to udpport socket double

Terminator — Terminator for ASCII string communication "LF" (default) | "CR" | "CR/LF" | numeric

BytesAvailableFcn — Function called when bytes-available event occurs function handle

BytesAvailableFcnCount — Number of available bytes to trigger event numeric

BytesAvailableFcnMode — Condition for triggering BytesAvailableFcn callback "off" (default) | "byte" | "terminator"

Datagram udpport Object Properties

NumDatagramsAvailable — Number of datagrams available to be read double

NumDatagramsWritten — Number of datagrams written to udpport socket double

DatagramsAvailableFcn — Function called when datagrams-available event occurs function handle

DatagramsAvailableFcnCount — Number of available datagrams to trigger event numeric

DatagramsAvailableFcnMode — Condition for triggering DatagramsAvailableFcn callback "off" (default) | "datagram"

Object Functions

Examples

Send and Receive UDP Bytes

Send and Receive UDP Datagrams

Control Datagram Size

Allow UDP Port Sharing

Version History

See Also

Functions

WeChat

`IPv` — IP address version
`"IPV4"` (default) | `"IPV6"`

Properties Common to Byte and Datagram `udpport` Objects

`IPAddressVersion` — Version type for IP address
`"IPV4"` (default) | `"IPV6"`

`LocalHost` — Local host name or IP address
string | character vector

`LocalPort` — Port of local host for binding
numeric

`ByteOrder` — Sequential arrangement of bytes
`"little-endian"` (default) | `"big-endian"`

`Timeout` — Time allowed for read and write operations
10 (default) | double

`OutputDatagramSize` — Maximum number of bytes written in datagram packet
512 (default) | double

`EnablePortSharing` — Allow other UDP sockets to bind to same local port
`false` (`0`) (default) | `true` (`1`)

`EnableBroadcast` — Allow broadcasting
`false` (`0`) (default) | `true` (`1`)

`EnableMulticast` — Allow multicast
`false` (`0`) (default) | `true` (`1`)

`MulticastGroup` — IP address group to receive multicast data
string

`EnableMulticastLoopback` — Allow looping back if sender is in multicast group
`true` (`1`) (default) | `false` (`0`)

`ErrorOccurredFcn` — Function to call when error event occurs
function handle

`UserData` — Application-specific data
any type

Byte `udpport` Object Properties

`NumBytesAvailable` — Number of bytes available to be read
double

`NumBytesWritten` — Number of bytes written to `udpport` socket
double

`Terminator` — Terminator for ASCII string communication
`"LF"` (default) | `"CR"` | `"CR/LF"` | numeric

`BytesAvailableFcn` — Function called when bytes-available event occurs
function handle

`BytesAvailableFcnCount` — Number of available bytes to trigger event
numeric

`BytesAvailableFcnMode` — Condition for triggering `BytesAvailableFcn` callback
`"off"` (default) | `"byte"` | `"terminator"`

Datagram `udpport` Object Properties

`NumDatagramsAvailable` — Number of datagrams available to be read
double

`NumDatagramsWritten` — Number of datagrams written to `udpport` socket
double

`DatagramsAvailableFcn` — Function called when datagrams-available event occurs
function handle

`DatagramsAvailableFcnCount` — Number of available datagrams to trigger event
numeric

`DatagramsAvailableFcnMode` — Condition for triggering `DatagramsAvailableFcn` callback
`"off"` (default) | `"datagram"`