fscanf (serial)

(To be removed) Read ASCII data from device, and format as text

This serial object function will be removed in a future release. Use serialport object functions instead. For more information on updating your code, see Version History.

Syntax

A = fscanf(obj)
A = fscanf(obj,'format')
A = fscanf(obj,'format',size)
[A,count] = fscanf(...)
[A,count,msg] = fscanf(...)


Description

A = fscanf(obj) reads ASCII data from the device connected to the serial port object, obj, and returns it to A. The data is converted to text using the %c format. For binary data, use fread.

A = fscanf(obj,'format') reads data and converts it according to format. format is a C language conversion specification. Conversion specifications involve the % character and the conversion characters d, i, o, u, x, X, f, e, E, g, G, c, and s. Refer to the sscanf file I/O format specifications or a C manual for more information.

A = fscanf(obj,'format',size) reads the number of values specified by size. Valid options for size are:

n	Read at most n values into a column vector.
[m,n]	Read at most m-by-n values filling an m–by–n matrix in column order.

size cannot be inf, and an error is returned if the specified number of values cannot be stored in the input buffer. If size is not of the form [m,n], and a character conversion is specified, then A is returned as a row vector. You specify the size, in bytes, of the input buffer with the InputBufferSize property. An ASCII value is one byte.

[A,count] = fscanf(...) returns the number of values read to count.

[A,count,msg] = fscanf(...) returns a warning message to msg if the read operation did not complete successfully.

Examples

Create the serial port object s and connect s to a Tektronix^® TDS 210 oscilloscope, which is displaying sine wave. This example works on a Windows^® platform.

s = serial('COM1');
fopen(s)

Use the fprintf function to configure the scope to measure the peak-to-peak voltage of the sine wave, return the measurement type, and return the peak-to-peak voltage.

fprintf(s,'MEASUREMENT:IMMED:TYPE PK2PK')
fprintf(s,'MEASUREMENT:IMMED:TYPE?')
fprintf(s,'MEASUREMENT:IMMED:VALUE?')

Because the default value for the ReadAsyncMode property is continuous, data associated with the two query commands is automatically returned to the input buffer.

s.BytesAvailable

ans =
    21

Use fscanf to read the measurement type. The operation will complete when the first terminator is read.

meas = fscanf(s)

meas =
PK2PK

Use fscanf to read the peak-to-peak voltage as a floating-point number, and exclude the terminator.

pk2pk = fscanf(s,'%e',14)

pk2pk =
    2.0200

Disconnect s from the scope, and remove s from memory and the workspace.

fclose(s)
delete(s)
clear s

Tips

Before you can read data from the device, it must be connected to obj 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.

If msg is not included as an output argument and the read operation was not successful, then a warning message is returned to the command line.

The ValuesReceived property value is increased by the number of values read – including the terminator – each time fscanf is issued.

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 number of values specified by size is read.

• The input buffer is filled (unless size is specified)

Version History

Introduced before R2006a

R2021a: serial object interface will be removed

Use of this function with a serial object will be removed. To access a serial port device, use a serialport object with its functions and properties instead.

The recommended functionality has additional capabilities and improved performance. See Transition Your Code to serialport Interface for more information about using the recommended functionality.