Configuration

mcgpib uses a TOML configuration file to define bridges and server behavior. If no configuration file is found, the server starts with no bridges configured.

Config file search order

The server looks for a configuration file in this order, using the first one found:

1. $MCGPIB_CONFIG — environment variable pointing to an explicit path
2. ./mcgpib.toml — current working directory
3. ~/.config/mcgpib/config.toml — XDG user config directory

If none of these paths exist, the server starts with an empty configuration (zero bridges). You can still add bridges dynamically in future versions, but for now at least one [[bridge]] section is required for useful operation.

Server section

The [server] section controls global server behavior.

[server]
log_level = "INFO"          # DEBUG, INFO, WARNING, ERROR
read_timeout_ms = 3000      # Default GPIB read timeout (overridden per-bridge)

Key	Type	Default	Description
log_level	string	"INFO"	Python logging level. DEBUG logs every ++ command sent to bridges
read_timeout_ms	integer	3000	Default GPIB read timeout in milliseconds (1—32000). Individual bridges can override this value

Bridge section

Each [[bridge]] section defines a single AR488 bridge. You can define as many bridges as needed — they are accessed independently and concurrently (one lock per bridge, concurrent across bridges).

Serial bridge

[[bridge]]
name = "bench-a"             # Unique identifier (alphanumeric, hyphens, underscores)
transport = "serial"          # "serial" or "tcp"
port = "/dev/ttyUSB0"         # Serial port path
baudrate = 115200             # Serial baud rate (default: 115200)
auto_scan = true              # Scan bus on connect (default: true)
auto_identify = true          # Send *IDN? to discovered listeners (default: true)
read_timeout_ms = 3000        # GPIB read timeout for this bridge (default: 3000)
inter_command_delay_ms = 10   # Delay between commands in ms (default: 10)

TCP bridge (WiFi)

[[bridge]]
name = "bench-b"
transport = "tcp"
host = "192.168.1.50"         # IP address or hostname of ESP32
tcp_port = 23                 # AR488 WiFi default port (default: 23)
auto_scan = false             # Skip initial scan (useful for slow WiFi links)
read_timeout_ms = 5000        # Longer timeout for WiFi latency
inter_command_delay_ms = 20   # Larger delay for WiFi stability

All bridge options

Key	Type	Default	Description
name	string	(required)	Unique bridge identifier. Alphanumeric with hyphens and underscores only
transport	string	"serial"	Transport type: "serial" or "tcp"
port	string	null	Serial port path (required for serial transport)
baudrate	integer	115200	Serial baud rate
host	string	null	TCP host address (required for TCP transport)
tcp_port	integer	23	TCP port number
auto_scan	boolean	true	Run ++findlstn immediately after connecting
auto_identify	boolean	true	Send *IDN? to each listener found by auto_scan
read_timeout_ms	integer	3000	GPIB read timeout in milliseconds (1—32000)
inter_command_delay_ms	integer	10	Delay between consecutive ++ commands (0—1000 ms)

Inter-command delay

The inter_command_delay_ms setting exists to prevent ESP32 brownout during rapid bus activity. The GPIB bus transceiver ICs (SN75160/SN75161) can draw significant current during state transitions. The default of 10ms is safe for most setups; reduce to 0 for maximum throughput on boards with stable power supplies, or increase to 20—50ms for WiFi bridges where latency is less predictable.

Environment variables

Variable	Description
MCGPIB_CONFIG	Absolute path to TOML config file. Overrides the default search order

Full working example

A complete configuration with two bridges — one serial and one WiFi:

mcgpib.toml

[server]
log_level = "INFO"
read_timeout_ms = 3000

# USB-connected bridge on the main bench
[[bridge]]
name = "main-bench"
transport = "serial"
port = "/dev/ttyUSB0"
baudrate = 115200
auto_scan = true
auto_identify = true
read_timeout_ms = 3000
inter_command_delay_ms = 10

# WiFi-connected bridge in the RF shielded room
[[bridge]]
name = "rf-bench"
transport = "tcp"
host = "192.168.1.50"
tcp_port = 23
auto_scan = true
auto_identify = true
read_timeout_ms = 5000
inter_command_delay_ms = 20

Bridge name rules

Bridge names must be alphanumeric with hyphens and underscores only. Spaces, dots, and other punctuation are rejected at config load time. Examples of valid names: bench-a, main_bench, rfroom1. Examples of invalid names: bench.a, my bench, bench@lab.