MCP tool

Purpose

scope_query

Raw SCPI command passthrough. Returns the response plus a caveats[] warning that observation limits are not auto-checked on this path.

scope_screenshot

Save a PNG of the current scope screen for user review. Optionally place manual cursors (Δt / ΔV) and channel labels (DIR / STP / NXT / CLK) to make the image easy to read.

scope_trigger

Read or configure the trigger — every trigger type the instrument supports. Call with no arguments to read the current state (returns mode, globals, the mode's params, and accepted_params describing what's settable). To set, pass mode and/or the global sweep / coupling / holdoff_s, and put all type-specific parameters in a params object (e.g. {"source":"CHAN1","slope":"NEG","nth_edge":2,"idle_s":2e-3} for an Nth-edge trigger). mode is validated against the profile's full type list (6 standard + 9 option-licensed DS1000Z types), and each params key/value is validated against that mode's schema (enum membership, numeric range, channel source). Unsupported types/params are rejected with the valid list; option-licensed types emit a caveats[] warning. Pass action to control acquisition — RUN / STOP / SINGLE (arm one shot) / FORCE (force a trigger; NORMAL/SINGLE sweep only); status (TD/WAIT/RUN/AUTO/STOP) reflects the result.

scope_measure

Read scope-side automatic measurements (:MEAS:ITEM?) for a list of items on a source channel. Single-source items: VMAX VMIN VPP VTOP VBASE VAMP VAVG VRMS OVERSHOOT PRESHOOT PERIOD FREQUENCY RTIME FTIME PWIDTH NWIDTH PDUTY NDUTY; two-source (require source2): RDELAY FDELAY RPHASE FPHASE. Un-measurable values come back as null with a caveat.

scope_measure_stat

Read measurement statistics (:MEASure:STATistic:ITEM) for one or more items on a source — accumulated current/max/min/average/deviation/count rather than a single instantaneous value. stat_types defaults to all six (CURRent MAXimum MINimum AVERages DEViation COUNt); pass a subset to limit the query. mode optionally sets the statistics mode (DIFFerence / EXTRemum). reset=True clears accumulated data before querying. Returns {source, statistics: [{item, current, max, min, avg, dev, count}], caveats}.

scope_channel

Read or configure an analog channel's vertical setup. channel (1-based) is required. Pass any subset of scale_v_per_div, offset_v, coupling (AC/DC/GND), display, probe, bw_limit (20M/OFF), invert, units. Validated against the profile; 20 MHz BW limit emits a caveat.

scope_timebase

Read or configure the horizontal (timebase) setup. Pass any subset of s_per_div, offset_s, mode (MAIN/XY/ROLL). Validated against the profile; long timebase emits a memory-downgrade caveat.

scope_waveform

Capture one channel and return a compact threshold-quantized event stream, not raw ADC samples. Raw volts pass through a Schmitt-trigger comparator (threshold_v ± hysteresis_v/2) into a 0/1 stream, then run-length-encoded into runs [(t_us, level, dur_us)] and edges [(t_us, channel, RISE/FALL)] (times in µs, trigger at t=0). Hysteresis is mandatory — a single threshold on a noisy edge fragments into useless micro-pulses. A hysteresis_v over 20 % of the signal peak-to-peak emits a detection-miss caveats[] warning; an over-budget stream is truncated with a caveat. Args: source (default CHAN1), mode (NORMal or RAW — RAW reads the full acquisition memory up to 24M points instead of the ~1200-point screen decimation; scope must be stopped first), threshold_v (1.5), hysteresis_v (0.1).

scope_acquire

Read or configure the acquisition mode — type (NORMal/AVERages/PEAK/HRESolution), averages (2..1024 powers of 2), and memory_depth (AUTO or numeric, validated per active channel count). Call with no args to read (returns type, averages, memory_depth, sample_rate). Selecting AVERages emits a caveats[] warning that the update rate is reduced.

scope_capture

Declarative single-shot capture — configure, arm, wait, and read in one call. Composes trigger/channel/timebase/acquire setup, arms :SINGle, polls until triggered (or timeout_s), then reads per-channel waveforms (quantized to runs/edges/bus_runs), scope-side measurements, and an optional screenshot. Use sweep='AUTO' or 'NORMAL' to skip arm+poll and read the current screen memory immediately. Set waveform_mode='RAW' to read the full acquisition memory after the trigger fires (scope is already stopped after SINGLE). Returns {triggered, channels, waveform, bus_runs, measurements, screenshot_path, caveats}.

scope_compare

Sim vs HW reference diff (P4) — the project's core goal. Takes a golden edge/run list from your RTL simulator and compares it against hardware (live capture or provided data). Returns {matched, shifted[{ref_t_us, hw_t_us, delta_us, kind}], missing[{t_us, kind}], added[{t_us, kind}], first_divergence_us, summary, caveats}. Two modes: live (captures from scope if hw_runs/hw_edges not provided) or offline (pass pre-captured data directly, no scope connection needed). tolerance_us (default 0.05 = 50 ns) sets how close two same-kind edges must be to count as a match. Signal-agnostic: works on SPI, I2C, UART, ULPI, or any digital signal.

scope_viewer

Generate a self-contained interactive HTML waveform viewer. Reads RAW waveform data (scope must be stopped) and embeds full analog voltage samples — no downsampling — into an HTML file. Features: per-channel ON/OFF toggle, per-channel V/div dropdown (10mV–100V), draggable GND offset markers (▶), T/div dropdown with 1-2-5 auto-stepping on scroll-zoom, drag-to-pan, vertical cursor snapped to sample points with fixed voltage readout, trigger position marker (▼T at t=0, derived from :TRIG:POS?). depth controls observation window centered on the trigger: "low" (30k pts, ~120µs, ~1s transfer), "mid" (300k, ~1.2ms, ~3s), "high" (3M+, ~12ms, ~17s). Browser renders millions of points via per-pixel min/max envelope when zoomed out, individual samples + dots when zoomed in.

Env var

Required

Meaning

SCOPE_MCP_HOST

yes

scope IP or hostname

SCOPE_MCP_PORT

no (default 5555)

SCPI TCP port

SCOPE_MCP_MODEL

no

model key (e.g. RIGOL_DS1104Z). If unset, *IDN? is parsed and matched against each profile's idn_match regex