Read data asynchronously from instrument
An interface object.
The number of bytes to read from the instrument.
readasync(obj) initiates an asynchronous
readasync(obj,size) asynchronously reads,
at most, the number of bytes specified by
size is greater than the difference between the
InputBufferSize property value and the
BytesAvailable property value, an error is returned.
This example creates the serial port object
s to a Tektronix® TDS 210 oscilloscope, configures
s on a Windows® machine to read data asynchronously only if
readasync is issued, and configures the instrument to return
the peak-to-peak value of the signal on channel 1.
s = serial('COM1'); fopen(s) s.ReadAsyncMode = 'manual'; fprintf(s,'Measurement:Meas1:Source CH1') fprintf(s,'Measurement:Meas1:Type Pk2Pk') fprintf(s,'Measurement:Meas1:Value?')
Initially, there is no data in the input buffer.
s.BytesAvailable ans = 0
Begin reading data asynchronously from the instrument using
readasync. When the read operation is complete, return the
data to the MATLAB® workspace using
readasync(s) s.BytesAvailable ans = 15 out = fscanf(s) out = 2.0399999619E0 fclose(s)
Before you can read data, you must connect
obj to the
instrument with the
fopen function. A connected
interface object has a
Status property value of
open. An error is returned if you attempt to perform a read
obj is not connected to the instrument.
For serial port, TCPIP, UDP, and VISA-serial objects, you should use
readasync only when you configure the
ReadAsyncMode property to
readasync is ignored if used when
TransferStatus property indicates if an asynchronous read
or write operation is in progress. For all interface objects, you cannot use
readasync while a read operation is in progress. For serial
port and VISA-serial objects, you can write data while an asynchronous read is in
progress because serial ports have separate read and write pins. You can stop
asynchronous read and write operations with the
You can monitor the amount of data stored in the input buffer with the
BytesAvailable property. Additionally, you can use the
BytesAvailableFcn property to execute a callback function
when the terminator or the specified amount of data is read.
Asynchronous operation is not supported for NI VISA objects on the UNIX® platform. So if you use the
readasync function with
a NI VISA object, you will get an error.
To get a list of options you can use on a function, press the Tab key after entering a function on the MATLAB command line. The list expands, and you can scroll to choose a property or value. For information about using this advanced tab completion feature, see Using Tab Completion for Functions.
An asynchronous read operation with
when one of these conditions is met:
The terminator is read. For serial port, TCPIP, UDP, and VISA-serial
objects, the terminator is given by the
property. Note that for UDP objects,
DatagramTerminateMode must be
For all other interface objects except VISA-RSIB, the terminator is
given by the
The time specified by the
The specified number of bytes is read.
The input buffer is filled.
A datagram has been received (UDP objects only if
The EOI line is asserted (GPIB and VXI instruments only).
For serial port, TCPIP, UDP, and VISA-serial objects,
readasync can be slow because it checks for the
terminator. To increase speed, you might want to configure
continuously return data to the input buffer as soon as it is available from the
serialobject interface is not recommended
Not recommended starting in R2019b