Events and Callbacks

Introduction to Events and Callbacks

You can enhance the power and flexibility of your instrument control application by using events. An event occurs after a condition is met, and might result in one or more callbacks.

While the instrument object is connected to the instrument, you can use events to display a message, display data, analyze data, and so on. Callbacks are controlled through callback properties and callback functions. All event types have an associated callback property. Callback functions are MATLAB^® functions that you construct to suit your specific application needs.

You execute a callback when a particular event occurs by specifying the name of the callback function as the value for the associated callback property.

This example uses the callback function instrcallback to display a message to the command line when a bytes-available event occurs. The event is generated when the EOSCharCode property value is read.

g = gpib('ni',0,1);
g.BytesAvailableFcnMode = 'eosCharCode';
g.BytesAvailableFcn = @instrcallback;
fopen(g)
fprintf(g,'*IDN?')
readasync(g)

The resulting display from instrcallback is shown below.

BytesAvailable event occurred at 17:30:11 for the object: GPIB0-1.

End the GPIB session.

fclose(g)
delete(g)
clear g

You can see the code for the built-in instrcallback function by using the type command.

Event Types and Callback Properties

The GPIB event types and associated callback properties are described below.

GPIB Event Types and Callback Properties

Event Type	Associated Property Name
Bytes-available	BytesAvailableFcn
	BytesAvailableFcnCount
	BytesAvailableFcnMode
Error	ErrorFcn
Output-empty	OutputEmptyFcn
Timer	TimerFcn
	TimerPeriod

Bytes-Available Event

A bytes-available event is generated immediately after a predetermined number of bytes are available in the input buffer or the End-Of-String character is read, as determined by the BytesAvailableFcnMode property.

If BytesAvailableFcnMode is byte, the bytes-available event executes the callback function specified for the BytesAvailableFcn property every time the number of bytes specified by BytesAvailableFcnCount is stored in the input buffer. If BytesAvailableFcnMode is eosCharCode, then the callback function executes every time the character specified by the EOSCharCode property is read.

This event can be generated only during an asynchronous read operation.

Error Event

An error event is generated immediately after an error, such as a timeout, occurs. A timeout occurs if a read or write operation does not successfully complete within the time specified by the Timeout property. An error event is not generated for configuration errors such as setting an invalid property value.

This event executes the callback function specified for the ErrorFcn property. It can be generated only during an asynchronous read or write operation.

Output-Empty Event

An output-empty event is generated immediately after the output buffer is empty.

This event executes the callback function specified for the OutputEmptyFcn property. It can be generated only during an asynchronous write operation.

Timer Event

A timer event is generated when the time specified by the TimerPeriod property passes. Time is measured relative to when the object is connected to the instrument.

This event executes the callback function specified for the TimerFcn property. Note that some timer events might not be processed if your system is significantly slowed or if the TimerPeriod value is too small.

Responding To Event Information

You can respond to event information in a callback function or in a record file. Event information stored in a callback function uses two fields: Type and Data. The Type field contains the event type, while the Data field contains event-specific information. As described in Creating and Executing Callback Functions, these two fields are associated with a structure that you define in the callback function header. Refer to Debugging: Recording Information to Disk to learn about storing event information in a record file.

The event types and the values for the Type and Data fields are given below.

GPIB Event Information

Event Type	Field	Field Value
Bytes available	Type	BytesAvailable
	Data.AbsTime	day-month-year hour:minute:second
Error	Type	Error
	Data.AbsTime	day-month-year hour:minute:second
	Data.Message	An error string
Output empty	Type	OutputEmpty
	Data.AbsTime	day-month-year hour:minute:second
Timer	Type	Timer
	Data.AbsTime	day-month-year hour:minute:second

The Data field values are described below.

AbsTime Field

AbsTime is defined for all events, and indicates the absolute time the event occurred. The absolute time is returned using the MATLAB clock format:

day-month-year hour:minute:second

Message Field

Message is used by the error event to store the descriptive message that is generated when an error occurs.

Creating and Executing Callback Functions

You specify the callback function to be executed when a specific event type occurs by including the name of the file as the value for the associated callback property. You can specify the callback function as a function handle or as a string cell array element. Note that if you are executing a local callback function from within a file, then you must specify the callback as a function handle.

For example, to execute the callback function mycallback every time the EOSCharCode property value is read from your instrument,

g.BytesAvailableFcnMode = 'eosCharCode';
g.BytesAvailableFcn = @mycallback;

Alternatively, you can specify the callback function as a cell array.

g.BytesAvailableFcn = {'mycallback'};

Callback functions require at least two input arguments. The first argument is the instrument object. The second argument is a variable that captures the event information given in the preceding table, GPIB Event Information. This event information pertains only to the event that caused the callback function to execute. The function header for mycallback is shown below.

function mycallback(obj,event)

You pass additional parameters to the callback function by including both the callback function and the parameters as elements of a cell array. For example, to pass the MATLAB variable time to mycallback,

time = datestr(now,0);
g.BytesAvailableFcnMode = 'eosCharCode';
g.BytesAvailableFcn = {@mycallback,time};

Alternatively, you can specify mycallback as a character vector in the cell array.

g.BytesAvailableFcn = {'mycallback',time};

The corresponding function header is

function mycallback(obj,event,time)

If you pass additional parameters to the callback function, then they must be included in the function header after the two required arguments.

Note

You can also specify the callback function as a character vector. In this case, the callback is evaluated in the MATLAB workspace and no requirements are made on the input arguments of the callback function.

Enabling Callback Functions After They Error

If an error occurs while a callback function is executing, then

• The callback function is automatically disabled.

• A warning is displayed at the command line, indicating that the callback function is disabled.

If you want to enable the same callback function, you can set the callback property to the same value or you can disconnect the object with the fclose function. If you want to use a different callback function, the callback will be enabled when you configure the callback property to the new value.

Using Events and Callbacks to Read Binary Data

This example extends Reading and Writing Binary Data by using the callback function instrcallback to display event-related information to the command line when a bytes-available event occurs during a binary read operation:

1. Create an instrument object — Create the GPIB object g associated with a National Instruments™ GPIB controller with board index 0, and an instrument with primary address 1.

   g = gpib('ni',0,1);

2. Configure properties — Configure the input buffer to accept a reasonably large number of bytes, and configure the timeout value to two minutes to account for slow data transfer.

   g.InputBufferSize = 50000;
   g.Timeout = 120;

   Configure g to execute the callback function instrcallback every time 5000 bytes is stored in the input buffer. Because instrcallback requires an instrument object and event information to be passed as input arguments, the callback function is specified as a function handle.

   g.BytesAvailableFcnMode = 'byte';
   g.BytesAvailableFcnCount = 5000;
   g.BytesAvailableFcn = @instrcallback;

3. Connect to the instrument — Connect g to the oscilloscope.

   fopen(g)

4. Write and read data — Configure the scope to transfer the screen display as a bitmap.

   fprintf(g,'HARDCOPY:PORT GPIB')
   fprintf(g,'HARDCOPY:FORMAT BMP')
   fprintf(g,'HARDCOPY START')

   Initiate the asynchronous read operation, and begin generating events.

   readasync(g)

   instrcallback is called every time 5000 bytes is stored in the input buffer. The resulting displays are shown below.

   BytesAvailable event occurred at 09:41:42 for the object: GPIB0-1.
   BytesAvailable event occurred at 09:41:50 for the object: GPIB0-1.
   BytesAvailable event occurred at 09:41:58 for the object: GPIB0-1.
   BytesAvailable event occurred at 09:42:06 for the object: GPIB0-1.
   BytesAvailable event occurred at 09:42:14 for the object: GPIB0-1.
   BytesAvailable event occurred at 09:42:22 for the object: GPIB0-1.
   BytesAvailable event occurred at 09:42:30 for the object: GPIB0-1.

   Wait until all the data is sent to the input buffer, and then transfer the data to the MATLAB workspace as unsigned 8-bit integers.

   g.TransferStatus
   ans =
   idle
   out = fread(g,g.BytesAvailable,'uint8');

5. Disconnect and clean up — When you no longer need g, you should disconnect it from the instrument, and remove it from memory and from the MATLAB workspace.

   fclose(g)
   delete(g)
   clear g