fread (serial) (External Interfaces Reference)

Read binary data from the device

Syntax

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

Arguments

obj
A serial port object.

size
The number of values to read.

'precision'
The number of bits read for each value, and the interpretation of the bits as character, integer, or floating-point values.

A
Binary data returned from the device.

count
The number of values read.

msg
A message indicating if the read operation was unsuccessful.

`obj`	A serial port object.
`size`	The number of values to read.
`'precision'`	The number of bits read for each value, and the interpretation of the bits as character, integer, or floating-point values.
`A`	Binary data returned from the device.
`count`	The number of values read.
`msg`	A message indicating if the read operation was unsuccessful.

Description

A = fread(obj,size) reads binary data from the device connected to obj, and returns the data to A. The maximum number of values to read is 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.

`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 Remarks.

[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.

Remarks

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.

If you use the help command to display help for fread, then you need to supply the pathname shown below.

```
help serial/fread
```

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

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

See Also

Functions

fgetl, fgets, fopen, fscanf

Properties

BytesAvailable, BytesAvailableFcn, InputBufferSize, Status, Terminator, ValuesReceived

fprintf (serial) fscanf (serial)