gds-octave(7)

NAME
gds-octave - GDS oscilloscope functions for Octave

DESCRIPTION
gds-octave(7) is a package for octave(1), containing functions for reading and processing GW Instek GDS oscilloscope waveform data within GNU octave(1). The most interesting function for getting started might be the interactive analysis tool gds_analyse. This tool can also be started directly from the command line as gds-analyse(1).

GNU octave(1) is a high-level interactive language for numerical computation.

octave(1) and gds-octave(7) are not capable of directly communicating with an oscilloscope. Instead the data needs to be available in files. The file format needs to be the .CSV format as stored by the oscilloscope on a USB memory stick or an SD card. Alternatively, gds-csv in gdsh(1) can create data in this format.

FUNCTIONS
The following is a list of octave functions as provided by gds-octave. Several of the functions include demo code that can be run with

    $ octave
    demo("function-name")

from within octave. Also, the octave help command provides more information.

    $ octave
    help function-name

gds_ac
    Returns the AC component of the waveform. That is, the DC component is removed from the signal.

gds_am
    Simple AM demodulator.

gds_analyse
    Interactive waveform data analysis tool.

gds_bitrate
    Estimate bitrate of a binary baseband signal.

gds_csvread
    Reads data from a GDS-oscilloscope .csv data file.

gds_csvwrite
    Write data to a file in GDS-oscilloscope .csv data format.

gds_eye
    Plots an eye diagram.

gds_dc
    Returns the DC value of the DC component of the signal in Volts.

gds_fm
    Simple FM demodulator.

gds_inv
    Invert waveform data.

gds_plot
    Plot GDS oscilloscope data.

gds_plotspectrum
    Plots the spectrum of GDS oscilloscope data.

gds_sign
    Calculates a rectangular signal, representing the sign (-1 V, 0 V, 1 V) of a waveform.

gds_spectrum
    Calculates the frequency spectrum of GDS oscilloscope data. Depending on usage also plots the data via gds_plotspectrum.

gds_struct2val
    Converts the waveform sample data from a gds data structure into a vector containing the corresponding values. The function takes the vertical units and the samples/div. into account.

gds_val2wd
    Converts values into waveform sample data, taking the samples/div. into account.

gds_wd2v
    Deprecated. Use gds_struct2val instead.

    Converts the waveform sample data out of a data structure into a vector containing the corresponding voltages. The function takes the vertical units and the samples/div. into account.

gds_wd2val
    Converts waveform sample data into a vector containing the corresponding values, taking the samples/div. into account.

gds_zcross
    Calculate and plot zero crossings of waveform data.

HELPER FUNCTIONS

gds_fmenu2
    Displays a two-column ``pick a number'' menu. The per-selection return values are configurable.

gds_menu2
    Displays a two-column ``pick a number'' menu. Similar octave's single-column menu function.

INSTALLATION
gds-octave(7) requires the installation of several octave(1) packages, available from <http://octave.sourceforge.net/packages.html> or from a particular Linux's package repository. The required packages are

io  Input/Output in external formats.

signal
    Signal processing tools, including filtering, windowing and display functions.

miscellaneous
    Miscellaneous tools.

Further, the following package is recommended, too.

communications
    Functions for processing communication signals.

The packages are installed as follows

    octave --eval "pkg install io-x.x.x.tar.gz;"
    octave --eval "pkg install signal-x.x.x.tar.gz;"
    octave --eval "pkg install miscellaneous-x.x.x.tar.gz;"
    octave --eval "pkg install communications-x.x.x.tar.gz;"

Replace x.x.x with the actual version numbers of the packages.

The gds-octave package file can be installed as follows.

    octave --eval "pkg install gds-octave-x.x.tar.gz;"

Replace x.x with the actual version number of gds-octave(7).

Within the gds2000tools build environment gds-octave(7) can also be installed with make(1):

    make install

FILES

$HOME/.gds-analyserc
    Configuration file used by gds_analyse.

gds-octave-x.x.tar.gz
    Octave package with GW Instek GDS-series oscilloscope functions.

<data>.csv
    Data file containing oscilloscope waveform data. The format is the one written by the oscilloscope to an USB memory stick or SD card.

  File Format
A typical GDS oscilloscope .csv file consists of two sections. The first section of the file documents the acquisitions settings which were used when the data was obtained. The second section contains the waveform data. The start of the second part is indicated by the single statement Waveform Data. A typical .csv file looks as follows.

    Memory Length,500
    Trigger Level,1.360E+00
    Source,CH1
    Vertical Units,V
    Vertical Scale,5.000E-01
    Vertical Position,-9.600E-01
    Horizontal Units,s
    Horizontal Scale,2.500E-04
    Horizontal Position,0.000E+00
    Horizontal Mode,Main
    Sampling Period,1.000E-05
    Firmware,V1.0
    Time,11-Jun-09 19:08
    Waveform Data
    1.98
    0.02
    <in total Memory Length lines of data>

Note, however, that some oscilloscope firmware versions create slightly different files, because of firmware bugs. One typical deviation contains superfluous empty data fields in each line of the .csv file. gds_csvread is capable of handling such files, and corrects a few problems.

BUGS
gds_csvread can be rather slow. This depends on the length of the data to be read.

The checks if a .csv file is complete and correct are only rudimentary.

Labeling of plot windows is inconsistent.

In particular gds_analyse does very few error checks.

EXAMPLES

NOTE:
    The PDF version of this manual page contains illustrations not present in this version.

The following example demonstrates how to plot some amplitude modulated data and the corresponding demodulated signal on a single plot.

    gs = gds_csvread("DS0013.CSV");
    subplot(2,1,1);
    gds_plot(gs);
    subplot(2,1,2);
    gds_am(gs);

The following example demonstrates how to start the interactive analysis tool from within octave. CSV files should be available in some working directory (here /media/GDS) before invoking the tool. The interface is an old-fashioned ASCII pick-a-number interface, since octave by default doesn't come with a GUI interface.

    octave:1> gds_analyse("/media/GDS")
                    _                             _
                   | |                           | |
           __ _  __| |___ ______ __ _ _ __   __ _| |_   _ ___  ___
          / _` |/ _` / __|______/ _` | '_ \ / _` | | | | / __|/ _ \
         | (_| | (_| \__ \     | (_| | | | | (_| | | |_| \__ \  __/
          \__, |\__,_|___/      \__,_|_| |_|\__,_|_|\__, |___/\___|
           __/ |                                     __/ |
          |___/                                     |___/
    --- Select input file ---
    Directory: /media/GDS
      [ 1] -QUIT-                          [ 6] DS0086.CSV
      [ 2] -CHANGE DIRECTORY-              [ 7] DS0089.CSV
      [ 3] DS0008.CSV                      [ 8] DS0090.CSV
      [ 4] DS0084.CSV                      [ 9] DS0091.CSV
      [ 5] DS0085.CSV
    pick a number: 4

The following example demonstrates how to load data, and access information from the data structure.

    octave:1> # Load waveform data from an oscilloscope .csv file
    octave:1> # into a structure called gs
    octave:1> gs = gds_csvread("DS0008.CSV");
    octave:2>
    octave:2> # Lookup some info from the just read data
    octave:2> gs.Memory_Length
    ans =  500
    octave:3> gs.Source
    ans = CH1

The following example uses the pwelch function from octave's signal processing package to estimate the power spectral density of some sampling data, using the Welch periodogram/FFT method.

    gs = gds_csvread("DS0010.CSV");
    pwelch(gs.Waveform_Data,[],[],[],1/gs.Sampling_Period,"dB");

The following example demonstrates how to quickly plot a spectrum from previously acquired oscilloscope data.

    gs = gds_csvread("DS0008.CSV");
    gds_spectrum(gs);

The following example demonstrates how to plot some data and its spectrum on a single plot.

    gs = gds_csvread("DS0008.CSV");
    subplot(2,1,1);
    gds_plot(gs);
    subplot(2,1,2);
    gds_plotspectrum(gs);

The next example demonstrates the gds_sign function.

    gs = gds_csvread("DS0084.CSV");
    sgn = gds_sign(gs);
    gds_plot(gs);
    hold on;
    gds_plot(sgn);

In the following example the raw waveform data as read into the gs structure is converted to absolute voltages.

    octave:1> gs = gds_csvread("DS0012.CSV")
    gs =
    {
      Memory_Length =  500
      Trigger_Level = 0
      Source = CH4
      Vertical_Units = V
      Vertical_Scale =  0.20000
      Vertical_Position = -0.0080000
      Horizontal_Units = s
      Horizontal_Scale =  5.0000e-07
      Horizontal_Position = 0
      Horizontal_Mode = Main
      Sampling_Period =  2.0000e-08
      Firmware = V1.04
      Time = 17-Jul-09 14:05
      Waveform_Data =
         -3
          6
         14
         21
         30
         37
         45
         49
         55
         59
    :q
    octave:2> v = gds_wd2v(gs)
    v =
      -0.0320000
       0.0400000
       0.1040000
       0.1600000
       0.2320000
       0.2880000
       0.3520000
       0.3840000
       0.4320000
       0.4640000
    :q
    octave:3>

The following example demonstrates how write some data to a file in the oscilloscope's .CSV format. It sets the minimum required data structure fields. As the following gds_csvread shows, gds_csvwrite uses defaults for the fields which were not supplied.

    octave:1> out.Waveform_Data = [ 1 2 3 4 ];
    octave:2> out.Vertical_Scale = 1;
    octave:3> out.Horizontal_Scale = 1; # or specify Sampling_Period
    octave:4> gds_csvwrite("simple.csv", out)
    octave:5> in = gds_csvread("simple.csv");
    in =
    {
      Memory_Length =  4
      Trigger_Level = 0
      Source = gds-octave
      Vertical_Units = V
      Vertical_Scale =  1
      Vertical_Position = 0
      Horizontal_Units = s
      Horizontal_Scale =  1
      Horizontal_Position = 0
      Horizontal_Mode = Main
      Sampling_Period =  0.040000
      Firmware = V1.00
      Time = 18-Jul-09 17:18
      Waveform_Data =
         1
         2
         3
         4
    }

Print the original and inverted waveform.

    gs = gds_csvread("DS0008.CSV");
    gds_plot(gs, gds_inv(gs));

SEE ALSO
gdsh(1), gds-analyse(1), octave(1).

COPYRIGHT
Copyright © 2009, 2010 Thomas Weidenfeller

gds2000tools/gds-octave is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License version 3 as published by the Free Software Foundation.

gds2000tools/gds-octave is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with gds2000tools/gds-octave.
If not, see <http://www.gnu.org/licenses/>.