Query Instruments

Most interaction with GPIB instruments comes down to two operations: sending a query (expecting a response) or sending a command (no response expected). mcgpib provides instrument_query and instrument_write for these, with the important distinction being whether the instrument sends data back.

Query vs write

The naming convention follows SCPI: commands ending with ? are queries that return data. Commands without ? configure the instrument without returning a response.

Tool	When to use	Example
instrument_query	The command expects a response back from the instrument	MEAS:VOLT:DC?, *IDN?, SYST:ERR?
instrument_write	The command configures the instrument with no response	CONF:VOLT:DC 10,0.001, *RST, OUTP ON

Caution

Using instrument_query for a command that produces no response will result in a timeout error. Using instrument_write for a query will silently discard the instrument’s response, leaving data in the buffer that may corrupt the next read. Match the tool to the command type.

Take a measurement

The simplest way to read a value from a multimeter or other measurement instrument:

> Measure DC voltage on the multimeter at address 22 on bench-a

The LLM calls instrument_query("bench-a", 22, "MEAS:VOLT:DC?"):

+1.23456789E+01

The response is the raw string from the instrument — typically a number in scientific notation.

Common SCPI measurement commands

These commands work on most modern SCPI-compliant multimeters (Keysight 34401A, Keithley 2000, Fluke 8846A, etc.):

One-shot measurements with MEAS

MEAS configures, triggers, and reads in a single command:

MEAS:VOLT:DC?              DC voltage, autorange
MEAS:VOLT:DC? 10,0.001     DC voltage, 10V range, 1mV resolution
MEAS:VOLT:AC?              AC voltage
MEAS:CURR:DC?              DC current
MEAS:CURR:AC?              AC current
MEAS:RES?                  2-wire resistance
MEAS:FRES?                 4-wire resistance
MEAS:FREQ?                 Frequency

Configure-then-read with CONF and READ?

For more control, separate configuration from reading:

> Configure the DMM for DC voltage on the 10V range

The LLM calls instrument_write("bench-a", 22, "CONF:VOLT:DC 10,0.001"), then:

> Now read the measurement

The LLM calls instrument_query("bench-a", 22, "READ?"):

+1.23456789E+01

CONF sets the function and range without triggering. READ? triggers a new measurement and returns the result. This pattern is useful when you want to configure once and take multiple readings.

Triggered measurements with INIT and FETCH?

For precise triggering control:

Immediate trigger

instrument_write("bench-a", 22, "CONF:VOLT:DC 10,0.001")
instrument_write("bench-a", 22, "TRIG:SOUR IMM")
instrument_write("bench-a", 22, "INIT")
instrument_query("bench-a", 22, "FETCH?")

INIT starts the measurement process. FETCH? retrieves the result without triggering a new measurement.

Bus trigger

instrument_write("bench-a", 22, "CONF:VOLT:DC 10,0.001")
instrument_write("bench-a", 22, "TRIG:SOUR BUS")
instrument_write("bench-a", 22, "INIT")
bus_trigger("bench-a", addresses=[22])
instrument_query("bench-a", 22, "FETCH?")

Bus trigger lets you synchronize the measurement with a Group Execute Trigger (GET) signal, which can trigger multiple instruments simultaneously.

Handle slow measurements

Some measurements take longer than the default 3-second read timeout:

• High-resolution DC measurements with long integration times (10 PLC or 100 PLC)
• Frequency measurements on low-frequency signals
• Resistance measurements in high ranges (above 10 MOhm)
• Self-test queries (*TST?)

Increase the timeout before a slow query

> Set the read timeout on bench-a to 30 seconds, then run a self-test on address 22

The LLM calls configure_bridge("bench-a", read_timeout_ms=30000), then instrument_query("bench-a", 22, "*TST?").

Tip

Increase the timeout before the slow command and restore it afterward. A permanently high timeout means every failed command takes that long to report an error.

Use the per-bridge config for consistently slow instruments

If an instrument is always slow (e.g., a precision electrometer), set a higher timeout in the config file rather than adjusting at runtime:

mcgpib.toml

[[bridge]]
name = "precision-bench"
transport = "serial"
port = "/dev/ttyUSB1"
read_timeout_ms = 15000

Query error status

After sending commands, check whether the instrument encountered an error:

> Check for errors on the instrument at address 22

The LLM calls instrument_query("bench-a", 22, "SYST:ERR?"):

0,"No error"

If there was an error:

-222,"Data out of range"

Read SYST:ERR? in a loop until you get 0,"No error" — instruments queue multiple errors:

> Keep reading errors from address 22 until the queue is empty

Work with non-SCPI instruments

Older instruments (HP 3478A, Fluke 8840A, Solartron 7150) use proprietary command sets. Use instrument_write and instrument_query the same way, but with instrument-specific commands:

> Send "F1RA" to address 22 on bench-a

The LLM calls instrument_write("bench-a", 22, "F1RA").

For instruments with non-standard response behavior, use raw_scpi with explicit control over whether to read back:

> Send "F1RA" to address 22 on bench-a and read the response

The LLM calls raw_scpi("bench-a", 22, "F1RA", read_after=True).

Note

The scpi_command_help prompt can provide instrument-specific command reference. Pass the model name and the LLM will look up the relevant programming manual commands.

Reset an instrument

To return an instrument to its power-on defaults:

> Reset the multimeter at address 22

The LLM calls instrument_reset("bench-a", 22), which sends *RST. The instrument reconfigures to its factory default measurement settings. Wait a few seconds after reset before sending new commands — some instruments take time to reconfigure internally.

Control front panel access

When mcgpib is communicating with an instrument, the front panel may be locked out. To return control to a human operator:

> Return address 22 to local control

The LLM calls instrument_local("bench-a", 22). The instrument’s front panel becomes active again.

To explicitly lock out the front panel (preventing accidental changes during automated sequences):

> Put address 22 in remote mode with lockout

The LLM calls instrument_remote("bench-a", 22, lockout=True).