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 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 terminator, the bytes-available event executes the callback function specified for the BytesAvailableFcn property every time the character specified by the Terminator 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 function mycallback 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 object g and to clear it from the MATLAB workspace when you are done working with it.
```
clear g
```