$Id: README,v 1.35 2010/12/06 23:27:31 tw Exp $

Copyright (C) 2008 - 2010 Thomas Weidenfeller


gds2000tools

_________________
Table of Contents

1 INTRODUCTION
2 LICENSE
3 REQUIRED READINGS
4 HARDWARE SETUP
5 PREREQUISITES
6 INSTALLATION
7 USAGE

______________
1 INTRODUCTION

gds2000tools is a set of free, simple UNIX/Linux software tools for the

	* GW Instek GDS-2000 series oscilloscopes (GDS-2062, GDS-2064,
	  GDS-2102, GDS-2104, GDS-2202, GDS-2204).

The tools should also work (not tested) with the

	* GW Instek GDS-800 series oscilloscopes (GDS-806, GDS-810,
	  GDS-820, GDS-840)

	* GW Instek GDS-1000 series oscilloscopes (GDS-1022, GDS-1042,
	  GDS-1062, GDS-1102)

	* GW Instek GDS-1000A series oscilloscopes (GDS-1062A, GDS-1102A,
	  GDS-1152A)

	* ISO-TECH IDS-8000 series oscilloscopes (IDS-8062, IDS-8102,
	  IDS-8104, IDS-8202, IDS-8204)

	* ISO-TECH IDS-6000A series oscilloscopes (IDS-6062A, IDS-6102A,
	  IDS-6152A)

	* ISO-TECH IDS-6000 series oscilloscopes (IDS-6022, IDS-6042)

	* Voltcraft-plus DSO-4000 series oscilloscopes (DSO-4022,
	  DSO-4042, DSO-4062, DSO-4102),

	* Voltcraft-plus DSO-4000A series (DSO-4062A, DSO-4152A),

	* Voltcraft-plus DSO-8000 series oscilloscopes (DSO-8062,
	  DSO-8064, DSO-8104, DSO-8204)

	* Tenma 72-7235, 72-7240 

The GDS-3000 series, the GDS-122, and the GRS-6000A series are not
supported.


The tools in gds2000tools are:

	gdsh	A set of bash shell functions to create a special shell
		for sending and receiving data to/from the oscilloscope.

		This allows a user to interactively configure the
		oscilloscope and to obtain data from it. It further allows
		to automate task by scripting them, using the well-known
		bash scripting language with the gdsh functions.

		Some features are:

		* Most GDS-8x0, all known GDS-1000, GDS-100A and GDS-2000
		  request and query commands as defined in the programming
		  manuals are supported.

		  In total 170 oscilloscope commands are available
		  in gdsh.

		* Several undocumented commands are supported

		* Obtaining screen snapshots (gds-snapshot function)

		* Obtaining the waveform data in CSV format (gds-csv
		  function) for further processing in spreadsheets or
		  analysis programs (e.g. in GNU octave with gds-octave)

		* Plotting waveform data (gds-plot function)

		* Syncing the oscilloscope's date and time from the
		  computer's system time (gds-sync* functions)

		* Obtaining information about the instrument

		* Decoding the instrument's event status enable and
		  service request enable register

		* Obtaining measurements. Either as single measurements or
		  at fixed intervals. 25+ measurement types are supported
		  (gds-measure function).

	gds-bandwidth	gds-channels	gds-csv		gds-firmware
	gds-flush	gds-measure	gds-plot	gds-query
	gds-read-bin	gds-send	gds-serialnum	gds-snapshot
	gds-sync	gds-sync-date	gds-sync-time	gds-template-get
	gds-type	gds-vendor	gds-version
		Shortcuts to gdsh functions of the same name.

	gds-read-bin
		A filter for reading binary waveform data and binary
		screen snapshot data from the oscilloscope and convert
		the data to ASCII, or in case of screen snapshots, to
		BMP images. gdsh uses this filter. The filer is normally
		not called directly, but used by gdsh.

	gds-octave
		A package for the GNU octave numerical computation
		language. It contains functions to read and write
		oscilloscope waveform data into GNU octave and process it.

	gds-analyse
		A wrapper around the gds_analyse function from the
		gds-octave package for direct access to that function.

	gds-csv-to-afg
		Converts GDS oscilloscope CSV waveform data to GW
		Instek AFG-3000 function generator data formats.

		This allows to replay waveforms captured on the
		oscilloscope with the function generator.

	gds-csv-to-rigol
		Converts GDS oscilloscope CSV waveform data to Rigol
		UltraWave DG series function generator file formats.

		This allows to replay waveforms captured on the
		oscilloscope with the function generator.

	gds-udev
		udev(1) rules to provide GDS oscilloscopes connected via
		USB with reproducible device names.

	gds-csv-info
		Displays GDS .csv file information in a window.

_________
2 LICENSE

gds2000tools 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 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.  If not, see <http://www.gnu.org/licenses/>.


See the file COPYING for a copy of the GPL version 3. Please note that
gds2000tools comes *without* the option to select a later version of
the GPL.

___________________
3 REQUIRED READINGS

The following documents are required readings to make successful usage
of the tools:

	* Manual pages

		man gdsh
		man 7 gdsh  (or man -s 7 gdsh)
		man gds-octave
		man gds-analyse
		man gds-csv-to-afg
		man gds-csv-to-rigol
		man gds-udev
		man gds-csv-info

	* Familiarity with one of the following manuals, depending on
	  the type of oscilloscope, is also required.  You will not be
	  able to use most of the software without.

		* GDS-806/810/820/840 Programming Manual. VA.
		  Good Will Instrument Co., Ltd. 2006/5/25.

		* GDS-1000 Series Programming Manual. V0.
		  Good Will Instrument Co., Ltd. 2007/11/20.

		* GDS-1000A Series Programming Manual. 82DS-1102AI01.
		  Good Will Instrument Co., Ltd. May 2009 edition.

		* GDS-2000 Series Programming Manual. V0.
		  Good Will Instrument Co., Ltd. 2006/12/13.

	  All manuals could be obtained from the GW Instek web site in
	  the past. Instek moved them around a few times.

________________
4 HARDWARE SETUP

The tools should support the RS232 and the USB interface. The USB
interface in the GDS-2000 series oscilloscopes implements a serial
interface (CDC-ACM USB profile). Current Linux and BSD distributions
already come with the necessary driver to handle the profile and provide
the mapping to a "terminal" device. It is highly recommended to use the
USB connection for performance reasons.

_______________
5 PREREQUISITES

At least the following items are needed:

	* A supported oscilloscope

	* The software listed in the following sections.

__________________________________________
5.1 Ubuntu and similar Linux Distributions

The following command is supposed to install all possibly missing
prerequisites on Ubuntu-like systems. But see the following section
5.2, too.

	sudo apt-get install build-essential bash gnuplot-x11 octave3.2	\
				octave-io octave-signal			\
				octave-missing-functions octave-specfun	\
				octave-optim extra-xdg-menus groff	\
				zenity ghostscript eog nautilus		\
				nautilus-script-manager xdg-utils

___________________________________
5.2 Prerequisite Software in Detail

* GNU make

* gcc - GNU C compiler

* bash 3.0 or later

* gnuplot <http://www.gnuplot.info/>

* eog or another image viewer capable of displaying BMP images

* Optional, if waveform analysis is desired:
	
	- GNU Octave 3.0.1 or later

	- Octave-Forge 'io' package

	- Octave-Forge 'signal' package, which in turn requires the

	     - Octave 'specfun' package, which in turn requires the

		 - Octave 'optim' package

	- Octave-Forge 'miscellaneous' package

  The Octave-Forge package can be found at
  <http://octave.sourceforge.net/packages.html> or typically in
  a Linux distribution's repository.

* Optional, if supported by the distribution (and if an "Electronics"
  menu category should be used for the desktop integration)

	- exmenen(1) (e.g. from extra-xdg-menus)

* GNU versions of misc. Unix text processing tools

* groff formatter, ghostscript postscript/pdf rasterizer

* A udev enabled system, if the udev rules should be installed

* For the desktop integration

	- a freedesktop.org compatible desktop with XDG utilities

	- gds-csv-info needs zenity(1) and is supposed to be
	  started from nautilus(1)

______________
6 INSTALLATION

* Ensure the tools listed in PREREQUISITES are installed.

* If waveform analysis with GNU octave is desired:

	- Install GNU octave 3.0.1 or later before building and
	  installing gds2000tools.

	  Many Linux distributions already have GNU octave and octave
	  packages in their repository. E.g. see section 5.1 above.

	- Install the required octave packages, too. Either from a package
	  repository (see section 5.1 above), or obtained from
	  <http://octave.sourceforge.net/packages.html>.

	  If obtained from <http://octave.sourceforge.net/packages.html>
	  install them as superuser or for each user.

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

	  As superuser:

		Become super user

		octave --eval "pkg install -global io-x.x.x.tar.gz;"
		octave --eval "pkg install -global optim-x.x.x.tar.gz;"
		octave --eval "pkg install -global specfun-x.x.x.tar.gz;"
		octave --eval "pkg install -global signal-x.x.x.tar.gz;"
		octave --eval "pkg install -global miscellaneous-x.x.x.tar.gz;"

	  Or for each user:

		Become the particular user

		octave --eval "pkg install -local io-x.x.x.tar.gz;"
		octave --eval "pkg install -local optim-x.x.x.tar.gz;"
		octave --eval "pkg install -local specfun-x.x.x.tar.gz;"
		octave --eval "pkg install -local signal-x.x.x.tar.gz;"
		octave --eval "pkg install -local miscellaneous-x.x.x.tar.gz;"

	- Set HAS_OCTAVE in config.mk to 1 before building and installing
	  gds2000tools.

* Edit the installation section in the file config.mk in this
  directory

* Build gds2000tools by running

	make clean
	make

  from this directory.

* If configured to be installed in a public directory (default in config.mk)
  become superuser in the build directory and install

  	su -c "make install"
  or
        sudo make install

* Create a $HOME/.gdshrc file with the following contents if automatic
  connection to the oscilloscope is desired when gdsh is started

	  GDSH_CONNECT_AT_START=1
	  GDSH_SYNC_DT_AT_START=0
	  GDSH_DEV=<device to which oscilloscope is connected, e.g /dev/ttyACM0>

  Note 1: See gdsh(1) for a description of these environment variables
          and .gdshrc

  Note 2: Only one user at a time can use a particular oscilloscope.

  Note 3: If gds-udev(7) was installed, using a reproducible device name
	  /dev/<model>-<serialnumber> instead of a kernel-assigned name
	  like /dev/ttyACM0 is recommended.

  Note 4: The above configuration is required if the stand-alone
	  versions of some gdhs(1) functions, like gds-snapshot, are to
	  be used.

* If gds-csv-info is supposed to be used as a nautilus(1) script:

	- If the nautilus script manager is installed

		nautilus-script-manager enable gds-csv-info

	- else

		mkdir -p $HOME/.gnome2/nautilus-scripts
		ln -s /usr/share/nautilus-scripts/gds-csv-info $HOME/.gnome2/nautilus-scripts

_______
7 USAGE

The main tool is gdsh. It runs the bash shell with a set of function
extensions to communicate with the oscilloscope. See the gdsh(1) manual
page for details. Here is a longer example of an interactive usage of
gdsh. "gdsh@" is the default prompt of gdsh, text after "gdsh@" is user
input, '#' indicates normal bash comments:

	$ gdsh

	GDSH vx.x - GDS-2000 series (and others) oscilloscope shell

	gdsh@ gds-open /dev/ttyACM0 # depends on actual HW setup
	gdsh@ _rst               # reset oscilloscope to defaults
	gdsh@
	gdsh@ # Timebase / horizontal configuration and trigger
	gdsh@ :tim:scal 1e-4     # 100 micro-sec/div
	gdsh@ :tim:del 150e-6    # start displaying 150 micro-sec earlier
	gdsh@ :trig:coup 0       # AC coupling for trigger
	gdsh@ :trig:mod 2        # trigger mode: normal
	gdsh@ :trig:sour 1       # trigger source channel 2
	gdsh@
	gdsh@ # Channel 1 configuration
	gdsh@ :chan1:disp 1      # activate channel
	gdsh@ :chan1:coup 0      # AC coupling
	gdsh@ :chan1:prob 1      # 10x probe
	gdsh@ :chan1:scal 5e-2   # 50mV/div vertical
	gdsh@
	gdsh@ # Channel 2 configuration
	gdsh@ :chan2:disp 1      # activate channel 2
	gdsh@ :chan2:coup 1      # DC coupling
	gdsh@ :chan2:prob 1      # 10x probe
	gdsh@ :chan2:scal 1      # 1V/div vertical
	gdsh@
	gdsh@ # Prepare acquisition
	gdsh@ :acq:mod 2         # acquisition mode: average
	gdsh@ :acq:aver 3        # average over 8 values
	gdsh@ :acq:leng 0        # 500 measurement values/channel
	gdsh@ 
	gdsh@ # Get ch1 and ch2 data, scale horizontal (-h) and
	gdsh@ # vertical (-V) correct. Store result in
	gdsh@ # one file, no headers (-0)
	gdsh@ :stop              # ensure channel data is from same time
	gdsh@ for ch in 1 2
	gdsh@ do
	gdsh@     :acq${ch}:mem_ -0 -h -V $(:chan${ch}:scal_) >> data.txt
	gdsh@     echo "e" >> data.txt     # place a separator in file
	gdsh@ done
	gdsh@ 
	gdsh@ # Get the ch1 data in .csv format
	gdsh@ gds-csv 1 > data1.csv
	gdsh@ :run 
	gdsh@ 
	gdsh@ # View the acquired ASCII data
	gdsh@ # There is a normal bash behind gdsh, so all
	gdsh@ # normal Unix/Linux commands can be launched.
	gdsh@ ls data.txt
	data.txt
	gdsh@ less data.txt
	...
	gdsh@ 
	gdsh@ # To learn more about gdsh
	gdsh@ man gdsh
	...
	gdsh@ 
	gdsh@ # To learn more about oscilloscope functions in gdsh
	gdsh@ man 7 gdsh
	gdsh@ 
	gdsh@ gds-close 
	gdsh@ exit

gds2000tools also comes with a few GNU octave function for analyzing
data from a file:

	# A simple front-end for some of the functions

	$ gds-analyse

	# Manually using GNU octave to analyse a waveform

	$ octave
	octave:1> # Load waveform data from an oscilloscope .csv file
	octave:1> # into a structure called gs
	octave:1> gs=gds_csvread("data1.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
	octave:4> 
	octave:4> # Plot spectrum of data
	octave:4> gds_plotspectrum(gs);
	octave:5>
	octave:5> exit

See gds-octave(1), gds-analyse(1) and the PDF versions of those
man pages. The PDF versions are typically installed in

	/usr/share/octave/packages/gds-octave-x.x.x/doc/
or

	~/octave/gds-octave-x.x.x/doc/

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

gds-read-bin is a tool used internally by gdsh. For example, the gdsh
functions gds-snapshot, :acquire<X>:[l]memory?, :display:output?, and
others use it to convert binary data from the oscilloscope. It can also
be used stand-alone. See gds-read-bin(1) for details.

gds-csv-to-afg converts GDS oscilloscope waveform data from the
.csv format into one of several formats understood by GW Instek's AFG-3000
series function generators.
This allows to replay a signal captured with the oscilloscope
on the generator. See gds-csv-to-afg(1) for details.

	gdsh@ gds-csv 1 | gds-csv-to-afg     \
		-t afg3051                   \
		-d                           \
		-o /media/usbstick/wave1.csv \
		--                           \
		-

gds-csv-to-rigol converts GDS oscilloscope waveform data from the
.csv format into one of several formats understood by Rigol DG waveform
generators. This allows to replay a signal captured with the oscilloscope
on the generator. See gds-csv-to-rigol(1) for details.

	gdsh@ gds-csv 1 | gds-csv-to-rigol   \
		-t dg1000                    \
		-d -m                        \
		-o /media/usbstick/wave1.rdf \
		--                           \
		-

gds-udev, if installed works behind the scenes. There is nothing to call
or execute by the user. See gds-udev(1) for details.

gds-csv-info can be started from the command line or from nautilus. See
gds-csv-info(1) for details.

	$ gds-csv-info /media/usbstick/*


				* * *
