External Interfaces |
Reading Data
This section describes reading data from your serial port device in three parts:
The functions associated with reading data are given below.
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.
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:
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.
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.
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.
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:
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:
Terminator
property is read.
Timeout
property passes.
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 |
© 1994-2005 The MathWorks, Inc.