Main Content

fwrite (serial)

(To be removed) Write binary data to 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

fwrite(obj,A)
fwrite(obj,A,'precision')
fwrite(obj,A,'mode')
fwrite(obj,A,'precision','mode')

Description

fwrite(obj,A) writes the binary data A to the device connected to the serial port object, obj.

fwrite(obj,A,'precision') writes binary data with precision specified by precision.

precision controls the number of bits written 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. The supported values for precision are listed in Tips.

fwrite(obj,A,'mode') writes binary data with command-line access specified by mode. If mode is sync, A is written synchronously and the command line is blocked. If mode is async, A is written asynchronously and the command line is not blocked. If mode is not specified, the write operation is synchronous.

fwrite(obj,A,'precision','mode') writes binary data with precision specified by precision and command-line access specified by mode.

Tips

Before you can write data to 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 write operation while obj is not connected to the device.

The ValuesSent property value is increased by the number of values written each time fwrite is issued.

An error occurs if the output buffer cannot hold all the data to be written. You can specify the size of the output buffer with the OutputBufferSize property.

If you set the FlowControl property to hardware on a serial object, and a hardware connection is not detected, fwrite returns an error message. This occurs if a device is not connected, or a connected device is not asserting that is ready to receive data. Check the remote device status and flow control settings to see if hardware flow control is causing errors in MATLAB®.

Note

If you want to check to see if the device is asserting that it is ready to receive data, set the FlowControl to none. Once you connect to the device, check the PinStatus structure for ClearToSend. If ClearToSend is off, there is a problem on the remote device side. If ClearToSend is on, there is a hardware FlowControl device prepared to receive data and you can execute fwrite.

Synchronous Versus Asynchronous Write Operations

By default, data is written to the device synchronously and the command line is blocked until the operation completes. You can perform an asynchronous write by configuring the mode input argument to be async. For asynchronous writes:

  • The BytesToOutput property value is continuously updated to reflect the number of bytes in the output buffer.

  • The callback function specified for the OutputEmptyFcn property is executed when the output buffer is empty.

You can determine whether an asynchronous write operation is in progress with the TransferStatus property.

Rules for Completing a Write Operation with fwrite

A binary write operation using fwrite completes when:

  • The specified data is written.

  • The time specified by the Timeout property passes.

    Note

    The Terminator property is not used with binary write operations.

Supported Precisions

The following table shows the supported values for precision.

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