Write and Read GPIB Data

Rules for Completing Write and Read Operations

Completing Write Operations

A write operation using write, writeline, or writebinblock completes when one of these conditions is satisfied:

The specified data is written.
The time specified by the Timeout property passes.

An instrument determines if a write operation is complete based on the Terminator and EOIMode property values. The default value of Terminator is the line feed character. Refer to the documentation for your instrument to determine the terminator required by your instrument.

If EOIMode is on, then the End Or Identify (EOI) line is asserted when the last byte is written to the instrument. The last byte can be part of a binary data stream or a text data stream. The last byte written is the Terminator value and the EOI line is asserted when the instrument receives this byte.

Completing Read Operations

A read operation with read, readline, or readbinblock completes when one of these conditions is satisfied:

The terminator specified by the Terminator property is read.
The time specified by the Timeout property passes.
The specified number of values is read.

Writing and Reading Text Data

This example illustrates how to communicate with a VISA-GPIB instrument by writing and reading text data.

The instrument is a Tektronix^® TDS 210 two-channel oscilloscope. Therefore, many of the commands in the example are specific to this instrument. A sine wave is input into channel 2 of the oscilloscope, and you want to measure the peak-to-peak voltage of the input signal.

You can use these functions and properties when reading and writing text.

Function	Purpose
`writeline`	Write text to an instrument.
`readline`	Read data from an instrument and format as text.
EOIMode	Whether EOI (end or identify) line is asserted.
Terminator	Character used to terminate commands sent to the instrument.

Create a VISA-GPIB object — Create the VISA-GPIB object g associated with a National Instruments™ GPIB controller with board index 0 and an instrument with primary address 1.
```
g = visadev("GPIB0::1::0::INSTR");
```
Write and read data — Write the *IDN? command to the instrument using writeline, and then read back the result of the command using readline.
```
writeline(g,"*IDN?")
```
```
ans =

     56
```
```
idn = readline(g)
```
```
idn =

     "TEKTRONIX,TDS 210,0,CF:91.1CT FV:v1.16 TDS2CM:CMV:v1.04"
```
You need to determine the measurement source. Possible measurement sources include channel 1 and channel 2 of the oscilloscope.
```
writeline(g,"MEASUREMENT:IMMED:SOURCE?")
source = readline(g)
```
```
source =

     "CH1"
```
The scope is configured to return a measurement from channel 1. Because the input signal is connected to channel 2, you must configure the instrument to return a measurement from this channel.
```
writeline(g,"MEASUREMENT:IMMED:SOURCE CH2")
writeline(g,"MEASUREMENT:IMMED:SOURCE?")
source = readline(g)
```
```
source =

     "CH2"
```
You can now configure the scope to return the peak-to-peak voltage, and then request the value of this measurement.
```
writeline(g,"MEASUREMENT:MEAS1:TYPE PK2PK")
writeline(g,"MEASUREMENT:MEAS1:VALUE?")
```
Read back the result using the readline function.
```
ptop = readline(g)
```
```
ptop =

     "2.0199999809E0"
```
Disconnect and clean up — Use clear to disconnect the instrument from the VISA-GPIB object g and to clear it from the MATLAB^® workspace when you are done working with it.
```
clear g
```

ASCII Write Properties

By default, the End or Identify (EOI) line is asserted when the last byte is written to the instrument. This behavior is controlled by the EOIMode property. When EOIMode is set to on, the EOI line is asserted when the last byte is written to the instrument. When EOIMode is set to off, the EOI line is not asserted when the last byte is written to the instrument.

Writing and Reading Binary Data

This example illustrates how you can download the TDS 210 oscilloscope screen display. The screen display data is saved to disk using the Windows^® bitmap format. This data provides a permanent record of your work, and is an easy way to document important signal and scope parameters.

You use these functions when reading and writing binary data.

Function	Purpose
`read`	Read binary data from an instrument.
`write`	Write binary data to an instrument.

Note

When performing a read or write operation, 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.

Create a VISA-GPIB object — Create the VISA-GPIB object g associated with a National Instruments GPIB controller with board index 0 and an instrument with primary address 1.
```
g = visadev("GPIB0::1::0::INSTR");
```
Configure timeout value — Configure the timeout value to two minutes to account for slow data transfer.
```
g.Timeout = 120;
```
Write and read data — Configure the scope to transfer the screen display as a bitmap.
```
writeline(g,"HARDCOPY:PORT GPIB")
writeline(g,"HARDCOPY:FORMAT BMP")
writeline(g,"HARDCOPY START")
```
Transfer the data to the MATLAB workspace as unsigned 8-bit integers.
```
out = read(g,g.NumBytesAvailable,"uint8");
```
Disconnect and clean up — Use clear to disconnect the instrument from the VISA-GPIB object g and to clear it from the MATLAB workspace when you are done working with it.
```
clear g
```

Viewing Bitmap Data

Follow these steps to view the bitmap data.

Open a disk file.
Write the data to the disk file.
Close the disk file.
Read the data using the imread function.
Scale and display the data using the imagesc function.

Use the MATLAB software file I/O functions fopen, fwrite, and fclose.

fid = fopen("test1.bmp","w");
fwrite(fid,out,"uint8");
fclose(fid)
a = imread("test1.bmp","bmp");

Display the image.

imagesc(a)

Use a gray colormap since the instrument generates only grayscale images.

c = colormap(gray);
colormap(flipud(c));

The resulting bitmap image is shown in the following figure.

Image of an oscilloscope screen displaying a sine wave in a MATLAB figure window

Parse Input String Data

This example illustrates how to use the split function to parse data that you read from a Tektronix TDS 210 oscilloscope. The split function is particularly useful when you want to parse a string into one or more array elements, where each element is determined to be either a double or a character vector.

Create a VISA-GPIB object — Create the VISA-GPIB object g associated with a National Instruments GPIB controller with board index 0 and an instrument with primary address 1.
```
g = visadev("GPIB0::1::0::INSTR");
```

Write and read data — Return identification information to separate elements of a cell array using the "," delimiters.

writeline(g,"*IDN?")
idn = readline(g);
idn = split(idn,",")

idn = 

  4×1 string array

    "TEKTRONIX"
    "TDS 210"
    "0"
    "CF:91.1CT FV:v1.16 TDS2CM:CMV:v1.04"

Disconnect and clean up — Use clear to disconnect the instrument from the VISA-GPIB object g and to clear it from the MATLAB workspace when you are done working with it.
```
clear g
```