ScopeDriverBase#

class ScopeDriverBase[source]#

Bases: ABC

Vendor scope driver contract. Concrete drivers compose a transport (typically VisaDriver).

Channels are 1-indexed analog input numbers throughout — the wrapper instrument (InstroScope) is responsible for range-checking against the declared num_channels.

Methods

`check_errors`	Drain the vendor's error queue; raise `RuntimeError` if any error is pending.
`close`	Close the underlying transport.
`digitize`	Arm a single acquisition and block until the trigger fires and the capture completes.
`fetch_waveform`	Fetch the most recently acquired waveform from `channel`.
`force_trigger`	Force a trigger event immediately, regardless of the configured conditions.
`get_acquisition_mode`	Read back the current acquisition mode.
`get_acquisition_state`	Read back the acquisition run state (RUNNING / STOPPED).
`get_average_count`	Read back the waveforms-to-average count.
`get_coupling`	Read back input coupling on `channel`.
`get_horizontal_scale`	Read back the timebase (seconds/div).
`get_probe_attenuation`	Read back `channel`'s probe attenuation ratio.
`get_sample_rate`	Read back the current sample rate (samples per second).
`get_trigger_status`	Read back the trigger status (ARMED / READY / TRIGGERED / …).
`get_vertical_offset`	Read back `channel`'s vertical offset (volts).
`get_vertical_scale`	Read back `channel`'s vertical scale (V/div).
`load_settings`	Recall a scope setup from `name`.
`measure`	Read a built-in measurement (VPP, VMAX, VMIN, VAVG, VRMS, …) on `channel`.
`open`	Open the underlying transport.
`run`	Start continuous (free-running) acquisition.
`save_screenshot`	Capture a screenshot.
`save_settings`	Save the current scope setup.
`set_acquisition_mode`	Set the acquisition mode.
`set_average_count`	Set the number of waveforms to average.
`set_coupling`	Set AC/DC input coupling on `channel`.
`set_horizontal_scale`	Set the timebase to `seconds_per_div`.
`set_probe_attenuation`	Set `channel`'s probe attenuation ratio (e.g. 1, 10, 100, 1000).
`set_trigger_level`	Set the trigger threshold to `level` (volts).
`set_trigger_mode`	Set the trigger sweep mode (AUTO / NORMAL).
`set_trigger_slope`	Set the trigger edge slope (RISING / FALLING / EITHER).
`set_trigger_source`	Set the trigger source to analog `channel`.
`set_trigger_type`	Set the trigger type (EDGE, PULSE, …).
`set_vertical_offset`	Set `channel`'s vertical offset to `offset` (volts).
`set_vertical_scale`	Set `channel`'s vertical scale to `volts_per_div` (V/div).
`setup_measurement`	Ensure a measurement slot exists for `measurement_type`/`channel` before the scope triggers.
`single`	Arm a single-shot acquisition.
`stop`	Stop acquisition.

abstractmethod open() → None[source]#

Open the underlying transport. Idempotent.

Concrete drivers also perform any one-shot instrument setup here (e.g. *CLS, remote-mode handshake).

abstractmethod close() → None[source]#: Close the underlying transport. Idempotent.

abstractmethod check_errors() → None[source]#

Drain the vendor’s error queue; raise RuntimeError if any error is pending.

Used between setup commands and any blocking query — calling a data query while the scope’s error queue holds a syntax error would hang.

abstractmethod set_vertical_scale( volts_per_div: float, channel: int, ) → None[source]#

Set channel’s vertical scale to volts_per_div (V/div).

Drivers may snap to the nearest hardware-supported step. Callers that need the actual applied value should get_vertical_scale() afterward.

abstractmethod get_vertical_scale(channel: int) → float[source]#: Read back channel’s vertical scale (V/div).

abstractmethod set_vertical_offset(offset: float, channel: int) → None[source]#: Set channel’s vertical offset to offset (volts).

abstractmethod get_vertical_offset(channel: int) → float[source]#: Read back channel’s vertical offset (volts).

abstractmethod set_coupling( coupling: Coupling, channel: int, ) → None[source]#: Set AC/DC input coupling on channel.

abstractmethod get_coupling( channel: int, ) → Coupling[source]#: Read back input coupling on channel.

abstractmethod set_probe_attenuation( factor: float, channel: int, ) → None[source]#: Set channel’s probe attenuation ratio (e.g. 1, 10, 100, 1000).

abstractmethod get_probe_attenuation(channel: int) → float[source]#: Read back channel’s probe attenuation ratio.

abstractmethod set_horizontal_scale(seconds_per_div: float) → None[source]#: Set the timebase to seconds_per_div. Applies globally to all channels.

abstractmethod get_horizontal_scale() → float[source]#: Read back the timebase (seconds/div).

abstractmethod get_sample_rate() → float[source]#

Read back the current sample rate (samples per second).

This is the effective hardware rate the scope is acquiring at; it depends on the timebase, memory depth, and interpolation settings.

abstractmethod set_acquisition_mode( mode: AcquisitionMode, ) → None[source]#

Set the acquisition mode.

Drivers should raise NotImplementedError for AcquisitionMode values their scope doesn’t support (e.g. Keysight 1200X has no ENVELOPE mode).

abstractmethod get_acquisition_mode() → AcquisitionMode[source]#: Read back the current acquisition mode.

abstractmethod set_average_count(count: int) → None[source]#: Set the number of waveforms to average. Only takes effect in AcquisitionMode.AVERAGE.

abstractmethod get_average_count() → int[source]#: Read back the waveforms-to-average count.

abstractmethod run() → None[source]#: Start continuous (free-running) acquisition.

abstractmethod stop() → None[source]#: Stop acquisition. Leaves the captured data intact for fetch_waveform / measure.

abstractmethod single() → None[source]#

Arm a single-shot acquisition.

Non-blocking — use get_acquisition_state to poll for STOPPED, or prefer digitize() which combines arming and waiting.

abstractmethod digitize(timeout: float) → None[source]#

Arm a single acquisition and block until the trigger fires and the capture completes.

Acquisition is global — all enabled channels capture simultaneously. On success the scope is left stopped with valid data ready for readout.

Parameters:

timeout

Maximum seconds to wait for the trigger to fire.

Raises:

TimeoutError – Trigger did not fire within timeout. The driver clears any pending operation so the session stays usable.

abstractmethod get_acquisition_state() → AcquisitionState[source]#: Read back the acquisition run state (RUNNING / STOPPED).

abstractmethod fetch_waveform( channel: int, ) → WaveformData[source]#

Fetch the most recently acquired waveform from channel.

Returns:: WaveformData with times in nanoseconds relative to the trigger point (negative = pre-trigger) and voltages already scaled through the configured probe attenuation.

setup_measurement( measurement_type: ScopeMeasurementType, channel: int, ) → None[source]#

Ensure a measurement slot exists for measurement_type/channel before the scope triggers.

Required for instruments (e.g. Tektronix) that compute measurements during acquisition — the slot must be present at trigger time or the first measure() returns stale/invalid data. Default is a no-op for instruments (e.g. Keysight 1200X) that compute on demand.

abstractmethod measure( measurement_type: ScopeMeasurementType, channel: int, ) → float[source]#

Read a built-in measurement (VPP, VMAX, VMIN, VAVG, VRMS, …) on channel.

Returns math.nan when the scope reports its invalid-measurement sentinel (no valid acquisition yet, channel off, etc.).

abstractmethod set_trigger_source(channel: int) → None[source]#

Set the trigger source to analog channel.

Drivers typically cache this value because the trigger-level SCPI on some scopes requires the source channel in the same command.

abstractmethod set_trigger_type( trigger_type: TriggerType, ) → None[source]#: Set the trigger type (EDGE, PULSE, …).

abstractmethod set_trigger_level(level: float) → None[source]#: Set the trigger threshold to level (volts). Applies to the configured trigger source.

abstractmethod set_trigger_slope( slope: TriggerSlope, ) → None[source]#: Set the trigger edge slope (RISING / FALLING / EITHER).

abstractmethod set_trigger_mode( mode: TriggerMode, ) → None[source]#

Set the trigger sweep mode (AUTO / NORMAL).

AUTO forces an acquisition if no trigger fires within the timeout; NORMAL waits indefinitely for a real trigger.

abstractmethod force_trigger() → None[source]#: Force a trigger event immediately, regardless of the configured conditions.

abstractmethod get_trigger_status() → TriggerStatus[source]#: Read back the trigger status (ARMED / READY / TRIGGERED / …).

abstractmethod save_screenshot( filepath: str, to_instrument: bool = False, ) → bytes[source]#

Capture a screenshot.

Parameters:

filepath

Output path. When to_instrument=False this is a host path; when True it is a path on the scope’s filesystem (USB stick, internal storage).
to_instrument

When True, the scope writes the file itself and this returns b"". When False, the image is transferred to the host, written to filepath, and the raw bytes are returned for in-memory use.

abstractmethod save_settings( name: str, to_instrument: bool = False, ) → bytes[source]#: Save the current scope setup. Path semantics mirror save_screenshot().

abstractmethod load_settings( name: str, from_instrument: bool = False, ) → None[source]#

Recall a scope setup from name.

With from_instrument=True the scope reads from its own filesystem; otherwise the host reads name and pushes the bytes to the scope. After loading, the calling InstroScope should invalidate its tracked ScopeState and resync if a fresh view is needed.