gdsh(1)

NAME
gdsh - GW Instek (and others) oscilloscope shell

SYNOPSIS
gdsh bash-options ...

DESCRIPTION
gdsh extends a bash shell with additional shell functions to communicate with

•   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),

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

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

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

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

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

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

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

•   Tenma 72-7235, or Tenam 72-7240 oscilloscopes.

Most documented, plus several undocumented, oscilloscope commands are provided via gdsh shell commands (see gdsh(7)). This allows to invoke oscilloscope commands right from an interactive shell, as well as scripting command sequences and more advanced measurement procedures, having the full power of a bash shell at hand. In fact, gdsh comes with a number of high-level functions, which are implemented this way on top of the oscilloscope commands.

  Connecting to the Oscilloscope
The oscilloscope needs to be connected to the computer either via RS232 or USB. It is highly recommended to use USB. In case USB is used, the USB driver module cdc_acm (Linux), umodem(4)/ucom(4) (BSD), usbsacm(7D)/usba(7D) (Solaris), or a similar module implementing the CDC-ACM USB profile must be present and loaded (the default behavior on most modern *ix operating systems).

In case the oscilloscope is connected via USB, the connection is opened from within gdsh with the

    gds-open [-u] [/dev/tty usb-dev]

command. In case the oscilloscope is connected via RS232, the connection is opened with the

    gds-open [-s] [/dev/tty rs232-dev] [baud] [parity] [stopbits]

command.

It is possible to configure gdsh to automatically try to open a connection at startup. See the description of the GDSH_CONNECT_AT_START, GDSH_DEV, and GDSH_DEV_TYPE environment variables in the section ENVIRONMENT below. The stand-alone shortcut scripts to gdsh functions of the same name require such a configuration.

  Commands, Requests & Queries

Command
    A command is either a request or a query.

Request
    A request is a command instructing the oscilloscope to change something. A request does not return information.

Query
    A query is a command that asks for some information from the oscilloscope. Query commands end in a '?' or (gdsh specific) alternatively in a '_'.

gdsh provides the oscilloscope commands in the form of shell functions. These shell functions can directly be interactively invoked form the gdsh command line. They can also be used in gdsh scripts. Most documented, plus several undocumented, oscilloscope commands are supported. Familiarity with the oscilloscope commands (see GW Instek's programming manuals) is a prerequisite to successfully use gdsh. See gdsh(7) for a comprehensive description of the commands.

gdsh provides a number of other functions in addition to the oscilloscope commands. These functions are described in the subsection GDS Functions below. For many of these functions gdsh comes with stand-alone shell script shortcuts, so these functions can also be called as if they are separate programs from other programs or a normal shell.

  GDS Functions

gds-avail
    Provides a list of potential device names to which an oscilloscope might be connected. Please note the words "potential" and "might". There is no guarantee that an oscilloscope is connected to the listed devices.

gds-open [-h] [([-u] usb-device) | ([-s] rs232-device [baud] [parity] [stopbits])]
    Opens the device for operation and returns the file descriptor assigned to the device. The device name can be omitted if the environment variable GDSH_DEV is set to the preferred device. baud, parity, and stopbits are ignored if the device name looks like a USB COM-ACM device (ACM, USB, GDS, or ttyU in the device name) or if the -u option is provided.

    The default values for RS232 devices are taken from the environment variables GDSH_DEV_BAUD, GDSH_DEV_PARITY, and GDSH_DEV_STOPBITS. If any of the variables is not defined, then the value 19200, N, or 1 is used as default instead. The commandline arguments always override the defaults.

    Possible values for parity are n, N, e, E, o, O for none, even and odd respectively. Possible values for stopbits are 1, and 2.

    Possible options are

    -h  Short help text.

    -u  Force to use USB communication default parameter.

    -s  Force to use RS232 communication default parameter for those not provided on the command line.

    The environment variable GDSH_DEV_TYPE can be set to either s, u, or ?, corresponding to the -s, or -u command line option, or to no command line option.

    See also gds-use for information of how to use the returned file descriptor if multiple instruments are in use. A successful call to gds-open implies a call to gds-use.

gds-use [fd]
    Switch to another instrument. All following commands are directed to that instrument. The instrument had to be opened previously with gds-open. The fd argument is the file descriptor value as returned by gds-open, for example obtained and stored in a variable with

    OSC1=$(gds-open ...)

    If no fd argument is provided, then the currently used file descriptors (if any) and the devices associated with the descriptors (if any) are returned. The currently active one is marked with a '*'.

gds-is-open [fd]
    Check if the communication device is open. If a file descriptor argument fd is provided then it is checked if a device is associated with that descriptor and if that device is open. If no argument is provided, then the device currently selected via gds-use is checked.

gds-close [fd]
    Close the oscilloscope's communication device. If a file descriptor argument fd is provided, then that device is closed. Otherwise the device currently selected via gds-use is closed.

gds-flush [fd]
    Read and discard possible oscilloscope output. All output that is sent by the oscilloscope not further apart than one second is discarded. If a file descriptor argument fd is provided, then that device is flushed. Otherwise the device currently selected via gds-use is flushed.

gds-read-silent
    Read a response line from the oscilloscope, but don't echo it to standard output. The line is stored in the environment variable GDSH_RESP only.

gds-read
    Read a response line from the oscilloscope. The response is echoed to standard output and the line is stored in the environment variable GDSH_RESP, too.

gds-query-silent query...
    Send a query, expect a single-line ASCII response in GDSH_RESP only.

gds-query query...
    Send a query, expect a single-line ASCII response. The response is echoed to standard output and also stored in the environment variable GDSH_RESP. This function is useful in case a direct shell function for some query is missing for whatever reasons.

gds-query-bin query [gds-read-bin-arguments]
    Send a query, expect a binary response. The response is converted with gds-read-bin(1) in accordance with the provided gds-read-binarguments.

gds-send (query|request) [arguments...]
    Generic send of a command. This function is useful in case a direct shell function for some command is missing for whatever reasons.

    If the command is a query (indicated by the command ending in '?' or '_', or by the first argument being '?' or '_'), then the query is redirected to gds-query. Else it is assumed the command is a request, and the request is just send, without expecting a response.

gds-send-bin (query|request) [arguments...]
    Generic send of a command. If the command is a query (indicated by the command ending in '?' or '_', or by the first argument being '?' or '_'), then the query is redirected to gds-query-bin (expecting a binary response). Else it is assumed the command is a request, and the request is just send, without expecting a response.

gds-measure [-h] [-f] [-s sec] [-p timestamp-format] [-F fieldsep] [-L lines] [-0] (ch (measure...))...
    Obtain one or more measurements from the oscilloscope. Either a single set of measurements or continuous measurements can be obtained. The format of the output differs, depending on single or continuous measurement.

    Note: At least firmware V1.04 has the habit of sometimes returning transient values for measurements, typically a zero, although there is a nice and stable input signal. It is not a problem of gdsh-measure, but of the instrument.

    Run gds-measure -h in gdsh(1) to get information about the command line arguments and options.

gds-sync-time
    Synchronize (set) the oscilloscope's time with the current system time.

    Note: The oscilloscope can take up to a minute to display the new time.

gds-sync-date
    Synchronize (set) the oscilloscope's date with the current system date.

    Note: The oscilloscope can take up to a minute to display the new date. The date display is only updated when the time display advances to the next minute.

gds-sync
    Synchronize (set) the oscilloscope's date and time with the current system date and time.

    Note: The oscilloscope can take up to a minute to display the new values.

gds-template-get nbr
    Read the go/no-go template with the number nbr from a GDS-8x0 oscilloscope.

    This uses the TEMPlate<X>:DOWNload? query to fetch the template.

    Note: The TEMPlate<X>:DOWNload? query is also available on GDS-2000 series oscilloscopes. However, experience is that the query, at least for firmware v1.04 and v1.09, returns unusable empty data sets from GDS-2000 oscilloscopes.

gds-csv [-h] [-b] [-F fs] [-l] channel-number
    Returns the current measurement data as comma-separated value list, similar to the one the oscilloscope's SAVE/RECALL function stores on a USB stick or SD card.

    Note 1: The GDS's programming interface does not allow to retrieve all data which can be found in CSV files stored directly on a USB stick or SD card. gds-csv either guesses the missing data or just doesn't provide it.

    Note 2: When reading from the GDS-1000A's long memory the continuous acquisition should be stopped (:stop) before reading the data, since the oscilloscope only returns long memory data when stopped.

    Note 3: The GDS-1000A's detail CSV format is not supported.

gds-manufacturer
    Returns the manufacturer field from the identification query. That should usually be the strings GW.

gds-vendor (deprecated)
    Returns the oscilloscope manufacturer. This is the old version of the gds-manufacturer command. gds-manufacturer should be preferred.

gds-model
    Returns the model field of the identification command.

gds-type (deprecated)
    Returns the model field of the identification command. This is the old version of the gds-model command. gds-model should be preferred.

gds-serialnum
    Returns oscilloscope's serial number from the identification command.

gds-version, gds-firmware
    Returns oscilloscope's firmware version. Should not be confused with the gdsh-version function.

gds-channels [-h|-e|-a]
    Returns the number of oscilloscope channels or enumerate them. Depending on the options the function returns the total number of available channels (no option), the above information as an enumeration (list) of channel numbers (-e), or an enumeration of the active (turned on) channels (-a).

    Note: This information is partly extracted from the oscilloscope type information. Changes in firmware, e.g. for OEM versions of the oscilloscope, might result in incorrect information.

gds-bandwidth
    Returns the bandwidth of the oscilloscope.

    Note: This information is extracted from the oscilloscope type information. Changes in firmware, e.g. for OEM versions of the oscilloscope, might result in incorrect information.

gds-is-1000A
    Returns true (exit code 0) if the oscilloscope is from the GDS-1000A series. Otherwise false (exit code 1) is returned.

gds-snapshot [-h] [-c colormap] [-n] [--] [image.bmp]
    Fetches a screen snapshot from the oscilloscope and stores it as a BMP image file, or shows it in the default/configured (GDSH_IMGVIEWER environment variable) image viewer for gdsh(1).

    Run gds-snapshot -h in gdsh(1) for more information.

gds-plot [-f format] [-t title] [-c comment] [ch ...] [--] [file]
    Plot one or more channel's waveforms. This function plots channel waveforms to one of a number of output devices in one of a number of formats. It requires gnuplot(1). All formats/devices as supported by gnuplot are supported by the functions. Run gds-plot -h in gdsh(1) for more information.

    Note: It is advisable to first stop the continuous data acquisition (:stop) before plotting the data. This ensures plotted data for multiple channels is from the same point in time.

    See also gds-snapshot, function gds_plot() in gds-octave(1), and gnuplot(1).

gds-esr [-h]
    Displays the current Event Status Enable Register (ESER, *ESE?), and the Standard Event Status Register (SESR, *ESR?). The ESER indicates which bits in the SESR are enabled.

    Note: The GDS' event status system is barely documented. Expect to receive inconclusive information, like the PON (power-on) bit returned as false in some firmware revisions when the instrument is apparently powered on (otherwise it couldn't respond). Further, some firmware revisions allow to turn event status bits on (*ese nbr), but not off (*ese 0 has no effect).

gds-sbr [-h]
    Displays the current Service Request Enable Register (SRER, *SRE?), and the Status Byte Register (SBR, *STB?). The SRER indicates which bits in the SBR are enabled.

    Note: The GDS' status system is barely documented. Expect to receive inconclusive information. Further, some firmware revisions allow to enable service request bits (*sre nbr), but not to disable them (*sre 0).

gds-help pattern
    Tries to find pattern in the gdsh(7) manual page. pattern is a regular expression.

gdsh-timeout [-h] [sec]
    Set or get the gdsh(1) read timeout used in the current gdsh(1) session.

gdsh-version
    Returns this gdsh(1)'s version. Should not be confused with the gds-version function.

gdsh-warranty
    Prints information about the warranty gdsh comes with (non at all).

gdsh-conditions
    Prints information about the gdsh redistribution conditions.

170+ additional commands
    See gdsh(7) for a description of all 170+ oscilloscope commands available in gdsh(1).

FILES

bash configuration files
    Since gdsh is in fact a bash, normal bash configuration files apply.

lib/gdsh.init
    Initialization script for gdsh. This script is loaded via bash's --rcfile command line option to initialize gdsh. The script then loads other gdsh components and user configuration files.

lib/gdsh.commands
    Contains the implementation of oscilloscope commands as bash functions. The function definitions are loaded by lib/gdsh.init at shell startup.

lib/gdsh.functions
    Contains the general functions for communicating with the oscilloscope. Typically the names of these functions start with 'gds-'. The function definitions are loaded by lib/gdsh.init at shell startup.

~/.bashrc
    Normal bash startup script. Loaded by lib/gdsh.init at gdsh startup. This file should not contain any gdsh specific settings. It is loaded so user's common shell configurations are available in gdsh.

~/.gdshrc
    gdsh-specific user startup script. It is loaded after ~/.bashrc by lib/gdsh.init.

    A typical ~/.gdshrc file contains settings like
    GDSH_CONNECT_AT_START=1
    GDSH_SYNC_DT_AT_START=0
    GDSH_DEV=/dev/ttyACM0
    GDSH_DEV_TYPE="u"

See also gds-udev(7) for available device names.

EXAMPLES
Open a particular device and print the oscilloscope's identification from that device:

    $ gdsh
    GDSH vx.x - GDS-2000 series (and others) oscilloscope shell
    gdsh@ gds-open /dev/ttyACM0
    gdsh@ _idn_
    GW,GDS-2xxx,xxxxxxxx,Vx.xx

Continuously measure trigger frequency, and channel 1's Vpp and Vmin:

    gdsh@ gds-measure -f tfreq 1 vpp vmin

Synchronize the oscilloscope's date and time with the system date and time (it can take up to a minute until the new date and time are displayed on the oscilloscope's LCD):

    gdsh@ gds-sync

Plot the current active channels on the screen:

    gdsh@ gds-plot

Plot channels 2 and 4 into a PNG image file named osc.png, and provide a comment in the image, too:

    gdsh@ gds-plot -c "Oscillator" 2 4 osc.png

Configure the oscilloscope for some measurement, then acquire the data.

    $ gdsh
    GDSH vx.x - GDS-2000 series (and others) oscilloscope shell
    gdsh@ gds-open /dev/ttyACM0
    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 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@ :run               # restart oscilloscope
    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 oscilloscope functions in gdsh
    gdsh@ man 7 gdsh
    gdsh@
    gdsh@ gds-close
    gdsh@ exit

ENVIRONMENT
The following environment variables can be defined in a user's ~/.gdshrc configuration file:

GDSH_CONNECT_AT_START
    If set, and set to non-zero, and GDSH_DEV is also defined, then gdsh tries to open the connection to the oscilloscope at gdsh startup. This is a prerequisite for using the stand-alone shortcuts.

GDSH_SYNC_DT_AT_START
    If set, and set to non-zero, and GDSH_CONNECT_AT_START is also set to non-zero, and GDSH_DEV is also defined, then try to synchronize the oscilloscope's date and time with the computer's date and time.

GDSH_DEBUG
    If set, and set to a non-zero number, then gdsh commands print various debugging messages during execution.

GDSH_DEV
    The default serial device to use when non is specified as argument to the gds-open command.

GDSH_DEV_BAUD
    The default baud rate for RS232 interfaces when non is specified as argument to the gds-open command. Ignored for USB interfaces.

GDSH_DEV_PARITY
    The default parity (n, N, e, E, o, O) for RS232 interfaces when non is specified as argument to the gds-open command. Ignored for USB interfaces.

GDSH_DEV_STOPBITS
    The default number of stop bits (1, 2) for RS232 interfaces when non is specified as argument to the gds-open command. Ignored for USB interfaces.

GDSH_DEV_TYPE
    The default device type to use when non is specified as argument to the gds-open command. Possible values are

    s   gds-open should assume an RS232 interface.

    u   gds-open should assume a USB interface.

    ?   gds-open should use its normal heuristic to determine the device type. This is equivalent to not having a GDSH_DEV_TYPE environment variable at all.

GDSH_GNUPLOT
    Path to the gnuplot(1) program to be used for the gds-plot function. If not given the normal PATH is searched for gnuplot.

GDSH_IMGVIEWER
    Path to an image viewer program capable of displaying BMP images files. To be used for the gds-snapshot function. If not given the normal PATH is searched for the eog (eye of gnome) image viewer.

GDSH_READ_TIMEOUT
    The number of seconds gdsh waits for a response to a query command. See also gdsh-timeout which sets this value in a gdsh session.

gdsh stores the last response it got in the environment variable GDSH_RESP. This variable can be used in case it is more convenient to work with a variable then to use command substitution to capture the response to a query command.

SEE ALSO
bash(1), eog(1), gdsh(7), gds-csv-info(1), gds-octave(7), gds-read-bin(1), gds-udev(7), gnuplot(1) ucom(4), umodem(4), usba(7D), usbsacm(7D).

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.

BUGS
This is beta software.

Error handling, especially communication error handling is rudimentary, only. Erratic gdsh behavior is usually due to the connection to the device not being open or the communication failed. In particular, a bad file descriptor message from bash(1) is an indication of a communication problem.

The software wasn't tested on any GDS-800, GDS-1000A, DSO-4000, DSO-4000A or DSO-8000 series oscilloscope. It was once partly tested on a GDS-1000 series oscilloscope.

The command set is not limited to the specific oscilloscope type. Sending an unsupported request to an oscilloscope results in no action or some error message from the oscilloscope. Sending an unsupported query results in a gdsh read timeout.

The output from gds-csv can significantly differ from what the instrument stores as .CSV files on a USB memory stick or an SD card. The main reason is that not all needed values can be obtained via SCPI commands or these commands are not documented.

COPYRIGHT
Copyright © 2008 - 2010 Thomas Weidenfeller

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