Documentation

Contents

Asynchronous Read and Write Operations Using VISA

This example explores asynchronous read and write operations using a VISA-GPIB object. The instrument used was a Tektronix® TDS 2024 oscilloscope.

This tutorial explores asynchronous read and write operations for a VISA-GPIB-VXI object. However, asynchronous read and write operations for VISA-GPIB, VISA-VXI, VISA-GPIB-VXI, VISA-TCPIP, and VISA-USB objects are identical to each other. Therefore, you can use the same commands. The only difference is the resource name specified in the VISA constructor.

Asynchronous read and write operations for the VISA-serial object are identical to asynchronous read and write operations for the serial port object. Therefore, to learn how to perform asynchronous read and write operations for the VISA-serial object, you should refer to the Serial Port Asynchronous Read/Write tutorial.

Asynchronous read and write operations are not supported for the VISA-RSIB object.

Functions and Properties

These functions are associated with reading and writing text asynchronously:

FunctionPurpose
fprintfWrite text to a instrument.
readasyncAsynchronously read bytes from an instrument.
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.

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

Synchronous Versus Asynchronous Operations

The VISA object can operate in either synchronous or asynchronous mode. In synchronous mode, the MATLAB command line is blocked until

  • The read or write operation completes

  • A timeout occurs as specified by the Timeout property

In asynchronous mode, control is immediately returned 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 Instrument

You need to create a VISA-GPIB object. In this example, an object is created using the ni driver and the VISA resource string shown below.

v = visa('ni', 'GPIB0::2::INSTR')

Before you can perform a read or write operation, you must connect the VISA-GPIB object to the instrument with the fopen function.

fopen(v)

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

v.Status
ans = 
    open

Reading Data Asynchronously

The VISA-GPIB object's asynchronous read functionality is controlled with the readasync function. Query the instrument for the channel 1 vertical scale:

fprintf(v, 'CH1:Scale?');

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

readasync(v, 20);

The readasyn function without a size specified will assume size is given by the difference between the InputBufferSize property value and the BytesAvailable property value. In the above example, size is 20. The asynchronous read terminates when one of the following occurs:

  • The terminator is read as specified by the EOSCharCode property

  • The specified number of bytes are stored in the input buffer

  • A timeout occurs as specified by the Timeout property

  • The EOI line has been asserted

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

Asynchronous Read Properties

Transfer Status

The TransferStatus property indicates what type of asynchronous operation is in progress. For VISA-GPIB objects, TransferStatus can be configured as read, write, or idle.

v.TransferStatus
ans = 
    idle

While an asynchronous read is in progress, an error occurs if you execute another write or asynchronous read operation. You can stop the asynchronous read operation with the stopasync function. The data in the input buffer will remain after stopasync is called. This allows you to bring the data that was read into the MATLAB workspace with one of the synchronous read routines (fscanf, fgetl, fgets, or fread).

BytesAvailable

If we now look at the BytesAvailable property, you see that 6 bytes were read.

v.BytesAvailable
ans = 
    6

You can bring the data into the MATLAB workspace with the fscanf function.

data = fscanf(v, '%g')
data =
     1

Using Callbacks During an Asynchronous Read

Now, configure the VISA-GPIB object to notify you when a line feed has been read. The BytesAvailableFcnMode property controls when the BytesAvailable event is created. By default, the BytesAvailable event is created when the EOSCharCode character is received. The BytesAvailable event can also be created after a certain number of bytes have been read. Note that the BytesAvailableFcnMode property cannot be configured while the object is connected to the instrument.

set(v, 'BytesAvailableFcn', {'dispcallback'});
set(v, 'EOSCharCode', 10);

The callback function dispcallback displays a message containing the type of the event, the name of the object that caused the event to occur, and the time the event occurred.

Now, query the instrument for the frequency of the signal. Once the linefeed has been read from the instrument and placed in the input buffer, dispcallback will be executed and a message will be displayed to the MATLAB command window indicating that a BytesAvailable event occurred.

fprintf(v, 'CH2:Scale?');
readasync(v);

Allow time for a response. In a typical application this is where you could do other tasks.

pause(0.5);

A BytesAvailable event occurred for VISA-GPIB0-2 at 01-Jun-2005 15:08:34.

v.BytesAvailable

ans =

     6

data = fscanf(v, '%c', 6)

data =

    à (0

Note that the last value read is the line feed (10):

real(data)

ans =

   224    32    40    16    48    10

Writing Data Asynchronously

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

While an asynchronous write is in progress, an error occurs if you execute a read or write operation. You can stop an asynchronous write operation with the stopasync function. The data remaining in the output buffer will be flushed.

Also configure the object to notify you when the write operation has completed by defining an asynchronous write callback.

set(v, 'OutputEmptyFcn', {'dispcallback'});
fprintf(v, 'CH1:Scale?', 'async');

Cleanup

If you are finished with the VISA-GPIB object, disconnect it from the instrument, remove it from memory, and remove it from the workspace.

fclose(v);
delete(v);
clear v
Was this topic helpful?