Configure Bridges

mcgpib supports two transport types for connecting to AR488 bridges: serial (USB) and TCP (WiFi). Each bridge gets its own [[bridge]] section in the TOML configuration file with transport-specific options and tuning parameters.

Configuration file locations

mcgpib searches for its config file in this order:

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

If no file is found, mcgpib starts with no bridges configured.

Transport options

Serial (USB)

Serial is the simplest and most reliable transport. Connect the ESP32 to your machine with a USB cable.

mcgpib.toml

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

Required fields:

Field	Description
name	Unique identifier for this bridge. Alphanumeric with hyphens and underscores.
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 bridge, list ports, plug it back in, and list again. The new entry is your bridge.

TCP (WiFi)

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

mcgpib.toml

[[bridge]]
name = "bench-b"
transport = "tcp"
host = "192.168.1.50"
tcp_port = 23

Required fields:

Field	Description
name	Unique identifier for this bridge.
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, mcgpib will fail with a connection timeout. Close other connections first.

WiFi setup

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

1. Connect to the bridge 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 bridge

   Power cycle the ESP32 or send ++rst. After rebooting, the bridge 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 bridge:

   ++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 bridge 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.

Behavior options

These fields are optional and apply to both serial and TCP bridges.

mcgpib.toml

[[bridge]]
name = "bench-a"
transport = "serial"
port = "/dev/ttyUSB0"
baudrate = 115200
auto_scan = true
auto_identify = true
read_timeout_ms = 3000
inter_command_delay_ms = 10

Field	Default	Description
auto_scan	true	Scan the bus for listeners immediately after connecting.
auto_identify	true	Send *IDN? to each discovered listener during scan.
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 bridge disconnect under heavy use, increase this value.

Disabling auto-scan

Set auto_scan = false when:

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

Set auto_identify = false (while keeping auto_scan = 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 bridges

Add multiple [[bridge]] sections to manage separate GPIB buses from a single mcgpib instance:

mcgpib.toml

[server]
log_level = "INFO"
read_timeout_ms = 3000

[[bridge]]
name = "bench-a"
transport = "serial"
port = "/dev/ttyUSB0"
baudrate = 115200
auto_scan = true
auto_identify = true

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

Each bridge operates independently with its own connection, lock, and bus state. Operations on different bridges run concurrently. The name field must be unique across all bridges.

Server-level options

The [server] section sets defaults that apply when a bridge does not specify its own value:

mcgpib.toml

[server]
log_level = "INFO"
read_timeout_ms = 3000

Field	Default	Description
log_level	"INFO"	Logging verbosity: DEBUG, INFO, WARNING, ERROR.
read_timeout_ms	3000	Default read timeout, overridden by per-bridge read_timeout_ms.

Changing configuration at runtime

Some bridge 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_bridge("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 bridge is disconnected. To make permanent changes, edit the TOML config file. To persist changes on the AR488 itself, use raw_command to send ++savecfg — but be careful, as this writes to the ESP32’s NVS flash.

Switching between transports

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

Before: serial

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

After: TCP

[[bridge]]
name = "bench-a"
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 scripts or saved conversations referencing "bench-a" continue to work. Restart mcgpib after changing the config file.