Controlling GPIB instruments from MATLAB and Octave with no toolbox at all

Overview

This one is different from the rest of the tutorials here. There is no VISA runtime to install, no Instrument Control Toolbox, no Octave package to compile, and no vendor SDK. It is a small module called XyVXI11 that speaks the VXI-11 protocol itself, written in plain MATLAB code.

The same files run unchanged on MATLAB and on GNU Octave, on Windows, Linux and macOS. There is no Octave variant to pick and no platform-specific build step. The only thing it uses that is not the language itself is java.net.Socket, which both MATLAB and Octave already embed.

Why this exists

The usual reason is dull and familiar: the licence server has no free Instrument Control Toolbox seats.

MATLAB is generally licensed per toolbox, and in a lot of companies there are far fewer instrument seats than there are engineers. So you sit down to log a measurement, MATLAB tells you the licence is checked out, and you have a choice between waiting for a colleague to close their session and finding another way. That single moment is one of the more common reasons people end up on free tools, and it usually has nothing to do with what they think of MATLAB.

This module is the other way. It needs no licensed toolbox, so it does not touch the licence server at all. If you later decide to move to Octave entirely, the same script comes with you unchanged, which makes the decision smaller than it looks.

It is also handy when a machine is locked down. Installing NI-VISA needs administrator rights and a driver install; this needs a folder on your path.

What you need

• A GPIBEE, with an instrument on the GPIB bus.
• MATLAB, any reasonably recent release, started normally rather than with -nojvm. Or GNU Octave, built with Java support.
• Network access from that machine to the adapter, on port 111 for the RPC portmapper plus the dynamic port the adapter reports back.

That is the whole list. No toolbox, no package, no runtime, no administrator rights.

Check Java first

Everything rests on the embedded Java runtime, so confirm it is there before anything else. At the MATLAB or Octave prompt:

usejava('jvm')

It has to return 1. On MATLAB it will, unless the session was started with -nojvm. On Octave it depends how your build was made: the official Windows and most Linux distribution builds have Java enabled, but a minimal or self-compiled build might not.

If it returns 0, this module cannot open a socket in that installation. Octave has no TCP support of its own, which is exactly why the Java route was chosen over anything else.

Download the example

Unpack it somewhere convenient. Nothing gets installed.

What is inside

There are three levels, and you can work at whichever suits you. GpibeeInstrument is the one to reach for. GpibeeInterface is for the adapter rather than an instrument. Vxi11Client is the bare protocol, useful if you are doing something unusual or debugging.

Putting it on the path

One line, once per session:

addpath('/path/to/MatlabOctaveGpibeeExample/XyVXI11')

Both example scripts already do this for themselves, working out their own location, so you can run them from anywhere without setting the path first.

Example 1: one instrument

example_basic.m is the smallest useful thing: connect to one instrument, ask who it is, then ask whether it is unhappy about anything.

ip = '192.168.3.2';
primaryAddress = 4;   % e.g. an HP 34401A on the bench

inst = GpibeeInstrument(ip, primaryAddress);
cleanupObj = onCleanup(@() inst.close());

inst.Timeout = 5; % seconds

idnString = inst.idn();
fprintf('*IDN?: %s\n', idnString);

err = inst.query('SYST:ERR?');
fprintf('SYST:ERR?: %s\n', err);

Change the two values at the top and it is ready. 192.168.3.2 is the address of your GPIBEE, and 4 is the GPIB address of the instrument on the bus. The adapter's web interface shows its own address and can scan the bus for you.

The onCleanup line is worth copying into your own code. It closes the link when the script ends, including when it ends because something threw. Without it, an error halfway through leaves a link open on the adapter, and the next run can find the instrument busy.

What a real run looks like

This is Octave, against a real adapter and a real multimeter:

octave:4> example_basic

*IDN?: HEWLETT-PACKARD,34401A,0,5-1-1
SYST:ERR?: -410,"Query INTERRUPTED"

The first line is the instrument stating its maker, model, serial number and firmware version. If you see that, the whole chain works: Octave reached the adapter over the network, and the adapter reached the instrument over GPIB.

The second line is the instrument's error queue, and it is doing its job. Asking SYST:ERR? after a sequence of commands is a good habit, because an instrument will quietly refuse a command it does not like and carry on as if nothing happened. Here it had something to report rather than the +0,"No error" you get from a clean queue, which is exactly the kind of thing you want to find out about early rather than late.

Example 2: the bus

example_gpib_scan.m talks to the adapter itself rather than to an instrument, so there is no GPIB address in it:

ifc = GpibeeInterface(ip);
cleanupObj = onCleanup(@() ifc.close());

addrs = ifc.scanBus();   % full-bus scan, takes a few seconds
fprintf('Devices found on the bus:\n');
for k = 1:numel(addrs)
    fprintf('  %s\n', addrs{k});
end

ppState = ifc.parallelPoll();
fprintf('Parallel poll (DIO1..DIO8): %d\n', ppState);

Two useful things happen here. The scan walks the bus and reports which addresses answer, which is the fastest way to settle an argument about whether an instrument is really at address 12. The parallel poll reads all eight DIO lines in one bus cycle and returns them as a number from 0 to 255.

These are GPIBEE features rather than standard VXI-11, reached through vendor SCPI commands on the adapter's own interface device. If a future firmware changes that syntax, the commands are all in one place at the top of GpibeeInterface.m.

GpibeeInstrument reference

The everyday level. One object, one instrument.

GpibeeInterface reference

The adapter rather than an instrument. Bus management.

Addressing

Device names follow the ordinary VXI-11 convention, the same one inside the PyVISA resource strings used elsewhere on this site:

What it does and does not do

The VXI-11 core channel is complete: creating and destroying links, writes chunked to whatever size the adapter asks for, reads that run until the end of the message or a terminator, status byte, trigger, clear, remote and local, lock and unlock. Protocol errors come back as ordinary MATLAB errors with a message you can read.

Two things are deliberately absent:

• The interrupt channel, meaning SRQ callbacks. Standard VXI-11 service requests need the client to run its own small RPC server for the instrument to call back into, which is a large thing to carry for a module this size. readStatusByte() covers the common case of checking on demand.
• The abort channel, for cancelling a call in flight from a second connection.

This code is young

That is said plainly because the alternative is worse. If you use it and it works, we would like to know. If you use it and something breaks, we would very much like to know, with whatever MATLAB or Octave printed at you.

This is not a module we intend to publish and forget. It is genuinely interesting to keep extending, fixing and maintaining, and real reports from real benches are what make that worth doing. Write to support@gpibee.com.

Troubleshooting