VISA Binary Read and Write Operations

Contents

Introduction

This demo explores binary read and write operations with a VISA object.

The information obtained for this demonstration was prerecorded. Therefore, you do not need an actual instrument to learn about binary read and write operations using a VISA object.

The GPIB board used was a National Instruments PCI-GPIB+ GPIB card. The instrument used was a Tektronix TDS 210 oscilloscope.

The Supported VISA Interfaces

The VISA object supports seven interfaces:

This tutorial explores binary read and write operations using a VISA-GPIB object. However, binary read and write operations for VISA-GPIB, VISA-VXI, VISA-GPIB-VXI, VISA-TCPIP, and VISA-USB objects are identical to each other. Therefore, you can use the same commands. The only difference is the resource name specified in the VISA constructor.

Binary read and write operations for the VISA-serial object are identical to binary read and write operations for the serial port object. Therefore, to learn how to perform binary read and write operations for the VISA-serial object, you should refer to the Serial Port Binary Read/Write tutorial.

Binary read and write operations for the VISA-RSIB object are identical to the binary read and write operations for the VISA-GPIB, VISA-VXI, VISA-GPIB-VXI, VISA-TCPIP, and VISA-USB objects, except the VISA-RSIB object does not support the EOSCharCode and EOSMode properties.

Functions and Properties

These functions are used when reading and writing binary data:

FREAD            - Read binary data from instrument.
FWRITE           - Write binary data to instrument.

These properties are associated with reading and writing binary data:

ValuesReceived   - Specifies the total number of values
                   read from the instrument.
ValuesSent       - Specifies the total number of values
                   sent to the instrument.
InputBufferSize  - Specifies the total number of bytes
                   that can be queued in the input buffer
                   at one time.
OutputBufferSize - Specifies the total number of bytes
                   that can be queued in the output buffer
                   at one time.
EOSMode          - Configures the End-Of-String termination
                   mode.
EOSCharCode      - Specifies the End-Of-String terminator.

Creating a VISA-GPIB Object

To begin, create a VISA-GPIB object. The board index is configured to 0, the primary address is configured to 1.

>> g = visa('ni', 'GPIB0::1::0::INSTR');
  VISA-GPIB Object Using NI Adaptor : VISA-GPIB0-1
  Communication Address
     BoardIndex:         0
     PrimaryAddress:     1
     SecondaryAddress:   0
  Communication State
     Status:             closed
     RecordStatus:       off
  Read/Write State
     TransferStatus:     idle
     BytesAvailable:     0
     ValuesReceived:     0
     ValuesSent:         0

Connecting the VISA-GPIB Object to the Instrument

Before you can perform a read or write operation, you must connect the VISA-GPIB object to the instrument with the FOPEN function. If the object was successfully connected, its Status property is automatically configured to open. 

>> fopen(g)
>> get(g, 'Status')
ans =
open

Note that the display summary is updated accordingly.

>> g
  VISA-GPIB Object Using NI Adaptor : VISA-GPIB0-1
  Communication Address
     BoardIndex:         0
     PrimaryAddress:     1
     SecondaryAddress:   0
  Communication State
     Status:             open
     RecordStatus:       off
  Read/Write State
     TransferStatus:     idle
     BytesAvailable:     0
     ValuesReceived:     0
     ValuesSent:         0

Writing Binary Data

You use the FWRITE function to write binary data to the instrument. For example, the following commands will send a sine wave to the oscilloscope: 

>> fprintf(g, 'Data:Destination RefB');
>> fprintf(g, 'Data:Encdg SRPbinary');
>> fprintf(g, 'Data:Width 1');
>> fprintf(g, 'Data:Start 1');
>> t = (0:499) .* 8 * pi / 500;
>> data = round(sin(t) * 90 + 127);
>> cmd = double('CURVE #3500');
>> fwrite(g, [cmd data])

By default, the FWRITE function operates in synchronous mode. This means that FWRITE blocks the MATLAB command line until one of the following occurs:

By default the FWRITE function writes binary data using the uchar precision. However, the following precisions can also be used: 

   MATLAB           Description
   'uchar'          unsigned character,  8 bits.
   'schar'          signed character,    8 bits.
   'int8'           integer,             8 bits.
   'int16'          integer,             16 bits.
   'int32'          integer,             32 bits.
   'uint8'          unsigned integer,    8 bits.
   'uint16'         unsigned integer,    16 bits.
   'uint32'         unsigned integer,    32 bits.
   'single'         floating point,      32 bits.
   'float32'        floating point,      32 bits.
   'double'         floating point,      64 bits.
   'float64'        floating point,      64 bits.
   'char'           character,           8 bits (signed or unsigned).
   'short'          integer,             16 bits.
   'int'            integer,             32 bits.
   'long'           integer,             32 or 64 bits.
   'ushort'         unsigned integer,    16 bits.
   'uint'           unsigned integer,    32 bits.
   'ulong'          unsigned integer,    32 bits or 64 bits.
   'float'          floating point,      32 bits.

Values Versus Bytes

When performing a write operation, you should think of the transmitted data in terms of values rather than bytes. A value consists of one or more bytes. For example, one uint32 value consists of four bytes.

Binary Write Properties -- OutputBufferSize

The OutputBufferSize property specifies the maximum number of bytes that can be written to the instrument at once. By default, OutputBufferSize is 512. 

>> get(g, 'OutputBufferSize')
ans =
    512

Configure the VISA-GPIB object's output buffer size to 3000 bytes. Note, the OutputBufferSize can be configured only when the object is not connected to the instrument. 

>> fclose(g);
>> set(g, 'OutputBufferSize', 3000);
>> fopen(g);

Writing Int16 Binary Data

Now write a waveform as an int16 array.

>> fprintf(g, 'Data:Destination RefB');
>> fprintf(g, 'Data:Encdg SRPbinary');
>> fprintf(g, 'Data:Width 2');
>> fprintf(g, 'Data:Start 1');
>> t = (0:499) .* 8 * pi / 500;
>> data = round(sin(t) * 90 + 127);
>> fprintf(g, 'CURVE #3500');

Note: one int16 value consists of two bytes. Therefore, the following command will write 1000 bytes.

>> fwrite(g, data, 'int16')

Properties Associated with Binary Writes

The ValuesSent property indicates the total number of values written to the instrument since the object was connected to the instrument. 

>> get(g, 'ValuesSent')
ans =
   576

Reading Binary Data

You use the FREAD function to read binary data from the instrument. For example, to read the waveform on channel 1 of the oscilloscope: 

>> fprintf(g, 'Data:Source CH1');
>> fprintf(g, 'Data:Encdg SRPbinary');
>> fprintf(g, 'Data:Width 1');
>> fprintf(g, 'Data:Start 1');
>> fprintf(g, 'Curve?')
>> data = fread(g, 512);

By default, the FREAD function reads data using the uchar precision and blocks the MATLAB command line until one of the following occurs:

By default the FREAD function reads data using the uchar precision. However, the following precisions can also be used:

   MATLAB           Description
   'uchar'          unsigned character,  8 bits.
   'schar'          signed character,    8 bits.
   'int8'           integer,             8 bits.
   'int16'          integer,             16 bits.
   'int32'          integer,             32 bits.
   'uint8'          unsigned integer,    8 bits.
   'uint16'         unsigned integer,    16 bits.
   'uint32'         unsigned integer,    32 bits.
   'single'         floating point,      32 bits.
   'float32'        floating point,      32 bits.
   'double'         floating point,      64 bits.
   'float64'        floating point,      64 bits.
   'char'           character,           8 bits (signed or unsigned).
   'short'          integer,             16 bits.
   'int'            integer,             32 bits.
   'long'           integer,             32 or 64 bits.
   'ushort'         unsigned integer,    16 bits.
   'uint'           unsigned integer,    32 bits.
   'ulong'          unsigned integer,    32 bits or 64 bits.
   'float'          floating point,      32 bits.

Values Versus Bytes

When performing a read operation, you should think of the received data in terms of values rather than bytes. A value consists of one or more bytes. For example, one uint32 value consists of four bytes.

Binary Read Properties -- InputBufferSize

The InputBufferSize property specifies the maximum number of bytes that you can read from the instrument. By default, InputBufferSize is 512. 

>> get(g, 'InputBufferSize')
ans =
    512

Configure the object's input buffer size to 2500. Note, the InputBufferSize can be configured only when the object is not connected to the instrument. 

>> fclose(g);
>> set(g, 'InputBufferSize', 2500);
>> fopen(g);

Reading Int16 Binary Data

Now read the same waveform on channel 1 as an int16 array.

>> fprintf(g, 'Data:Source CH1');
>> fprintf(g, 'Data:Encdg SRIbinary');
>> fprintf(g, 'Data:Width 2');
>> fprintf(g, 'Data:Start 1');
>> fprintf(g, 'Curve?')

Note: one int16 value consists of two bytes. Therefore, the following command will read 2400 bytes.

>> data = fread(g, 1200, 'int16');

Binary Read Properties -- ValuesReceived

The ValuesReceived property is updated by the number of values read from the instrument.

>> get(g, 'ValuesReceived')
ans =
    1200

Binary Read Properties -- EOSMode and EOSCharCode

For VISA-GPIB, objects, the terminator is defined by setting the object's EOSMode property to read and setting the object's EOSCharCode property to the ASCII code for the character received. For example, if the EOSMode property is set to read and the EOSCharCode property is set to 10, then one of the ways that the read terminates is when the linefeed character is received.

Let's configure the VISA-GPIB object's terminator to the letter E.

>> set(g, 'EOSMode', 'read');
>> set(g, 'EOSCharCode', double('E'));

Now, read the signal frequency of channel 1.

>> fprintf(g, 'Measurement:Meas1:Source CH1')
>> fprintf(g, 'Measurement:Meas1:Type Freq')
>> fprintf(g, 'Measurement:Meas1:Value?')

Note, the first read terminates due to the EOSCharCode being detected, while the second read terminates due to the EOI line being asserted. 

>> data = fread(g, 30);
Warning: The EOI line was asserted or the EOSCharCode was detected before SIZE values were available.
>> char(data)'
ans =
9.980040283203E
>> data = fread(g, 30);
Warning: The EOI line was asserted or the EOSCharCode was detected before SIZE values were available.
>> char(data)'
ans =
2

Cleanup

If you are finished with the VISA-GPIB object, disconnect it from the instrument, remove it from memory, and remove it from the workspace. 

>> fclose(g);
>> delete(g);
>> clear g

Copyright 1999-2004 The MathWorks, Inc.