gds-read-bin(1)

NAME
gds-read-bin - GDS-2000 series oscilloscope binary data reading filter

SYNOPSIS
gds-read-bin [-0|-1] [-f mem] [-F fieldsep] [-h|-i] [-t timeout] [(-v scale) | (-V 25scale)]
gds-read-bin -f outp [-c colormap] [-t timeout]
gds-read-bin -f go-nogo [-t timeout]

DESCRIPTION

  Overview
The supported oscilloscopes usually send data as ASCII text. There are, however some exceptions. This filter handles oscilloscope data for three such exceptions:

1.  Sample waveform data in response to a :ACQuire<X>:MEMory? (GDS-2000 and other series), :ACQuire<X>:LMEMory? (GDS-1000A), or :ACQuire<X>:POINt? (GDS-8x0) query.

2.  Screen snapshot data in response to an (undocumented) :DISPlay:OUTPut? query.

3.  Go/no-go template data in response to a TEMPlate<X>:DOWNload? query (GDS-8x0).

    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.

gds-read-bin expects that its standard input is connected to a tty device. It reads data from this device, expecting particular binary data. It only reads as much data as indicated in the binary data itself. To do so gds-read-bin reconfigures the serial device's incoming direction into 'raw' mode, to ensure no data is accidentally converted by the line discipline. At exit gds-read-bin restores the original configuration of the device.

The filter does not send the above mentioned queries. It expects a query has been send by other means. It just processes the response to the query and converts it, depending on the -f option and the data. The result is written to the filter's standard output.

The most convenient way to use the filter is via gdsh(1). gdsh(1) automatically uses the filter for handling the responses to the above mentioned queries.

  Sampling Waveform Data
The option -f mem or no -f option at all indicates to gds-read-bin to expect and convert sampling waveform data (:ACQuire<X>:MEMory (GDS-2000 and other series), :ACQuire<X>:LMEMory? (GDS-1000A), or :ACQuire<X>:POINt (GDS-8x0) query response). It converts the respective received binary data into ASCII data.

If no further options are specified then gds-read-bin produces an ASCII output of the following form. Items reproduced here in bold are generated verbatim, while items in italic (underlined) are placeholders for actual values:

    Interval horizontalInterval
    Channel channelNbr
    Length nbrOfDatapoints
    0 value0
    1 value1
    ...
    nbrOfDatapoints-1 valueForNbrOfDatapoints-1

The placeholders have the following meanings and can take the following values:

    horizontalInterval
        The horizontal (x axis) time duration between two data points in seconds. Usually a floating point number with exponent is printed. Please note that this value is usually not identical to the horizontal time division.

        KNOWN BUG: The GDS-2000 firmware v1.09 (and maybe others) returns wrong horizontal interval information when the horizontal display mode is set to Window Zoom. A typical value returned by the oscilloscopes is 4e-11, wrongly indicating 25 GS/s. Instead of relying on the interval value is recommended to use the :TIMebase:SCALe? (non Window Zoom display mode) or :TIMebase:WINDow:SCALe? (Window Zoom display mode) query instead, and divide the result by 25.

    channelNbr
        The oscilloscopes channel from which the data was take. E.g. 1 for channel 1.

    nbrOfDatapoints
        The number of obtained waveform data points. Typical values are 500 (for :ACQuire:LENGth 0) and 5000 (three or for channels active), 12500 (two channels active), or 25000 (one channel active) for :ACQuire:LENGth 1.

    valueX
        The value at horizontal position X. Values are provided by the oscilloscope as integers in the range -32768 to 32767. A value should be multiplied by 1/25 of the vertical scale in Volts/div (:CHANnel<X>:SCALe?) to get the actual value in Volts (see -v and -V options below).

The above describe output format can be changed by using several options, described later in this manual page.

  Screen Snapshot
If the option -f outp is specified, then gds-read-bin expects to receive screen snapshot image data from the oscilloscope as a response to a :DISPlay:OUTPut? query. The data is converted into the BMP image format.

Screenshot image data can come in four formats from the oscilloscope, depending which value was set for :DISPlay:OUTPut and depending on the oscilloscope series and firmware version. When :DISPlay:OUTPut is set to 0 the data from GDS-2000 series oscilloscopes does not contain graticule and trigger mark information. The second format (:DISPlay:OUTPut set to 1) contains the graticule and trigger marker. The third format (GDS-1000 series) uses a completely different image data encoding. This format actually comes in two versions, one incorrectly announcing the size of the data.

gds-read-bin accepts all mentioned formats and creates images from all of them. But images obtained when :DISPlay:OUTPut 0 is set naturally don't show the graticule and trigger markers.

  Go/No-Go Template
If the option -f go-nogo is specified, then gds-read-bin expects to receive go/no-go template data from the oscilloscope as a response to a :TEMPlate<X>:DOWNload? query. The binary data is converted to ASCII data of the following form. Items reproduced here in bold are generated verbatim, while items in italic (underlined) are placeholders for actual values:

    Package Type packageType
    Template Number templateNbr
    Position position
    Text text
    Checksum checksum
    Template Data
    value0
    value1
    ...
    value249

The placeholders have the following meanings and can take the following values:

    packageType
        A fixed package type number invented by Instek. Typically 0x03. The exact meaning is not known.

    templateNbr
        The number of the template. This should be the same number as what was used for the <X> placeholder in the :TEMPlate<X>:DOWNload? query. Range 1 to 100.

    position
        The vertical offset of the template in display pixels. Range -300 to 300.

    text
        A descriptive text.

    checksum
        A checksum over the data bytes.

    valueX
        250 values of vertical pixel positions. Range -100 to 100.

OPTIONS

  Format Option

-f format
    Specifies which data format type gds-read-bin expects and in which format it converts the data. The following format arguments are possible:

    mem Expect and convert sample waveform data to ASCII. This is also the default if no -f option is specified.

    outp
        Expect and convert a screen snapshot into BMP image data.

    go-nogo
        Expect and convert go/no-go template data.

  Common Options

-t timeout
    The read timeout in seconds. Default 2.

  Sample Waveform Data specific Options
The following options only apply to the generation of ASCII data from sample waveform input data.

-0  (zero) The initial three lines with the Interval, Channel and Length information are not printed.

-1  (one) The initial three lines with the Interval, Channel and Length information are printed in the style of the CSV waveform data.

-F fieldsep
    Changes the default field separator from a single space to fieldsep. The three header lines (Interval, Channel and Length), as well as the data point lines are affected by this. The separator can be multiple characters long.

-h  The horizontal position values (x axis, first column) are multiplied by the horizontal interval. This gives the horizontal values in Seconds.

    KNOWN BUG: The GDS-2000 firmware v1.09 (and maybe others) returns wrong horizontal interval information when the horizontal display mode is set to Window Zoom. This results in wrong horizontal poition values when Window Zoom and the -h option are used together.

-i  The horizontal position values are not printed (ignored). Only the vertical values are printed.

-v scale
    The data points (y axis) are multiplied by the scale value.

-V 25scale
    The data points (y axis) are multiplied by 1/25 of the 25scale value. This option is useful with the value returned by :CHANnel<X>:SCALe?. Using that value as 25scale argument gives the vertical values in Volts without the need for further scaling.

  Screenshot Image Data specific Option
The following option only applies to the generation of BMP image data from screenshot image data.

-c colormap
    Specifies which colormap should be used to create the image. The available colormaps are build into gds-read-bin. The following colormap arguments are understood:

    standard
        The standard (dark) colormap that matches the color on the oscilloscope's screen. This is also the default if not -c option is specified.

    improved
        A slightly lighter colormap.

    inksave
        A colormap matching the inksave option of the oscilloscope when it saves screen snapshots to USB memory sticks.

    bw  A colormap to generate a black & white image.

BUGS
The colors gds-read-bin uses when decoding screen snapshots differ from what the oscilloscope uses on the screen or in hardcopies.

The size of a black & white image is the same as that of color images.

The GDS-2000 firmware v1.09 (and maybe others) returns wrong horizontal interval information when the horizontal display mode is set to Window Zoom. A typical value returned by the oscilloscopes is 4e-11, wrongly indicating 25 GS/s. The Interval or Sampling Period (-1 option) output should not be used in this case.

EXAMPLES
The following usage of gdsh(1) implicitly uses gds-read-bin:

$ gdsh
GDSH vx.x - GDS-2000 series oscilloscope shell
gdsh@ gds-open /dev/ttyACM0
gdsh@ :chan1:disp 1	# turn on display of channel 1
gdsh@ :aut		# autoset
gdsh@ :acq:leng 1	# set record length to max
gdsh@ :acq1:mem_ -h -V `:chan1:scal_`	# get data from channel 1
Interval 4e-07
Channel 1
Length 25000
0 0
4e-07 1.52
8e-07 1.96
...

The following normal shell example explicitly uses gds-read-bin without any safety net:

$ echo ":ACQ1:MEM?" > /dev/ttyACM0
$ gds-read-bin < /dev/ttyACM0
Interval 2e-05
Channel 1
Length 500
0 0
1 38
2 49
...

The following normal shell example explicitly uses gds-read-bin without any safety net to generate a screen snapshot image file snap.bmp with the inksave colormap. Note that first of all the output format is set to include graticule and trigger marker information.

$ echo ":DISP:OUTP 1;:DISP:OUTP?" > /dev/ttyACM0
$ gds-read-bin -f outp -c inksave < /dev/ttyACM0 > snap.bmp

SEE ALSO
gdsh(1).

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.

COPYRIGHT
Copyright © 2008 - 2010 Thomas Weidenfeller

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

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