Reading and Writing Binary Data Using VISA

This example explores binary read and write operations with a VISA object. The instrument used was a Tektronix® TDS 210 oscilloscope.

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.

These functions are used when reading and writing binary data:

FunctionPurpose
freadRead binary data from the instrument.
fwriteWrite binary data to the instrument.

These properties are associated with reading and writing binary data:

PropertyPurpose
ValuesReceivedSpecifies the total number of values read from the instrument.
ValuesSentSpecifies the total number of values sent to the instrument.
InputBufferSizeSpecifies the total number of bytes that can be queued in the input buffer at one time.
OutputBufferSizeSpecifies the total number of bytes that can be queued in the output buffer at one time.
EOSModeConfigures the End-Of-String termination mode.
EOSCharCodeSpecifies the End-Of-String terminator.

Configuring and Connecting to the Instrument

You need to create a VISA-GPIB object. In this example, an object is created using the ni driver and the VISA resource string shown below.

v = visa('ni', 'GPIB0::2::INSTR');

Before you can perform a read or write operation, you must connect the VISA-GPIB object to the instrument with the fopen function.

fopen(v);

If the object was successfully connected, its Status property is automatically configured to open.

v.Status
ans = 
    open

Writing Binary Data

You use the fwrite function to write binary data to the instrument. For example, the following command will send a sine wave to the instrument. By default, the fwrite function operates in a synchronous mode. This means that fwrite blocks the MATLAB® command line until one of the following occurs:

  • All the data is written

  • A timeout occurs as specified by the Timeout property

By default the fwrite function writes binary data using the uchar precision. However, other precisions can also be used. For a list of supported precisions, see the function reference page for fwrite.

Note

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.

v.OutputBufferSize
ans = 
    512

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

fclose(v);
v.OutputBufferSize = 3000;
fopen(v);

Writing Int16 Binary Data

Now write a waveform as an int16 array.

fprintf(v, 'Data:Destination RefB');
fprintf(v, 'Data:Encdg SRPbinary');
fprintf(v, 'Data:Width 2');
fprintf(v, 'Data:Start 1');

t = (0:499) .* 8 * pi / 500;
data = round(sin(t) * 90 + 127);
fprintf(v, 'CURVE #3500');

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

fwrite(v, data, 'int16')

ValuesSent

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

v.ValuesSent
ans = 
    576

Reading Binary Data

You use the fread function to read binary data from the instrument.

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

  • A timeout occurs as specified by the Timeout property

  • The input buffer is filled

  • The specified number of values is read

  • The EOI line is asserted

  • The terminator is received as specified by the EOSCharCode property (if defined)

By default the fread function reads binary data using the uchar precision. However, other precisions can also be used. For a list of supported precisions, see the function reference page for fread.

Note

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 you can read from the instrument. By default, InputBufferSize is 512.

v.InputBufferSize
ans = 
    512

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

fclose(v);
v.InputBufferSize = 5100;
fopen(v);

Reading Int16 Binary Data

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

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

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

data = fread(v, 1200, 'int16');

ValuesReceived

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

v.ValuesReceived

ans =

    1200

Since we may not have read all of the values, clear the input buffer.

flushinput(v);

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.

Configure the GPIB object's terminator to the letter E.

set(v, 'EOSMode', 'read');
set(v, 'EOSCharCode', double('E'));

Now, read the channel 1's signal frequency.

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

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

data = fread(v, 30);
char(data)'

Warning: The EOI line was asserted or the EOSCharCode was detected 
% before SIZE values were available.

ans =

    9.9E

data = fread(v, 30);
char(data)'

Warning: The EOI line was asserted or the EOSCharCode was detected 
% before SIZE values were available.

ans =

    37

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(v);
delete(v);
clear v