How to use¶

The VISA addresses of connected instruments can be found with $ list_visa_devices in the command line, or can be found in NI MAX or the PyVISA shell. The address should be set as the _visa_address 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 can also be used in python scripts. For example

import keyoscacquire.oscacq as koa
import matplotlib.pyplot as plt

def get_averaged(osc_address, averages=8):
    scope = koa.Oscilloscope(address=osc_address)
    time, volts, channels = scope.set_options_get_trace(acq_type='AVER'+str(averages))
    scope.close()
    return time, volts, channels

time, volts, channels = get_averaged('USB0::1234::1234::MY1234567::INSTR')
for y, ch in zip(volts.T, channels): # need to transpose volts: each row is one channel
    plt.plot(time, y, label=ch, color=koa._screen_colors[ch])
plt.legend()
plt.show()

See Instrument communication: The Oscilloscope class and Data processing and file saving 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.

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):

# -*- coding: utf-8 -*-
"""Default options for keyoscacquire"""

#: 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'
#: list of chars, e.g. ['1', '3'], or 'active' to capture all currently displayed channels
_ch_nums = 'active'
#: {HRESolution, NORMal, AVER<m>} where <m> is the number of averages in range [2, 65536]
_acq_type = "HRESolution"
#: default number of averages used if only AVER is given as acquisition type
_num_avg = 2
#: 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 _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

None of the functions access the global variables directly, but they are feed them as default arguments.

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.