External Interfaces |
Writing Data
This section describes writing data to your serial port device in three parts:
The functions associated with writing data are given below.
Function Name |
Description |
fprintf |
Write text to the device |
fwrite |
Write binary data to the device |
stopasync |
Stop asynchronous read and write operations |
The properties associated with writing data are given below.
Property Name |
Description |
BytesToOutput |
Indicate the number of bytes currently in the output buffer |
OutputBufferSize |
Specify the size of the output buffer in bytes |
Timeout |
Specify the waiting time to complete a read or write operation |
TransferStatus |
Indicate if an asynchronous read or write operation is in progress |
ValuesSent |
Indicate the total number of values written to the device |
The Output Buffer and Data Flow
The output buffer is computer memory allocated by the serial port object to store data that is to be written to the device. When writing data to your device, the data flow follows these two steps:
The OutputBufferSize
property specifies the maximum number of bytes that you can store in the output buffer. The BytesToOutput
property indicates the number of bytes currently in the output buffer. The default values for these properties are given below.
If you attempt to write more data than can fit in the output buffer, an error is returned and no data is written.
For example, suppose you write the string command *IDN?
to the TDS 210 oscilloscope using the fprintf
function. As shown below, the string is first written to the output buffer as six values.
The *IDN?
command consists of six values because the terminator is automatically written. Moreover, the default data format for the fprintf
function specifies that one value corresponds to one byte. For more information about bytes and values, refer to Bytes Versus Values. fprintf
and the terminator are discussed in Writing Text Data.
As shown below, after the string is written to the output buffer, it is then written to the device via the serial port.
Writing Text Data
You use the fprintf
function to write text data to the device. For many devices, writing text data means writing string commands that change device settings, prepare the device to return data or status information, and so on.
For example, the Display:Contrast
command changes the display contrast of the oscilloscope.
By default, fprintf
writes data using the %s\n
format because many serial port devices accept only text-based commands. However, you can specify many other formats as described in the fprintf
reference pages.
You can verify the number of values sent to the device with the ValuesSent
property.
Note that the ValuesSent
property value includes the terminator because each occurrence of \n
in the command sent to the device is replaced with the Terminator
property value.
The default value of Terminator
is the line feed character. The terminator required by your device will be described in its documentation.
Synchronous Versus Asynchronous Write Operations. By default, fprintf
operates synchronously and will block the MATLAB command line until execution completes. To write text data asynchronously to the device, you must specify async
as the last input argument to fprintf
.
Asynchronous operations do not block access to the MATLAB command line. Additionally, while an asynchronous write operation is in progress, you can:
You can determine which asynchronous operations are in progress with the TransferStatus
property. If no asynchronous operations are in progress, then TransferStatus
is idle
.
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.
Writing Binary Data
You use the fwrite
function to write binary data to the device. Writing binary data means writing numerical values. A typical application for writing binary data involves writing calibration data to an instrument such as an arbitrary waveform generator.
Note
Some serial port devices accept only text-based commands. These commands might use the SCPI language or some other vendor-specific language. Therefore, you might need to use the fprintf function for all write operations.
|
By default, fwrite
translates values using the uchar
precision. However, you can specify many other precisions as described in the reference pages for this function.
By default, fwrite
operates synchronously. To write binary data asynchronously to the device, you must specify async
as the last input argument to fwrite
. For more information about synchronous and asynchronous write operations, refer to the Writing Text Data. For a description of the rules used by fwrite
to complete a write operation, refer to its reference pages.
Controlling Access to the MATLAB Command Line | Reading Data |
© 1994-2005 The MathWorks, Inc.