Read and Write Binary Data over TCP/IP

This section provides details and examples exploring binary read and write operations with a TCP/IP object.

Note

Most bench-top instruments (oscilloscopes, function generators, etc.) that provide network connectivity do not use raw TCP socket communication for instrument command and control. Instead, it is supported through the VISA standard. For more information on using VISA to communicate with your instrument, see VISA Overview.

Functions and Properties

These functions are used when reading and writing binary data:

Function	Purpose
fread	Read binary data from the server.
fwrite	Write binary data to the server.

These properties are associated with reading and writing binary data:

Property	Purpose
ValuesReceived	Specifies the total number of values read from the server.
ValuesSent	Specifies the total number of values sent to the server.
InputBufferSize	Specifies the total number of bytes that can be queued in the input buffer at one time.
OutputBufferSize	Specifies the total number of bytes that can be queued in the output buffer at one time.
ByteOrder	Specifies the byte order of 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 TCP/IP 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.

echotcpip('on', 4000)

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

t = tcpip('127.0.0.1', 4000);

You may need to configure the OutputBufferSize of the TCP/IP object. The OutputBufferSize property specifies the maximum number of bytes that can be written to the server at once. By default, OutputBufferSize is 512.

t.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 4000 bytes will be written to the server. Therefore, the OutputBufferSize is increased to 4000.

t.OutputBufferSize = 4000;
t.OutputBufferSize
ans = 
    4000

You may need to configure the ByteOrder of the TCP/IP object. The ByteOrder property specifies the byte order of the server. By default ByteOrder is bigEndian.

t.ByteOrder
ans = 
    'bigEndian'

If the server's byte order is little-endian, the ByteOrder property of the object can be configured to littleEndian:

t.ByteOrder = 'littleEndian'
t.ByteOrder
ans = 
    'littleEndian'

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

fopen(t)

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

t.Status
ans = 
    open

Writing Binary Data

You use the fwrite function to write binary data to the server. For example, the following command will send a sine wave to the server.

Construct the sine wave to be written to the server.

x = (0:999) .* 8 * pi / 1000;
data = sin(x);

Write the sine wave to the server.

fwrite(t, data, 'float32');

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.

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.

Binary Write Properties

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

t.ValuesSent
ans = 
    1000

Configuring InputBufferSize

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

t.InputBufferSize
ans = 
    512

Next, the waveform stored in the function generator's memory will be read. The waveform contains 4000 bytes. Configure the InputBufferSize to hold 4000 bytes. Note, the InputBufferSize can be configured only when the object is not connected to the server.

fclose(t);
t.InputBufferSize = 4000;
t.InputBufferSize
ans = 
    4000

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

fopen(t);

Reading Binary Data

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

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

• A timeout occurs as specified by the Timeout property

• The specified number of values is read

• The InputBufferSize number of values is read

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.

For reading float32 binary data, send the waveform again. Closing the object clears any available data from earlier writes.

fwrite(t, data, 'float32');

Now read the same waveform as a float32 array.

data = fread(t, 1000, 'float32');

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

t.ValuesReceived
ans = 
    1000

Cleanup

If you are finished with the TCP/IP 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(t);
delete(t);
clear t

echotcpip('off');