readasync

(To be removed) Read data asynchronously from instrument

This serial, Bluetooth, tcpip, udp, visa, and gpib object function will be removed in a future release. Use serialport, bluetooth, tcpclient, tcpserver, udpport, and visadev object functions instead. For more information on updating your code, see Version History.

Syntax

readasync(obj)
readasync(obj,size)

Arguments

obj

An interface object.

size

The number of bytes to read from the instrument.

Description

readasync(obj) initiates an asynchronous read operation.

readasync(obj,size) asynchronously reads, at most, the number of bytes specified by size. If size is greater than the difference between the InputBufferSize property value and the BytesAvailable property value, an error is returned.

Examples

This example creates the serial port object s, connects 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 fscanf.

readasync(s)
s.BytesAvailable
ans =
     15
out = fscanf(s)
out =
2.0399999619E0
fclose(s)

Tips

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 operation while 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 manual. readasync is ignored if used when ReadAsyncMode is continuous.

The 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 stopasync function.

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.

Note

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.

Rules for Completing an Asynchronous Read Operation

An asynchronous read operation with readasync completes 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 Terminator property. Note that for UDP objects, DatagramTerminateMode must be off.

    For all other interface objects except VISA-RSIB, the terminator is given by the EOSCharCode property.

  • The time specified by the Timeout property passes.

  • The specified number of bytes is read.

  • The input buffer is filled.

  • A datagram has been received (UDP objects only if DatagramTerminateMode is on)

  • 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 ReadAsyncMode to continuous and continuously return data to the input buffer as soon as it is available from the instrument.

Version History

Introduced before R2006a

expand all

See Also

Functions