How to use

The VISA addresses of connected instruments can be found running list_visa_devices in cmd or the terminal (this programme is installed with keyoscacquire), or can be found in NI MAX or the PyVISA shell.

Setting the address of your oscilloscope in _visa_address in keyoscacquire.config will make all the installed command line programmes talk to your by default. The config file can be found with cmd/terminal by path_of_config (see Default options in keyoscacquire.config).

Note

In order to connect to a VISA instrument, NI MAX or similar might need to be running on the computer.

Command line programmes for trace export

Four command line programmes for trace exporting can be ran directly from the command line after installation (i.e. from whatever folder and no need for $ python [...].py):

  • get_single_trace

  • get_num_traces

  • get_traces_connect_each_time and

  • get_traces_single_connection

They all have options, the manuals are available using the flag -h.

The two first programmes will obtain one and a specified number of traces, respectively. The two latter programmes are loops for which every time enter is hit a trace will be obtained and exported as csv and png files with successive numbering. By default all active channels on the oscilloscope will be captured (this can be changed, see Default options in keyoscacquire.config).

The difference between the two latter programmes is that the first programme is establishing a new connection to the instrument each time a trace is to be captured, whereas the second opens a connection to start with and does not close the connection until the program is quit. The second programme only checks which channels are active when it connects, i.e. the first programme will save only the currently active channels for each saved trace; the second will each time save the channels that were active at the time of starting the programme.

Optional command line arguments

The programmes takes optional arguments, the manuals are available using the flag -h (see also Command line programmes for more details). Here are three examples

  • -v USB0::1234::1234::MY1234567::INSTR set the visa address of the instrument

  • -f "custom filename" sets the base filename to “custom filename”

  • -a AVER8 sets acquiring type to average with eight traces

For example

get_traces_single_connection_loop -f "measurement"

will give output files measurement n<n>.csv and measurement n<n>.png. The programmes will check if the file "measurement"+_file_delimiter+num+_filetype) exists, and if it does, prompt the user for something to append to measurement until "measurement"+appended+"0"+_filetype is not an existing file. The same checking procedure applies also when no base filename is supplied and config._default_filename is used.

Waveform formats

The oscilloscope can transfer the waveform to the computer in three different ways

  • Comma separated ASCII values

  • 8-bit integers

  • 16-bit integers

Keysight call these ASCii, BYTE and WORD, respectively. The two latter integer types must be post-processed on the computer using a preamble that can be queried for from the ocilloscope. The keyoscacquire package supports all three formats and does the conversion for the integer transfer types, i.e. the output files will be ASCII format anyway, it is simply a question of how the data is transferred to and processed on the computer (see capture_and_read() and process_data()).

The 16-bit values format is approximately 10x faster than ascii and gives the same vertical resolution. 8-bit has significantly lower vertical resolution than the two others, but gives an even higher speed-up.

The default waveform type can be set in with _waveform_format, see Default options in keyoscacquire.config, or using the API wav_format.

Using the API

The package provides an API for use with your Python code. For example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
import keyoscacquire as koa
import matplotlib.pyplot as plt

def averaged_trace(scope, measurement_number, averages=8):
    # Set the number of averages and get a trace
    time, voltages, _ = scope.set_options_get_trace(acq_type=f"AVER{averages}")
    # Save the trace data as a csv and a png plot, without showing the plot
    # (the averaging mode and the number of averages is also automatically
    # saved inside the file, together with a timestamp and more)
    scope.save_trace(fname=f"measurement{measurement_number}_AVER{averages}",
                     showplot=False)
    return time, voltages


def different_averaging(visa_address, measurement_number):
    # Connect to the scope
    with koa.Oscilloscope(address=visa_address) as scope:
        # Set the channels to view on the scope
        scope.active_channels = [1, 3]
        # Prepare a two panel plot
        fig, ax = plt.subplots(nrows=2, sharex=True)
        # Obtain traces for different numbers of averages
        for averages in [2, 4, 8, 16, 32]:
            time, voltages = averaged_trace(scope, measurement_number, averages=averages)
            # Plot channel 1 to ax[0] and ch 3 to ax[1]
            for a, ch in zip(ax, voltages.T):
                a.plot(time, ch, label=f"{averages}", alpha=0.5)
        # Add legends to and labels to both plots
        for a, ch_num in zip(ax, scope.active_channels):
            a.set_xlabel("Time [s]")
            a.set_ylabel(f"Channel {ch_num} [V]")
            a.legend()
    plt.show()


different_averaging(visa_address="USB0::1234::1234::MY1234567::INSTR",
                    measurement_number=1)

See Instrument communication and Data processing, file saving & loading for more. The command line programmes have a Python backend that can integrated in Python scripts or used as examples, see Python backend for command line programmes.

Todo

Expand examples

Note on obtaining traces when the scope is running vs when stopped

When the scope is running the capture_and_read functions will obtain a trace by the :DIGitize VISA command, causing the instrument to acquire a trace and then stop the oscilloscope. When the scope is stopped the current trace on the screen of the oscilloscope will be captured.

Warning

The settings specified with VISA commands under :ACQuire, i.e. acquiring mode and number of points to be captured, will not be applied to the acquisition if the scope already is stopped while in a different mode.

The scope will always be set to running after a trace is captured.

Default options in keyoscacquire.config

The package takes its default options from keyoscacquire.config (to find the location of the file run $ path_to_config in the command line):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
# -*- coding: utf-8 -*-
"""Default options for keyoscacquire"""

#: VISA address of instrument
_visa_address = 'USB0::1234::1234::MY1234567::INSTR'
#: Waveform format transferred from the oscilloscope to the computer
#: WORD formatted data is transferred as 16-bit uint.
#: BYTE formatted data is transferred as 8-bit uint.
#: 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.
_waveform_format = 'WORD'
#: The acqusition type
#: {HRESolution, NORMal, AVER<m>} where <m> is the number of averages in range [2, 65536]
_acq_type = "HRESolution"
#: Points mode of the oscilloscope: ``'NORMal'`` is limited to 62,500 points,
#: whereas ``'RAW'`` gives up to 1e6 points.
#: {RAW, MAX, NORMal}
_p_mode = 'RAW'
#: Number of points to transfer to the computer
#: zero gives maximum
_num_points = 0
#: Default base filename of all traces and pngs exported, a number is appended to the base
_filename = "data"
#: Delimiter used between :attr:`_filename` and filenumber (before :attr:`_filetype`)
_file_delimiter = " n"
#: filetype of exported data, can also be txt/dat etc.
_filetype = ".csv"
#: export png of plot of obtained trace
_export_png = True
#: show each plot when generated (program pauses until it is closed)
_show_plot = False
#: ms timeout for the instrument connection
_timeout = 15000

Note

Changing these after importing the module with an import statement will not have any effect.

The command line programmes will save traces in the folder from where they are ran as _filename+_file_delimiter+<n>+_filetype, i.e. by default as data n<n>.csv and data n<n>.png.

Logging

The module gives output for debugging through logging. The output can be directed to the terminal by adding the following to the top level file using the keyoscacquire package:

import logging
logging.basicConfig(level=logging.DEBUG)

or directed to a file mylog.log with:

import logging
logging.basicConfig(filename='mylog.log', level=logging.DEBUG)

Miscellaneous

Executing the module

Running the module with

python -m keyoscacquire

obtains and saves a trace with default options being used. Alternatively, the filename and acquisition type can be specified as per the paragraph above using the executable, e.g.

get_single_trace -f "fname" -a "AVER"

Scripts in ./scripts

These can be ran as command line programmes from the scripts folder with $ python [script].py [options], where the options are as for the installed command line programmes, and can be displayed with the flag -h.