Configure Backends

mcpyvisa supports four backend types for connecting to instruments: ar488 (GPIB via serial or TCP), pyvisa-py (USB-TMC, LAN/VXI-11), system (NI-VISA or Keysight IO Libraries), and sim (simulated instruments via YAML definitions). Each backend gets its own [[backend]] section in the TOML configuration file, and instruments can be given friendly aliases through [instruments.*] sections.

Configuration file locations

mcpyvisa searches for its config file in this order:

1. The path in the $MCPYVISA_CONFIG environment variable
2. ./mcpyvisa.toml in the current working directory
3. ~/.config/mcpyvisa/config.toml

If no file is found, mcpyvisa starts with no backends configured.

Backend types

AR488 (Serial)

Serial is the simplest and most reliable transport for AR488/Prologix GPIB adapters. Connect the ESP32 to your machine with a USB cable.

mcpyvisa.toml

[[backend]]
name = "bench-a"
type = "ar488"
transport = "serial"
port = "/dev/ttyUSB0"
baudrate = 115200

Required fields:

Field	Description
name	Unique identifier for this backend. Alphanumeric with hyphens and underscores.
type	Set to "ar488".
transport	Set to "serial".
port	Serial port path.
baudrate	Baud rate matching the AR488 firmware (default 115200).

Finding your serial port:

• Linux: ls /dev/ttyUSB* or ls /dev/ttyACM*
• macOS: ls /dev/cu.usbserial-* or ls /dev/cu.usbmodem*
• Windows: Check Device Manager for COM ports (e.g., COM3)

Tip

If you have multiple USB serial devices, unplug the adapter, list ports, plug it back in, and list again. The new entry is your adapter.

AR488 (TCP)

TCP transport connects to an AR488 adapter over the network. The ESP32 acts as a TCP server on port 23.

mcpyvisa.toml

[[backend]]
name = "bench-b"
type = "ar488"
transport = "tcp"
host = "192.168.1.50"
tcp_port = 23

Required fields:

Field	Description
name	Unique identifier for this backend.
type	Set to "ar488".
transport	Set to "tcp".
host	IP address or hostname of the ESP32.
tcp_port	TCP port number (default 23).

Caution

The ESP32 AR488 firmware accepts only one TCP client at a time. If a serial terminal or another application is already connected, mcpyvisa will fail with a connection timeout. Close other connections first.

pyvisa-py

The pyvisa-py backend uses the pure-Python VISA implementation. It supports USB-TMC instruments and LAN instruments via VXI-11 or raw sockets — no proprietary drivers needed.

mcpyvisa.toml

[[backend]]
name = "lan-bench"
type = "pyvisa-py"

No transport-specific fields are required. pyvisa-py discovers instruments from the resource strings you configure in the [instruments.*] sections.

Common resource strings for pyvisa-py:

Transport	Example resource string
USB-TMC	USB0::0x0957::0x0607::MY47000419::INSTR
LAN (VXI-11)	TCPIP::192.168.1.100::INSTR
LAN (raw socket)	TCPIP::192.168.1.100::5025::SOCKET
Serial	ASRL/dev/ttyUSB0::INSTR

System VISA

The system backend uses your installed VISA library (NI-VISA, Keysight IO Libraries Suite, or R&S VISA). Use this when you need features that pyvisa-py does not provide, such as GPIB through a NI-488.2 adapter.

mcpyvisa.toml

[[backend]]
name = "ni-bench"
type = "system"

The system backend delegates entirely to the VISA shared library installed on your machine. Resource strings follow the same format as pyvisa-py.

Note

The system backend requires a VISA shared library to be installed. On Linux, this is typically /usr/lib/libvisa.so. On Windows, NI-VISA or Keysight IO Libraries install this automatically. If pyvisa cannot find the library, you will see a VisaIOError at startup.

Simulated (sim)

The sim backend uses pyvisa-sim to create virtual instruments defined in a YAML file. No hardware needed — ideal for development, testing prompts, and learning SCPI without physical equipment.

mcpyvisa.toml

[[backend]]
name = "sim-bench"
type = "sim"
sim_file = "./gpib-catalog/sim/all_instruments.yaml"

Required fields:

Field	Description
name	Unique identifier for this backend.
type	Set to "sim".
sim_file	Path to a pyvisa-sim YAML definition file. Relative paths are resolved from the working directory.

The YAML file defines instrument dialogues — query/response pairs that simulate real SCPI behavior. The Instrument Catalog provides all_instruments.yaml with 16 pre-built instruments covering multimeters, power supplies, oscilloscopes, counters, and more.

Tip

The sim backend is a great way to develop and test prompts, workflows, and multi-instrument sequences before connecting to real hardware. Simulated instruments respond to the same SCPI commands as the real thing.

WiFi setup (AR488)

Before using TCP transport with an AR488 backend, you need to configure WiFi on the ESP32 itself. This is a one-time setup done over USB serial.

1. Connect to the adapter over serial

   Open a serial terminal at 115200 baud (e.g., picocom /dev/ttyUSB0 -b 115200).

2. Set the WiFi credentials

   ++wifi ssid YourNetworkName
   ++wifi pass YourPassword

3. Enable WiFi and save

   ++wifi enable
   ++savecfg

4. Reboot the adapter

   Power cycle the ESP32 or send ++rst. After rebooting, the adapter connects to your WiFi network and starts listening on port 23.

5. Find the IP address

   Check your router’s DHCP client list, or query the adapter:

   ++wifi

   This prints the current WiFi status, including the assigned IP address.

Once you have the IP address, use it as the host value in your TCP backend configuration.

Tip

Assign a static IP to the ESP32 in your router’s DHCP reservation table. This prevents the address from changing after a power cycle, which would break your config.

Instrument aliases

Instead of using full VISA resource strings in every tool call, you can define friendly aliases in [instruments.*] sections. Each alias maps a short name to a resource string and backend.

mcpyvisa.toml

[instruments.dmm]
resource = "GPIB0::22::INSTR"
backend = "bench-a"

[instruments.psu]
resource = "GPIB0::5::INSTR"
backend = "bench-a"

[instruments.scope]
resource = "TCPIP::192.168.1.100::INSTR"
backend = "lan-bench"

With these aliases configured, tool calls become concise:

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

You can always use the full VISA resource string instead of an alias:

instrument_query("GPIB0::22::INSTR", "MEAS:VOLT:DC?")

Tip

Aliases are especially useful in prompts and saved workflows. If you move an instrument to a different address or backend, update the alias mapping once and all references keep working.

Behavior options

These fields are optional and apply to AR488 backends. They control timing and auto-discovery behavior.

mcpyvisa.toml

[[backend]]
name = "bench-a"
type = "ar488"
transport = "serial"
port = "/dev/ttyUSB0"
baudrate = 115200
auto_discover = true
auto_identify = true
read_timeout_ms = 3000
inter_command_delay_ms = 10

Field	Default	Description
auto_discover	true	Discover instruments on the bus immediately after connecting.
auto_identify	true	Send *IDN? to each discovered instrument during discovery.
read_timeout_ms	3000	How long to wait for an instrument response (1—32000 ms).
inter_command_delay_ms	10	Pause between consecutive bus commands (0—1000 ms).

Tuning timeouts

The right timeout depends on your instruments and transport:

Scenario	read_timeout_ms	inter_command_delay_ms
Serial, fast instruments (34401A, 2000)	3000	10
Serial, slow instruments (electrometer, source measure)	10000	10
TCP, typical bench	5000	20
TCP, high-latency network	10000	30

Note

inter_command_delay_ms exists because rapid command sequences can cause voltage dips on the ESP32, triggering the brownout detector. The default of 10 ms is conservative. If you see the adapter disconnect under heavy use, increase this value.

Disabling auto-discovery

Set auto_discover = false when:

• You want faster connection times and will discover instruments manually later
• The bus has instruments that behave unpredictably when polled (some older instruments respond to findlstn inconsistently)
• You are connecting to an empty backend for diagnostic purposes

Set auto_identify = false (while keeping auto_discover = true) when:

• You want to discover listener addresses quickly without the overhead of *IDN? queries
• Your instruments do not support IEEE 488.2 identification

Multiple backends

Add multiple [[backend]] sections to manage separate instrument buses from a single mcpyvisa instance:

mcpyvisa.toml

[server]
log_level = "INFO"
auto_discover = true
auto_identify = true

[[backend]]
name = "bench-a"
type = "ar488"
transport = "serial"
port = "/dev/ttyUSB0"
baudrate = 115200

[[backend]]
name = "bench-b"
type = "ar488"
transport = "tcp"
host = "192.168.1.50"
tcp_port = 23
read_timeout_ms = 5000
inter_command_delay_ms = 20

[[backend]]
name = "lan-bench"
type = "pyvisa-py"

# Sim backend for testing prompts while real instruments are in use
[[backend]]
name = "sim-bench"
type = "sim"
sim_file = "./gpib-catalog/sim/all_instruments.yaml"

[instruments.dmm]
resource = "GPIB0::22::INSTR"
backend = "bench-a"

[instruments.scope]
resource = "TCPIP::192.168.1.100::INSTR"
backend = "lan-bench"

[instruments.sim-dmm]
resource = "GPIB0::22::INSTR"
backend = "sim-bench"

Each backend operates independently with its own connection, lock, and state. Operations on different backends run concurrently. The name field must be unique across all backends. A sim backend can run alongside real backends — useful for developing prompts and workflows against simulated instruments while your physical equipment handles other tasks.

Server-level options

The [server] section sets defaults that apply to all backends:

mcpyvisa.toml

[server]
log_level = "INFO"
auto_discover = true
auto_identify = true

Field	Default	Description
log_level	"INFO"	Logging verbosity: DEBUG, INFO, WARNING, ERROR.
auto_discover	true	Default auto-discovery setting, overridden per backend.
auto_identify	true	Default auto-identify setting, overridden per backend.

Changing AR488 configuration at runtime

Some AR488 backend settings can be changed after connecting without editing the config file:

> Set the read timeout on bench-a to 10 seconds

The LLM calls configure_ar488("bench-a", read_timeout_ms=10000). Runtime-configurable parameters:

Parameter	Description
read_timeout_ms	Read timeout in milliseconds
auto_mode	Auto-read mode (0=off, 1=prologix, 2=on-query, 3=continuous)
eos	End-of-send character (0=CRLF, 1=CR, 2=LF, 3=None)
eoi	Whether to assert EOI on the last byte sent

Caution

Runtime changes are not persisted. They last until the backend is disconnected. To make permanent changes, edit the TOML config file. To persist changes on the AR488 itself, use ar488_command to send ++savecfg — but be careful, as this writes to the ESP32’s NVS flash.

Switching between transports

If you move an AR488 adapter from USB to WiFi (or vice versa), update the transport and its associated fields in the config:

Before: serial

[[backend]]
name = "bench-a"
type = "ar488"
transport = "serial"
port = "/dev/ttyUSB0"
baudrate = 115200

After: TCP

[[backend]]
name = "bench-a"
type = "ar488"
transport = "tcp"
host = "192.168.1.50"
tcp_port = 23
read_timeout_ms = 5000
inter_command_delay_ms = 20

Keep the name the same so that any instrument aliases, scripts, or saved conversations referencing "bench-a" continue to work. Restart mcpyvisa after changing the config file.