fprintf (serial)

(Not recommended) Write text to device

This serial object function is not recommended. Use serialport object functions instead. See Compatibility Considerations.

Syntax

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

Description

fprintf(obj,'cmd') writes the string cmd to the device connected to the serial port object, obj. The default format is %s\n. The write operation is synchronous and blocks the command line until execution completes. The cmd can be either a SCPI command you provide, or a command you provide based on instructions from your device vendor.

fprintf(obj,'format','cmd') writes the string using the format specified by format.

fprintf(obj,'cmd','mode') writes the string with command-line access specified by mode. mode specifies if cmd is written synchronously or asynchronously.

fprintf(obj,'format','cmd','mode') writes the string using the specified format. format is a C language conversion specification.

You need an open connection from the serial port object, obj, to the device before performing read or write operations.

To open a connection to the device, use the fopen function. When obj has an open connection to the device, it has a Status property value of open.

Input Arguments

format

ANSI C conversion specification includes these conversion characters.

Specifier

Description

%c

Single character

%d or %i

Decimal notation (signed)

%e

Exponential notation (using lowercase e as in 3.1415e+00)

%E

Exponential notation (using uppercase E as in 3.1415E+00)

%f

Fixed-point notation

%g

The more compact of %e or %f. Insignificant zeros do not print.

%G

Same as %g, but using uppercase E

%o

Octal notation (unsigned)

%s

String of characters

%u

Decimal notation (unsigned)

%x

Hexadecimal notation (using lowercase letters a–f)

%X

Hexadecimal notation (using uppercase letters A–F)

cmd

Specifies the string cmd, which can be either a SCPI command you provide, or a command you provide based on instructions from your device vendor.

mode

Specifies whether the string cmd is written synchronously or asynchronously:

  • sync: cmd is written synchronously and the command line is blocked.

  • async: cmd is written asynchronously and the command line is not blocked.

If mode is not specified, the write operation is synchronous.

If you specify asynchronous mode, when the write operation occurs:

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

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

To determine whether an asynchronous write operation is in progress, use the TransferStatus property.

Examples

Create a serial port object s and connect it to a Tektronix TDS 210 oscilloscope. Write the RS232? command with fprintf. RS232? instructs the scope to return serial port communications settings. This example works on a Windows® platform.

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

Specify a format for the data that does not include the terminator, or configure the terminator to empty.

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

The default format for fprintf is %s\n. Therefore, the terminator specified by the Terminator property is automatically written. However, sometimes you might want to suppress writing the terminator.

Specify an array of formats and commands:

s = serial('COM1');
fopen(s)
fprintf(s,['ch:%d scale:%d'],[1 20e-3],'sync')

Compatibility Considerations

expand all

Not recommended starting in R2019b

See Also

Functions

Introduced before R2006a

MATLAB Documentation

Support