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
.