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.
The GPIB event types and associated callback properties are described below.
GPIB Event Types and Callback Properties
Event Type | Associated Property Name |
---|---|
Bytes-available | |
Error | |
Output-empty | |
Timer | |
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.
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.
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.
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.
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 |
|
|
| day-month-year hour:minute:second | |
Error |
|
|
| day-month-year hour:minute:second | |
| An error string | |
Output empty |
|
|
| day-month-year hour:minute:second | |
Timer |
|
|
| day-month-year hour:minute:second |
The Data
field values are described below.
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
is used by the error event to store
the descriptive message that is generated when an error occurs.
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.
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.
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:
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);
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;
Connect to the instrument —
Connect g
to the oscilloscope.
fopen(g)
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');
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