External Interfaces Reference |
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. |
Description
writes the string fprintf(obj,'cmd')
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.
writes the string using the format specified by fprintf(obj,'
format
','cmd')
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.
writes the string with command line access specified by fprintf(obj,'cmd','
mode
')
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.
writes the string using the specified format. If fprintf(obj,'
format
','cmd','
mode
')
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.
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:
BytesToOutput
property value is continuously updated to reflect the number of bytes in the output buffer.
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:
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.
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.
Functions
Properties
BytesToOutput
, OutputBufferSize
, OutputEmptyFcn
, Status
, TransferStatus
, ValuesSent
fopen (serial) | fread (serial) |
© 1994-2005 The MathWorks, Inc.