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 devicespath_of_config
: find the path ofkeyoscacquire.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 instructionsget_num_traces
: get a set number of traces, use with option-h
for instructionsget_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