Oscilloscope Instrument

The Oscilloscope instrument provides time-domain views of voltages. It contains a built-in Waveform Generator that can control the Moku:Lab analog outputs as well.

In normal operation, the Oscilloscope shows the signal present on the two analog inputs but it can be set to loop back the signals being generated (see set_source). This loopback takes up a channel (only two signals in total may be viewed at once). Data is provided at the framerate in the form of VoltsData objects. These objects contain the channel data and the required metadata to interpret them.

If you wish to log or network stream time-series voltage data at low rate, the Datalogger instrument provides this facility.

Example Usage

For an in-depth walkthrough on using the pymoku Oscilloscope Instrument, see the pymoku Oscilloscope tutorial. The following example code and a wide range of other pymoku demo scripts can be found at the pymoku Github repository.

oscilloscope_basic.py
#
# pymoku example: Basic Oscilloscope
#
# This script demonstrates how to use the Oscilloscope instrument
# to retrieve a single frame of dual-channel voltage data.
#
# (c) 2019 Liquid Instruments Pty. Ltd.
#
from pymoku import Moku
from pymoku.instruments import Oscilloscope

# Connect to your Moku by its device name
# Alternatively, use Moku.get_by_serial('#####') or Moku('192.168.###.###')
m = Moku.get_by_name('Moku')

try:
	i = m.deploy_or_connect(Oscilloscope)

	# Span from -1s to 1s i.e. trigger point centred
	i.set_timebase(-1, 1)

	# Get and print a single frame worth of data (time series
	# of voltage per channel)
	data = i.get_data(timeout=10)
	print(data.ch1, data.ch2, data.time)

finally:
	m.close()

The VoltsData Class

class pymoku.instruments.VoltsData(instrument, scales)

Object representing a frame of dual-channel data in units of Volts, and time in units of seconds. This is the native output format of the Oscilloscope instrument. The waveformid property enables identification of uniqueness of a frame of data, as it is possible to retrieve the same data more than once (i.e. if the instrument has been paused).

This object should not be instantiated directly, but will be returned by a call to get_data or get_realtime_data on the associated Oscilloscope instrument.

ch1 = [CH1_DATA]
ch2 = [CH2_DATA]
time = [TIME]
waveformid = n

The Oscilloscope Class

class pymoku.instruments.Oscilloscope

Oscilloscope instrument object.

To run a new Oscilloscope instrument, this should be instantiated and deployed via a connected Moku object using deploy_instrument. Alternatively, a pre-configured instrument object can be obtained by discovering an already running Oscilloscope instrument on a Moku:Lab device via discover_instrument.

__init__()

Create a new WaveformGenerator instance, ready to be attached to a Moku.

framerate = 10

Frame Rate, range 10 - 30.

type = "oscilloscope"

Name of this instrument.

commit()

Apply all modified settings.

Note

If the autocommit feature has been turned off, this function can be used to manually apply any instrument settings to the Moku device. These instrument settings are those configured by calling all set_ and gen_ type functions. Manually calling this function allows you to atomically apply many instrument settings at once.

gen_off(*args, **kwargs)

Turn Waveform Generator output(s) off.

The channel will be turned on when configuring the waveform type but can be turned off using this function. If ch is None (the default), both channels will be turned off, otherwise just the one specified by the argument.

Parameters:ch (int; {1,2} or None) – Channel to turn off, or both.
gen_rampwave(*args, **kwargs)

Generate a Ramp with the given parameters on the given channel.

This is a wrapper around the Square Wave generator, using the riserate and fallrate parameters to form the ramp.

Parameters:
  • ch (int; {1,2}) – Channel on which to generate the wave
  • amplitude (float, [0, 2.0] volts) – Waveform peak-to-peak amplitude
  • frequency (float, [0, 100e6] hertz) – Frequency of the wave
  • offset (float, [-1.0, 1.0] volts) – DC offset applied to the waveform
  • symmetry (float, [0, 1.0]) – Fraction of the cycle rising.
  • phase (float, degrees [0, 360]) – Phase offset of the wave
gen_sinewave(*args, **kwargs)

Generate a Sine Wave with the given parameters on the given channel.

Parameters:
  • ch (int; {1,2}) – Channel on which to generate the wave
  • amplitude (float, [0.0,2.0] Vpp) – Waveform peak-to-peak amplitude
  • frequency (float, [0,250e6] Hz) – Frequency of the wave
  • offset (float, [-1.0,1.0] Volts) – DC offset applied to the waveform
  • phase (float, [0-360] degrees) – Phase offset of the wave
gen_squarewave(*args, **kwargs)

Generate a Square Wave with given parameters on the given channel.

Parameters:
  • ch (int; {1,2}) – Channel on which to generate the wave
  • amplitude (float, [0, 2.0] volts) – Waveform peak-to-peak amplitude
  • frequency (float, [0, 100e6] hertz) – Frequency of the wave
  • offset (float, [-1.0, 1.0] volts) – DC offset applied to the waveform
  • duty (float, [0, 1.0]) – Fractional duty cycle
  • risetime (float, [0, 1.0]) – Fraction of a cycle taken for the waveform to rise
  • falltime (float [0, 1.0]) – Fraction of a cycle taken for the waveform to fall
  • phase (float, degrees 0-360) – Phase offset of the wave
get_data(timeout=None, wait=True)

Get full-resolution data from the instrument.

This will pause the instrument and download the entire contents of the instrument’s internal memory. This may include slightly more data than the instrument is set up to record due to rounding of some parameters in the instrument.

All settings must be committed before you call this function. If pymoku.autocommit=True (the default) then this will always be true, otherwise you will need to have called commit first.

The download process may take a second or so to complete. If you require high rate data, e.g. for rendering a plot, see get_realtime_data.

If the wait parameter is true (the default), this function will wait for any new settings to be applied before returning. That is, if you have set a new timebase (for example), calling this with wait=True will guarantee that the data returned has this new timebase.

Note that if instrument configuration is changed, a trigger event must occur before data captured with that configuration set can become available. This can take an arbitrary amount of time. For this reason the timeout should be set appropriately.

Parameters:
  • timeout (float) – Maximum time to wait for new data, or None for indefinite.
  • wait (bool) – If true (default), waits for a new waveform to be captured with the most recently-applied settings, otherwise just return the most recently captured valid data.
Returns:

InstrumentData subclass, specific to the instrument.
get_frontend(channel)

Get the analog frontend configuration.

Parameters:channel (int; {1,2}) – Channel for which the relay settings are being retrieved
Returns:Array of bool with the front end configuration of channels - [0] 50 Ohm - [1] 10xAttenuation - [2] AC Coupling
get_realtime_data(timeout=None, wait=True)

Get downsampled data from the instrument with low latency.

Returns a new InstrumentData subclass (instrument-specific), containing a version of the data that may have been downsampled from the original in order to be transferred quickly.

This function always returns a new object at framerate (10Hz by default), whether or not there is new data in that object. This can be verified by checking the return object’s waveformid parameter, which increments each time a new waveform is captured internally.

The downsampled, low-latency nature of this data makes it particularly suitable for plotting in real time. If you require high-accuracy, high-resolution data for analysis, see get_data.

If the wait parameter is true (the default), this function will wait for any new settings to be applied before returning. That is, if you have set a new timebase (for example), calling this with wait=True will guarantee that the data returned has this new timebase.

Note that if instrument configuration is changed, a trigger event must occur before data captured with that configuration set can become available. This can take an arbitrary amount of time. For this reason the timeout should be set appropriately.

Parameters:
  • timeout (float) – Maximum time to wait for new data, or None for indefinite.
  • wait (bool) – If true (default), waits for a new waveform to be captured with the most recently-applied settings, otherwise just return the most recently captured valid data.
Returns:

InstrumentData subclass, specific to the instrument.
get_samplerate()
Returns:The current instrument sample rate (Hz)
set_defaults(*args, **kwargs)

Reset the Oscilloscope to sane defaults.

set_framerate(*args, **kwargs)

Set framerate

set_frontend(channel, fiftyr=True, atten=False, ac=False)

Configures gain, coupling and termination for each channel.

Parameters:
  • channel (int; {1,2}) – Channel to which the settings should be applied
  • fiftyr (bool) – 50Ohm termination; default is 1MOhm.
  • atten (bool) – Turn on 10x attenuation. Changes the dynamic range between 1Vpp and 10Vpp.
  • ac (bool) – AC-couple; default DC.
set_precision_mode(*args, **kwargs)

Change aquisition mode between downsampling and decimation. Precision mode, a.k.a Decimation, samples at full rate and applies a low-pass filter to the data. This improves precision. Normal mode works by direct downsampling, throwing away points it doesn’t need.

Parameters:state (bool) – Select Precision Mode
set_samplerate(*args, **kwargs)

Manually set the sample rate of the instrument.

The sample rate is automatically calculated and set in set_timebase.

This interface allows you to specify the rate at which data is sampled, and set a trigger offset in number of samples. This interface is useful for datalogging and capturing of data frames.

Parameters:
  • samplerate (float; 0 < samplerate <= MAX_SAMPLERATE smp/s) – Target samples per second. Will get rounded to the nearest allowable unit.
  • trigger_offset (int; -2^16 < trigger_offset < 2^31) – Number of samples before (-) or after (+) the trigger point to start capturing.
Raises:

ValueOutOfRangeException – if either parameter is out of range.
set_source(*args, **kwargs)

Sets the source of the channel data to either the analog input or internally looped-back digital output.

This feature allows the user to preview the Waveform Generator outputs.

Parameters:
  • ch (int; {1,2}) – Channel Number
  • source (string, {'in1','in2','out1','out2','ext'}) – Where the specified channel should source data from (either the input or internally looped back output)
  • lmode (string, {'clip','round'}) – DAC Loopback mode (ignored ‘in’ sources)
set_timebase(*args, **kwargs)

Set the left- and right-hand span for the time axis. Units are seconds relative to the trigger point.

Parameters:
  • t1 (float) – Time, in seconds, from the trigger point to the left of screen. This may be negative (trigger on-screen) or positive (trigger off the left of screen).
  • t2 (float) – As t1 but to the right of screen.
Raises:

InvalidConfigurationException – if the timebase is backwards or zero.
set_trigger(*args, **kwargs)

Sets trigger source and parameters.

Parameters:
  • source (string, {'in1','in2','out1','out2','ext'}) – Trigger Source. May be either an input or output channel, or external. The output options allow triggering off an internally-generated waveform. External refers to the back-panel connector of the same name, allowing triggering from an externally-generated digital [LV]TTL or CMOS signal.
  • edge (string, {'rising','falling','both'}) – Which edge to trigger on. In Pulse Width modes this specifies whether the pulse is positive (rising) or negative (falling), with the ‘both’ option being invalid.
  • level (float, [-10.0, 10.0] volts) – Trigger level
  • minwidth (float, seconds) – Minimum Pulse Width. 0 <= minwidth < (2^32/samplerate). Can’t be used with maxwidth.
  • maxwidth (float, seconds) – Maximum Pulse Width. 0 <= maxwidth < (2^32/samplerate). Can’t be used with minwidth.
  • hysteresis (float, [100e-6, 1.0] volts) – Hysteresis around trigger point.
  • hf_reject (bool) – Enable high-frequency noise rejection
  • mode (string, {'auto', 'normal'}) – Trigger mode.

Note

Traditional Oscilloscopes have a “Single Trigger” mode that captures an event then pauses the instrument. In pymoku, there is no need to pause the instrument as you can simply choose to continue using the last captured frame. That is, set trigger mode='normal' then retrieve a single frame using get_data or get_realtime_data with wait=True.

set_xmode(*args, **kwargs)

Set rendering mode for the horizontal axis.

Parameters:xmode (string, {'roll','sweep','fullframe'}) – Respectively; Roll Mode (scrolling), Sweep Mode (normal oscilloscope trace sweeping across the screen) or Full Frame (like sweep, but waits for the frame to be completed).
sync_phase(*args, **kwargs)

Synchronize the phase of both output channels.

The phase of both channels is reset to their respestive phase offset values.