External Interfaces/API    

Reading Data

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

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.

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.

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.

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.

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.

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

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

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

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.

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.

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.

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.

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