Scope (Oscilloscope)¤
Errors raised by these methods are documented in Exceptions.
Interface¤
Bases: Instrument
Oscilloscope instrument. Tracks scope state locally; call sync_configuration() after open() to refresh.
Provide either config or driver/num_channels together, not both.
Parameters:
-
(name¤str | None, default:None) –Channel-name prefix for published data. Falls back to
config.device.namewhenconfigis given. -
(driver¤ScopeDriverBase | None, default:None) –Concrete scope driver; owns its own transport::
scope = InstroScope( "scope", driver=Keysight1200X("
"), num_channels=4, ) -
(num_channels¤int | None, default:None) –Analog-input channel count.
-
(publishers¤list[Publisher] | None, default:None) –Publishers that receive emitted Measurement/Command data. Combined with any publishers declared in
config. -
(config¤ScopeConfig | dict | Path | str | None, default:None) –A
ScopeConfig, a dict, or a path to a JSON config file. Itschannels,acquisition, andtriggerblocks are applied through the public setters onopen(); each channel'smeasurementsare registered as background daemon functions. -
(autostart¤bool, default:False) –When True, open the connection and start background polling. Requires
configwith at least onemeasurementsentry, since the daemon has nothing to poll otherwise. -
–**kwargs¤Default tags applied to every emitted Measurement/Command. Pass
dataset_rid="<rid>"to auto-create a NominalCorePublisher (uses the on-disk 'default' Nominal credential).
property
¤
Return an insertion-ordered snapshot of all published channel names.
Names are complete after one full daemon iteration: {name}.loop_time publishes every iteration, so call get_channel("loop_time", wait_for_new_samples=True) then read channel_names to ensure the complete set has arrived.
Raises:
-
RuntimeError–No background buffer;
start()was not called.
add_publisher(publisher: Publisher)
Register a publisher to receive this instrument's Measurement/Command data.
publish(data: Measurement | Command, **kwargs)
Fan data out to every configured publisher; kwargs pass through.
add_background_daemon_function(method: Callable, *args, **kwargs)
Append method to the daemon's call list. Use define_background_daemon to replace instead.
get_channel(
channel_name: str,
length: int = 1,
wait_for_new_samples: bool = False,
timeout: float = 10.0,
) -> Measurement
Return the most recent length samples for channel_name from the in-memory buffer.
If the channel does not exist yet, or no sample is available, the code will always block until timeout expires.
Parameters:
-
(channel_name¤str) –Name of the channel to retrieve.
-
(length¤int, default:1) –Number of trailing samples to return.
-
(wait_for_new_samples¤bool, default:False) –Block until at least
lengthnew values arrive. -
(timeout¤float, default:10.0) –Seconds to wait when insufficient data exists or
wait_for_new_samples=True.
Raises:
-
RuntimeError–No background buffer;
start()was not called. -
ChannelNotFoundError–channel had no values and no data appeared before
timeout.wait_for_new_samples=Trueand channel did not appear withintimeout. -
ChannelValueTimeoutError–wait_for_new_samples=Trueand values did not arrive withintimeout.
get_single_channel_value(channel_name: str) -> float | str | None
Return the most recent sample for channel_name from the in-memory buffer.
This will not wait, if data is not available then None is returned.
Parameters:
Raises:
-
RuntimeError–No background buffer;
start()was not called.
define_background_daemon(method: Callable, *args, **kwargs)
Replace all daemon functions with a single method (called with the given args).
sync_configuration() -> ScopeState
Bulk-query the instrument and overwrite the tracked ScopeState with live state.
Note that trigger source/type/level/slope/mode aren't bulk-queried — not all scopes expose every trigger field, so call the per-field getters where supported.
Set the vertical scale (V/div) on channel.
get_vertical_scale(channel: int, **kwargs) -> Measurement | None
Query the vertical scale (V/div) on channel.
Set the vertical offset (volts) on channel.
get_vertical_offset(channel: int, **kwargs) -> Measurement | None
Query the vertical offset (volts) on channel.
Set AC/DC input coupling on channel.
get_coupling(channel: int, **kwargs) -> Measurement
Query the input coupling mode on channel (published as a string).
Set the probe attenuation ratio (e.g. 1, 10, 100) on channel.
get_probe_attenuation(channel: int, **kwargs) -> Measurement | None
Query the probe attenuation ratio on channel.
Set the timebase (seconds/div).
get_horizontal_scale(**kwargs) -> Measurement | None
Query the timebase (seconds/div).
get_sample_rate(**kwargs) -> Measurement | None
Query the current sample rate (Sa/s).
set_acquisition_mode(mode: AcquisitionMode, **kwargs) -> Command
Set the acquisition mode (NORMAL/AVERAGE/HIRES/PEAK_DETECT/ENVELOPE).
get_acquisition_mode(**kwargs) -> Measurement
Query the current acquisition mode (published as a string).
Set the average count (waveforms averaged) used in AVERAGE acquisition mode.
stop_acquisition(**kwargs) -> Command
Stop acquisition; records the acquisition timestamp if one was armed.
get_acquisition_state(**kwargs) -> Measurement
Query RUNNING/STOPPED. If STOPPED while armed, records the acquisition timestamp.
fetch_waveform(
channel: int, timeout: float = 5.0, **kwargs
) -> Measurement
Fetch the acquired waveform from channel.
Timestamps are ns relative to the trigger point (negative = pre-trigger).
If an acquisition is armed, blocks up to timeout seconds for it to
complete; raises TimeoutError if it doesn't.
measure(
measurement_type: ScopeMeasurementType,
channel: int = 1,
timeout: float = 5.0,
**kwargs,
) -> Measurement | None
Take a built-in measurement on channel.
Timestamps default to the last recorded acquisition time (falls back to
time.time_ns() if none). If an acquisition is armed, blocks up to
timeout seconds for it to complete; raises TimeoutError if it doesn't.
Set the trigger source to channel.
set_trigger_type(trigger_type: TriggerType, **kwargs) -> Command
Set the trigger type (EDGE, PULSE, …).
Set the trigger level (volts).
set_trigger_slope(slope: TriggerSlope, **kwargs) -> Command
Set the trigger edge slope (RISING/FALLING/EITHER).
set_trigger_mode(mode: TriggerMode, **kwargs) -> Command
Set the trigger mode (AUTO/NORMAL).
get_trigger_status(**kwargs) -> Measurement
Query the trigger status (published as a string).
Capture a screenshot and save it. to_instrument=True writes to the scope's filesystem; otherwise to the host.
Save scope setup. to_instrument=True writes to the scope's filesystem; otherwise to the host.
Recall a scope setup. from_instrument=True reads from the scope's filesystem; otherwise from the host.
Invalidates the tracked ScopeState since instrument state changed externally;
call sync_configuration() to refresh.
Types & Configuration¤
Oscilloscope shared types: coupling, acquisition/trigger modes, waveform data, tracked state.
dataclass
¤
dataclass
¤
ChannelState(
vertical_scale: float | None = None,
vertical_offset: float | None = None,
coupling: Coupling | None = None,
probe_attenuation: float | None = None,
)
Tracked per-channel state. Fields start as None and populate on set/query.
dataclass
¤
TriggerState(
source: int | None = None,
type: TriggerType | None = None,
level: float | None = None,
slope: TriggerSlope | None = None,
mode: TriggerMode | None = None,
)
Tracked trigger state (source channel, type, level (V), slope, mode). Fields start as None.
dataclass
¤
ScopeState(
channels: dict[int, ChannelState] = dict(),
trigger: TriggerState = TriggerState(),
acquisition_mode: AcquisitionMode | None = None,
average_count: int | None = None,
horizontal_scale: float | None = None,
)
Tracked scope state: per-channel (1-based), trigger, acquisition mode, average count, timebase.
class-attribute
instance-attribute
¤
channels: dict[int, ChannelState] = field(default_factory=dict)
class-attribute
instance-attribute
¤
trigger: TriggerState = field(default_factory=TriggerState)
class-attribute
instance-attribute
¤
acquisition_mode: AcquisitionMode | None = None
Pydantic config models for JSON config-driven InstroScope construction.
module-attribute
¤
SCOPE_VENDOR_REGISTRY: dict[str, str] = {
"Keysight1200X": "instro.scope.drivers.keysight_1200x.Keysight1200X",
"SiglentSDS1000XE": "instro.scope.drivers.siglent_sds1000x_e.SiglentSDS1000XE",
"Tektronix2SeriesMSO": "instro.scope.drivers.tektronix_2series.Tektronix2SeriesMSO",
}
Bases: BaseModel
Publisher config for writing measurements to a local file.
Bases: BaseModel
Publisher config for streaming to a Nominal Core dataset.
class-attribute
instance-attribute
¤
type: Literal['NominalCorePublisher'] = 'NominalCorePublisher'
class-attribute
instance-attribute
¤
dataset_rid: str = Field(description="Target Nominal Core dataset RID.")
Bases: BaseModel
Device metadata. name is the channel-name prefix on publish (e.g. my_device.temperature).
Bases: BaseModel
Initial per-channel state and polled measurements, applied through the InstroScope setters on open().
class-attribute
instance-attribute
¤
vertical_scale: float | None = Field(
default=None, gt=0, description="Vertical scale in V/div."
)
class-attribute
instance-attribute
¤
vertical_offset: float | None = Field(
default=None, description="Vertical offset in volts."
)
class-attribute
instance-attribute
¤
coupling: Coupling | None = Field(
default=None, description="Input coupling, 'AC' or 'DC'."
)
class-attribute
instance-attribute
¤
probe_attenuation: float | None = Field(
default=None,
gt=0,
description="Probe attenuation ratio, e.g. 1, 10, 100.",
)
class-attribute
instance-attribute
¤
measurements: list[ScopeMeasurementType] = Field(
default_factory=list,
description="Built-in measurements to background-poll on this channel.",
)
Bases: BaseModel
Initial acquisition state, applied through the InstroScope setters on open().
class-attribute
instance-attribute
¤
mode: AcquisitionMode | None = Field(
default=None,
description="Acquisition mode, e.g. 'NORMAL' or 'AVERAGE'.",
)
class-attribute
instance-attribute
¤
average_count: int | None = Field(
default=None,
ge=2,
description="Waveforms to average; requires mode 'AVERAGE'.",
)
Bases: BaseModel
Initial trigger state, applied through the InstroScope setters on open().
class-attribute
instance-attribute
¤
source: int = Field(
ge=1,
description="1-based analog channel used as the trigger source.",
)
class-attribute
instance-attribute
¤
type: TriggerType | None = Field(
default=None, description="Trigger type, 'EDGE' or 'PULSE'."
)
class-attribute
instance-attribute
¤
level: float | None = Field(
default=None, description="Trigger level in volts."
)
class-attribute
instance-attribute
¤
slope: TriggerSlope | None = Field(
default=None,
description="Trigger slope, 'RISING', 'FALLING', or 'EITHER'.",
)
class-attribute
instance-attribute
¤
mode: TriggerMode | None = Field(
default=None, description="Trigger sweep mode, 'AUTO' or 'NORMAL'."
)
Driver Interface¤
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.
abstractmethod
¤
open() -> None
Open the underlying transport. Idempotent.
Concrete drivers also perform any one-shot instrument setup here
(e.g. *CLS, remote-mode handshake).
abstractmethod
¤
check_errors() -> None
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 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
¤
Read back channel's vertical scale (V/div).
abstractmethod
¤
Set channel's vertical offset to offset (volts).
abstractmethod
¤
Read back channel's vertical offset (volts).
abstractmethod
¤
Set AC/DC input coupling on channel.
abstractmethod
¤
Read back input coupling on channel.
abstractmethod
¤
Set channel's probe attenuation ratio (e.g. 1, 10, 100, 1000).
abstractmethod
¤
Read back channel's probe attenuation ratio.
abstractmethod
¤
set_horizontal_scale(seconds_per_div: float) -> None
Set the timebase to seconds_per_div. Applies globally to all channels.
abstractmethod
¤
get_horizontal_scale() -> float
Read back the timebase (seconds/div).
abstractmethod
¤
get_sample_rate() -> float
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
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
Read back the current acquisition mode.
abstractmethod
¤
set_average_count(count: int) -> None
Set the number of waveforms to average. Only takes effect in AcquisitionMode.AVERAGE.
abstractmethod
¤
get_average_count() -> int
Read back the waveforms-to-average count.
abstractmethod
¤
stop() -> None
Stop acquisition. Leaves the captured data intact for fetch_waveform / measure.
abstractmethod
¤
single() -> None
Arm a single-shot acquisition.
Non-blocking — use get_acquisition_state to poll for STOPPED, or
prefer digitize() which combines arming and waiting.
abstractmethod
¤
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:
Raises:
-
TimeoutError–Trigger did not fire within
timeout. The driver clears any pending operation so the session stays usable.
abstractmethod
¤
get_acquisition_state() -> AcquisitionState
Read back the acquisition run state (RUNNING / STOPPED).
abstractmethod
¤
fetch_waveform(channel: int) -> WaveformData
Fetch the most recently acquired waveform from channel.
Returns:
-
WaveformData–WaveformDatawithtimesin nanoseconds relative to the -
WaveformData–trigger point (negative = pre-trigger) and
voltagesalready -
WaveformData–scaled through the configured probe attenuation.
setup_measurement(
measurement_type: ScopeMeasurementType, channel: int
) -> None
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
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
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
Set the trigger type (EDGE, PULSE, …).
abstractmethod
¤
set_trigger_level(level: float) -> None
Set the trigger threshold to level (volts). Applies to the configured trigger source.
abstractmethod
¤
set_trigger_slope(slope: TriggerSlope) -> None
Set the trigger edge slope (RISING / FALLING / EITHER).
abstractmethod
¤
set_trigger_mode(mode: TriggerMode) -> None
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
Force a trigger event immediately, regardless of the configured conditions.
abstractmethod
¤
get_trigger_status() -> TriggerStatus
Read back the trigger status (ARMED / READY / TRIGGERED / …).
abstractmethod
¤
save_screenshot(filepath: str, to_instrument: bool = False) -> bytes
Capture a screenshot.
Parameters:
-
(filepath¤str) –Output path. When
to_instrument=Falsethis is a host path; whenTrueit is a path on the scope's filesystem (USB stick, internal storage). -
(to_instrument¤bool, default:False) –When
True, the scope writes the file itself and this returnsb"". WhenFalse, the image is transferred to the host, written tofilepath, and the raw bytes are returned for in-memory use.
abstractmethod
¤
Save the current scope setup. Path semantics mirror :meth:save_screenshot.
abstractmethod
¤
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.
Vendor Drivers¤
Keysight 1200X¤
Keysight InfiniiVision 1200 X-Series oscilloscope driver (EDUX1052G and family).
Keysight1200X(visa_resource: str | VisaConfig)
Bases: ScopeDriverBase
SCPI driver for Keysight InfiniiVision 1200 X-Series oscilloscopes.
check_errors() -> None
Query :SYSTem:ERRor? once and raise on a non-zero code. Does not drain the queue.
digitize(timeout: float) -> None
:DIGitize the cached trigger source, then *OPC? under a scoped VISA timeout.
On timeout, clear() aborts the pending op and restores the session.
get_acquisition_state() -> AcquisitionState
:OPERegister:CONDition? bit 3 (0x08) — set = RUNNING, clear = STOPPED.
fetch_waveform(channel: int) -> WaveformData
Fetch the waveform from channel over WORD (unsigned 16-bit, LSB-first), 1000 points.
measure(measurement_type: ScopeMeasurementType, channel: int) -> float
Install then query a built-in measurement on channel.
The install form runs first as a guard — bad command syntax surfaces
via check_errors() before we'd block on the query. The vendor's
invalid-measurement sentinel maps to NaN.
get_trigger_status() -> TriggerStatus
:OPERegister:CONDition? bits: 0x20 = ARMED, 0x08 = AUTO (running), else TRIGGERED.
:SAVE:IMAGe to the scope, or :DISPlay:DATA? PNG,COLor and write locally.
:SAVE:SETup to scope memory or to the host (:SYSTem:SETup?).
:RECall:SETup from scope memory, or send local bytes via :SYSTem:SETup.
setup_measurement(
measurement_type: ScopeMeasurementType, channel: int
) -> None
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.
Siglent SDS1000X-E¤
Siglent SDS1000X-E series oscilloscope driver (SDS1104X-E and family).
SiglentSDS1000XE(visa_resource: str | VisaConfig)
Bases: ScopeDriverBase
SCPI driver for Siglent SDS1000X-E series oscilloscopes (SDS1104X-E and family).
check_errors() -> None
Poll CMR? then EXR? and raise on the first non-zero code (no error queue on Siglent).
digitize(timeout: float) -> None
Arm a single acquisition then poll INR? bit 0 (new signal acquired) until set or timeout.
fetch_waveform(channel: int) -> WaveformData
Fetch the full waveform from channel over C{n}:WF? DAT2 (signed 8-bit codes).
measure(measurement_type: ScopeMeasurementType, channel: int) -> float
Query a built-in parameter via C{n}:PAVA?; unavailable/sentinel results map to NaN.
Transfer a screen dump (SCDP, a raw BMP) to the host and write it to filepath.
Save the panel setup to a USB file (STPN) or transfer it to the host (PNSU?).
Recall a panel setup from a USB file (RCPN) or push host bytes back (PNSU).
The host-side PNSU write-back is known to wedge the USBTMC interface on some
SDS1000X-E firmware; prefer from_instrument=True (USB stick) over USB connections.
setup_measurement(
measurement_type: ScopeMeasurementType, channel: int
) -> None
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.
Tektronix 2 Series MSO¤
Tektronix 2 Series MSO oscilloscope driver (MSO22, MSO24).
Tektronix2SeriesMSO(visa_resource: str | VisaConfig)
Bases: ScopeDriverBase
SCPI driver for Tektronix 2 Series MSO oscilloscopes (MSO22, MSO24).
digitize(timeout: float) -> None
SEQuence+RUN, then *OPC? under a scoped VISA timeout. clear() on timeout to restore the session.
fetch_waveform(channel: int) -> WaveformData
Fetch the waveform from channel over RIBinary (signed 16-bit).
setup_measurement(
measurement_type: ScopeMeasurementType, channel: int
) -> None
Ensure a persistent measurement slot exists for this type and channel.
Uses MEASUrement:ADDMEAS <type> to create the slot atomically with
the target type — this avoids the race where ADDNew "MEAS<n>" +
MEAS<n>:TYPe creates a slot that briefly computes under the scope's
default type (typically Period) before the type change takes effect,
causing the first measure() call to return a stale, wrong-type
value. ADDMEAS doesn't take a name; the new slot's name (the scope
auto-assigns the next MEAS<n>) is recovered by diffing
MEASUrement:LIST? before and after the add.
Tektronix computes measurements during acquisition, so the slot must exist before the scope triggers for results to be valid.
clear_measurements() -> None
Delete every measurement slot on the scope and reset the local cache.
measure(measurement_type: ScopeMeasurementType, channel: int) -> float
Read a built-in measurement from a persistent slot; the vendor's invalid sentinel maps to NaN.