External Interfaces/API

Writing Data

This section describes writing data to your serial port device in three parts:

• "The Output Buffer and Data Flow" describes the flow of data from MATLAB to the device.
• "Writing Text Data" describes how to write text data (string commands) to the device.
• "Writing Binary Data" describes how to write binary (numerical) data to the device.

The functions associated with writing data are given below.

Table 8-5: Functions Associated with Writing Data 

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.

Table 8-6: Properties Associated with Writing Data 

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:

1. The data specified by the write function is sent to the output buffer.
2. The data in the output buffer is sent to the device.

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.

• s = serial('COM1');
  get(s,{'OutputBufferSize','BytesToOutput'})
  ans = 
      [512]    [0]
  

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.

• s = serial('COM1');
  fopen(s)
  fprintf(s,'Display:Contrast 45')
  

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.

• s.ValuesSent
  ans =
      20
  

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.

• s.Terminator
  ans =
  LF
  

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.

• fprintf(s,'Display:Contrast 45','async')
  

Asynchronous operations do not block access to the MATLAB command line. Additionally, while an asynchronous write operation is in progress, you can:

• Execute an asynchronous read operation because serial ports have separate pins for reading and writing
• Make use of all supported callback properties

You can determine which asynchronous operations are in progress with the TransferStatus property. If no asynchronous operations are in progress, then TransferStatus is idle.

• s.TransferStatus
  ans =
  idle
  

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.

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