Controlling GPIB instruments from GNU Octave on Linux with GPIBEE

Overview

This one is different from the others on this site, and in a way that is worth knowing about before you start.

The C, Pascal and Excel examples all reach the instrument through a vendor VISA runtime. This one does not. It speaks VXI-11 directly, which is the same protocol GPIBEE itself talks on the network, so there is no VISA to install at all. One Octave package, one script, done.

To be precise about what that means: the vxi11 functions in Octave's instrument-control package are not a VISA wrapper. There is no visa32.dll, no libvisa, no NI, Keysight or R&S runtime involved anywhere. The package implements VXI-11 itself, as ONC/RPC over TCP/IP, and opens an ordinary socket to the adapter. VISA is one way to reach a VXI-11 instrument; it is not the only one, and here it is simply not in the path.

That is why the RPC development packages appear in the install list below: they are what the package compiles its RPC layer against.

By the end you will have a script that connects to an instrument, identifies it and logs ten voltage readings with timestamps, and you will know the four calls needed to write your own.

What GNU Octave is

GNU Octave is a free, open source environment for numerical computing, and it is deliberately close to MATLAB. The language, the matrix-first way of working, the plotting, and a great deal of the function library are the same or near enough, so MATLAB code often runs with little or no change and someone who knows one can use the other straight away.

"Close" is not "identical", though. Compatibility is good rather than complete, and Octave also has extensions of its own that MATLAB does not accept. The example here uses several of them, which is covered further down.

For instrument work it is a sensible choice on Linux: it is in every distribution's package manager, it costs nothing, the maths and plotting you want for measurement data are built in, and the instrument-control package gives it network instrument support without a vendor runtime.

The project lives here, with the documentation and the source:

Prerequisites

• A GPIBEE, with an instrument on the GPIB bus.
• Linux. The instructions below are for Debian and Ubuntu; adjust the package manager for other distributions.
• No VISA runtime. Genuinely not needed here.

Install Octave

Octave and the pieces the instrument-control package needs:

sudo apt install octave gnuplot octave-dev pkg-config libtirpc-dev rpcsvc-proto

More than just octave is in that list for a reason. The instrument-control package is compiled from source on your machine when you install it, so the build tools have to be there first:

Then start Octave with its GUI, from a terminal:

octave --gui

Add & at the end if you want your terminal back:

octave --gui &

Install instrument-control

At the Octave prompt:

pkg install -forge instrument-control

When it finishes you get a single line back, and the prompt returns:

>> pkg install -forge instrument-control
For information about changes from previous versions of the instrument-control package, run 'news instrument-control'.
>>

That is the whole installation. It is a one-off: the package stays installed for future sessions, though each script still has to pkg load it, which the example does for you.

If you skip this step, the script stops immediately with:

FAIL: could not load the instrument-control package: package instrument-control is not installed
      Install it first, e.g.: pkg install -forge instrument-control
>>

Download the example

Save it somewhere Octave can see it, your home directory is fine.

Open and run it

In Octave, use File → Open and pick the script. Octave then looks like this:

To run it, press F5, or use Run → Save file and run.

Output does not appear in the editor. Click the Command Window tab at the bottom to see it.

What the output shows

Reading down what happened:

• Connecting to VXI-11 instrument inst0,4 at 192.168.3.2 ... then Connected. The script opened a VXI-11 link to GPIB address 4 behind the adapter at that IP.
• *IDN?: HEWLETT-PACKARD,34401A,0,5-1-1 The instrument identified itself: manufacturer, model, serial number and firmware revision. If this line appears, the whole chain works.
• Ten numbered lines, each with a timestamp, the raw reply such as +3.71490000E-05, and the parsed value 0.000037 Vdc.

Keeping the raw reply next to the parsed number is deliberate. When a value looks wrong, the first question is whether the instrument sent something unexpected or the parsing went astray, and with both on the line you can see which.

The readings themselves are a multimeter measuring an open input, so they are tens of microvolts of noise. That is the expected result with nothing connected, and a good sanity check: the numbers move a little between readings, which tells you they are real measurements rather than a cached value.

How the script works

Everything you would normally change sits in one block:

instrument_ip    = "192.168.3.2";  % GPIBee / instrument LAN address
instrument_name  = "inst0,4";      % VXI-11 device name
read_count       = 10;             % number of MEAS:VOLT:DC? readings
io_timeout_s     = 3;              % informational only

instrument_ip is the adapter. 192.168.3.2 is the default address of a GPIBEE connected over USB, which is used here because it is predictable; over Ethernet you put in whatever address it has on your network.

instrument_name is the VXI-11 device name, and inst0,4 means GPIB primary address 4. It is the same thing as the tail of the VISA resource string used in the other tutorials: TCPIP::192.168.3.2::inst0,4::INSTR.

The instrument work itself is four calls:

A query is a write followed by a read, which the script wraps in a small helper:

function response = query_instrument(vi, command)
  vxi11_write(vi, [command "\n"]);
  [data, count] = vxi11_read(vi, 4096);
  response = strip_termination(char(reshape(data(1:count), 1, count)));
endfunction

Note what vxi11_read hands back: a numeric byte array and a count, not a string. The char(reshape(...)) turns the first count bytes into text. Forgetting the count and converting the whole 4096-byte buffer is a common first mistake, and it gives you your answer followed by a great deal of rubbish.

The main loop is wrapped in unwind_protect:

unwind_protect
  % ... open, query, read ...
unwind_protect_cleanup
  if !isempty(vi)
    vxi11_close(vi);
  endif
end_unwind_protect

That is Octave's try/finally, and it matters more than it looks. The cleanup block runs whether the script finishes normally, hits an error, or you interrupt it with Ctrl+C, so the link to the instrument is always closed. Without it, an error mid-run leaves a link open on the adapter, and the next run can find the instrument busy.

Octave, not MATLAB

Octave and MATLAB overlap heavily, but this script uses Octave-only syntax in several places. If you want to run it under MATLAB, these are what you would have to change:

Termination and timeout

The script appends a line feed to every command it sends, in query_instrument, and strips any trailing CR or LF from what comes back, in strip_termination. That suits nearly every SCPI instrument, including the 34401A. If yours needs a carriage return instead, change the "\n" in the write; the stripping side already handles CR, LF and CRLF.

Troubleshooting