fprintf (serial) (External Interfaces/API Reference)

Write text to the device

Syntax

fprintf(obj,'cmd')
fprintf(obj,'format','cmd')
fprintf(obj,'cmd','mode')
fprintf(obj,'format','cmd','mode')

Arguments

obj
A serial port object.

'cmd'
The string written to the device.

'format'
C language conversion specification.

'mode'
Specifies whether data is written synchronously or asynchronously.

`obj`	A serial port object.
`'cmd'`	The string written to the device.
`'format'`	C language conversion specification.
'`mode`'	Specifies whether data is written synchronously or asynchronously.

Description

fprintf(obj,'cmd') writes the string cmd to the device connected to obj. The default format is %s\n. The write operation is synchronous and blocks the command line until execution is complete.

fprintf(obj,'format','cmd') writes the string using the format specified by 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 sprintf file I/O format specifications or a C manual for more information.

fprintf(obj,'cmd','mode') writes the string with command line access specified by mode. If mode is sync, cmd is written synchronously and the command line is blocked. If mode is async, cmd is written asynchronously and the command line is not blocked. If mode is not specified, the write operation is synchronous.

fprintf(obj,'format','cmd','mode') writes the string using the specified format. If mode is sync, cmd is written synchronously. If mode is async, cmd is written asynchronously.

Remarks

Before you can write text 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 fprintf 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 use the help command to display help for fprintf, then you need to supply the pathname shown below.

```
help serial/fprintf
```

Synchronous Versus Asynchronous Write Operations

By default, text 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 M-file 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.

Synchronous and asynchronous write operations are discussed in more detail in Controlling Access to the MATLAB Command Line.

Rules for Completing a Write Operation with fprintf

A synchronous or asynchronous write operation using fprintf completes when:

The specified data is written.

The time specified by the Timeout property passes.

Additionally, you can stop an asynchronous write operation with the stopasync function.

Rules for Writing the Terminator

All occurrences of \n in cmd are replaced with the Terminator property value. Therefore, when using the default format %s\n, all commands written to the device will end with this property value. The terminator required by your device will be described in its documentation.

Example

Create the serial port object s, connect s to a Tektronix TDS 210 oscilloscope, and write the RS232? command with the fprintf function. RS232? instructs the scope to return serial port communications settings.

s = serial('COM1');
fopen(s)
fprintf(s,'RS232?')

Because the default format for fprintf is %s\n, the terminator specified by the Terminator property was automatically written. However, in some cases you might want to suppress writing the terminator. To do so, you must explicitly specify a format for the data that does not include the terminator, or configure the terminator to empty.

```
fprintf(s,'%s','RS232?')
```

See Also

Functions

fopen, fwrite, stopasync

Properties

BytesToOutput, OutputBufferSize, OutputEmptyFcn, Status, TransferStatus, ValuesSent

fopen (serial) fread (serial)