Read and Write ASCII Data over UDP

This section provides details and examples exploring ASCII read and write operations with a UDP object.

Functions and Properties

These functions are used when reading and writing text:

FunctionPurpose
fprintfWrite text to the server.
fscanfRead data from the server and format as text.

These properties are associated with reading and writing text:

PropertyPurpose
ValuesReceivedSpecifies the total number of values read from the server.
ValuesSentSpecifies the total number of values sent to the server.
InputBufferSizeSpecifies the total number of bytes that can be queued in the input buffer at one time.
OutputBufferSizeSpecifies the total number of bytes that can be queued in the output buffer at one time.
TerminatorCharacter used to terminate commands sent to the server.

Note

To get a list of options you can use on a function, press the Tab key after entering a function on the MATLAB® command line. The list expands, and you can scroll to choose a property or value. For information about using this advanced tab completion feature, see Using Tab Completion for Functions.

Configuring and Connecting to the Server

For this example, we will use an echo server that is provided with the toolbox. The echo server allows you to experiment with the basic functionality of the UDP objects without connecting to an actual device. An echo server is a service that returns to the sender's address and port, the same bytes it receives from the sender.

echoudp('on', 8000)

You need to create a UDP object. In this example, create a UDP object associated with the host 127.0.0.1 (your local machine), port 8000. In general, the host name or address and the host port will be defined by the device and your network configuration.

u = udp('127.0.0.1', 8000);

Before you can perform a read or write operation, you must connect the UDP object to the server with the fopen function.

fopen(u)

If the object was successfully connected, its Status property is automatically configured to open.

u.Status
ans = 
    open

Note

UDP ports can be shared by other applications to allow for multiple applications to listen to the UDP datagrams on that port. This allows for the ability to listen to UDP broadcasts on the same local port number in both MATLAB and other applications. You can enable and disable this capability with a new property of the UDP object called EnablePortSharing. See Enable Port Sharing over UDP.

Writing ASCII Data

You use the fprintf function to write ASCII data to the server. For example, write a string to the echoserver.

fprintf(u, 'Request Time');

By default, the fprintf function operates in a synchronous mode. This means that fprintf blocks the MATLAB command line until one of the following occurs:

  • All the data is written

  • A timeout occurs as specified by the Timeout property

By default the fprintf function writes ASCII data using the %s\n format. All occurrences of \n in the command being written to the server are replaced with the Terminator property value. When using the default format, %s\n, all commands written to the server will end with the Terminator character.

For the previous command, the linefeed (LF) is sent after 'Request Time' is written to the server, thereby indicating the end of the command.

You can also specify the format of the command written by providing a third input argument to fprintf. The accepted format conversion characters include: d, i, o, u, x, X, f, e, E, g, G, c, and s.

For example, the data command previously shown can be written to the server using two calls to fprintf.

fprintf(u, '%s', 'Request');
fprintf(u, '%s'\n, 'Time');

The Terminator character indicates the end of the command and is sent after the last call to fprintf.

ASCII Write Properties

The OutputBufferSize property specifies the maximum number of bytes that can be written to the server at once. By default, OutputBufferSize is 512.

u.OutputBufferSize
ans = 
    512

If the command specified in fprintf contains more than 512 bytes, an error is returned and no data is written to the server.

The ValuesSent property indicates the total number of values written to the server since the object was connected to the server.

u.ValuesSent
ans = 
    26

Remove any data that was returned from the echoserver and captured by the UDP object.

flushinput(u);

Reading ASCII Data

UDP sends and receives data in blocks that are called datagrams. Each time you write or read data with a UDP object, you are writing or reading a datagram. For example, a datagram with 13 bytes (12 ASCII bytes plus the LF terminator) is sent to the echoserver.

fprintf(u, 'Request Time');

The echo server will send back a datagram containing the same 13 bytes.

u.BytesAvailable
ans = 
    13

You use the fscanf function to read ASCII data from the server.

data = fscanf(u)
data = 
    Request Time

By default, the fscanf function reads data using the '%c' format and blocks the MATLAB command line until one of the following occurs:

  • The terminator is received as specified by the Terminator property (if DatagramTerminateMode is off)

  • A timeout occurs as specified by the Timeout property

  • The input buffer is filled

  • The specified number of values is read (if DatagramTerminateMode is off)

  • A datagram has been received (if DatagramTerminateMode is on)

You can also specify the format of the data read by providing a second input argument to fscanf. The accepted format conversion characters include: d, i, o, u, x, X, f, e, E, g, G, c, and s.

For example, the character vector'0.80' sent to the echoserver can be read into MATLAB as a double using the %f format character vector.

fprintf(u, '0.80');
data = fscanf(u, '%f')
data = 
    0.8000

isnumeric(data)
ans = 
    1

ASCII Read Properties

The DatagramTerminateMode property indicates whether a read operation should terminate when a datagram is received. By default DatagramTerminateMode is on, which means that a read operation terminates when a datagram is received. To read multiple datagrams at once, you can set DatagramTerminateMode to off. In this example, two datagrams are written. Note, only the second datagram sends the Terminator character.

fprintf(u, '%s', 'Request Time');
fprintf(u, '%s\n', 'Request Time'); 

Since DatagramTerminateMode is off, fscanf will read across datagram boundaries until the Terminator character is received.

u.DatagramTerminateMode = 'off';
data = fscanf(u)
data = 
    Request TimeRequest Time

The InputBufferSize property specifies the maximum number of bytes you can read from the server. By default, InputBufferSize is 512.

u.InputBufferSize
ans = 
    512

The ValuesReceived property indicates the total number of values read from the server, including the terminator.

u.ValuesReceived
ans = 
    43

Cleanup

If you are finished with the UDP object, disconnect it from the server, remove it from memory, and remove it from the workspace. If you are using the echo server, turn it off.

fclose(u);
delete(u);
clear u
echoudp('off');