| MATLAB Function 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
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.
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.
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.
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.
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:
BytesToOutput property value is continuously updated to reflect the number of bytes in the output buffer.OutputEmptyAction 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 Writing Data.
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.
s = serial('COM1');
fopen(s)
fprintf(s,'RS232?')
Since the default format for fprintf is %s\n, the terminator specified by the Terminator property was automatically written. However, in some cases you may want to suppress writing the terminator. To do so, you must explicitly specify a format for the data that does not include the terminator.
fprintf(s,'%s','RS232?')
Functions
Properties
BytesToOutput, OutputBufferSize, OutputEmptyAction, Status, TransferStatus, ValuesSent
| | fprintf | frame2im | |