Instrument Control Toolbox

Reading Data

The functions associated with reading data are given below.

Table 2-4: Functions Associated with Reading Data 

Function Name	Description
binblockread	Read binblock data from the instrument.
fgetl	Read one line of text from the instrument and discard the terminator.
fgets	Read one line of text from the instrument and include the terminator.
fread	Read binary data from the instrument.
fscanf	Read data from the instrument, and format as text.
readasync	Read data asynchronously from the instrument.
scanstr	Read data from the instrument, format as text, and parse
stopasync	Stop asynchronous read and write operations.

The properties associated with reading data are given below.

Table 2-5: Properties Associated with Reading Data 

Property Name	Description
BytesAvailable	Indicate the number of bytes available in the input buffer.
InputBufferSize	Specify the size of the input buffer in bytes.
ReadAsyncMode	Specify whether an asynchronous read is continuous or manual (serial port, TCP/IP, UDP, and VISA-serial objects only).
Timeout	Specify the waiting time to complete a read or write operation.
TransferStatus	Indicate if an asynchronous read or write operation is in progress.
ValuesReceived	Indicate the total number of values read from the instrument.

The Input Buffer and Data Flow

The input buffer is computer memory allocated by the instrument object to store data that is to be read from the instrument. The flow of data from your instrument to MATLAB follows these steps:

1. The data read from the instrument is stored in the input buffer.
2. The data in the input buffer is returned to the MATLAB variable specified by the read function.

The InputBufferSize property specifies the maximum number of bytes that you can store in the input buffer. The BytesAvailable property indicates the number of bytes currently available to be read from the input buffer. The default values for these properties are given below.

• g = gpib('ni',0,1);
  get(g,{'InputBufferSize','BytesAvailable'})
  ans = 
      [512]    [0]
  

If you attempt to read more data than can fit in the input buffer, an error is returned and no data is read.

For example, suppose you use the fscanf function to read the text-based response of the *IDN? command previously written to the instrument. As shown below, the data is first read into the input buffer.

Note that for a given read operation, you might not know the number of bytes returned by the instrument. Therefore, you might need to preset the InputBufferSize property to a sufficiently large value before connecting the instrument object.

As shown below, after the data is stored in the input buffer, it is then transferred to the output variable specified by fscanf.

Reading Text Data Versus Reading Binary Data

For many instruments, reading text data means reading string data that reflect instrument settings, status information, and so on. Reading binary data means reading numerical values from the instrument.

You can read text data with the fgetl, fgets, and fscanf functions. By default, these functions return data using the %c format. You can read binary data with the fread function. By default, fread returns numerical values as double-precision arrays. Both the fscanf and fread functions support many other formats and precisions, as described in their reference pages.

The following example illustrates reading text data and binary data from a Tektronix TDS 210 oscilloscope, which is displaying a periodic input signal with a nominal frequency of 1.0 kHz.

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.

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

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

• fopen(g)
  

3. Write and read data -- Write the *IDN? command to the scope, and read back the identification information as text.

• fprintf(g,'*IDN?')
  idn = fscanf(g)
  idn =
  TEKTRONIX,TDS 210,0,CF:91.1CT FV:v1.16 TDS2CM:CMV:v1.04
  

1. Configure the scope to return the period of the input signal, and then read the period as a binary value. The output display format is configured to use short exponential notation for doubles.

   • fprintf(g,'MEASUREMENT:MEAS1:TYPE PERIOD')
     fprintf(g,'MEASUREMENT:MEAS1:VALUE?')
     format short e
     period = fread(g,9)'
     period =
         49    46    48    48    54    69    45    51    10
     

   period consists of positive integers representing character codes, where 10 is a line feed. To convert the voltage value to a string, use the char function.

   • char(period)
     ans =
     1.006E-3
     

   The ValuesReceived property indicates the total number of values that were read from the instrument.

   • g.ValuesReceived
     ans =
          65
     

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 Read Operations

The fgetl, fgets, fscanf, and fread functions operate synchronously and block the MATLAB command line until the operation completes. To perform an asynchronous read operation, you must use the readasync function. readasync asynchronously reads data from the instrument and stores it in the input buffer. To transfer the data from the input buffer to a MATLAB variable, you must use one of the synchronous read functions.

Note    For serial port, TCP/IP, UDP, and VISA-serial objects, you can also perform an asynchronous read operation by configuring the ReadAsyncMode property to continuous.

For example, to modify the preceding example to asynchronously read the scope's identification information, you would issue the readasync function after the *IDN? command is written.

• fprintf(g,'*IDN?')
  readasync(g)
  

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

• g.TransferStatus
  ans =
  read
  

You can use the BytesAvailable property to indicate the number of bytes that exist in the input buffer waiting to be transferred to MATLAB.

• g.BytesAvailable
  ans =
       56
  

When the read completes, you can transfer the data as text to a MATLAB variable using the fscanf function.

• idn = fscanf(g);
  

Writing Data

Disconnecting and Cleaning Up