4.1. The class ds1054z.DS1054Z - Easy communication with your scope

class ds1054z.DS1054Z(host, *args, **kwargs)

Bases: vxi11.vxi11.Instrument

This class represents the oscilloscope.

Variables:
  • product – like 'DS1054Z' (depending on your device)
  • vendor – should be 'RIGOL TECHNOLOGIES'
  • serial – e.g. 'DS1ZA118171631'
  • firmware – e.g. '00.04.03.SP1'
static decode_ieee_block(ieee_bytes)

Strips headers (and trailing bytes) from a IEEE binary data block off.

This is the block format commands like :WAVeform:DATA?, :DISPlay:DATA?, :SYSTem:SETup?, and :ETABle<n>:DATA? return their data in.

Named after decode_ieee_block() in python-ivi

display_channel(channel, enable=True)

Display (enable) or hide (disable) a channel for aquisition and display

display_only_channel(channel)

Convenience function to display (enable) a single channel and hide (disable) all others.

static format_si_prefix(number, unit=None, as_unicode=True, number_format='{0:.6f}')

Formats the given number by choosing an appropriate metric prefix and stripping the formatted number of its zero-digits giving a nice human readable form.

If you provide a unit, it will be appended to the resulting string.

Example:

>>> DS1054Z.format_si_prefix(2E-9, unit='s')
'2 ns'
get_channel_measurement(channel, item, type='CURRent')

Measures value on a channel

Parameters:
  • channel (int or str) – The channel name (like CHAN1, ...). Alternatively specify the channel by its number (as integer).
  • item (str) – Item to measure, can be vmax, vmin, vpp, vtop, vbase, vamp, vavg, vrms, overshoot, preshoot, marea, mparea, period, frequency, rtime, ftime, pwidth, nwidth, pduty, nduty, rdelay, fdelay, rphase, fphase, tvmax, tvmin, pslewrate, nslewrate, vupper, vmid, vlower, variance, pvrms
  • type (str) – Type of measurement, can be CURRent, MAXimum, MINimum, AVERages, DEViation
get_channel_offset(channel)

Returns the channel offset in volts.

get_channel_scale(channel)

Returns the channel scale in volts.

Returns:channel scale
Return type:float
get_probe_ratio(channel)

Returns the probe ratio for a specific channel

get_waveform_bytes(channel, mode='NORMal')

Get the waveform data for a specific channel as bytes. (In most cases you would want to use the higher level function get_waveform_samples() instead.)

This function distinguishes between requests for reading the waveform data currently being displayed on the screen or if you will be reading the internal memory. If you set mode to RAW, the scope will be stopped first and you will get the bytes from internal memory. (Please start it again yourself, if you need to, afterwards.) If you set the mode to MAXimum this function will return the internal memory if the scope is stopped, and the screen memory otherwise.

In case the internal memory will be read, the data request will automatically be split into chunks if it’s impossible to read all bytes at once.

Parameters:
  • channel (int or str) – The channel name (like CHAN1, ...). Alternatively specify the channel by its number (as integer).
  • mode (str) – can be NORMal, MAXimum, or RAW
Returns:

The waveform data
Return type:

bytes
get_waveform_samples(channel, mode='NORMal')

Returns the waveform voltage samples of the specified channel.

The mode argument translates into a call to :WAVeform:MODE setting up how many samples you want to read back. If you set it to normal mode, only the screen content samples will be returned. In raw mode, the whole scope memory will be read out, which can take many seconds depending on the current memory depth.

If you set mode to RAW, the scope will be stopped first. Please start it again yourself, if you need to, afterwards.

If you set mode to NORMal you will always get 1200 samples back. Those 1200 points represent the waveform over the full screen width. This can happend when you stop the acquisition and move the waveform horizontally so that it starts or ends inside the screen area, the missing data points are being set to float(‘nan’) in the list.

Parameters:
  • channel (int or str) – The channel name (like ‘CHAN1’ or 1).
  • mode (str) – can be ‘NORMal’, ‘MAX’, or ‘RAW’
Returns:

voltage samples
Return type:

list of float values
query(message, *args, **kwargs)

Write a message to the scope and read back the answer. See vxi11.Instrument.ask() for optional parameters.

query_raw(message, *args, **kwargs)

Write a message to the scope and read a (binary) answer.

This is the slightly modified version of vxi11.Instrument.ask_raw(). It takes a command message string and returns the answer as bytes.

Parameters:message (str) – The SCPI command to send to the scope.
Returns:Data read from the device
Return type:bytes
run()

Start acquisition

set_channel_offset(channel, volts)

Set the (vertical) offset of a specific channel in Volt.

The range of possible offset values depends on the current vertical scale and on the probe ratio. With the probe ratio set to 1x the offset can be set between:

  • -100V and +100V (if vertical scale ≥ 500mV/div), or
  • -2V and +2V (if vertical scale < 500mV/div).

The range scales with the probe ratio. Thus, when the probe ratio is set to 10x, for example, the offset could be set between:

  • -1000V and +1000V (if vertical scale ≥ 5V/div), or
  • -20V and +20V (if vertical scale < 5V/div).
Parameters:
  • channel (int or str) – The channel name (like CHAN1, ...). Alternatively specify the channel by its number (as integer).
  • volts (float) – the new vertical scale offset in volts
set_channel_scale(channel, volts, use_closest_match=False)

The default steps according to the programming guide:

  • 1mV, 2mV, 5mV, 10mV...10V (for a 1x probe),
  • 10mV, 20mV, 50mV, 100mV...100V (for a 10x probe).

You can also set the scale to values in between those steps (as with using the fine adjustment mode on the scope).

Parameters:
  • channel (int or str) – The channel name (like CHAN1, ...). Alternatively specify the channel by its number (as integer).
  • volts (float) – the new value for the vertical channel scaling
  • use_closest_match (bool) – round new scale value to closest match from the default steps
set_probe_ratio(channel, ratio)

Set the probe ratio of a specific channel.

The possible ratio values are: 0.01, 0.02, 0.05, 0.1, 0.2, 0.5, 1, 2, 5, 10, 20, 50, 100, 200, 500, and 1000.

Parameters:
  • channel (int or str) – The channel name (like CHAN1, ...). Alternatively specify the channel by its number (as integer).
  • ratio (float) – Ratio of the probe connected to the channel
set_waveform_mode(mode='NORMal')

Changing the waveform mode

single()

Set the oscilloscope to the single trigger mode.

stop()

Stop acquisition

tforce()

Generate a trigger signal forcefully.

display_data

The bitmap bytes of the current screen content. This property will be updated every time you access it.

displayed_channels

The list of channels currently displayed on the scope. This property will be updated every time you access it.

idn

The *IDN? string of the device. Will be fetched every time you access this property.

memory_depth

This maps to the aquisition memory depth the scope is currently set to. In contrast to memory_depth_curr_waveform, memory_depth_internal_currently_shown and memory_depth_internal_total, this property is simply a quite direct access to the :ACQuire:MDEPth command of the oscilloscope.

You can change the memory_depth like this:

>>> scope.memory_depth = 12e6

This will set the memory depth to 12M data points. Please note that changing the memory_depth is only possible when the oscilloscope is running. Otherwise, setting this property will raise an exception. In addition, not all values are valid in all cases. This depends on the number of channels currently in use (including the trigger!). Please read the property back after setting it, to check that your desired value was actually acknowledged by the oscilloscope.

When requesting this property, an integer value is returned or the string ‘AUTO’.

This value of this property will be updated every time you access it.

memory_depth_curr_waveform

The current memory depth of the oscilloscope. This value is the number of samples to expect when reading the waveform data and depends on the status of the scope (running / stopped).

Needed by waveform_time_values.

This property will be updated every time you access it.

memory_depth_internal_currently_shown

The number of samples in the raw (=deep) memory of the oscilloscope which are currently being displayed on the screen.

This property will be updated every time you access it.

memory_depth_internal_total

The total number of samples in the raw (=deep) memory of the oscilloscope. If it’s running, the scope will be stopped temporarily when accessing this value.

This property will be updated every time you access it.

timebase_offset

The timebase offset of the scope in seconds.

You can change the timebase offset by assigning to this property:

>>> scope.timebase_offset = 200e-6

The possible values according to the programming manual:

  • -Screen/2 to 1s or -Screen/2 to 5000s.
timebase_scale

The timebase scale of the scope in seconds.

The possible values according to the programming guide:

  • Normal mode: 5 ns to 50 s in 1-2-5 steps
  • Roll mode: 200 ms to 50 s in 1-2-5 steps

You can change the timebase like this:

>>> scope.timebase_scale = 200E-9

The nearest possible value will be set.

waveform_preamble

Provides the values returned by the command :WAVeform:PREamble?. They will be converted to float and int as appropriate.

Those values are essential if you want to convert BYTE data from the scope to voltage readings or if you want to recreate the scope’s display content programmatically.

This property is also accessible via the wrapper property waveform_preamble_dict where it returns a dict instead of a tuple.

This property will be fetched from the scope every time you access it.

Returns:(fmt, typ, pnts, cnt, xinc, xorig, xref, yinc, yorig, yref)
Return type:tuple of float and int values
waveform_preamble_dict

Provides a dictionary with 10 entries corresponding to the tuple items of the property waveform_preamble.

This property will be fetched from the scope every time you access it.

Returns:{‘fmt’, ‘typ’, ‘pnts’, ‘cnt’, ‘xinc’, ‘xorig’, ‘xref’, ‘yinc’, ‘yorig’, ‘yref’}
Return type:dict
waveform_time_values

The timestamps that belong to the waveform samples accessed to to be accessed beforehand.

Access this property only after fetching your waveform data, otherwise the values will not be correct.

Will be fetched every time you access this property.

Returns:sample timestamps (in seconds)
Return type:list of float
waveform_time_values_decimal

This is a wrapper for waveform_time_values. It returns the time samples as Decimal values instead of float which can be convenient for writing with an appropriate precision to a human readable file format.

Access this property only after fetching your waveform data, otherwise the values will not be correct.

Will be fetched every time you access this property.

Returns:sample timestamps (in seconds)
Return type:list of Decimal