Main Content

fread (serial)

(To be removed) Read binary data from device

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

Syntax

A = fread(obj)
A = fread(obj,size,'precision')
[A,count] = fread(...)
[A,count,msg] = fread(...)

Description

A = fread(obj) and A = fread(obj,size) read binary data from the device connected to the serial port object, obj, and returns the data to A. The maximum number of values to read is specified by size. If size is not specified, the maximum number of values to read is determined by the object's InputBufferSize property. 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. You specify the size, in bytes, of the input buffer with the InputBufferSize property. A value is defined as a byte multiplied by the precision (see below).

A = fread(obj,size,'precision') reads binary data with precision specified by precision.

precision controls the number of bits read for each value and the interpretation of those bits as integer, floating-point, or character values. If precision is not specified, uchar (an 8-bit unsigned character) is used. By default, numeric values are returned in double-precision arrays. The supported values for precision are listed below in Tips.

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

[A,count,msg] = fread(...) returns a warning message to msg if the read operation was unsuccessful.

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, each time fread is issued.

Rules for Completing a Binary Read Operation

A read operation with fread blocks access to the MATLAB® command line until:

  • The specified number of values are read.

  • The time specified by the Timeout property passes.

    Note

    The Terminator property is not used for binary read operations.

Supported Precisions

The supported values for precision are listed below.

Data Type

Precision

Interpretation

Character

uchar

8-bit unsigned character

schar

8-bit signed character

char

8-bit signed or unsigned character

Integer

int8

8-bit integer

int16

16-bit integer

int32

32-bit integer

uint8

8-bit unsigned integer

uint16

16-bit unsigned integer

uint32

32-bit unsigned integer

short

16-bit integer

int

32-bit integer

long

32- or 64-bit integer

ushort

16-bit unsigned integer

uint

32-bit unsigned integer

ulong

32- or 64-bit unsigned integer

Floating-point

single

32-bit floating point

float32

32-bit floating point

float

32-bit floating point

double

64-bit floating point

float64

64-bit floating point

Version History

Introduced before R2006a

collapse all

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.

See Also

Functions