Controlling GPIB instruments from MATLAB with GPIBEE

Overview

This is a single MATLAB script that opens an instrument through GPIBEE, asks it *IDN?, then loops a hundred DC voltage measurements with timestamps and plots them. No project, no build, one file.

GPIBEE is a fully VXI-11 compliant instrument and appears to MATLAB as an ordinary VISA resource, so nothing here is specific to this adapter. Point the same script at any other VISA instrument and it behaves the same way.

What you need

• A GPIBEE, with an instrument on the GPIB bus.
• MATLAB. Any reasonably current release. The script uses the modern visadev interface, which replaced the older visa object model.
• Instrument Control Toolbox. This is a separate add-on, not part of base MATLAB. Without it, visadev does not exist. See below.
• A VISA runtime. Also separate, and not from MathWorks. See below.

The toolbox question

This is the first thing to check, because it is the most common reason the script fails immediately and the error message does not make the cause obvious.

MATLAB is sold as a base product with toolboxes bought separately, and instrument communication lives in one of them. Instrument Control Toolbox is what provides visadev, writeread, writeline and everything else this script uses. A MATLAB installation without it cannot talk to an instrument at all.

To find out what you have, type ver at the MATLAB prompt. It prints every installed toolbox. Look for this line:

Instrument Control Toolbox                            Version 24.2

If it is not listed, the toolbox is not installed, and nothing further on this page will work until it is. It can be added to an existing licence through the MathWorks account portal, or installed from the Add-On Explorer inside MATLAB if your licence already covers it.

Install MATLAB

Skip this if you already have it. MathWorks distribute MATLAB through their own download page, which needs a MathWorks account tied to a licence:

For personal and hobby use there is a lower cost MATLAB Home licence. It is restricted to non-commercial use, and toolboxes are still bought individually on top of it, so check that Instrument Control Toolbox is included in what you are buying:

Licence terms are set by MathWorks and change from time to time. Read yours before using it for work.

Install a VISA

VISA is the standard API between your program and the instrument. Your code says "open this resource, write this string, read the answer", and VISA handles the transport underneath. GPIBEE appears on the network as a VXI-11 instrument, so any VISA can talk to it.

MATLAB does not ship one. It uses whichever VISA runtime is installed on the machine, so this is a separate download.

NI-VISA and the Keysight IO Libraries Suite work as well, and if one of them is already on the machine there is no reason to add another. Worth knowing: MathWorks' own documentation for the VXI-11 interface uses NI-VISA as its example, so if MATLAB ever refuses to see a resource that other software finds happily, trying NI-VISA is a sensible next step rather than a step backwards.

Download the example

Save it anywhere MATLAB can see it. Your working folder is fine.

Set your instrument address

Three lines near the top of the script are the only ones you need to touch:

instrument_ip   = "192.168.3.2";   % GPIBee address on the LAN
instrument_name = "inst0,4";       % GPIB address 4 on the bus
read_count      = 100;             % how many measurements to take

They are assembled into a VISA resource name that looks like this:

192.168.3.2 is the IP address of your GPIBEE, and the 4 at the end of inst0,4 is the GPIB address of the instrument. Both come from the adapter's web interface, which shows its own address and can scan the bus for you.

Run it

Open the file in MATLAB and press Run, or type this at the prompt:

run MatlabGpibeeExample

What you should see

The command window fills up as the readings come in:

Connecting to TCPIP0::192.168.3.2::inst0,4::INSTR ...
*IDN?: HEWLETT-PACKARD,34401A,0,5-1-1
Reading 100 DC-voltage measurement(s) via MEAS:VOLT:DC? ...
#  1: +1.05426700E-01     -> 0.105427 Vdc (t = 0.18 s)
#  2: +1.05430100E-01     -> 0.105430 Vdc (t = 0.35 s)
...
Connection closed.

Then a figure window opens with the readings plotted against elapsed time.

The line that matters most is the second one. HEWLETT-PACKARD,34401A,0,5-1-1 is the instrument stating its maker, model, serial number and firmware version. If you see that, every link in the chain works: MATLAB reached VISA, VISA reached the GPIBEE over the network, and the adapter reached the instrument over GPIB.

How the script works

Opening the instrument is one line, and setting a timeout is one more:

v = visadev(resource);
v.Timeout = 3;

Timeout is in seconds here, not milliseconds. That catches people who have come from another language, where three seconds is usually written as 3000.

A query is also one line, because writeread does both halves:

idn = writeread(v, "*IDN?");

It appends the terminator, sends the command, reads the answer back up to the terminator, and strips it. There is no buffer to size and no byte count to guess. If you want the two halves separately, writeline and readline do the same thing in two steps.

The reading loop is the same call in a for, with str2double turning each answer into a number and tic/toc stamping it with elapsed time. The whole thing sits inside try and catch, so a failure halfway through still releases the instrument instead of leaving the link open.

Closing, which looks like nothing

There is no close function for a visadev object. The connection is released when the object goes away:

clear v

That looks like housekeeping and is not. Until the object is cleared, the adapter still considers the link open, and the next run can find the instrument busy. It is why the script clears it in the error path too.

Termination

The script never sets a terminator, because it does not have to. A visadev object defaults its Terminator to "LF", the newline that nearly every SCPI instrument puts at the end of its answers, and that is what the rest of this tutorial set uses as well.

If your instrument ends its answers with a carriage return instead, set it explicitly:

configureTerminator(v, "CR");

visadev reference

Everything the script uses, in one place:

This is example code

The script is an example, not a product. It exists to save you the first afternoon and to give you something that already runs, so you can start from working code instead of a blank file. Take it apart, keep what you need and treat the rest as disposable.

It also does only the simple half of instrument control. Device clear, triggering, reading the status byte and waiting on service requests are all part of VISA and none of them appear here. Instrument Control Toolbox does support them, so adding one is a matter of finding the right function rather than working around a gap in the example.

Troubleshooting