AR488 Command Reference

The AR488 firmware implements the Prologix GPIB-USB command set with extensions. All commands use the ++ prefix to distinguish them from data sent directly on the GPIB bus. Text sent without the ++ prefix is transmitted verbatim to the currently addressed instrument.

Note

Most of these commands are abstracted by mcgpib’s higher-level tools. You only need to use raw_command to send these directly when working outside the tool abstractions. The gpib://protocol/commands resource also provides this reference in machine-readable JSON format.

Standard Prologix Commands

These commands are compatible with the original Prologix GPIB-USB adapter.

---

++addr

Show or set the currently addressed GPIB instrument.

Syntax: ++addr [N]

Mode: Controller and Device

Argument	Description
(none)	Show the current GPIB address
N	Set the address to N (0—30)

Example

++addr        → 22
++addr 5      → (no output, address set to 5)

---

++auto

Set the auto-read mode. Controls whether the bridge automatically reads from the bus after sending data.

Syntax: ++auto [0|1|2|3]

Mode: Controller

Value	Behavior
0	Off — manual read with ++read (default for mcgpib)
1	Prologix mode — read after every write
2	On query — read after commands ending with ?
3	Continuous — read continuously

Caution

mcgpib sets ++auto 0 during bridge initialization. Changing this via configure_bridge or raw_command may interfere with instrument_query behavior, which explicitly issues ++read eoi after each query.

Example

++auto        → 0
++auto 2      → (no output, auto mode set to 2)

---

++clr

Send Selected Device Clear (SDC) to the currently addressed instrument.

Syntax: ++clr

Mode: Controller

Example

++addr 22
++clr         → (no output, SDC sent to address 22)

---

++eoi

Enable or disable EOI (End or Identify) assertion on the last byte of data sent on the bus.

Syntax: ++eoi [0|1]

Mode: Controller and Device

Value	Behavior
0	Do not assert EOI
1	Assert EOI on last byte (default)

Example

++eoi         → 1
++eoi 0       → (no output, EOI disabled)

---

++eos

Set the end-of-send character appended to data sent on the GPIB bus.

Syntax: ++eos [0|1|2|3]

Mode: Controller and Device

Value	Character
0	CR+LF (default)
1	CR only
2	LF only
3	None

Example

++eos         → 0
++eos 2       → (no output, LF-only mode)

---

++ifc

Assert Interface Clear (IFC) for 150 microseconds. Resets all device interfaces to idle and makes this controller the Controller-In-Charge (CIC).

Syntax: ++ifc

Mode: Controller

Example

++ifc         → (no output, IFC asserted)

---

++llo

Send Local Lockout (LLO) to disable the front panel on one or all instruments.

Syntax: ++llo [all]

Mode: Controller

Argument	Description
(none)	Lockout the currently addressed instrument
all	Lockout all instruments on the bus

Example

++llo         → (no output, current device locked out)
++llo all     → (no output, all devices locked out)

---

++loc

Send Go To Local (GTL) to re-enable front panel control.

Syntax: ++loc [all]

Mode: Controller

Argument	Description
(none)	Return current instrument to local
all	Return all instruments to local

Example

++loc         → (no output, current device returned to local)
++loc all     → (no output, all devices returned to local)

---

++mode

Set the interface mode.

Syntax: ++mode [0|1]

Mode: Both

Value	Mode
0	Device — bridge acts as a GPIB peripheral
1	Controller — bridge controls the bus (default for mcgpib)

Example

++mode        → 1
++mode 0      → (no output, switched to device mode)

---

++read

Read data from the GPIB bus. Reads until EOI is asserted, a specific character is received, or the read timeout expires.

Syntax: ++read [eoi|N]

Mode: Controller

Argument	Description
eoi	Read until EOI is asserted (most common)
N	Read until ASCII character N is received
(none)	Read until timeout

Example

++read eoi    → +4.23451000E+00
++read 10     → (read until LF character)

---

++read_tmo_ms

Set the read timeout in milliseconds.

Syntax: ++read_tmo_ms [N]

Mode: Controller

Argument	Description
(none)	Show current timeout
N	Set timeout to N milliseconds (1—32000)

Example

++read_tmo_ms      → 3000
++read_tmo_ms 5000 → (no output, timeout set to 5000ms)

---

++rst

Reset the AR488 controller. This is a firmware reset, not a GPIB bus reset.

Syntax: ++rst

Mode: Both

Example

++rst         → (controller resets)

---

++savecfg

Save the current configuration to NVS (non-volatile storage) flash. Settings persist across power cycles.

Syntax: ++savecfg

Mode: Both

Example

++savecfg     → (no output, config saved to NVS)

---

++spoll

Serial poll an instrument. Returns the 8-bit status byte. Bit 6 (0x40) is the RQS (Requesting Service) bit.

Syntax: ++spoll [N]

Mode: Controller

Argument	Description
(none)	Poll the currently addressed instrument
N	Poll address N

Example

++spoll 22    → 64

The response 64 (0x40) means bit 6 is set — the device is requesting service.

---

++srq

Check the SRQ (Service Request) bus line state.

Syntax: ++srq

Mode: Controller

Returns: 0 (not asserted) or 1 (asserted).

Example

++srq         → 0

---

++status

Set or read the status byte used when this bridge is in device mode.

Syntax: ++status [N]

Mode: Device

Argument	Description
(none)	Show current status byte
N	Set status byte to N (0—255)

Example

++status      → 0
++status 64   → (no output, status byte set to 64)

---

++trg

Send Group Execute Trigger (GET) to one or more addresses.

Syntax: ++trg [N ...]

Mode: Controller

Argument	Description
(none)	Trigger the currently addressed device
N ...	Trigger specific addresses (space-separated)

Example

++trg 5 22    → (no output, GET sent to addresses 5 and 22)

---

++ver

Show the firmware version string.

Syntax: ++ver [real]

Mode: Both

Argument	Description
(none)	Show the version string (possibly customized via ++id verstr)
real	Show the actual firmware version, ignoring any custom verstr

Example

++ver         → AR488 GPIB controller 0.51.29
++ver real    → AR488 GPIB controller 0.51.29

---

++verbose

Enable or disable human-readable output. When enabled, commands echo their settings in a descriptive format. When disabled, only numeric values are returned.

Syntax: ++verbose [0|1]

Mode: Both

Value	Behavior
0	Numeric output only (default for mcgpib)
1	Human-readable descriptions

Caution

mcgpib sets ++verbose 0 during initialization. Enabling verbose mode will cause parsing errors in the higher-level tools.

Example

++verbose     → 0
++verbose 1   → (no output, verbose mode enabled)

---

AR488 Extended Commands

These commands are extensions specific to the AR488 firmware, not part of the original Prologix command set.

---

++allspoll

Serial poll multiple addresses in a single operation. Returns address:status pairs.

Syntax: ++allspoll N [N ...]

Mode: Controller

Example

++allspoll 5 22 7    → 5:0 22:64 7:0

---

++dcl

Send Universal Device Clear (DCL) to all devices on the bus. Unlike ++clr which is selective, ++dcl clears every device regardless of addressing.

Syntax: ++dcl

Mode: Controller

Example

++dcl         → (no output, all devices cleared)

---

++default

Reset the AR488 to factory default configuration. This resets all settings in memory but does not modify NVS — a subsequent ++savecfg would persist the defaults.

Syntax: ++default

Mode: Both

Example

++default     → (no output, settings reset to defaults)

---

++findlstn

Find all listeners on the GPIB bus. Polls addresses 1—30 and returns those that acknowledge.

Syntax: ++findlstn

Mode: Controller

Returns: Space-separated list of listener addresses.

Example

++findlstn    → 5 7 22

---

++findrqs

Find the device requesting service. Polls the specified addresses and returns the first one with the RQS bit set in its status byte.

Syntax: ++findrqs N [N ...]

Mode: Controller

Returns: SRQ:address,status_byte or nothing if no device is requesting service.

Example

++findrqs 5 7 22    → SRQ:22,64

---

++id name

Show or set the bridge’s interface name. Limited to 15 characters.

Syntax: ++id name [S]

Mode: Both

Argument	Description
(none)	Show current name
S	Set name to S (max 15 characters)

Example

++id name           → bench-a
++id name bench-a   → (no output, name set)

---

++macro

List, run, edit, or delete macros. The ESP32 supports 10 macro slots (0—9), each up to 128 bytes. Macro 0 auto-executes at startup.

Syntax: ++macro [N] [set|del]

Mode: Both

Usage	Description
++macro	List all macros
++macro N	Execute macro N
++macro N set	Enter edit mode for macro N (send commands, end with ++macro end)
++macro N del	Delete macro N
++macro N clear	Clear macro N (same as del)

Macro 0 auto-executes

Macro 0 runs automatically at power-on. This is useful for instrument initialization sequences but can make the bridge unreachable if the macro sends commands that hang the bus. If you lose serial access due to a bad macro 0, use ++macro 0 clear immediately after power-on (before the macro finishes executing) to clear it.

Example

++macro           → (lists all macros)
++macro 1 set     → (enter edit mode for macro 1)
*RST              → (macro content: send *RST to current device)
++macro end       → (exit edit mode)
++macro 1         → (execute macro 1)

---

++ppoll

Conduct a parallel poll. Simultaneously reads one bit from each device configured for parallel poll response. Returns the response byte as a decimal integer.

Syntax: ++ppoll

Mode: Controller

Returns: Decimal integer (0—255) representing the combined response bits.

Example

++ppoll       → 5

The response 5 (binary 00000101) means DIO1 and DIO3 are asserted.

---

++prompt

Show or hide the command prompt. When enabled, the bridge displays a > prompt after each command.

Syntax: ++prompt [0|1]

Mode: Both

Value	Behavior
0	No prompt (default for mcgpib)
1	Show > prompt

Caution

mcgpib sets ++prompt 0 during initialization. Enabling the prompt will cause parsing errors in the transport layer, as the > character will be prepended to response data.

Example

++prompt      → 0
++prompt 1    → (no output, prompt enabled)

---

++ren

Assert or deassert the REN (Remote Enable) bus line. When asserted, instruments addressed to listen will enter remote mode.

Syntax: ++ren [0|1]

Mode: Controller

Value	Behavior
0	Deassert REN (all instruments return to local)
1	Assert REN

Example

++ren 1       → (no output, REN asserted)
++ren 0       → (no output, REN deasserted)

---

++xdiag

Bus diagnostics. Writes a byte directly to the data bus or control bus lines and holds it for 10 seconds. Designed for hardware testing with a multimeter or logic analyzer.

Syntax: ++xdiag mode byte

Mode: Both

Argument	Description
mode	0 = data bus (DIO1—DIO8), 1 = control bus
byte	Value to write (0—255)

Example

++xdiag 0 255     → (all data lines driven high for 10 seconds)
++xdiag 1 128     → (control bus bit 7 driven high for 10 seconds)

---

Additional Extended Commands

These commands are less commonly used but available for specific scenarios.

Command	Syntax	Mode	Description
++eor	++eor [0-7]	Both	Set EOR (End of Receive) character: 0=CRLF, 1=CR, 2=LF, 3=None, 4=LFCR, 5=ETX, 6=CRLF+ETX, 7=SPACE
++eot_enable	++eot_enable [0|1]	Both	Enable/disable appending EOT character when EOI is detected
++eot_char	++eot_char [N]	Both	Set EOT character (ASCII 0—255)
++id serial	++id serial [N]	Both	Show/set interface serial number (max 9 digits)
++id verstr	++id verstr [S]	Both	Show/set custom version string (max 47 characters)
++idn	++idn [0|1|2]	Both	Enable *IDN? auto-response: 0=off, 1=name, 2=name+serial
++repeat	++repeat N ms cmd	Controller	Repeat a command N times with ms delay between
++setvstr	++setvstr [S]	Both	Alias for ++id verstr
++srqauto	++srqauto [0|1]	Controller	Auto serial poll when SRQ asserts
++tmbus	++tmbus [N]	Controller	Bus settling delay in microseconds (0—30000)
++ton	++ton [0|1]	Both	Talk-only mode