Instrument Tools

These are the primary tools for interacting with instruments. Most sessions will use instrument_query and instrument_write for the majority of operations, with the other tools providing identification, reset, and control-mode management.

---

instrument_query

Send a SCPI query to an instrument and return the response. This is the most common operation — send a command (typically ending with ?) and read back the instrument’s answer. Internally, this addresses the device, sends the command, then issues ++read eoi.

Parameters

Name	Type	Required	Description
bridge_name	string	Yes	Name of the bridge the instrument is on
address	integer	Yes	GPIB address of the instrument (0—30)
command	string	Yes	SCPI command to send (typically ends with ?)

Example

# Measure DC voltage on a Keithley 2000
result = await client.call_tool("instrument_query", {
    "bridge_name": "bench-a",
    "address": 22,
    "command": "MEAS:VOLT:DC?"
})

# Read frequency on an HP 34401A
result = await client.call_tool("instrument_query", {
    "bridge_name": "bench-a",
    "address": 1,
    "command": "MEAS:FREQ?"
})

# Check operation complete
result = await client.call_tool("instrument_query", {
    "bridge_name": "bench-a",
    "address": 5,
    "command": "*OPC?"
})

Returns

The raw response string from the instrument, for example:

+4.23451000E+00

Note

If the instrument does not respond within the configured read_timeout_ms, an InstrumentError is raised. Increase the bridge timeout with configure_bridge for slow measurements (e.g., high-resolution ADC integrations).

---

instrument_write

Send a SCPI command to an instrument with no response expected. Use this for configuration commands that set parameters without returning data.

Parameters

Name	Type	Required	Description
bridge_name	string	Yes	Name of the bridge the instrument is on
address	integer	Yes	GPIB address of the instrument (0—30)
command	string	Yes	SCPI command to send

Example

# Configure a Keithley 2000 for DC voltage measurement
await client.call_tool("instrument_write", {
    "bridge_name": "bench-a",
    "address": 22,
    "command": "CONF:VOLT:DC 10,0.001"
})

# Turn on output on an Agilent E3631A
await client.call_tool("instrument_write", {
    "bridge_name": "bench-a",
    "address": 5,
    "command": "OUTP ON"
})

# Set immediate trigger source on an HP 34972A
await client.call_tool("instrument_write", {
    "bridge_name": "bench-a",
    "address": 9,
    "command": "TRIG:SOUR IMM"
})

Returns

Sent to address 22: CONF:VOLT:DC 10,0.001

---

instrument_identify

Identify an instrument by sending the IEEE 488.2 *IDN? query. The response is parsed into four fields per the standard: manufacturer, model, serial number, and firmware version.

Parameters

Name	Type	Required	Description
bridge_name	string	Yes	Name of the bridge the instrument is on
address	integer	Yes	GPIB address of the instrument (0—30)

Example

result = await client.call_tool("instrument_identify", {
    "bridge_name": "bench-a",
    "address": 22
})

Returns

Address 22 on bench-a:
  Manufacturer: KEITHLEY INSTRUMENTS INC.
  Model: MODEL 2000
  Serial: 1234567
  Firmware: A01
  Raw: KEITHLEY INSTRUMENTS INC.,MODEL 2000,1234567,A01

Caution

Older instruments (HP 3478A, Fluke 8842A, etc.) may not support *IDN? at all. These pre-IEEE-488.2 instruments will time out. Use bus_scan with identify=false to find them, then refer to the instrument’s programming manual for command syntax.

---

list_instruments

List all discovered instruments across all connected bridges. Returns instruments found during the most recent bus_scan on each bridge. Run bus_scan first if instruments have not been discovered yet.

Parameters

Name	Type	Required	Description
bridge_name	string	No	Filter to instruments on this bridge only. Omit to list all bridges

Example

# List instruments across all bridges
result = await client.call_tool("list_instruments", {})

# List instruments on a specific bridge
result = await client.call_tool("list_instruments", {
    "bridge_name": "bench-a"
})

Returns

Discovered instruments:
  [bench-a] Address 5: Agilent Technologies E3631A
  [bench-a] Address 22: KEITHLEY INSTRUMENTS INC. MODEL 2000
  [bench-b] Address 1: Hewlett-Packard 34401A

---

instrument_reset

Send *RST to reset an instrument to its power-on defaults. This clears all configuration and returns the instrument to a known state.

Parameters

Name	Type	Required	Description
bridge_name	string	Yes	Name of the bridge the instrument is on
address	integer	Yes	GPIB address of the instrument (0—30)

Example

result = await client.call_tool("instrument_reset", {
    "bridge_name": "bench-a",
    "address": 22
})

Returns

Reset instrument at address 22 on bench-a

Tip

After *RST, most instruments need a brief settling period (a few hundred milliseconds to a few seconds depending on the model) before they accept new configuration commands. Some instruments support *OPC? to signal readiness.

---

instrument_local

Return instrument(s) to local (front panel) control. Sends the IEEE-488 Go To Local (GTL) message. With an address, returns one instrument to local. Without, returns all instruments on the bridge to local.

Parameters

Name	Type	Required	Description
bridge_name	string	Yes	Name of the bridge
address	integer	No	GPIB address (0—30). Omit to return all instruments to local

Example

# Return a single instrument to local control
result = await client.call_tool("instrument_local", {
    "bridge_name": "bench-a",
    "address": 22
})

# Return all instruments to local control
result = await client.call_tool("instrument_local", {
    "bridge_name": "bench-a"
})

Returns

Instrument at address 22 returned to local control

or

All instruments on bench-a returned to local control

---

instrument_remote

Put instrument(s) in remote mode by asserting REN (Remote Enable). With lockout=true, also sends Local Lockout (LLO) to prevent front panel operation — the instrument can only return to local via instrument_local.

Parameters

Name	Type	Required	Description
bridge_name	string	Yes	Name of the bridge
address	integer	No	GPIB address (0—30). Omit to affect all instruments
lockout	boolean	No	Lock out front panel (default: false)

Example

# Remote mode for one instrument
result = await client.call_tool("instrument_remote", {
    "bridge_name": "bench-a",
    "address": 22
})

# Remote with lockout for all instruments
result = await client.call_tool("instrument_remote", {
    "bridge_name": "bench-a",
    "lockout": True
})

Returns

Instrument at address 22 set to remote

or

All instruments on bench-a set to remote + lockout

Caution

With lockout=true, the front panel buttons are disabled. The only way to restore local control is to send instrument_local via GPIB. If communication with the bridge is lost while lockout is active, a power cycle of the instrument is required.