Instrument communication: The Oscilloscope class

Class API

class keyoscacquire.oscacq.Oscilloscope(address='USB0::1234::1234::MY1234567::INSTR', timeout=15000, verbose=True)[source]

PyVISA communication with the oscilloscope.

Creator opens a connection to an instrument and chooses settings for the connection.

Parameters

  • address (str, default _visa_address) – Visa address of instrument. To find the visa addresses of the instruments connected to the computer run list_visa_devices in the command line. Example address 'USB0::1234::1234::MY1234567::INSTR'

  • timeout (int, default _timeout) – Milliseconds before timeout on the channel to the instrument

  • verbose (bool, default True) – If True: prints when the connection to the device is opened etc, and sets attr:acquire_print to True

Raises

pyvisa.errors.Error – if no successful connection is made.

inst

The oscilloscope PyVISA resource

Type

pyvisa.resources.Resource

id

The maker, model, serial and firmware version of the scope. Examples:

'AGILENT TECHNOLOGIES,DSO-X 2024A,MY1234567,12.34.567891234'
'KEYSIGHT TECHNOLOGIES,MSO9104A,MY12345678,06.30.00609'
Type

str

model

The instrument model name

Type

str

model_series

The model series, e.g. ‘2000’ for a DSO-X 2024A. See interpret_visa_id().

Type

str

address

Visa address of instrument

Type

str

timeout

Milliseconds before timeout on the channel to the instrument

Type

int

acq_type

Acquisition mode of the oscilloscope. <m> will be used as num_averages if supplied.

  • 'NORMal' — sets the oscilloscope in the normal mode.

  • 'AVERage' — sets the oscilloscope in the averaging mode. You can set the count by num_averages.

  • 'HRESolution' — sets the oscilloscope in the high-resolution mode (also known as smoothing). This mode is used to reduce noise at slower sweep speeds where the digitizer samples faster than needed to fill memory for the displayed time range.

    For example, if the digitizer samples at 200 MSa/s, but the effective sample rate is 1 MSa/s (because of a slower sweep speed), only 1 out of every 200 samples needs to be stored. Instead of storing one sample (and throwing others away), the 200 samples are averaged together to provide the value for one display point. The slower the sweep speed, the greater the number of samples that are averaged together for each display point.

Type

{‘HRESolution’, ‘NORMal’, ‘AVERage’, ‘AVER<m>’}

num_averages

The number of averages applied (applies only to the 'AVERage' acq_type)

Type

int, 2 to 65536

p_mode

'NORMal' is limited to 62,500 points, whereas 'RAW' gives up to 1e6 points. Use 'MAXimum' for sources that are not analogue or digital.

Type

{'NORMal', 'RAW', 'MAXimum'}

num_points

Use 0 to let p_mode control the number of points, otherwise override with a lower number than maximum for the p_mode

Type

int

wav_format

Select the data transmission mode for waveform data points, i.e. how the data is formatted when sent from the oscilloscope.

  • 'ASCii' formatted data converts the internal integer data values to real Y-axis values. Values are transferred as ascii digits in floating point notation, separated by commas.

  • 'WORD' formatted data transfers signed 16-bit data as two bytes.

  • 'BYTE' formatted data is transferred as signed 8-bit bytes.

Type

{‘WORD’, ‘BYTE’, ‘ASCii’}

acquire_print

True prints that the capturing starts and the number of points captured

Type

bool

capture_and_read(sources, sourcestring, set_running=True)[source]

This is a wrapper function for choosing the correct capture_and_read function according to wav_format, capture_and_read_binary() or capture_and_read_ascii().

Acquire raw data from selected channels according to acquring options currently set with set_acquiring_options(). The parameters are provided by determine_channels().

The output should be processed by process_data().

Parameters

  • sources (list of str) – list of sources, example ['CHANnel1', 'CHANnel3']

  • sourcesstring (str) – String of comma separated sources, example 'CHANnel1, CHANnel3'

  • set_running (bool, default True) – True leaves oscilloscope running after data capture

Returns

Depends on the capture_and_read function used

Return type

See respective

Raises

ValueError – If wav_format is not {‘BYTE’, ‘WORD’, ‘ASCii’}

See also

process_data()

capture_and_read_ascii(sources, sourcesstring, set_running=True)[source]

Capture and read data and metadata from sources of the oscilloscope when waveform format is ASCii.

The parameters are provided by determine_channels(). The output should be processed by process_data_ascii().

Parameters

  • sources (list of str) – list of sources, example ['CHANnel1', 'CHANnel3']

  • sourcesstring (str) – String of comma separated sources, example 'CHANnel1, CHANnel3'

  • set_running (bool, default True) – True leaves oscilloscope running after data capture

Returns

  • raw (str) – Raw data to be processed by process_data_ascii(). The raw data is a list of one IEEE block per channel with a head and then comma separated ascii values.

  • metadata (tuple of str) – Tuple of the preamble for one of the channels to calculate time axis (same for all channels) and the model series

capture_and_read_binary(sources, sourcesstring, datatype='standard', set_running=False)[source]

Capture and read data and metadata from sources of the oscilloscope when waveform format is 'WORD' or 'BYTE'.

The parameters are provided by determine_channels(). The output should be processed by process_data_binary().

Parameters

  • sources (list of str) – list of sources, example ['CHANnel1', 'CHANnel3']

  • sourcesstring (str) – String of comma separated sources, example 'CHANnel1, CHANnel3'

  • datatype (char or 'standard', optional but must match waveform format used) – To determine how to read the values from the oscilloscope depending on wav_format. Datatype is 'h' for 16 bit signed int ('WORD'), for 8 bit signed bit ('BYTE') (same naming as for structs, https://docs.python.org/3/library/struct.html#format-characters). 'standard' will evaluate oscacq._datatypes[self.wav_format] to automatically choose according to the waveform format

  • set_running (bool, default True) – True leaves oscilloscope running after data capture

Returns

  • raw (ndarray) – Raw data to be processed by process_data_binary(). An ndarray of ints that can be converted to voltage values using the preamble.

  • preamble (str) – Preamble metadata (comma separated ascii values)

close(set_running=True)[source]

Closes the connection to the oscilloscope.

Parameters

set_running (bool, default True) – True sets the oscilloscope to running before closing the connection, False leaves it in its current state

determine_channels(source_type='CHANnel', channel_nums='active')[source]

Decide the channels to be acquired, or determine by checking active channels on the oscilloscope.

Note

Use channel_nums='active' to capture all the currently active channels on the oscilloscope.

Parameters

  • source_type (str, default 'CHANnel') – Selects the source type. Must be 'CHANnel' in current implementation. Future version might include {‘MATH’, ‘FUNCtion’}.

  • channel_nums (list or 'active', default _ch_nums) – list of the channel numbers to be acquired, example ['1', '3']. Use 'active' or [''] to capture all the currently active channels on the oscilloscope.

Returns

  • sources (list of str) – list of the sources, example ['CHAN1', 'CHAN3']

  • sourcesstring (str) – String of comma separated sources, example 'CHANnel1, CHANnel3'

  • channel_nums (list of chars) – list of the channels, example ['1', '3']

generate_file_header(channels, additional_line=None, timestamp=True)[source]

Generate string to be used as file header for saved files

The file header has this structure:

<id>
<mode>,<averages>
<timestamp>
additional_line
time,<chs>

Where <id> is the id of the oscilloscope, <mode> is the acq_type, <averages> num_averages ("N/A" if not applicable) and <chs> are the comma separated channels used.

Note

If additional_line is not supplied the fileheader will be four lines. If timestamp=False the timestamp line will not be present.

Parameters

  • channels (list of str) – Any list of identifies for the channels used for the measurement to be saved.

  • additional_line (str or None, default None) – No additional line if set to None, otherwise the value of the argument will be used as an additonal line to the file header

  • timestamp (bool) – True gives a line with timestamp, False removes the line

Returns

string to be used as file header

Return type

str

Example

If the oscilloscope is acquiring in 'AVER' mode with eight averages:

Oscilloscope.generate_file_header(['1', '3'], additional_line="my comment")

gives:

# AGILENT TECHNOLOGIES,DSO-X 2024A,MY1234567,12.34.1234567890
# AVER,8
# 2019-09-06 20:01:15.187598
# my comment
# time,1,3
get_active_channels()[source]

Get list of the currently active channels on the instrument

Returns

list of the active channels, example ['1', '3']

Return type

list of chars

get_trace(sources, sourcesstring, acquire_print=None)[source]

Obtain one trace with current settings.

Parameters

  • sources (list of str) – list of sources, example ['CHANnel1', 'CHANnel3']

  • sourcesstring (str) – String of comma separated sources, example 'CHANnel1, CHANnel3'

  • acquire_print (bool or None, default None) – Possibility to override acquire_print temporarily, but the current setting will be restored afterwards

Returns

  • time (ndarray) – Time axis for the measurement

  • y (ndarray) – Voltage values, same sequence as sources input, each row represents one channel

is_running()[source]

Determine if the oscilloscope is running.

Returns

True if running, False otherwise

Return type

bool

query(command)[source]

Query a VISA command to the oscilloscope.

Parameters

command (str) – VISA query

run()[source]

Set the ocilloscope to running mode.

set_acquire_print(value)[source]

Control attribute which decides whether to print information while acquiring.

Parameters

value (bool) – True to print information to info level in log

set_acquiring_options(wav_format='WORD', acq_type='HRESolution', num_averages=2, p_mode='RAW', num_points=0, acq_print=None)[source]

Sets the options for acquisition from the oscilloscope.

Parameters

  • wav_format ({'WORD', 'BYTE', 'ASCii'}, default _waveform_format) – Select the format of the communication of waveform from the oscilloscope, see wav_format

  • acq_type ({'HRESolution', 'NORMal', 'AVERage', 'AVER<m>'}, default _acq_type) – Acquisition mode of the oscilloscope. <m> will be used as num_averages if supplied, see acq_type

  • num_averages (int, 2 to 65536, default _num_avg) – Applies only to the 'AVERage' mode: The number of averages applied

  • p_mode ({'NORMal', 'RAW', 'MAXimum'}, default 'RAW') – 'NORMal' is limited to 62,500 points, whereas 'RAW' gives up to 1e6 points. Use 'MAXimum' for sources that are not analogue or digital

  • num_points (int, default 0) – Use 0 to let p_mode control the number of points, otherwise override with a lower number than maximum for the p_mode

  • acq_print (bool or None, default None) – Temporarily control attribute which decides whether to print information while acquiring: bool sets it to the bool value, None leaves as the it is in the Oscilloscope object

Raises

ValueError – if num_averages are outside of the range or <m> in acq_type cannot be converted to int

set_options_get_trace(channel_nums='active', source_type='CHANnel', wav_format='WORD', acq_type='HRESolution', num_averages=2, p_mode='RAW', num_points=0)[source]

Set the options provided by the parameters and obtain one trace.

Parameters

  • channel_nums (list or 'active', default _ch_nums) – list of the channel numbers to be acquired from, example ['1', '3']. Use 'active' to capture all the currently active channels on the oscilloscope.

  • source_type (str, default 'CHANnel') – Selects the source type. Must be 'CHANnel' in current implementation. Future version might include {‘MATH’, ‘FUNCtion’}.

  • wav_format ({'WORD', 'BYTE', 'ASCii'}, default _waveform_format) – Select the format of the communication of waveform from the oscilloscope, see wav_format

  • acq_type ({'HRESolution', 'NORMal', 'AVERage', 'AVER<m>'}, default _acq_type) – Acquisition mode of the oscilloscope. <m> will be used as num_averages if supplied, see acq_type

  • num_averages (int, 2 to 65536, default _num_avg) – Applies only to the 'AVERage' mode: The number of averages applied

  • p_mode ({'NORMal', 'RAW', 'MAXimum'}, default 'RAW') – 'NORMal' is limited to 62,500 points, whereas 'RAW' gives up to 1e6 points. Use 'MAXimum' for sources that are not analogue or digital

  • num_points (int, default 0) – Use 0 to let p_mode control the number of points, otherwise override with a lower number than maximum for the p_mode

Returns

  • time (ndarray) – Time axis for the measurement

  • y (ndarray) – Voltage values, same sequence as channel_nums, each row represents one channel

  • channel_nums (list of chars) – list of the channels obtained from, example ['1', '3']

set_options_get_trace_save(fname='data', ext='.csv', channel_nums='active', source_type='CHANnel', wav_format='WORD', acq_type='HRESolution', num_averages=2, p_mode='RAW', num_points=0)[source]

Get trace and save the trace to a file and plot to png.

Filename is recursively checked to ensure no overwrite. The file header is:

self.id+"\n"+
"time,"+",".join(channel_nums)+"\n"+
timestamp
Parameters

  • fname (str, default _filename) – Filename of trace

  • ext (str, default _filetype) – Choose the filetype of the saved trace

  • channel_nums (list or 'active', default _ch_nums) – list of the channel numbers to be acquired from, example ['1', '3']. Use 'active' to capture all the currently active channels on the oscilloscope

  • source_type (str, default 'CHANnel') – Selects the source type. Must be 'CHANnel' in current implementation. Future version might include {‘MATH’, ‘FUNCtion’}

  • wav_format ({'WORD', 'BYTE', 'ASCii'}, default _waveform_format) – Select the format of the communication of waveform from the oscilloscope, see wav_format

  • acq_type ({'HRESolution', 'NORMal', 'AVERage', 'AVER<m>'}, default _acq_type) – Acquisition mode of the oscilloscope. <m> will be used as num_averages if supplied, see acq_type

  • num_averages (int, 2 to 65536, default _num_avg) – Applies only to the 'AVERage' mode: The number of averages applied

  • p_mode ({'NORMal', 'RAW', 'MAXimum'}, default 'RAW') – 'NORMal' is limited to 62,500 points, whereas 'RAW' gives up to 1e6 points. Use 'MAXimum' for sources that are not analogue or digital

  • num_points (int, default 0) – Use 0 to let p_mode control the number of points, otherwise override with a lower number than maximum for the p_mode

stop()[source]

Stop the oscilloscope.

write(command)[source]

Write a VISA command to the oscilloscope.

Parameters

command (str) – VISA command to be written

Auxiliary to the class

keyoscacquire.oscacq.interpret_visa_id(id)[source]

Interprets VISA ID, finds oscilloscope model series if applicable

Parameters

id (str) – VISA ID as returned by the *IDN? command

Returns

  • maker (str) – Maker of the instrument, e.g. Keysight Technologies

  • model (str) – Model of the instrument

  • serial (str) – Serial number of the instrument

  • firmware (str) – Firmware version

  • model_series (str) – “N/A” unless the instrument is a Keysight/Agilent DSO and MSO oscilloscope. Returns the model series, e.g. ‘2000’. Returns “not found” if the model name cannot be interpreted.

keyoscacquire.oscacq._supported_series = ['1000', '2000', '3000', '4000', '6000']

Supported Keysight DSO/MSO InfiniiVision series

keyoscacquire.oscacq._screen_colors = {'1': 'C1', '2': 'C2', '3': 'C0', '4': 'C3'}

Keysight colour map for the channels

keyoscacquire.oscacq._datatypes = {'BYTE': 'b', 'WORD': 'h'}

Datatype is 'h' for 16 bit signed int (WORD), 'b' for 8 bit signed bit (BYTE). Same naming as for structs docs.python.org/3/library/struct.html#format-characters

The preamble

The preamble returned by the capture_and_read functions (i.e. returned by the oscilloscope when querying the VISA command :WAV:PREamble?) is a string of comma separated values, the values have the following meaning:

  1. FORMAT : int16 - 0 = BYTE, 1 = WORD, 4 = ASCII.

  2. TYPE : int16 - 0 = NORMAL, 1 = PEAK DETECT, 2 = AVERAGE

  3. POINTS : int32 - number of data points transferred.

  4. COUNT : int32 - 1 and is always 1.

  5. XINCREMENT : float64 - time difference between data points.

  6. XORIGIN : float64 - always the first data point in memory.

  7. XREFERENCE : int32 - specifies the data point associated with x-origin.

  8. YINCREMENT : float32 - voltage diff between data points.

  9. YORIGIN : float32 - value is the voltage at center screen.

  10. YREFERENCE : int32 - specifies the data point where y-origin occurs.