Discover/connect an instrument and attach it to the session.

Call this first — every other tool needs a connected instrument. Runs the
transport cascade (USB → LAN → manual host); pass ``host`` to skip discovery
and target a known address.

Return the connected instrument's identity (vendor, model, serial, firmware).

Takes no arguments; requires a prior self_config.

Report the connected instrument's detected capabilities.

Returns channel count/ids, bandwidth, source & logic support, max memory
depth, and installed options. Takes no arguments; requires a prior
self_config. Use it to learn what the scope can do before driving it.

Capture the on-screen waveform for one channel (~1200 points).

Capture the deep-memory waveform for one channel (full sample-rate record).

Capture multiple channels on the same time base, time-aligned.

The instrument shares one time base across channels, so a sequence of reads is already time-aligned. (Real hardware reads them back-to-back; the mock is instantaneous.) Use this to compare two signals sample-for-sample.

Take a single measurement of one quantity on one channel.

Take several measurements at once on one channel (one read per quantity).

Poll one measurement repeatedly, returning a short time series.

Useful for watching a value drift or settle (e.g. a ramping duty cycle).
``interval_s`` is honored via the instrument's settle hook so the mock stays
instant in tests while real hardware actually waits between reads.

Set a channel's vertical configuration (enable, V/div, offset, coupling).

Only the arguments you pass are changed; omit any to leave it as-is. Use this to fit a signal on screen before measuring or capturing.

Set the horizontal time base (seconds/div and trigger offset).

Controls how many periods of the signal are shown; widen s/div to see slow events, narrow it to resolve fast ones. Shared across all channels.

Configure the edge trigger (source channel, level, slope).

Sets up a stable trigger so repetitive signals hold still, or so a
single-shot (see acq_single) fires on the right edge of a one-off event.

Start continuous (free-running) acquisition. Disruptive — needs confirm=True.

Stop acquisition, freezing the current trace. Disruptive — needs confirm=True.

Arm a single-shot acquisition: capture one trigger then stop. Needs confirm=True.

Pair with set_trigger to catch a one-off transient (e.g. a power-on spike).

Force a trigger now, ignoring the trigger condition. Needs confirm=True.

Set acquisition type and/or memory depth. Disruptive — needs confirm=True.

Deeper memory captures more points at a given time base; averaging/peak modes trade update rate for noise rejection or glitch capture.

Characterize the signal on channel — the FLAGSHIP goal-level tool.

Runs the probe → vertical fit → horizontal fit → trigger hunt → characterize
loop, settling and re-verifying after each adjustment (bounded by
:data:`MAX_SETTLE_ITERATIONS`). Returns the discovered signal parameters, a
full measurement snapshot, and a confidence flag. When ``export_path`` is
given, the deep-memory capture is rendered to a PNG there.