keyoscacquire: Keysight oscilloscope acquire

.. image:: https://img.shields.io/pypi/v/keyoscacquire?style=flat-square :target: https://pypi.org/project/keyoscacquire/ :alt: PyPI

.. image:: https://img.shields.io/codefactor/grade/github/asvela/keyoscacquire?style=flat-square :target: https://www.codefactor.io/repository/github/asvela/keyoscacquire :alt: CodeFactor

.. image:: https://img.shields.io/codeclimate/maintainability/asvela/keyoscacquire?style=flat-square :target: https://codeclimate.com/github/asvela/keyoscacquire :alt: Code Climate maintainability

.. image:: https://img.shields.io/readthedocs/keyoscacquire?style=flat-square :target: https://keyoscacquire.rtfd.io :alt: Read the Docs Building

.. image:: https://img.shields.io/pypi/l/keyoscacquire?style=flat-square :target: https://keyoscacquire.readthedocs.io/en/dev-v4.0.0/contents/license.html :alt: License

keyoscacquire is a Python package for acquiring traces from Keysight InfiniiVision oscilloscopes through a VISA interface.

Based on PyVISA <https://pyvisa.readthedocs.io/en/latest/>, keyoscacquire provides programmes for acquiring and exporting traces to your choice of ASCII format files (default csv) or numpy npy <https://numpy.org/doc/stable/reference/generated/numpy.lib.format.html>, and a png of the trace plot. The package also provides an API for integration in other Python code.

By default, the package uses the binary WORD format for the waveform transfer from the oscilloscope, giving roughly an order of magnitude speed-up over the ASCII transfer type.

The code has been tested on Windows 7 and 10 with a Keysight DSO2024A model using a USB connection.

.. documentation-marker

Documentation

Available at keyoscacquire.rtfd.io <http://keyoscacquire.readthedocs.io/en/latest/>_. A few examples below, but formatting and links are broken as this file is intended for the documentation parser.

Building a local copy of the docs ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. start-local-copy-documentation-marker

Should you wish to build a local copy of the sphinx docs, make sure the necessary packages are installed::

pip install sphinx sphinx-prompt furo recommonmark

and then build by executing make html in the docs folder.

.. end-local-copy-documentation-marker

Installation

Install the package with pip::

pip install keyoscacquire

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

.. API-use-marker

Python console/API

The Reference/API section (particularly :ref:osc-class) 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

.. prompt:: bash

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

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

.. prompt:: bash

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

.. prompt:: bash

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 :mod: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 :mod:keyoscacquire.config storing default options. Change this file to your choice of standard settings, see :ref:default-options.
• 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 :ref:cli-programmes-short.

.. contribute-marker

Contribute/report issues

Please report any issues with the package with the issue tracker on Github <https://github.com/asvela/keyoscacquire/issues>_.

Contributions are welcome via Github <https://github.com/asvela/keyoscacquire.git>_.

The package is written and maintained by Andreas Svela.