fwrite

Write binary data to instrument

Syntax

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


Arguments

obj	An interface object.
A	The binary data written to the instrument.
'precision'	The number of bits written for each value, and the interpretation of the bits as character, integer, or floating-point values.
'mode'	Specifies whether data is written synchronously or asynchronously.

Description

fwrite(obj,A) writes the binary data A to the instrument connected to 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 support values for precision are listed in Supported Precisions.

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 instrument, it must be connected to obj with the fopen function. A connected interface 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 instrument.

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.

fwrite will return an error message if you set the FlowControl property to hardware on a serial object, and a hardware connection is not detected. This occurs if a device is not connected, or a connected device is not asserting that is ready to receive data. Check you remote device's 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.

Note

To get a list of options you can use on a function, press the Tab key after entering a function on the MATLAB command line. The list expands, and you can scroll to choose a property or value. For information about using this advanced tab completion feature, see Using Tab Completion for Functions.

Synchronous Versus Asynchronous Write Operations

By default, data is written to the instrument 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 and EOSCharCode properties are not used with binary write 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

R2024a: i2c object interface warns

Use of this function with an i2c object issues a warning that i2c will be removed in a future release. To connect to a peripheral device on an I2C controller, use the device function with an aardvark or ni845x object, its functions, and its properties instead.

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

R2023a: i2c object interface will be removed

Use of this function with an i2c object will be removed in a future release.

R2021b: gpib object interface will be removed

Use of this function with a gpib object will be removed. To access a GPIB instrument, use the VISA-GPIB interface with a visadev object, its functions, and its properties instead.

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

R2021a: tcpip, visa, and serial object interfaces will be removed

Use of this function with the tcpip (with NetworkRole set to server), visa, and serial interfaces will be removed. Use the following interfaces and their functions instead. The recommended interfaces have additional capabilities and improved performance.

Functionality	Use This Instead	Additional Information
tcpip	tcpserver	Transition Your Code to tcpserver Interface
visa	visadev	Transition Your Code to visadev Interface
serial	serialport	Transition Your Code to serialport Interface

R2020b: Bluetooth, tcpip, and udp object interfaces will be removed

Use of this function with the Bluetooth, tcpip (with NetworkRole set to client), and udp interfaces will be removed. Use the following interfaces and their functions instead. The recommended interfaces have additional capabilities and improved performance.

Functionality	Use This Instead	Additional Information
Bluetooth	bluetooth (case-sensitive)	Transition Your Code to bluetooth Interface
tcpip	tcpclient	Transition Your Code to tcpclient Interface
udp	udpport	Transition Your Code to udpport Interface

R2019b: serial object interface is not recommended

Use of this function with a serial object is not recommended. To access a serial port, use a serialport object 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.