udpport

Connect to UDP socket

Since R2020b

expand all in page

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

    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.

    example

    Input Arguments

    expand all

    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

    expand all

    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

    This property is read-only.

    Version type for IP address, specified as "IPV4" or "IPV6".

    Example: "IPV6"

    Data Types: char | string

    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

    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

    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

    Time allowed for read and write operations in seconds, specified as a double.

    Example: 20

    Data Types: 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

    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

    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

    Setting to allow broadcasting, specified as logical true (1) or false (0).

    Example: true

    Data Types: logical

    This property is read-only.

    Setting to allow multicast, specified as logical true (1) or false (0).

    Example: true

    Data Types: logical

    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

    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

    Function to call when an error event occurs, specified as a function handle.

    Example: @myErrorFun

    Data Types: function_handle

    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

    This property is read-only.

    Number of bytes available to be read, returned as a double.

    Example: 512

    Data Types: double

    This property is read-only.

    Number of bytes written to udpport socket, returned as a double.

    Example: 48

    Data Types: double

    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

    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

    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

    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

    This property is read-only.

    Number of datagrams available to be read, returned as a double.

    Example: 64

    Data Types: double

    This property is read-only.

    Number of datagrams written to udpport socket, returned as a double.

    Example: 8

    Data Types: double

    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

    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

    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:

    readRead data from UDP socket
    writeWrite data to UDP socket
    configureCallbackSet callback function and trigger condition for communication with UDP socket
    configureMulticastSet multicast properties for communication with UDP socket
    flushClear UDP socket buffers

    Functions for a byte-type udpport interface only:

    readlineRead line of ASCII string data from UDP socket
    writelineWrite line of ASCII data to UDP socket
    configureTerminatorSet terminator for ASCII string communication with UDP socket

    Examples

    collapse all

    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

    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

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

    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 =

     []

    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

    expand all

    See Also

    |

    Topics