Main Content

Use Callbacks for UDP Communication

You can enhance the power and flexibility of your UDP port by using events and callbacks. An event occurs after a condition is met and can result in one or more callbacks.

While MATLAB® is connected to a UDP port, you can use events to display a message, display data, analyze data, and so on. You can control callbacks through callback properties and callback functions. All event types have an associated callback property. Callback functions are MATLAB functions that you write to suit your specific application needs. Execute a callback when a particular event occurs by specifying the name of the callback function as the value for the associated callback property.

Callback Properties

The udpport properties and functions associated with callbacks follow.

Property or FunctionPurpose
NumBytesAvailableNumber of bytes available to read
BytesAvailableFcnBytes available callback function
BytesAvailableFcnCountNumber of bytes of data to trigger callback
BytesAvailableFcnModeBytes available callback trigger mode
NumDatagramsAvailableNumber of datagrams available to read
DatagramsAvailableFcnDatagrams available callback function
DatagramsAvailableFcnCountNumber of datagrams to trigger callback
DatagramsAvailableFcnModeDatagrams available callback trigger mode
configureCallbackSet callback function and trigger condition for communication with UDP port
ErrorOccurredFcnCallback function triggered by error event
UserDataGeneral purpose property for user data

For more information about configuring these properties and functions, see udpport Properties.

Use Byte-Mode Callback with Byte-Type UDP Object

This example shows how to set a callback function to trigger when a certain number of bytes of data are available from a byte-type udpport object.

  1. Create an echo server to connect to from your UDP network socket. An echo server returns the same data that is written to it.

    echoudp("on",4040)
  2. Create the callback function. Define a callback function readUDPData that reads received data and displays it in the command window.

    function readUDPData(src,~)
        src.UserData = src.UserData + 1;
        disp("Callback Call Count: " + num2str(src.UserData))
        data = read(src,src.BytesAvailableFcnCount,"uint8")
    end
    

    Save this as an .m file in the directory that you are working in.

  3. Create a byte-type udpport object u.

    u = udpport("byte","LocalPort",3030)
    u = 
    
      UDPPort with properties:
    
         IPAddressVersion: "IPV4"
                LocalHost: "0.0.0.0"
                LocalPort: 3030
        NumBytesAvailable: 0
    
      Show all properties, functions
    

    Set the UserData property to 0.

    u.UserData = 0;
  4. Configure callback properties to read and display data each time five bytes are received in MATLAB.

    configureCallback(u,"byte",5,@readUDPData)
  5. Write ten bytes of data to trigger the callback function twice.

    write(u,1:10,"localhost",4040)
    Callback Call Count: 1
    
    data =
    
         1     2     3     4     5
    
    Callback Call Count: 2
    
    data =
    
         6     7     8     9    10
    
  6. Clear the udpport object when you are done working with it. Turn off the echo server.

    clear u
    echoudp("off")

Use Terminator-Mode Callback with Byte-Type UDP Object

This example shows how to set a callback function to trigger when a terminator is available to be read from a byte-type udpport object.

  1. Create an echo server to connect to from your UDP network socket. An echo server returns the same data that is written to it.

    echoudp("on",4040)
  2. Create the callback function. Define a callback function readUDPData that reads received data and displays it in the command window

    function readUDPData(src,~)
        src.UserData = src.UserData + 1;
        disp("Callback Call Count: " + num2str(src.UserData))
        data = readline(src)
    end
    

    Save this as an .m file in the directory that you are working in.

  3. Create a byte-type udpport object u.

    u = udpport("byte","LocalPort",3030)
    u = 
    
      UDPPort with properties:
    
         IPAddressVersion: "IPV4"
                LocalHost: "0.0.0.0"
                LocalPort: 3030
        NumBytesAvailable: 0
    
      Show all properties, functions
    

    Set the UserData property to 0.

    u.UserData = 0;
  4. Configure callback properties to read and display data each time ASCII-terminated data is received in MATLAB.

    configureCallback(u,"terminator",@readUDPData)
  5. Write a string to trigger the callback function. The writeline function automatically appends the terminator to the string before it is written to the server.

    writeline(u,"hello","localhost",4040)
    Callback Call Count: 1
    
    data = 
    
        "hello"
    

    Write another string to trigger the callback function a second time.

    writeline(u,"world","localhost",4040)
    Callback Call Count: 2
    
    data = 
    
        "world"
    
  6. Clear the udpport object when you are done working with it. Turn off the echo server.

    clear u
    echoudp("off")

Use Datagram-Mode Callback with Datagram-Type UDP Object

This example shows how to set a callback function to trigger when a certain number of datagrams are available from a datagram-type udpport object.

  1. Create an echo server to connect to from your UDP network socket. An echo server returns the same data that is written to it.

    echoudp("on",4040)
  2. Create the callback function. Define a callback function readUDPData that reads received data and displays it in the command window

    function readUDPData(src,~)
        src.UserData = src.UserData + 1;
        disp("Callback Call Count: " + num2str(src.UserData))
        data = read(src,1,"uint8")
    end
    

    Save this as an .m file in the directory that you are working in.

  3. Create a datagram-type udpport object u.

    u = udpport("datagram","LocalPort",3030)
    u = 
    
      UDPPort with properties:
    
             IPAddressVersion: "IPV4"
                    LocalHost: "0.0.0.0"
                    LocalPort: 3030
        NumDatagramsAvailable: 0
    
      Show all properties, functions
    

    Set the UserData property to 0.

    u.UserData = 0;

    Specify the maximum number of bytes to be written in a datagram packet as ten bytes by setting the OutputDatagramSize property.

    u.OutputDatagramSize = 10;
  4. Configure callback properties to read and display data each time one datagram is received in MATLAB.

    configureCallback(u,"datagram",1,@readUDPData)
  5. Write 30 bytes of data to trigger the callback function three times.

    write(u,1:30,"localhost",4040)
    Callback Call Count: 1
    
    data = 
    
      Datagram with properties:
    
                 Data: [1 2 3 4 5 6 7 8 9 10]
        SenderAddress: "127.0.0.1"
           SenderPort: 4040
    
    Callback Call Count: 2
    
    data = 
    
      Datagram with properties:
    
                 Data: [11 12 13 14 15 16 17 18 19 20]
        SenderAddress: "127.0.0.1"
           SenderPort: 4040
    
    Callback Call Count: 3
    
    data = 
    
      Datagram with properties:
    
                 Data: [21 22 23 24 25 26 27 28 29 30]
        SenderAddress: "127.0.0.1"
           SenderPort: 4040
    
  6. Clear the udpport object when you are done working with it. Turn off the echo server.

    clear u
    echoudp("off")

See Also

|

Related Topics