External Interfaces/API

Reading Data

This section describes reading data from your serial port device in three parts:

• "The Input Buffer and Data Flow" describes the flow of data from the device to MATLAB.
• "Reading Text Data" describes how to read from the device, and format the data as text.
• "Reading Binary Data" describes how to read binary (numerical) data from the device.

The functions associated with reading data are given below.

Table 8-7: Functions Associated with Reading Data 

Function Name	Description
fgetl	Read one line of text from the device and discard the terminator
fgets	Read one line of text from the device and include the terminator
fread	Read binary data from the device
fscanf	Read data from the device, and format as text
readasync	Read data asynchronously from the device
stopasync	Stop asynchronous read and write operations

The properties associated with reading data are given below.

Table 8-8: Properties Associated with Reading Data 

Property Name	Description
BytesAvailable	Indicate the number of bytes available in the input buffer
InputBufferSize	Specify the size of the input buffer in bytes
ReadAsyncMode	Specify whether an asynchronous read operation is continuous or manual
Timeout	Specify the waiting time to complete a read or write operation
TransferStatus	Indicate if an asynchronous read or write operation is in progress
ValuesReceived	Indicate the total number of values read from the device

The Input Buffer and Data Flow

The input buffer is computer memory allocated by the serial port object to store data that is to be read from the device. When reading data from your device, the data flow follows these two steps:

1. The data read from the device is stored in the input buffer.
2. The data in the input buffer is returned to the MATLAB variable specified by the read function.

The InputBufferSize property specifies the maximum number of bytes that you can store in the input buffer. The BytesAvailable property indicates the number of bytes currently available to be read from the input buffer. The default values for these properties are given below.

• s = serial('COM1');
  get(s,{'InputBufferSize','BytesAvailable'})
  ans = 
      [512]    [0]
  

If you attempt to read more data than can fit in the input buffer, an error is returned and no data is read.

For example, suppose you use the fscanf function to read the text-based response of the *IDN? command previously written to the TDS 210 oscilloscope. As shown below, the text data is first read into to the input buffer via the serial port.

Note that for a given read operation, you might not know the number of bytes returned by the device. Therefore, you might need to preset the InputBufferSize property to a sufficiently large value before connecting the serial port object.

As shown below, after the data is stored in the input buffer, it is then transferred to the output variable specified by fscanf.

Reading Text Data

You use the fgetl, fgets, and fscanf functions to read data from the device, and format the data as text.

For example, suppose you want to return identification information for the oscilloscope. This requires writing the *IDN? command to the instrument, and then reading back the result of that command.

• s = serial('COM1');
  fopen(s)
  fprintf(s,'*IDN?')
  out = fscanf(s)
  out =
  TEKTRONIX,TDS 210,0,CF:91.1CT FV:v1.16 TDS2CM:CMV:v1.04
  

By default, fscanf reads data using the %c format because the data returned by many serial port devices is text based. However, you can specify many other formats as described in the fscanf reference pages.

You can verify the number of values read from the device - including the terminator - with the ValuesReceived property.

• s.ValuesReceived
  ans =
      56
  

Synchronous Versus Asynchronous Read Operations.   You specify whether read operations are synchronous or asynchronous with the ReadAsyncMode property. You can configure ReadAsyncMode to continuous or manual.

If ReadAsyncMode is continuous (the default value), the serial port object continuously queries the device to determine if data is available to be read. If data is available, it is asynchronously stored in the input buffer. To transfer the data from the input buffer to MATLAB, you use one of the synchronous (blocking) read functions such as fgetl or fscanf. If data is available in the input buffer, these functions will return quickly.

• s.ReadAsyncMode = 'continuous';
  fprintf(s,'*IDN?')
  s.BytesAvailable
  ans =
      56
  out = fscanf(s);
  

If ReadAsyncMode is manual, the serial port object does not continuously query the device to determine if data is available to be read. To read data asynchronously, you use the readasync function.You then use one of the synchronous read functions to transfer data from the input buffer to MATLAB.

• s.ReadAsyncMode = 'manual';
  fprintf(s,'*IDN?')
  s.BytesAvailable
  ans =
      0
  readasync(s)
  s.BytesAvailable
  ans =
      56
  out = fscanf(s);
  

Asynchronous operations do not block access to the MATLAB command line. Additionally, while an asynchronous read operation is in progress, you can:

• Execute an asynchronous write operation because serial ports have separate pins for reading and writing
• Make use of all supported callback properties

You can determine which asynchronous operations are in progress with the TransferStatus property. If no asynchronous operations are in progress, then TransferStatus is idle.

• s.TransferStatus
  ans =
  idle
  

Rules for Completing a Read Operation with fscanf.   A read operation with fscanf blocks access to the MATLAB command line until:

• The terminator specified by the Terminator property is read.
• The time specified by the Timeout property passes.
• The specified number of values specified is read.
• The input buffer is filled.

Reading Binary Data

You use the fread function to read binary data from the device. Reading binary data means that you return numerical values to MATLAB.

For example, suppose you want to return the cursor and display settings for the oscilloscope. This requires writing the CURSOR? and DISPLAY? commands to the instrument, and then reading back the results of those commands.

• s = serial('COM1');
  fopen(s)
  fprintf(s,'CURSOR?')
  fprintf(s,'DISPLAY?')
  

Because the default value for the ReadAsyncMode property is continuous, data is asynchronously returned to the input buffer as soon as it is available from the device. You can verify the number of values read with the BytesAvailable property.

• s.BytesAvailable
  ans =
      69
  

You can return the data to MATLAB using any of the synchronous read functions. However, if you use fgetl, fgets, or fscanf, then you must issue the function twice because there are two terminators stored in the input buffer. If you use fread, then you can return all the data to MATLAB in one function call.

• out = fread(s,69);
  

By default, fread returns numerical values in double precision arrays. However, you can specify many other precisions as described in the fread reference pages. You can convert the numerical data to text using the MATLAB char function.

• val = char(out)'
  val =
  HBARS;CH1;SECONDS;-1.0E-3;1.0E-3;VOLTS;-6.56E-1;6.24E-1
  YT;DOTS;0;45
  

For more information about synchronous and asynchronous read operations, refer to Reading Text Data. For a description of the rules used by fread to complete a read operation, refer to its reference pages.

Writing Data

Example: Writing and Reading Text Data