Asynchronous Read and Write Operations over TCP/IP

This section provides details and examples exploring asynchronous 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 associated with reading and writing text asynchronously:

FunctionPurpose
fprintfWrite text to a server.
readasyncAsynchronously read bytes from a server.
stopasyncStop an asynchronous read or write operation.

These properties are associated with reading and writing text asynchronously:

PropertyPurpose
BytesAvailableIndicates the number of bytes available in the input buffer.
TransferStatusIndicates what type of asynchronous operation is in progress.
ReadAsyncModeIndicates whether data is read continuously in the background or whether you must call the readasync function to read data asynchronously.

Additionally, you can use all the callback properties during asynchronous read and write operations.

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.

Synchronous Versus Asynchronous Operations

The object can operate in synchronous mode or in asynchronous mode. When the object is operating synchronously, the read and write routines block the MATLAB command line until the operation has completed or a timeout occurs. When the object is operating asynchronously, the read and write routines return control immediately to the MATLAB command line.

Additionally, you can use callback properties and callback functions to perform tasks as data is being written or read. For example, you can create a callback function that notifies you when the read or write operation has finished.

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

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

Reading Data Asynchronously

You can read data asynchronously with the TCP/IP object in one of these two ways:

  • Continuously, by setting ReadAsyncMode to continuous. In this mode, data is automatically stored in the input buffer as it becomes available from the server.

  • Manually, by setting ReadAsyncMode to manual. In this mode, you must call the readasync function to store data in the input buffer.

The fscanf, fread, fgetl and fgets functions are used to bring the data from the input buffer into MATLAB. These functions operate synchronously.

Reading Data Asynchronously – Continuous ReadAsyncMode

To begin, read data continuously.

t.ReadAsyncMode = continuous;

Now, send data to the server that will be returned for reading.

fprintf(t, 'Hello World 123');

Because the ReadAsyncMode property is set to continuous, the object is continuously checking whether any data is available. Once the last fprintf function completes, the server begins sending data, the data is read from the server and is stored in the input buffer.

t.BytesAvailable
ans = 
    16

You can bring the data from the object's input buffer into the MATLAB workspace with fscanf.

fscanf(t)
ans = 
    Hello World 123

Reading Data Asynchronously – Manual ReadAsyncMode

Next, read data manually.

t.ReadAsyncMode = manual;

Now, send data to the server that will be returned for reading.

fprintf(t, 'Hello World 456');

Once the last fprintf function completes, the server begins sending data. However, because ReadAsyncMode is set to manual, the object is not reading the data being sent from the server. Therefore no data is being read and placed in the input buffer.

t.BytesAvailable
ans = 
    0

The readasync function can asynchronously read the data from the server. The readasync function returns control to the MATLAB command line immediately.

The readasync function takes two input arguments. The first argument is the server object and the second argument is the size, the amount of data to be read from the server.

The readasync function without a size specified assumes size is given by the difference between the InputBufferSize property value and the BytesAvailable property value. The asynchronous read terminates when:

  • The terminator is read as specified by the Terminator property

  • The specified number of bytes have been read

  • A timeout occurs as specified by the Timeout property

  • The input buffer is filled

An error event will be generated if readasync terminates due to a timeout.

The object starts querying the server for data when the readasync function is called. Because all the data was sent before the readasync function call, no data will be stored in the input buffer and the data is lost.

When the TCP/IP object is in manual mode (the ReadAsyncMode property is configured to manual), data that is sent from the server to the computer is not automatically stored in the input buffer of the TCP/IP object. Data is not stored until readasync or one of the blocking read functions is called.

Manual mode should be used when a stream of data is being sent from your server and you only want to capture portions of the data.

Defining an Asynchronous Read Callback

You can configure a TCP/IP object to notify you when a terminator has been read using the dispcallback function.

t.ReadAsyncMode = 'continuous';
t.BytesAvailableFcn = 'dispcallback';

Note, the default value for the BytesAvailableFcnMode property indicates that the callback function defined by the BytesAvailableFcn property will be executed when the terminator has been read.

The callback function dispcallback displays event information for the specified event. Using the syntax dispcallback(obj, event), it displays a message containing the type of event, the name of the object that caused the event to occur, and the time the event occurred.

callbackTime = datestr(datenum(event.Data.AbsTime));
fprintf(['A ' event.Type ' event occurred for ' obj.Name ' at ' 
     callbackTime '.\n']);

Using Callbacks During an Asynchronous Read

Once the terminator is read from the server and placed in the input buffer, dispcallback is executed and a message is posted to the MATLAB command window indicating that a BytesAvailable event occurred.

fprintf(t, 'Hello World 789')
t.BytesAvailable
ans = 
    16

data = fscanf(t, '%c', 18)
data = 
    Hello World 789

Note

If you need to stop an asynchronous read or write operation, you do not have to wait for the operation to complete. You can use the stopasync function to stop the asynchronous read or write.

Writing Data Asynchronously

You can perform an asynchronous write with the fprintf or fwrite functions by passing 'async' as the last input argument.

In asynchronous mode, you can use callback properties and callback functions to perform tasks while data is being written. For example, configure the object to notify you when an asynchronous write operation completes.

t.OutputEmptyFcn = 'dispcallback';
fprintf(t, 'Hello World 123', 'async')

Note

If you need to stop an asynchronous read or write operation, you do not have to wait for the operation to complete. You can use the stopasync function to stop the asynchronous read or write.

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