Query Instruments

Most interaction with instruments comes down to two operations: sending a query (expecting a response) or sending a command (no response expected). mcpyvisa 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.

Instrument addressing

All tools accept an instrument parameter that can be either a configured alias or a full VISA resource string:

Using aliases

instrument_query("dmm", "MEAS:VOLT:DC?")
instrument_write("psu", "OUTP ON")
instrument_identify("scope")

Aliases are defined in mcpyvisa.toml under [instruments.*] sections. They map to a VISA resource string and backend.

Using VISA resource strings

instrument_query("GPIB0::22::INSTR", "MEAS:VOLT:DC?")
instrument_write("GPIB0::5::INSTR", "OUTP ON")
instrument_identify("TCPIP::192.168.1.100::INSTR")

VISA resource strings can be used directly without configuring aliases. mcpyvisa resolves them to the correct backend automatically.

Take a measurement

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

> Measure DC voltage on the DMM

The LLM calls instrument_query("dmm", "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("dmm", "CONF:VOLT:DC 10,0.001"), then:

> Now read the measurement

The LLM calls instrument_query("dmm", "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("dmm", "CONF:VOLT:DC 10,0.001")
instrument_write("dmm", "TRIG:SOUR IMM")
instrument_write("dmm", "INIT")
instrument_query("dmm", "FETCH?")

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

Bus trigger

instrument_write("dmm", "CONF:VOLT:DC 10,0.001")
instrument_write("dmm", "TRIG:SOUR BUS")
instrument_write("dmm", "INIT")
bus_trigger("bench-a", instruments=["dmm"])
instrument_query("dmm", "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 the DMM

The LLM calls configure_ar488("bench-a", read_timeout_ms=30000), then instrument_query("dmm", "*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-backend 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:

mcpyvisa.toml

[[backend]]
name = "precision-bench"
type = "ar488"
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 DMM

The LLM calls instrument_query("dmm", "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 the DMM 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 the HP 3478A

The LLM calls instrument_write("hp3478", "F1RA").

For instruments with non-standard response behavior, you can still use instrument_query with any command string and read the response:

> Send "F1RA" to the HP 3478A and read the response

The LLM calls instrument_query("hp3478", "F1RA").

Note

The quick-measure prompt can provide instrument-specific command guidance. Pass the instrument alias and measurement type, and the LLM will configure and read the instrument using the appropriate commands.

Reset an instrument

To return an instrument to its power-on defaults:

> Reset the DMM

The LLM calls instrument_reset("dmm"), 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 mcpyvisa is communicating with an instrument, the front panel may be locked out. To return control to a human operator:

> Return the DMM to local control

The LLM calls instrument_local("dmm"). The instrument’s front panel becomes active again.

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

> Put the DMM in remote mode with lockout

The LLM calls instrument_remote("dmm", lockout=True).