Overview and getting started

The code is structured as a module keyoscacquire.oscilloscope containing the engine doing the PyVISA interfacing in a class Oscilloscope, and support functions for data processing. Programmes are located in keyoscacquire.programmes, and the same programmes can be run directly from the command line as they are installed in the Python path, see Command line programmes. Default options are found in keyoscacquire.config, and the keyoscacquire.fileio provides functions for plotting, saving, and loading traces from disk.

keyoscacquire uses the logging module, see Logging.

Installation

Install the package with pip

pip install keyoscacquire

or download locally and install with $ python setup.py install or by running install.bat.

Quick reference

Python console/API

The Reference/API section (particularly Instrument communication) gives all the necessary information about the API.

As an example of API usage/use in the Python console:

>>> import keyoscacquire as koa
>>> scope = koa.Oscilloscope(address='USB0::1234::1234::MY1234567::INSTR')
Connected to:
   AGILENT TECHNOLOGIES
   DSO-X 2024A (serial MY1234567)
>>> scope.acq_type = 'AVER8'
>>> print(scope.num_points)
7680
>>> time, y, channel_numbers = scope.get_trace(channels=[2, 1, 4])
Acquisition type: AVER
# of averages:    8
From channels:    [1, 2, 4]
Acquiring ('WORD').. done
Points captured per channel: 7,680
>>> print(channel_numbers)
[1, 2, 4]
>>> scope.save_trace(showplot=True)
Saving trace to:  data.csv
>>> scope.close()

where time is a vertical numpy (2D) array of time values and y is a numpy array which columns contain the data from the active channels listed in channel_numbers. The trace saved to data.csv also contains metadata (can be further customised) in the first lines:

# AGILENT TECHNOLOGIES,DSO-X 2024A,MY1234567,02.50.2019022736
# AVER,8
# 2020-12-21 03:13:18.184028
# time,1,2,4
-5.000063390000000080e-03,-4.853398528000013590e-03,-5.247737759999995810e-03,-5.247737759999995810e-03
...

The trace can be easily loaded from disk to a Pandas dataframe with:

>>> df, metadata = koa.fileio.load_trace("data")
>>> df.head()
    time         1         2         4
0 -0.005 -0.004853 -0.005248 -0.005248
1 -0.005 -0.005406 -0.005017 -0.005248
2 -0.005 -0.004964 -0.005190 -0.005248
3 -0.005 -0.005185 -0.005363 -0.005248
4 -0.005 -0.005517 -0.005074 -0.005248
>>> metadata
['AGILENT TECHNOLOGIES,DSO-X 2024A,MY1234567,02.50.2019022736', 'AVER,8', '2020-12-21 03:13:18.184028', 'time,1,2,4']

Command line use

Capture the active channels on an oscilloscope connected with VISA address from command prompt

get_single_trace -v "USB0::1234::1234::MY1234567::INSTR"

The get_single_trace programme takes several other arguments too, see them with

get_single_trace -h

If you need to find the VISA address of your oscilloscope, simply use the command line programme list_visa_devices provided by this package

list_visa_devices

If you want to set a default VISA address (and other default options too), run path_of_config to find the folder of the keyoscacquire.config module, locate it and change the _visa_address variable to the VISA address of your chosen default instrument.

The package installs the following command line programmes in the Python path

  • list_visa_devices: list the available VISA devices

  • path_of_config: find the path of keyoscacquire.config storing default options. Change this file to your choice of standard settings, see Default options in keyoscacquire.config.

  • get_single_trace: use with option -h for instructions

  • get_num_traces: get a set number of traces, use with option -h for instructions

  • get_traces_single_connection: get a trace each time enter is pressed, use with option -h for instructions

See more under Command line programmes for trace export.

Known issues and suggested improvements

  • Issues:

    • An issue has been reported where the data transfer/interpretation where the output waveform is not correct, causing the trace to look nothing like on the oscilloscope screen. If this happens, a fix has been to open KeySight BenchVue and obtain one trace through the software. Now try to obtain a trace through this package – it should now work again. Please report this if this happens.

  • Improvements:

    • (feature) include capture of MATH waveform

    • (feature) expand API to include

      • waveform measurements

      • trigger settings

      • time and voltage axes settings

    • (feature) pickling trace to disk for later post-processing to give speed-up in consecutive measurements

    • (instrument support) expand support for Infiniium oscilloscopes

    • (development) include tests