External Interfaces/API Reference

readasync

Read data asynchronously from the device

Syntax

• readasync(obj)
  readasync(obj,size)
  

Arguments

obj	A serial port object.
size	The number of bytes to read from the device.

Description

readasync(obj) initiates an asynchronous read operation.

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

Remarks

Before you can read data, you must connect obj to the device with the fopen function. A connected serial port 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 device.

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. 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 an M-file callback function when the terminator or the specified amount of data is read.

Rules for Completing an Asynchronous Read Operation

An asynchronous read operation with readasync completes when one of these conditions is met:

• The terminator specified by the Terminator property is read.
• The time specified by the Timeout property passes.
• The specified number of bytes is read.
• The input buffer is filled (if size is not specified).

Because readasync checks for the terminator, this function can be slow. 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 device.

Example

This example creates the serial port object s, connects s to a Tektronix TDS 210 oscilloscope, configures s 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?')
  

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)
  

See Also

Functions

fopen, stopasync

Properties

BytesAvailable, BytesAvailableFcn, ReadAsyncMode, Status, TransferStatus

load (serial)

record