This demo explores asynchronous read and write operations using a GPIB object. The information obtained for this demonstration was prerecorded. Therefore, you do not need an actual instrument to learn about GPIB asynchronous operations.
The GPIB board used was a National Instruments PCI-GPIB+ GPIB card.
The instrument used was a Hewlett Packard 33120A function generator.
These functions are associated with reading and writing text asynchronously:
FPRINTF - Write text to instrument. READASYNC - Asynchronously read bytes from an instrument. STOPASYNC - Stop an asynchronous read and write operation.
These properties are associated with ASCII read and write asynchronous operations:
BytesAvailable - Indicate the number of bytes available in
the input buffer.
TransferStatus - Indicate what type of asynchronous operation
is in progress.Additionally, you can use all callback properties during asynchronous read and write operations.
The GPIB object can operate in either synchronous or asynchronous mode.
In synchronous mode, the MATLAB command line is blocked until
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.
To begin, create a GPIB object. The board index is configured to 0, the primary address of the instrument is configured to 1.
>> g = gpib('ni', 0, 1)GPIB Object Using NI Adaptor : GPIB0-1
Communication Address
BoardIndex: 0
PrimaryAddress: 1
SecondaryAddress: 0 Communication State
Status: closed
RecordStatus: off Read/Write State
TransferStatus: idle
BytesAvailable: 0
ValuesReceived: 0
ValuesSent: 0Before you can perform a read or write operation, you must connect the GPIB object to the instrument with the FOPEN function. If the GPIB object was successfully connected, its Status property is automatically configured to open.
>> fopen(g) >> get(g, 'Status')
ans =
open
You read data asynchronously from the instrument with the READASYNC function. For example, query the instrument for the signal's voltage and asynchronously read 20 bytes.
>> fprintf(g, 'Volt?'); >> readasync(g, 20)
If you do not specify the number of bytes to read, READASYNC reads up to the difference between the InputBufferSize property value and the BytesAvailable property value.
An asynchronous read terminates when
An error event will occur if READASYNC terminates due to a timeout.
The TransferStatus property indicates what type of asynchronous operation is in progress. For GPIB objects, TransferStatus can be read, write, or idle.
>> get(g, 'TransferStatus')
ans =
read
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. STOPASYNC will not flush any data remaining in the input buffer. This allows you to bring the data that was read into the MATLAB workspace with one of the synchronous read functions (FSCANF, FGETL, FGETS, or FREAD).
If we now look at the BytesAvailable property, you see that 13 bytes were read.
>> get(g, 'BytesAvailable')
ans =
13
You can bring the data into the MATLAB workspace with the FSCANF function.
>> data = fscanf(g, '%g')
data =
1
In asynchronous mode, you can use callback properties and callback functions to perform a task as data is read. For example, configure the GPIB object to notify you when a linefeed 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: the BytesAvailableFcnMode property cannot be configured while the object is connected to the instrument.
>> set(g, 'BytesAvailableFcn', {'dispcallback'})
>> set(g, 'EOSCharCode', 10);The M-file callback function, DISPCALLBACK, is defined below.
function dispcallback(obj, event) %DISPCALLBACK Display event information for the specified event. % % DISPCALLBACK(OBJ, EVENT) a callback function that displays % a message which contains the type of the event, the name % of the object which caused the event to occur and the % time the event occurred. % % See also INSTRCALLBACK.
callbackTime = datestr(datenum(event.Data.AbsTime)); fprintf(['A ' event.Type ' event occurred for ' obj.Name ' at ' callbackTime '.\n]);
Now, query the instrument for the frequency of the signal. Once the linefeed is read from the instrument and placed in the input buffer, DISPCALLBACK is executed and a message is displayed to the MATLAB command window indicating that an event occurred.
>> fprintf(g, 'Freq?') >> readasync(g)
A BytesAvailable event occurred for Gpib0-1 at 30-Dec-1999 11:26:22.
>> get(g, 'BytesAvailable')
ans =
19
>> data = fscanf(g, '%c', 19)
data =
+1.00000000000E+03
Note that the last value read is the line feed (10):
>> real(data)
ans =
Columns 1 through 12
43 49 46 48 48 48 48 48 48 48 48 48
Columns 13 through 19
48 48 69 43 48 51 10
You can perform an asynchronous write with the FPRINTF or FWRITE functions by passing 'async' 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.
In asynchronous mode, you can use callback properties and callback functions to perform tasks as data is written. For example, configure our GPIB object to notify you when the write operation is complete.
>> set(g, 'OutputEmptyFcn', {'dispcallback'});
>> fprintf(g, 'Func:Shape?', 'async')A OutputEmpty event occurred for Gpib0-1 at 30-Dec-1999 12:01:17.
If you are finished with the GPIB object, disconnect it from the instrument, remove it from memory, and remove it from the workspace.
>> fclose(g) >> delete(g) >> clear g