SCPI instruments

Bench instruments that speak SCPI, such as multimeters, power supplies, electronic loads and data acquisition units, over TCP, a serial line, or USB and GPIB through VISA: how each is reached, the Instrument card, queries and write commands, discovery, and two worked examples.

The SCPI instruments driver reads and writes bench instruments that speak SCPI, the command language of IEEE 488.2 test equipment: multimeters, power supplies, electronic loads, data acquisition units such as the Fluke 1586A Super-DAQ, calibrators, from Keysight, Rigol, Tektronix, Siglent, GW Instek, B&K Precision, Fluke and the others. Each tag asks the instrument a query, such as MEAS:VOLT:DC? or READ?, and reads its answer; a tag that is written sends a command with the value in it, such as VOLT 5. It is the exchange a LabVIEW program makes through VISA, set up on a panel instead of wired in a block diagram, and the values land where every other tag's do: in Logic, on dashboards, in the runs of a Process test bench.

An instrument is reached in one of three ways, chosen when its device is created:

An instrument on a serial line hangs under its line, so that part of the tree reads Driver → Line → Device → Tag, as under Generic serial and TCP. An instrument reached over TCP or VISA sits under the driver and may be filed in folders like any other driver's device, Driver → Folder → Device → Tag. A device stays on the side it was created on: TCP and VISA can be switched, but a device never moves between a line and the network.

The driver's page

The line under the header reads "Serial lines carry the instruments that share a bus, and the instruments reached over TCP or VISA sit under the driver. Add a line or a device, then open it to give its queries." and the page holds, one under the other:

The header counts the devices in parentheses, and the driver row in the tree counts both levels once a line exists ("1 line · 2 devices"). The driver's bar carries Discover. Right-clicking the driver row offers Add device, Add line, New folder, Refresh and Discover, then, after a separator, Remove driver; in the column's New… menu the driver's entry offers New device, New serial line and New folder, then its lines, folders and devices. Once added, the driver stands under the Drivers folder of the tree, with or without a line or a device.

Serial line

A line of this driver is the line described on Serial lines, with the fields of a line of the Generic serial and TCP driver. Its page says "One physical serial bus: the port settings its instruments share, one request at a time." and its Physical line card holds Name, Serial port (with Refresh), Baud and Serial format, all ten formats offered, six of 8 bits and four of 7 bits. It has no transmission mode, no response timeout, no minimum transaction interval and no Discover units card: each instrument says on its own Instrument card what ends its messages and how long it waits for an answer, and an instrument is told apart by what it is asked, not by an address, so the Devices table of the line has no Unit ID column.

A line created here starts disabled, so the port settings are typed before the port opens; the port, the baud and the format change only while the line is disabled. Add device on the line, or on its right-click menu, creates a device of this driver on that line. A line belongs to the driver it was created under, for good: no device of another driver goes on it, and one port belongs to one line whatever driver the line belongs to.

The driver opens the port once for every instrument on the line and sends one request at a time, waiting for its answer before the next. It holds DTR on while the port is open, because an instrument that paces its output by DTR and DSR, such as the Keysight 34401A or an E36xx power supply, sends nothing while DTR is off. A port that fails is reopened after a pause that doubles from 1 second up to 1 minute while it keeps failing, and every instrument on it is set up again, its setup commands sent anew, as at its first connection.

Device

Connection

A new device is a TCP device: it reads "Host not entered yet" and is not connected until it has a host. A VISA device dials no host and never waits for one. Switching to VISA keeps the host and the port for when TCP comes back, and switching to TCP keeps the resource. A device the driver cannot work with is not saved, and the feed says why:

The Base URI the header shows is the runtime address: scpi://tcp/<host>:<port>, scpi://visa/<resource> or scpi://serial/<line id>/<port>/<baud>/<format>, followed by the terminator (term), the response timeout (timeout), the write confirmation (check) and the setup commands (setup, one after another, separated by %0A). A copy of a device on a line stays on that line; a copy of a TCP or VISA device lands at the driver's own level.

The Instrument card

Under the Connection card, the Instrument card says what the instrument is and how the station talks to it.

Each time the station connects to the instrument, and each time a serial line reopens its port, it sends, in order: *CLS when the write confirmation reads the error queue, the setup commands, then reads the error queue into the journal (an error a setup command caused is written there and does not stop the device), and asks *IDN?, whose answer the Identity field shows. A value the card cannot take is not saved, and the feed says why: "The response timeout must be from 100 to 60000 ms.", "A setup command holds a character outside plain ASCII, such as a typographic quote, which no instrument reads." or "Send at most 32 setup commands, of at most 512 characters each." SCPI is plain ASCII, so a command copied from a manual with a typographic quote or a non-breaking space is refused where it is typed rather than sent to an instrument that cannot read it.

VISA on this computer

The product carries no VISA and installs none. A VISA device opens its instrument through the 64-bit VISA library (visa64.dll) already on this computer, which NI-VISA, which LabVIEW installs, and the Keysight IO Libraries Suite both put there. Only VISA devices need it: a TCP or serial instrument connects without it. The station checks by itself whether the library loads, without waiting for a device: the first time the driver's page, the page of a VISA device or the agent asks, and again every 30 seconds while it is missing. Until the Connector has started, whether VISA is there is not known, and nothing is said about it. While it is missing:

To install it:

1. Download NI-VISA from NI's page NI-VISA Download, or the Keysight IO Libraries Suite from Keysight's page IO Libraries Suite Downloads.
2. Either one works, and a computer with LabVIEW already has NI-VISA. NI's page asks you to sign in with an NI account before the download; Keysight's links the installer directly. Take the latest Windows installer: on 64-bit Windows both install the 64-bit VISA, the only one Ganter Lab sees.
3. Run the installer as administrator, from a folder on drive C: (Keysight's does not install from another drive), and restart the computer when it asks.

A VISA that installed only its 32-bit library (visa32.dll), such as one made for 32-bit Windows, is not seen: Ganter Lab reads only the 64-bit visa64.dll.

Within 30 seconds of the installation the notice goes away and the VISA devices connect with the configuration they have, without restarting Ganter Lab. An instrument with a network port can also be reached over TCP, without VISA.

Tag addressing

A tag of this driver asks its instrument a query. Its Source card holds:

A field the tag's access does not use is not drawn, and keeps its value for when it is. The data types are Boolean, Int32, Int64, Float, Double and String, Float by default. A tag whose fields cannot work is not saved, and the tag's page says what it lacks:

The read-only Source address (wire) line shows what the driver receives: ask=READ? for a tag that reads the whole answer, ask=READ?&field=3 for the third value of it, ask=VOLT?&write=VOLT {value} for a tag that is read and written, and write=*TRG for a Write only one.

Reading

At the tag's poll interval the station sends the query and reads one answer, up to the terminator, within the response timeout. The text taken, the whole answer or the value the tag names, is read as the tag's type before the tag's own stages convert it, as for every driver (see The value pipeline):

Writing

A write goes through the same funnel as any other driver's: the write box takes the engineering value, and the conversion stages are reversed before the raw value is sent (see Connector). The command is the write command with the value where {value} stands: a number in invariant culture, the shortest text that reads back as the same number, or formatted by {value:FORMAT} with a .NET number format (CURR {value:0.000} sends 1.5 as CURR 1.500); a Boolean as 1 or 0, which every SCPI Boolean parameter takes; a text as it is, the command carrying the quotes it needs (DISP:TEXT "{value}"). Not-a-number and infinity are refused before anything is sent. On a Boolean tag a command without {value}, such as *TRG, is sent when true is written, and writing false is refused.

Writes wait their turn on the device's queue with the reads: on a line they share the line's one request at a time, over TCP and VISA the device's own connection.

Discovery

The driver's page carries a Scan scope card with one optional box, "Instrument address for a TCP probe, e.g. 192.168.0.20 or 192.168.0.20:5025 (empty = the instruments VISA lists)". Discover then asks two questions, one after the other:

Each instrument has 1.5 seconds to answer, and one that does not is not offered. A candidate is named by the manufacturer and the model it answered (Keysight Technologies 34461A), carries every default of the Instrument card, and no tags, since an instrument publishes no list of its queries: "No tags reported. Add the device to configure tags in its editor." A VISA candidate whose resource a device of the driver already has is marked as already configured and offers Open instead of Add; an instrument found over TCP is never matched, because a host is only where an instrument is reached. VISA lists every serial port of the computer as a resource (ASRL3::INSTR), whether anything is attached or not, and asking would write to whatever is: the scan leaves those out, and a serial instrument goes on a serial line of this driver. A serial resource typed by hand on a VISA device is still opened. Something in the box that is not a host is refused under it, and Discover greys: "A SCPI scan asks the instrument written here to identify itself over TCP: its IP address or name, optionally with its port (for example 192.168.0.20 or 192.168.0.20:5025). Leave it empty to ask only the instruments VISA lists." The rest of the scan's behaviour is on Discovery.

Example: a multimeter over TCP

A Keysight 34461A on the network answers SCPI on its LXI socket, port 5025. Read its DC voltage:

1. On the driver's page, Add device; name it DMM, keep TCP (LXI socket), enter Host 192.168.0.20 and keep Port 5025.
2. On the Instrument card keep LF (line feed), a Response timeout (ms) of 2000 and Error queue (SYST:ERR?), and type two Setup commands, *RST and then CONF:VOLT:DC 10: the meter is reset and set to DC volts on its 10 V range each time the station connects.
3. Once connected, the Identity field shows what the meter answered, such as Keysight Technologies,34461A,MY53212345,A.02.14-02.40-02.14-00.49-02-01.
4. Add tag; name it Voltage, Double, Read only, with the Query READ?, the Value in the answer empty and the Unit V. READ? takes one measurement in the configured function and answers it.

The Base URI reads scpi://tcp/192.168.0.20:5025?term=lf&timeout=2000&check=errorqueue&setup=*RST%0ACONF:VOLT:DC 10. An agent does the same with two tool calls:

device_upsert driver=Scpi name=DMM transport=Tcp host=192.168.0.20 port=5025 setupCommands='*RST\nCONF:VOLT:DC 10'
tag_upsert device=DMM name=Voltage opcUaType=Double address='READ?' unit=V

Example: a power supply on RS-232

A Keysight E3631A answers SCPI on its RS-232 port, at 9600 baud with 8 data bits, no parity and 2 stop bits, and over RS-232 it takes commands only once it is put in remote mode. Set its voltage, switch its output and read its current:

1. Add line on the driver's page; name it PSU line, pick COM4, set Baud to 9600 and Serial format to 8N2, then Enable the line.
2. Add device on the line; name it PSU. On the Instrument card set the Response timeout (ms) to 3000, type SYST:REM as the one line of Setup commands, and set the Write confirmation to Completion, then error queue (*OPC?, SYST:ERR?), so a write is done only once the output has followed it.
3. Add tag Setpoint, Double, Read and write, Query VOLT?, Write command VOLT {value}.
4. Add tag Output, Boolean, Read and write, Query OUTP?, Write command OUTP {value}: writing true sends OUTP 1, false OUTP 0, and the supply answers OUTP? with 1 or 0.
5. Add tag MeasuredCurrent, Double, Read only, Query MEAS:CURR?, Unit A.

The Setpoint tag's wire address is ask=VOLT?&write=VOLT {value}. A supply with several outputs, as this one has, acts on the output it has selected; a second setup command such as INST:SEL P6V picks it. The same with the agent's tools:

serial_line_upsert driver=Scpi name='PSU line' serialPort=COM4 baudRate=9600 serialFormat=8N2
device_upsert driver=Scpi name=PSU transport=SerialLine serialLineId=<id> responseTimeoutMs=3000 setupCommands='SYST:REM' writeCheck=CompletionAndErrorQueue
tag_upsert device=PSU name=Setpoint opcUaType=Double accessType=ReadAndWrite address='VOLT?' writeTemplate='VOLT {value}'
tag_upsert device=PSU name=Output opcUaType=Boolean accessType=ReadAndWrite address='OUTP?' writeTemplate='OUTP {value}'
tag_upsert device=PSU name=MeasuredCurrent opcUaType=Double address='MEAS:CURR?' unit=A

Agent tools

driver_capabilities describes this driver under scpi: its three transports, whether this computer has VISA (under prerequisite, with every step to install it), the terminators, the response timeout, the write confirmations, the setup commands, how a query and a write command are written, how answers are read, discovery and the two examples above. device_upsert driver=Scpi takes transport (Tcp, the default, Visa, or SerialLine, which serialLineId implies), host and port over TCP, visaResource over VISA, serialLineId for a line of this driver, terminator (Lf, CrLf or Cr; \n, \r\n and \r are read too), responseTimeoutMs (100 to 60000), writeCheck (ErrorQueue, CompletionAndErrorQueue or None) and setupCommands (one per line, or separated by \n; '' clears them). tag_upsert takes the query as address, valueField (1 to 1000; 0 or omitted reads the whole answer) and writeTemplate ('' clears it). serial_line_upsert driver=Scpi creates a line of this driver, with serialPort, baudRate and serialFormat only. device_discover driver=Scpi runs the scan, with target for the TCP probe. A device the tools return carries scpi, with the instrument's identity once it has answered, and so does a tag. The other tools are on Agent tools.

Limits worth knowing

• The Fluke NetDAQ 2640A, 2645A, 2680A and 2686A speak a protocol of Fluke's own, which is not SCPI: this driver does not read them. The Fluke 1586A Super-DAQ and 2638A Hydra Series III speak SCPI, and it does.
• Answers sent as an IEEE 488.2 binary block (a #, a length and raw bytes), such as a waveform or a screen image, are not read: a tag reads an answer written as text.
• The product does not install VISA. Without NI-VISA or the Keysight IO Libraries Suite on this computer, USB and GPIB instruments are not reached; TCP and serial instruments are.
• The scan does not list VISA's serial resources (ASRL…::INSTR): a serial instrument goes on a serial line of this driver.
• Every value is polled: the driver does not wait on service requests (SRQ) or on the status byte.
• A device cannot be moved between a serial line and the network, nor to another line: create it where it belongs and delete the old one.