Instrument communication

The keyoscacquire.oscilloscope module is responsible for the instrument communication.

The Oscilloscope class

class keyoscacquire.oscilloscope.Oscilloscope(address='USB0::1234::1234::MY1234567::INSTR', timeout=15000, get_errors_on_init=False, verbose=True)

PyVISA communication with the oscilloscope.

Init opens a connection to an instrument and chooses default settings for the connection and acquisition as specified in keyoscacquire.config.

Leading underscores indicate that an attribute or method is read-only or suggested to be for interal use only.

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

• get_errors_on_init (bool) – The error queue of the scope is by default cleared when __init__ is called; however, when this parameter is True, the error queue is extracted from the scope before the log is cleared, it is printed to the terminal and the attribute errors is populated with the errors

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

Raises

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

verbose

If True: prints when the connection to the device is opened, the acquistion mode, etc

Type

bool, default True

verbose_acquistion

If True: prints that the capturing starts, the channels acquired from and the number of points captured

Type

bool, defaulting to self.verbose

fname

The filename to which the trace will be saved with save_trace()

Type

str, default keyoscacquire.config._filename

ext

The extension for saving traces, must include the period, e.g. .csv

Type

str, default keyoscacquire.config._filetype

savepng

If True: will save a png of the plot when save_trace()

Type

bool, default keyoscacquire.config._export_png

showplot

If True: will show a matplotlib plot window when save_trace()

Type

bool, default keyoscacquire.config._show_plot

_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’s model name

Type

str

_serial

The instrument’s serial number

Type

str

_address

Visa address of instrument

Type

str

_time

The time axis of the most recent captured trace

Type

ndarray

_values

The values for the most recent captured trace

Type

ndarray

_capture_channels

The channels of captured for the most recent trace

Type

list of ints

High-level functions

Oscilloscope.get_trace(channels=None, verbose_acquistion=None)

Obtain one trace with current settings. Will return the values of the traces, but alos populate a few attributes, including _time, _values and _capture_channels.

Use save_trace() to save the trace to disk.

Parameters

• channels (list of ints or 'active', uses oscilloscope setting by default) – Optionally change the list of the channel numbers to be acquired, example [1, 3]. Use 'active' or [] to capture all the currently active channels on the oscilloscope.

• verbose_acquistion (bool or None, default None) – Optionally change verbose_acquistion

Returns

• _time (ndarray) – Time axis for the measurement

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

• _capture_channels (list of ints) – list of the channels obtaied from, example [1, 3]

Oscilloscope.save_trace(fname=None, ext=None, additional_header_info=None, savepng=None, showplot=None, nowarn=False)

Save the most recent trace to fname+ext. Will check if the filename exists, and let the user append to the fname if that is the case.

Parameters

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

• ext ({'.csv', '.npy'}, default keyoscacquire.config._filetype) – Choose the filetype of the saved trace

• additional_header_info (str, default `None) – Will put this string as a separate line before the column headers

• savepng (bool, default keyoscacquire.config._export_png) – Choose whether to also save a png with the same filename

• showplot (bool, default keyoscacquire.config._show_plot) – Choose whether to show a plot of the trace

Oscilloscope.plot_trace()

Plot and show the most recent trace

Oscilloscope.set_options_get_trace(channels=None, wav_format=None, acq_type=None, num_averages=None, p_mode=None, num_points=None)

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

Parameters

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

• 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, uses oscilloscope setting by default) – Applies only to the 'AVERage' mode: The number of averages applied

• p_mode ({'NORMal', 'RAW', 'MAXimum'}, default keyoscacquire.config._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

• num_points (int, default keyoscacquire.config._num_points) – Use 0 to get the maximum amount of points for the current p_mode, otherwise override with a lower number than maximum for the p_mode

Returns

• _time (ndarray) – Time axis for the measurement

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

• _capture_channels (list of ints) – list of the channels obtaied from, example [1, 3]

Oscilloscope.set_options_get_trace_save(fname=None, ext=None, channels=None, wav_format=None, acq_type=None, num_averages=None, p_mode=None, num_points=None, additional_header_info=None)

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

Filename is recursively checked to ensure no overwrite. The file header when capturing ch 1 and 3 in AVER8 is:

# AGILENT TECHNOLOGIES,DSO-X 2024A,MY1234567,12.34.1234567890
# AVER,8
# 2019-09-06 20:01:15.187598
# time,1,3

Parameters

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

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

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

• 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, uses oscilloscope setting by default) – Applies only to the 'AVERage' mode: The number of averages applied

• p_mode ({'NORMal', 'RAW', 'MAXimum'}, default keyoscacquire.config._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

• num_points (int, default keyoscacquire.config._num_points) – Use 0 to get the maximum amount of points for the current p_mode, otherwise override with a lower number than maximum for the p_mode

• additional_header_info (str, default `None) – Will put this string as a separate line before the column headers

Connection and VISA commands

Oscilloscope.close(set_running=True)

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

property Oscilloscope.timeout

The timeout on the VISA communication with the instrument. The timeout must be longer than the acquisition time.

Getter

Returns the number of milliseconds before timeout of a query command

Setter

Set the number of milliseconds before timeout of a query command

Type

int

Oscilloscope.write(command)

Write a VISA command to the oscilloscope.

Parameters

command (str) – VISA command to be written

Oscilloscope.query(command, action='')

Query a VISA command to the oscilloscope. Will ask the oscilloscope for the latest error if the query times out.

Parameters

• command (str) – VISA query

• action (str, default "") – Optional argument used to customise the error message if there is a timeout

Oscilloscope.get_error()

Get the first error in the error queue, a FIFO queue of max length 30. The queue is reset when *CLS is written to the scope, which happens in __init__().

Returns

error number,description

Return type

str

Oscilloscope state control

Oscilloscope.run()

Set the oscilloscope to running mode.

Oscilloscope.stop()

Stop the oscilloscope.

Oscilloscope.is_running()

Determine if the oscilloscope is running.

Returns

True if running, False otherwise

Return type

bool

property Oscilloscope.active_channels

Find the currently active channels on the instrument

Note

Changing the active channels will not affect with channels are captured unless set_channels_for_capture() is subsequently run. The get_traces() family of methods will make sure of this.

Getter

Returns a list of the active channels, for example [1, 3]

Setter

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

Type

list of ints

Acquisition and transfer properties

These are properties, meaning that they can be used like this:

with Oscilloscope() as scope:
  scope.acq_type = 'AVER8'
  print(f"Number of points that will be captured {scope.num_points}")
  scope.num_points = 1500
  print(f"Changed the number of points to be captured to {scope.num_points}")

property Oscilloscope.acq_type

Acquisition mode of the oscilloscope

Choose between

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

• 'AVERage' or 'AVER<m>' — sets the oscilloscope in the averaging mode. The number of averages can be set with num_averages, or <m> will be used as num_averages if supplied. <m> can be in the range 2 to 65,536

• '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.

Getter

Returns the current mode (will not return <m> for AVER)

Setter

Sets the mode, for example AVER8, if verbose will print the type and the number of averages number

Type

{'NORMal', 'AVERage', 'AVER<m>', 'HRES'}

Raises

ValueError – If <m> in cannot be converted to an int (or is out of range)

property Oscilloscope.num_averages

The number of averages taken if the scope is in the 'AVERage' acq_type

Getter

Returns the current number of averages

Setter

Set the number, will print the number if verbose

Type

int, 2 to 65,536

Raises

ValueError – If the number is is out of range

property Oscilloscope.p_mode

The points mode of the acquistion

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

Getter

Returns the current mode

Setter

Set the mode, will check if compatible with the acq_type

Type

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

property Oscilloscope.num_points

The number of points to be acquired for each channel. Use 0 to get the maximum number given the p_mode, or override with a lower number than maximum for the given p_mode

Warning

If the exact number of points is crucial, always check the number of points with the getter after performing the setter.

Note

The scope must be stopped to get the number of points that will be transferred when it is in the stopped state. As this package always stops the scope when getting a trace, the getter will also do this to get the actual number of points that will be transferred (otherwise the returned number will be capped by the p_mode NORMal (which can be transferred without stopping the scope)).

Getter

Returns the number of points that will be acquired (stopping and re-running the scope as explained in the note above)

Setter

Set the number, but beware that the scope might change the number depending on memory depth, time axis settings, etc.

Type

int

Raises

ValueError – If a negative integer or other datatypes are given.

property Oscilloscope.wav_format

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.

Getter

Returns the number of points that will be acquired, however it does not seem to be fully stable

Setter

Set the number, but beware that the scope might change the number depending on memory depth, time axis settings, etc.

Type

{'WORD', 'BYTE', 'ASCii'}

Multiple acquisition and transfer options setting functions

Oscilloscope.set_channels_for_capture(channels='active')

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

Parameters

channels (list of ints or 'active', default active) – 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

the channels that will be captured, example [1, 3]

Return type

list of ints

Oscilloscope.set_acquiring_options(wav_format=None, acq_type=None, num_averages=None, p_mode=None, num_points=None, verbose_acquistion=None)

Change acquisition options

Parameters

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

• acq_type ({'HRESolution', 'NORMal', 'AVERage', 'AVER<m>'}, default keyoscacquire.config._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) – Applies only to the 'AVERage' mode: The number of averages applied

• p_mode ({'NORMal', 'RAW', 'MAXimum'}, default keyoscacquire.config._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

• num_points (int, default keyoscacquire.config._num_points) – Use 0 to get the maximum amount of points for the current p_mode, otherwise override with a lower number than maximum for the p_mode

• verbose_acquistion (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

Oscilloscope.set_waveform_export_options(wav_format=None, num_points=None, p_mode=None)

Set options for the waveform export from the oscilloscope to the computer

Parameters

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

• p_mode ({'NORMal', 'RAW'}, default keyoscacquire.config._p_mode) – 'NORMal' is limited to 62,500 points, whereas 'RAW' gives up to 1e6 points.

• num_points (int, default keyoscacquire.config._num_points) – Use 0 to get the maximum amount of points, otherwise override with a lower number than maximum for the p_mode

Other

Oscilloscope.capture_and_read(set_running=True)

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

The populated attributes raw and metadata should be processed by keyoscacquire.dataprocessing.process_data().

rawndarray

An ndarray of ints that can be converted to voltage values using the preamble.

metadata

depends on the wav_format

Parameters

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

Raises

ValueError – If wav_format is not one of {'BYTE', 'WORD', 'ASCii'}

See also

keyoscacquire.dataprocessing.process_data()

Oscilloscope.generate_file_header(channels=None, additional_line=None, timestamp=True)

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 strs or ints) – 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, 'piezo'], 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,piezo

Oscilloscope.print_acq_settings()

Print the current settings for acquistion from the scope

The preamble

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

0. FORMAT : int16 - 0 = BYTE, 1 = WORD, 4 = ASCII.
1. TYPE : int16 - 0 = NORMAL, 1 = PEAK DETECT, 2 = AVERAGE
2. POINTS : int32 - number of data points transferred.
3. COUNT : int32 - 1 and is always 1.
4. XINCREMENT : float64 - time difference between data points.
5. XORIGIN : float64 - always the first data point in memory.
6. XREFERENCE : int32 - specifies the data point associated with x-origin.
7. YINCREMENT : float32 - voltage diff between data points.
8. YORIGIN : float32 - value is the voltage at centre of the screen.
9. YREFERENCE : int32 - specifies the data point where y-origin occurs.