Arbitrary Waveform Generator (AWG)¤
This category ships in the instro-unstable package (instro[unstable]); its API is not settled and may change without notice.
Errors raised by these methods are documented in Exceptions.
Interface¤
Bases: Instrument
AWG instrument. Methods return Measurement/Command for publishing.
property
writable
¤
background_interval
Seconds between background daemon iterations (0 = no wait).
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 | 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).
start() -> None
Start the background daemon; raises unless set_waveform was called for at least one channel.
Program channel with the waveform definition; numeric shape parameters publish as companion channels.
Read back the current waveform definition on channel.
set_amplitude(
channel: int,
amplitude: float,
unit: AmplitudeMeasurementUnit,
**kwargs,
) -> Command
Set the output amplitude on channel; the unit ships as a unit tag.
get_amplitude(channel: int) -> tuple[float, AmplitudeMeasurementUnit]
Read back the current amplitude and its measurement unit on channel.
convert_amplitude(
channel: int,
amplitude: float,
from_unit: AmplitudeMeasurementUnit,
to_unit: AmplitudeMeasurementUnit,
impedance_ohms: float | None = None,
) -> float
Convert an amplitude value between units using channel's configured waveform.
DBM conversions need a load impedance; if impedance_ohms isn't given, channel's
output load is used instead. Raises ValueError if neither is available.
Set the DC offset (volts) on channel.
Enable or disable the output on channel.
Set the output load impedance; None means high-Z.
get_offset(channel: int, **kwargs) -> Measurement | None
Read back the DC offset (volts) on channel.
get_output_state(channel: int, **kwargs) -> Measurement | None
Read back whether the output is enabled on channel.
get_output_load(channel: int, **kwargs) -> Measurement | None
Read back the output load impedance on channel; high-Z is published as float('inf').
Types & Configuration¤
AWG shared types and waveform definitions.
module-attribute
¤
dataclass
¤
dataclass
¤
dataclass
¤
dataclass
¤
dataclass
¤
dataclass
¤
convert_amplitude(
value: float,
from_unit: AmplitudeMeasurementUnit,
to_unit: AmplitudeMeasurementUnit,
waveform: Waveform,
impedance_ohms: float | None = None,
) -> float
Convert an amplitude value between measurement units for a waveform shape.
VPP/VP/VRMS conversions depend on the waveform's crest factor, which is universal
math shared across every driver. DBM additionally requires impedance_ohms (the
load the instrument drives), since power depends on it.
Driver Interface¤
Bases: ABC
Vendor AWG driver contract. Concrete drivers own their transport and lifecycle.
abstractmethod
¤
check_errors() -> None
Drain the instrument error queue; raise if any error is pending.
abstractmethod
¤
Program channel with the waveform definition; raise ValueError if the definition is unsupported.
abstractmethod
¤
Get the current waveform on channel; drivers may return the last-programmed definition if not readable.
abstractmethod
¤
set_amplitude(
channel: int, amplitude: float, unit: AmplitudeMeasurementUnit
) -> None
Set the output amplitude on channel.
abstractmethod
¤
get_amplitude(channel: int) -> tuple[float, AmplitudeMeasurementUnit]
Get the current output amplitude and voltage unit on channel.
abstractmethod
¤
Set the DC offset (volts) on channel.
abstractmethod
¤
Enable or disable the output on channel.
abstractmethod
¤
Return True if the output on channel is enabled.
Set the output load impedance; None means high-Z.
Get the output load impedance; None means high-Z.
Vendor Drivers¤
Rigol DG1022Z¤
Rigol DG1022Z arbitrary waveform generator driver (DG1000Z series).
RigolDG1022Z(visa_resource: str | VisaConfig)
Bases: AWGDriverBase
SCPI driver for the Rigol DG1022Z two-channel arbitrary waveform generator.
check_errors() -> None
Query :SYSTem:ERRor? once and raise on a non-zero code. Does not drain the queue.
set_amplitude(
channel: int, amplitude: float, unit: AmplitudeMeasurementUnit
) -> None