This post provides information on how to configure and collect data from oscilloscopes (or other test equipment) via your PC. The example here shows how to configure, collect, process and plot data all from a single free open source application; GNU Octave.
It is simple to use and the code is attached below; plug in the oscilloscope, start up Octave, and type just one line to capture from the oscilloscope and plot to the screen. You can then give it a title and axis names and save the graphic image.
The power of Octave can be employed when you want to process the data. This filtering operation was done with a few seconds of typing at the Octave command line:
Why is this useful?
The ability to process data such as filtering as shown above is clearly useful, but beyond that, the ability to control the entire system of configuration - data acquisition - processing – viewing, from start to finish, from the PC is extremely valuable too.
Instrument control is heavily used for production test and automation, but is less often used by hardware developers. However it’s become a lot more important in recent years because test equipment has become more feature-rich so anything that can make operating test equipment easier will help. There are plenty of other reasons:
- Ideal for teaching signal processing; rapidly capture live signals (e.g. audio or RF) and perform DSP operations with PC software tools, all without needing to know the intricacies of using the scope
- Create and save test tool settings on the PC so that you can be confident that you are testing using identical settings when multitasking between projects or when sharing test tools
- Simulate part of the design before implementation, by capturing data and processing it using PC math tools
- Capture more data and traces more frequently – ideal for sharing and collaboration or for presenting data
- Ideal for setting up multiple oscilloscopes (e.g. in a lab or college) to the exact settings desired, with no mistakes due to manual configuration on the instrument
- Ideal for specific automated test at low cost (no need for commercial software)
- Ideal for working remotely from the test tool
- Ideal for extending the existing processing capabilities of a test tool; perform more advanced math operations on the data with a PC
How does it work?
Equipment manufacturers provide an application programming interface (API) known as VISA which allows software to be written on a PC to communicate to the oscilloscope or other test instruments in a standard manner, regardless of the method of access (such as USB, Ethernet or GPIB). I used Windows, but there is a different method that is possible with Linux, using a driver called USBTMC which apparently is built-in to Linux, or can be downloaded from Agilent’s site.
What devices will this work with?
It was tested with a Tektronix MSO 2024B (read the review here). It can work with other Tektronix models (1k, 2k, TDS2X0, TDS30XX, DPO4000, TDS5000, TDS5000B) with little code changes because the VISA libraries and header files for these model oscilloscopes are available. All you would need to do is replace the references to functions beginning with tkdpo2k_ with the appropriate one to suit the desired oscilloscope library and recompile. It would be trivial to make the software multi-oscilloscope compatible for all the above devices so that the oscilloscope model type becomes a command-line option (I don’t mind doing this if there is interest, but it would need people with those oscilloscope models to test it). It will also work for other manufacturer oscilloscopes with possibly small code changes assuming the VISA libraries and header files are available.
What other software is available?
Depending on the use-case, a commercial application could be more appropriate. There are commercial applications like SignalExpress and MATLAB. The latter offers an ‘Instrument Control Toolbox’ for connecting to test tools. The code that was written works for GNU Octave but may function with MATLAB too.
Code Description
The VISA driver is downloadable from the Tektronix website. When installed, it provides (in the C:\Program Files (X86)\IVI Foundation\VISA\WINNT folder) a complete set of libraries for all the supported oscilloscopes, header files, and example C program and documentation in the form of Windows help files. The information is sufficient to get coding, to create a custom application.
The information was used to create a program called scopectrl_app.exe that basically just accepts many command line options (from the Windows command prompt) and uses them as parameters for the API. The full integration into Octave is done by an intermediate program called an ‘m-file’.
What is GNU Octave, and what can you do with it?
Although the attached software can be run from the Windows command prompt, it is easier if you can control the oscilloscope from within a math program like Octave. How to do that is described next. But briefly, Octave is similar to MATLAB and the easiest way to describe it is to suggest that it is a mix of a programming language, a graphing calculator, a spreadsheet and a simulation environment for many engineering tasks. It is used by NASA and CERN; it is highly regarded open source software.
Octave together with a suitable application would therefore allow you to easily capture data from the oscilloscope, process it (e.g. filter it to remove noise) and then plot the result. You could also generate a frequency spectrum view – see the review mentioned earlier for some ideas of why this could be useful.
Configuring Octave to control your Oscilloscope
- Install any oscilloscope drivers that came with the oscilloscope, or from the manufacturer website, so that the PC will recognize when it is plugged in via USB for instance
- Install Octave (the file I installed was called octave-3.6.4-vs2010-setup.exe ) on your PC, for example into a folder such as C:\Software\Octave.
- Create a folder for your personal Octave files, such as C:\projects\octave_m_files
- Save the attached windows software into a folder, such as C:\projects\octave-scope
- Open up the file octaverc which will be in C:\Software\Octave\share\octave\3.6.4\m\startup and add a line at the end with this text (note the forward slash. Also, manually type this instead of copy-paste from here, because the quote marks might not paste with the correct ASCII value from the web page): addpath('c:/projects/octave_m_files');
- Open up the attached file called scopecapture.m and edit line 12 to suit your particular oscilloscope. Also, edit line 13 to match the path used in step 4 earlier, but do it using forward slash.
- Place the scopecapture.m file at the location in step 3 (C:\projects\octave_m_files)
Using the application within Octave
This is really easy. Start up Octave, connect a signal to channel 1 of the oscilloscope, and then type the following:
data=scopecapture(1);
It will save the oscilloscope capture into a vector called data, and will automatically plot it on the screen too. The example here shows a noisy sinewave (to demonstrate filtering further below) that was captured in this manner. The axes can be labelled with Octave (described later too).
The filtered result is shown below. The original trace was colored yellow to make it easier to view the filtered content which is pink.
If you want to control more parameters, you can type (for example)
data2=scopecapture(1, 2, 2e-6, 0.3);
The above line will capture from channel 1 again, but with a full scale voltage range of 2V, and a timebase setting of 2usec per division, and a trigger voltage level of 0.3V.
That’s it – very easy. If you want to now perform additional operations such as filtering, that is described in the reference section below, which includes a quick crash-course on some Octave commands if you need it.
If you want to experiment with processing with Octave immediately, an example capture file is in the attached .zip file. It can be read into a vector using the following syntax (use forward-slashes in Octave, not back-slash):
d=csvread('c:/path_to_file/trace1.csv');
Reference
How to use the program from the Windows command prompt
If you want to use the software directly from the Windows command line instead of Octave, or if you are looking to extend the functionality then this information will be useful to you.
Here are some command line examples. The output is saved to CSV files with hard-coded names of trace1.csv for channel 1, trace2.csv for channel 2, etc
.
1. Use defaults for everything, which configures channel 1 only, to 10msec per division and 5V per division, positive edge trigger at 0.1V and saves the capture to trace1.csv
scopectrl_app.exe --resource USB0::0x1234::0x1234::C012345::INSTR
2. Configure channels 1 and 3, so that two capture files are saved (trace1.csv and trace3.csv):
scopectrl_app.exe --resource USB0::0x1234::0x1234::C012345::INSTR --ch1 --ac --range 10 --ch2 --dc --range 20
3. Configure the trigger, disable the default channel 1 and enable channel 2 (the trace will be saved to trace2.csv)
scopectrl_app.exe --resource USB0::0x1234::0x1234::C012345::INSTR --trigtype edge --triglevel 0.5 --trigedge pos --trigsrc 1 --trigcoupling ac --ch1 --disable --ch2 --x10 --range 20
Full Command Line Options
These are the options currently supported:
scopectrl_app.exe [--option [value]] [--option [value]]... --resource <identifier> // full resource identifier, e.g. USB:xxxxxx --reset <val> // 0-1: default 1 to reset the scope --fullres // perform acquisition at full resolution --hperiod <fullperiod> // Sets the time in seconds for the entire aquisition, e.g. 0.1 sec (the default) would be 0.01 sec per div --scale <divperiod> // Sets the time per division, e.g. 0.01sec, if hperiod is not specified --minqty <val> // Sets the minimum number of points collected. Default is 1000000 --aftertrig <waittime> // Sets the time in seconds to wait after trigger (positive value) or pretrigger (negative value). Default is 0.0 --ch1 // Select and enable channel 1 for subsequent options (this is the default) --ch2 // Select and enable channel 2 for subsequent options --ch3 // Select and enable hannel 3 for subsequent options --ch4 // Select and enable channel 4 for subsequent options --chan <val> // Select and enable channel <val> for subsequent options (range is 1-4) --range <amplitude> // Selects input voltage scale. Default is 50 which is 5V per division --offset <voltage> // Select the input offset. Default is 0.0 --atten <val> // Selects the probe attenuation. Default is 10 which is for x10 probes --x10 // Selects the probe attenuation to be x10 --x1 // Selects the probe attenuation to be x1 --ac // Selects ac coupling for the input --dc // Selects dc coupling for the input --gnd // Selects gnd coupling for the input --disable // Disables the selected channel --maxbw <bandwidth> // Selects any digital filtering on input. Default is 2e7 which is 200MHz, i.e. filtering disabled on MSO2024B --trigtype <trigger_type> // Selects the trigger type. Currently supported values are edge or imm (for edge triggering or immediate triggering) --trigcoupling <coupling> // Selects the trigger coupling. Supported values are ac or dc. --trigsrc <chan_num> // Selects which channel to trigger off. Supported values currently are 1-4 --triglevel <voltage> // Selects the trigger level in volts. Default is 0.1 --trigedge <pos_neg> // Selects the edge to trigger from. Default is pos. Choices are pos or neg. --conftrig <val> // Value 0-1 which selects whether to configure the trigger options or not. Default is 1 (configure the trigger options) --confacq <val> // Value 0-1 which selects whether to configure the aquisition options or not. Default 1 configure the aquisition options) --confchans <val> // Value 0-1 which selects whether to configure the channel settings or not. Default 1 configure the channel settings) --justcapture // This option sets conftrig, confacq, confchans and reset all to zero --continue // This sets continuous capture mode --graph // This is a very experimental option which displays a live scope view window rather than saving CSV files.
As you can see, only a (popular) subset of oscilloscope features has been implemented in the code so far. It should be sufficient for many typical test scenarios however.
Quick Octave Tutorial
At the Octave command like, it can almost be used like a normal calculator:
5^2 + 3^2 ans = 34
Matrices can be written as follows (An important rule is that rows are separated by semicolons):
b=[4 5 6 7 8; 18.5 18.7 19.0 18.2 17.0] b = 4.0000 5.0000 6.0000 7.0000 8.0000 18.5000 18.7000 19.0000 18.2000 17.0000
A single row or column is known as a row or column vector:
a=[18.5 18.7 19.0 18.2 17.0] a = 18.500 18.700 19.000 18.200 17.000
c=[10; 20; 30; 40; 50] c = 10 20 30 40 50
Functions use brackets and commas much like programming languages:
plot(x,y)
A very useful function is size, you will use it a lot; it tells you the dimensions of a matrix:
size(c) ans = 5 1
Operations can be performed on matrices:
a=[0.1 0.2 0.3] a = 0.10000 0.20000 0.30000 b=10; b*a ans = 1 2 3 a+a ans = 0.20000 0.40000 0.60000
Data from (say) a data logger or an oscilloscope is likely to be a single stream of data, i.e. a vector. Although often you won’t care if it is a row or column vector, many functions do care.
You can convert from row to column (or column to row) using:
a=[1 2 3] a = 1 2 3 a' ans = 1 2 3
Custom functions can be written:
function f=period2freq(p) f=1/p; end
The function can then be run just like any in-built Octave function:
period2freq(2) ans = 0.50000
As a matter of practicality, you probably won’t want to type up many functions on the command line, but rather in text files that you can reuse. Create a folder for your work (e.g. c:\projects\octave_m_files) and you can save any functions there. The filename should be the name of the function and with a .m suffix, e.g. period2freq.m for the example above.
Then, in Octave, you can type the following to make Octave aware to search that folder:
addpath('C:/projects/octave_m_files');
If you’re going to be working with data and plotting, then this function may be helpful; it creates a vector of linearly-spaced values (the example here creates a vector of 11 elements):
linspace(-5, +5, 11) ans = -5 -4 -3 -2 -1 0 1 2 3 4 5
Plotting data
A vector of data (e.g. the changing temperature):
a=[18.5 18.7 19.0 18.2 17.0]; plot(a)
Result:
Two rows of data (e.g. the temperature at specific times between 4-8pm):
b=[4 5 6 7 8; 18.5 18.7 19.0 18.2 17.0]; plot(b(1,:), b(2,:)) title('Temperature during 4-8pm');
If you want to overlay a plot on top of an earlier one, type
hold on;
to freeze the current plot.
To plot in a different color (yellow, red, green and magenta):
plot(data, 'y'); plot(data, 'r'); plot(data, 'g'); plot(data, 'm');
Filtering Data
Filtering is one of the most common things you might want to do (there are other ways – here is the simplest (it is performing convolution with a rectangular window), it assumes that the column vector ‘d’ contains the input data that you wish to filter):
z=ones(1,10); q=conv(d, z, 'same'); plot(q/10);
Building the Code
There is a makefile that can be inspected to see the build details. Note that the code uses two functions that require three files listed below which are part of NI LabWindows/CVI 2013 and can be freely downloaded from the NI site. Two functions are used: Delay(), and Scan() (which is similar to scanf()). The first is easily replaced if you don’t want to rely on the NI code, it is just a delay function. The second should be feasible too, although the documentation on the format codes for Scan were a little unclear. However, the supplied demo source code actually uses these functions, so I don’t believe there is any violation in using them. If you feel uncomfortable with this, then you will need to replace the functions. I have not published the files (you will need to download LabWindows/CVI if you want these files just in case there is a violation). According to this link it is legally ok to link to the library file under circumstances, but it doesn’t explain them; but in theory you may be fine to link for 30 days which is the evaluation period.
Files needed: cvirte.h, cvidef.h, cvirt.lib
The source code (minus those files which you can download from NI's site), and the executable is attached. An example oscilloscope capture is inside the zip file if you wish to experiment with Octave without an oscilloscope.