Read and Write Binary Data over UDP

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

Functions and Properties

These functions are used when reading and writing binary data:

FunctionPurpose
freadRead binary data from the instrument or server.
fwriteWrite binary data to the instrument or server.

These properties are associated with reading and writing binary data:

PropertyPurpose
ValuesReceivedSpecifies the total number of values read from the instrument or server.
ValuesSentSpecifies the total number of values sent to the instrument or 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.
DatagramTerminateMode Defines how fread and fscanf read operations terminate.

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);

You may need to configure the OutputBufferSize of the UDP object. 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 fwrite contains more than 512 bytes, an error is returned and no data is written to the server. In this example 1000 bytes will be written to the instrument. Therefore, the OutputBufferSize is increased to 1000.

u.OutputBufferSize = 1000
u.OutputBufferSize
ans = 
    1000

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 Binary Data

You use the fwrite function to write binary data to the server or instrument.

By default, the fwrite function operates in a synchronous mode. This means that fwrite 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 fwrite function writes binary data using the uchar precision. However, other precisions can also be used. For a list of supported precisions, see the function reference page for fwrite.

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. In the example below, a datagram with 1000 bytes, 4 bytes per integer number, will be sent to the echoserver.

fwrite(u, 1:250, 'int32');

Note

When performing a write operation, you should think of the transmitted data in terms of values rather than bytes. A value consists of one or more bytes. For example, one uint32 value consists of four bytes.

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

u.ValuesSent
ans = 
    250

Configuring InputBufferSize

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

u.InputBufferSize
ans = 
    512

In the next example, 1000 bytes will be read from the server. Configure the InputBufferSize to hold 1000 bytes. Note, the InputBufferSize can be configured only when the object is not connected to the server or instrument.

fclose(u);
u.InputBufferSize = 1000);
u.InputBufferSize
ans = 
    1000

Now that the property is configured correctly, you can reopen the connection to the server:

fopen(u);

Reading Binary Data

You use the fread function to read binary data from the server or instrument.

The fread function blocks the MATLAB command line until one of the following occurs:

  • 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)

By default the fread function reads binary data using the uchar precision. However, other precisions can also be used. For a list of supported precisions, see the function reference page for fread.

Note

When performing a read operation, you should think of the received data in terms of values rather than bytes. A value consists of one or more bytes. For example, one uint32 value consists of four bytes.

You can read int32 binary data. For example, read one datagram consisting of 250 integers from the instrument or server.

fwrite(u, 1:250, 'int32');
data = fread(u, 250, 'int32');

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

u.ValuesReceived
ans = 
    500

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 to the echoserver.

fwrite(u, 1:125, 'int32');
fwrite(u, 1:125, 'int32');

Because DatagramTerminateMode is off, fread will read across datagram boundaries until 250 integers have been received.

u.DatagramTerminateMode = 'off';
data = fread(u, 250, 'int32');
size(data)
ans = 
    250

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');