Instrument Control Toolbox

Writing Data

The functions associated with writing data are given below.

Table 2-2: Functions Associated with Writing Data 

Function Name	Description
binblockwrite	Write binblock data to the instrument.
fprintf	Write text to the instrument.
fwrite	Write binary data to the instrument.
stopasync	Stop asynchronous read and write operations.

The properties associated with writing data are given below.

Table 2-3: 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 instrument.

The Output Buffer and Data Flow

The output buffer is computer memory allocated by the instrument object to store data that is to be written to the instrument. The flow of data from MATLAB to your instrument follows these 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 instrument.

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.

• g = gpib('ni',0,1);
  get(g,{'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.

Note    When writing data, you might need to specify a value, which can consist of one or more bytes. This is because some write functions allow you to control the number of bits written for each value and the interpretation of those bits as character, integer or floating point values. For example, if you write one value from an instrument using the int32 format, then that value consists of four bytes.

For example, suppose you write the string command *IDN? to an instrument 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 End-Of-String character is written to the instrument, as specified by the EOSMode and EOSCharCode properties. Moreover, the default data format for the fprintf function specifies that one value corresponds to one byte.

As shown below, after the string is stored in the output buffer, it is then written to the instrument.

Writing Text Data Versus Writing Binary Data

For many instruments, writing text data means writing string commands that change instrument settings, prepare the instrument to return data or status information, and so on. Writing binary data means writing numerical values to the instrument such as calibration or waveform data.

You can write text data with the fprintf function. By default, fprintf uses the %s\n format, which formats the data as a string and includes the terminator. You can write binary data with the fwrite function. By default, fwrite writes data using the uchar precision, which translates the data as unsigned 8-bit characters. Both of these functions support many other formats and precisions, as described in their reference pages.

The following example illustrates writing text data and binary data to a Tektronix TDS 210 oscilloscope. The text data consists of string commands, while the binary data is a waveform that is to be downloaded to the scope and stored in its memory.

1. Create an instrument object -- Create the GPIB object g associated with a National Instruments GPIB controller with board index 0, and an instrument with primary address 1. The size of the output buffer is increased to accommodate the waveform data. You must configure the OutputBufferSize property while the GPIB object is disconnected from the instrument.

• g = gpib('ni',0,1);
  g.OutputBufferSize = 3000;
  

2. Connect to the instrument -- Connect g to the instrument.

• fopen(g)
  

3. Write and read data -- Write string commands that configure the scope to store binary waveform data in memory location A.

• fprintf(g,'DATA:DESTINATION REFA');
  fprintf(g,'DATA:ENCDG SRPbinary');
  fprintf(g,'DATA:WIDTH 1');
  fprintf(g,'DATA:START 1');
  

1. Create the waveform data.

   • t = linspace(0,25,2500);
     data = round(sin(t)*90 + 127);
     

   Write the binary waveform data to the scope.

   • cmd = double('CURVE #42500');
     fwrite(g,[cmd data]);
     

   The ValuesSent property indicates the total number of values that were written to the instrument.

   • g.ValuesSent
     ans =
             2577
     

4. Disconnect and clean up -- When you no longer need g, you should disconnect it from the instrument, remove it from memory, and remove it from the MATLAB workspace.

• fclose(g)
  delete(g)
  clear g
  

Synchronous Versus Asynchronous Write Operations

By default, all write functions operate synchronously and block the MATLAB command line until the operation completes. To perform an asynchronous write operation, you must supply the async input argument to the fprintf or fwrite functions.

For example, you use the following syntax to modify the fprintf commands used in the preceding example to write text data asynchronously.

• fprintf(g,'DATA:DESTINATION REFA','async');
  

Similarly, you use the following syntax to modify the fwrite command used in the preceding example to write binary data asynchronously.

• fwrite(g,[cmd data],'async');
  

You can monitor the status of the asynchronous write operation with the TransferStatus property. A value of idle indicates that no asynchronous operations are in progress.

• g.TransferStatus
  ans =
  write
  

You can use the BytesToOutput property to indicate the numbers of bytes that exist in the output buffer waiting to be written to the instrument.

• g.BytesToOutput
  ans =
          2512
  

Writing and Reading Data

Reading Data