Workbench and Instruments

Workbench & Instruments

Workbench files

A workbench is a JSON file in workbenches/ that describes your connected instruments. One is symlinked as workbenches/active.json — this is what the GUI and all scripts use by default.

Each instrument entry looks like:

{
  "resource":     "USB0::0x2A8D::0x1302::MY12345::INSTR",
  "connection":   "USB",
  "manufacturer": "Keysight",
  "model":        "EDU36311A",
  "serial":       "MY12345",
  "type":         "psu",
  "role":         "psu",
  "family_id":    "keysight_edu36311a"
}

Field	Description
resource	PyVISA resource string — uniquely identifies the physical instrument
connection	USB, TCPIP, or ASRL (serial)
type	Instrument class: scope, psu, awg, dmm, load, smu
role	How scripts find the instrument: scope, psu, generator, dmm, load, smu
family_id	Key into eewBackbone.json — determines which SCPI commands are used

role is the field scripts use to look up instruments. This means your test scripts work regardless of which USB port or IP address an instrument is on.

---

The GUI workbench tab

When you load a workbench, the GUI shows one card per instrument. Each card has live controls appropriate for the instrument type:

• Scope — channel settings, timebase sync, measurements, screenshot
• PSU — per-channel voltage/current set and readback, output on/off
• AWG / FGen — waveform type, frequency, amplitude, offset, output on/off
• DMM — measurement mode selector, single/continuous measurement

Cards show a connection status dot (amber = pending, green = connected, red = error). The connection status of an instrument does not affect other instruments.

---

Bench state — save, load, reset

Once instruments are connected, a state bar appears above the instrument grid with three actions.

Save state

Type a name in the field and click Save state. The current settings of all connected PSUs and AWGs are snapshotted and saved to workbench_states/<name>.json:

• PSU — voltage setpoint and current limit per channel
• AWG — waveform function, frequency, amplitude, and offset per channel

Output enable states are always saved as off — a deliberate safety choice so that loading a state never unexpectedly energises outputs. Turn outputs on manually after confirming the loaded settings look correct.

Load state

Click Load state to open a picker that lists all saved states with their instrument summary and timestamp. Select a state and click Load — the settings are applied to the matching connected instruments immediately, without reconnecting. Instruments not present in the saved state are left untouched.

Each entry in the list has a ✕ button to permanently delete that state.

Reset all

Click Reset all (with confirmation) to drive all connected instruments to safe defaults:

• PSU — all channels set to 0 V / 100 mA limit, outputs off
• AWG — all outputs off, instrument reset

This is the GUI equivalent of python core/setWorkbench.py --reset-bench.

State files

Saved states live in workbench_states/ at the project root as plain JSON. The format is compatible with setWorkbench.py config files and can be edited manually or shared between setups:

{
  "name": "preamp_bias",
  "saved_at": "2026-06-08T14:30:00",
  "summary": "PSU EDU36311A, AWG EDU33211A",
  "instruments": {
    "USB0::0x2A8D::0x3602::MY12345::INSTR": {
      "type": "psu",
      "model": "EDU36311A",
      "outputs": [
        { "channel": 1, "voltage": 12.0, "current_limit": 0.5, "enabled": false },
        { "channel": 2, "voltage": -5.0, "current_limit": 0.2, "enabled": false }
      ]
    }
  }
}

---

Manual instrument assignment

If an instrument is not automatically recognised (no match in eewBackbone), its card shows an Assign instrument… button. For any recognised instrument, hover its card to reveal a ✎ edit button. Both open the same assignment picker:

1. Type — select the instrument class (Scope, PSU, AWG/FGen, DMM, Load, SMU)
2. Vendor — filtered by type
3. Family / Model — filtered by vendor; selects the exact SCPI dialect
4. Role — optional override (defaults sensibly: psu, generator, scope, etc.)

On confirm the workbench file is updated immediately and the new SCPI family activates without needing to reconnect.

When to use manual assignment

• Instrument returned an IDN string that doesn't match any known pattern
• You want to use a compatible family's commands on an unlisted variant
• The auto-detected family is wrong (e.g. a rebadged instrument)

Adding permanent support

If you find yourself manually assigning the same instrument repeatedly, the right fix is to add its IDN pattern to core/eewBackbone.json. See eewBackbone for how.

---

Instrument roles

Scripts use open_by_role(rm, wb, role) from core/workbench.py to open instruments:

from workbench import load_workbench, open_by_role
import pyvisa

wb  = load_workbench()                      # loads active workbench
rm  = pyvisa.ResourceManager("@py")
psu = open_by_role(rm, wb, "psu")
gen = open_by_role(rm, wb, "generator")

If you have two PSUs in a workbench, give them distinct roles (e.g. psu_main, psu_bias) by editing the workbench JSON directly.