Use Callbacks for VISA Communication
Note
Callback functions for the
visadev
interface have been removed. The
configureCallback
function and the
NumBytesAvailable
,
BytesAvailableFcnMode
,
BytesAvailableFcnCount
, and
BytesAvailableFcn
properties and are no longer supported
for visadev
objects. (since R2022a)
You can enhance the power and flexibility of your instrument control application by using events and callbacks. An event occurs after a condition is met and can result in one or more callbacks.
While MATLAB® is connected to the instrument, you can use events to display a message,
display data, analyze data, and so on. You can control callbacks through
configureCallback
and callback functions. Callback functions are
MATLAB functions that you write to suit your specific application needs.
Use Events and Callbacks
This example uses the callback function mycallback
to read from
the instrument when a terminator is available to be read. The event is generated
when the Terminator
property value is read. Specify the event
type and the callback function to be executed using the
configureCallback
function. Specify the callback function as
a function handle.
function mycallback(src,evt) data = readline(src) disp(evt) end
g = visadev("GPIB0::1::0::INSTR"); configureCallback(g,"terminator",@mycallback) writeline(g,"*IDN?")
The resulting display from mycallback
is shown below.
data = "TEKTRONIX,TDS 210,0,CF:91.1CT FV:v1.16 TDS2CM:CMV:v1.04" DataAvailableInfo with properties: BytesAvailableFcnCount: 1 AbsTime: 1-Apr-2021 14:54:16
End the VISA-GPIB session.
clear g
Event Types and Callback Properties
The following table lists the visadev
properties and functions
associated with callbacks.
Property or Function | Purpose |
---|---|
configureCallback | Set callback function and trigger condition for communication |
BytesAvailableFcn | Callback function triggered by bytes available event |
BytesAvailableFcnCount | Number of bytes of data to trigger callback |
BytesAvailableFcnMode | Bytes available callback trigger mode |
ErrorOccurredFcn | Callback function triggered by error event |
UserData | General purpose property for user data |
For more information about configuring these properties and functions, see visadev Properties.
Bytes-Available Event Modes
A bytes-available event is generated immediately after a specified number of
bytes are available in the input buffer or the terminator character specified is
read, as determined by the BytesAvailableFcnMode
property.
If
BytesAvailableFcnMode
isbyte
, the bytes-available event executes the callback function specified for theBytesAvailableFcn
property every time the number of bytes specified byBytesAvailableFcnCount
is stored in the input buffer.If
BytesAvailableFcnMode
isterminator
, the bytes-available event executes the callback function specified for theBytesAvailableFcn
property every time the character specified by theTerminator
property is read.
Error Event
An error event is generated immediately after an error occurs. An error event
is generated when the connection to your VISA resource is interrupted or when an
asynchronous read error occurs. 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
ErrorOccurredFcn
property.
Use Events and Callbacks to Display Event Information
This example extends Writing and Reading Binary Data by using the custom callback function mycallback
to display
event-related information to the command line when a bytes-available event occurs
during a binary read operation.
Create a callback function
mycallback
and save it as an .m file in the directory that you are working in.function mycallback(src,evt) disp(evt) end
Create the VISA-GPIB object
g
associated with a National Instruments™ GPIB controller with primary address 1 and secondary address 0.g = visadev("GPIB0::1::0::INSTR");
Configure the timeout value to two minutes to account for slow data transfer.
g.Timeout = 120;
Configure
g
to execute the callback functionmycallback
every time 5000 bytes is stored in the input buffer.configureCallback(g,"byte",5000,@mycallback)
Configure the scope to transfer the screen display as a bitmap.
writeline(g,"HARDCOPY:PORT GPIB") writeline(g,"HARDCOPY:FORMAT BMP") writeline(g,"HARDCOPY START")
mycallback
is called every time 5000 bytes is stored in the input buffer. The resulting displays are as follows.DataAvailableInfo with properties: BytesAvailableFcnCount: 5000 AbsTime: 1-Apr-2021 15:06:11 DataAvailableInfo with properties: BytesAvailableFcnCount: 5000 AbsTime: 1-Apr-2021 15:06:16 DataAvailableInfo with properties: BytesAvailableFcnCount: 5000 AbsTime: 1-Apr-2021 15:06:21
After all the data is sent to the input buffer, transfer the data to the MATLAB workspace as unsigned 8-bit integers.
out = read(g,g.NumBytesAvailable,"uint8");
Use
clear
to disconnect the instrument from the VISA-GPIB objectg
and to clear it from the MATLAB workspace when you are done working with it.clear g