Provided by: xoscope_2.3-1_amd64 bug

NAME

       xoscope - Digital Oscilloscope

SYNOPSIS

       xoscope [X toolkit options] [xoscope options] [file]

DESCRIPTION

       Xoscope  is  a digital real-time oscilloscope. It graphically displays signal amplitude or
       bit logic as a  function  of  time.   Signals  may  be  displayed,  saved,  recalled,  and
       manipulated by math functions.  Signal input devices currently include:

       Soundcard
            Audio sound recording via Advanced Linux Sound Architecture (ALSA).  Two 8-bit analog
            channels at 8000 S/s to 44100 S/s.  Left and right audio is  connected  to  A  and  B
            inputs  respectively.   Use an external mixer program to select which sound inputs to
            record.  AC coupled, voltages unknown, 256K sample memory.

       EsounD
            Shared audio sound via the Enlightened Sound Daemon.   This  is  great  for  watching
            music  but  support for it is an option at compile-time.  EsounD is auto-detected and
            preferred over /dev/dsp.

       COMEDI
            The COMEDI project (www.comedi.org) develops Linux drivers, tools, and libraries  for
            data acquisition.  Many commercially available ADC cards are supported by COMEDI, and
            Xoscope can receive signals from them via the COMEDI library.

RUN-TIME KEYBOARD CONTROLS

       Xoscope is an interactive program and can be completely controlled from  the  keyboard  at
       run-time.   In  verbose  key  help  mode,  each  available  key  is shown on the screen in
       (parentheses).  The following single key commands are available:

       ?    Toggle verbose key help display mode.

       Escape
            Immediately quit the program.

       @    Load a previously saved file.  You are prompted for the filename.

       #    Save current settings and memory buffers to a file that can be loaded later.  You are
            prompted  for  the  filename  and  asked  for confirmation to overwrite if it already
            exists.

       Enter
            Clear and refresh the entire screen.

       &    Cycle between the various input devices.  Note that this key will not  toggle  to  an
            unresponsive  input  device, so if only one device is present, it will appear to have
            no effect.

       *    Different behavior for different input devices

            Under EsounD, this value instead determines whether the  connection  to  EsounD  will
            block  or  not.   Blocking mode is nicest to CPU usage but the xoscope interface will
            not respond when the there is no sound stream coming from EsounD.   Nonblocking  mode
            will  let  xoscope  be responsive whether sound is available or not, but will consume
            all available CPU cycles.

            Under COMEDI, this key toggles between different  analog  reference  points  (ground,
            differential, or common).

       ^    Different behavior for different input devices

       (/)  Decrease/increase the sampling rate.

       9/0  Increase/decrease the Sec/Div horizontal time scale (zoom out/in on time).

       -/=  Decrease/increase the trigger level.

       _    Cycle the trigger channel.

       +    Cycle the trigger type: none, rising edge, or falling edge.

       Space
            Cycle the trigger mode: run, wait, stop.  Run mode continuously acquires and displays
            samples after trigger events.  Wait mode  waits  for  the  first  trigger  event  and
            displays  only  the  first  set  of  samples;  this is "single-shot" mode.  Stop mode
            suspends the data acquisition and displays the current samples.

       !    Cycle the plotting mode: point, point accumulate, line, or line accumulate.   In  the
            accumulate modes, all samples stay on the screen; use Enter to clear them.

       ,    Cycle the graticule style: none, minor divisions only, or minor and major divisions.

       .    Toggle the graticule position: behind or in front of the signals.

       '    Toggle   the   manual  cursors  on/off.   When  manual  cursors  are  displayed,  the
            measurements between the cursor positions are shown.  When cursors are not displayed,
            automatic measurements are shown.

       "    Reset both manual cursor positions to the sample just after trigger.

       Ctrl-q/w/e/r
            The  Control key held down in combination with q/w/e/r moves the first cursor back or
            forward by 10 samples or back or forward by 1 sample respectively.

       Ctrl-a/s/d/f
            The Control key held down in combination with a/s/d/f moves the second cursor back or
            forward by 10 samples or back or forward by 1 sample respectively.

       1-8  Select  the  corresponding  display  channel.   Measurements  are  displayed  for the
            channel.  Channel 1 and 2 are used as input to the math functions so  they  can't  be
            used  to  do  math.   By  default,  they are connected to the A and B input channels.
            Channel 1 and 2 can also be used to display memory  buffers  or  for  doing  math  on
            memory  or  the  alternate  input.  Channel 3 through 8 are not restricted and can be
            used for any purpose.  The remaining single key commands  operate  on  the  currently
            selected channel:

       Tab  Toggle visibility: Hide or show the selected channel.

       {/}  Decrease/Increase vertical scale of the selected channel.

       [/]  Decrease/Increase vertical position of the selected channel.

       `/~  Decrease/Increase  number of logic analyzer bits displayed.  The default of zero bits
            plots the signal as one analog line of varying  amplitude.   Any  other  value  plots
            multiple digital lines representing the least significant bits from bottom to top.

       ;/:  Increase/Decrease  the  math function of the selected channel.  This is not available
            on channel 1 & 2.

       $    Show the result of an external  math  command  on  the  selected  channel.   You  are
            prompted  for the command.  The command must accept samples of channel 1 & 2 on stdin
            and write a new signal to stdout.  See operl, offt.c and xy.c in the distribution for
            examples of external math filter commands.  Not available on channel 1 & 2.

       a-z  Recall  the  corresponding  memory  buffer  or input device to the currently selected
            channel.  Input device channels are mapped to the earliest letters of  the  alphabet;
            the rest of the buffers are available for signal memory.

       A-Z  Store  the  currently  selected  channel into the corresponding memory buffer.  Early
            letters of the alphabet can not be  used  because  they're  reserved  as  the  signal
            inputs,  so  the  exact number of available buffers is dependent on the input device.
            Memories are stored from time zero to the current display update position.  So it  is
            best to STOP the display before storing to a memory buffer.

MOUSE CONTROLS

       Xoscope  adds mouse controls to menus or around the edges of the scope area.  These should
       be nearly self-explanatory.  They perform the same functions as  the  equivalent  keyboard
       commands  above.   If  built  with GTK+, a context-sensitive pop-up menu is available with
       right-click to select channels, change scale and position, recall and store signals and so
       on.   Left click decreases a variable while right click increases.  The manual measurement
       cursors can also be positioned with the mouse.

COMMAND-LINE OPTIONS

       The command-line options define the startup state of xoscope and have reasonable defaults.
       All  options  may  be  capitalized  in case they conflict with an X toolkit option.  These
       options are also recorded in text files saved by xoscope.

       -h   Help usage message showing these startup options  with  their  default  values,  then
            exit.

       -# <code>
            Startup  conditions  of  each  channel.  # is a channel number from 1 to 8.  Code can
            have up to three fields, separated  by  colons:  position[.bits][:scale[:function  #,
            memory  letter,  or  external  command]].   Position  is  the  number of pixels above
            (positive) or below (negative) the center of the display.   Bits  is  the  number  of
            logic  analyzer  bits  to  display.  Scale is a valid scaling factor from 1/50 to 50,
            expressed as a fraction.  The third  field  may  contain  a  built-in  math  function
            number,  memory  letter, or external math command to run on the channel.  Using these
            options makes the channel visible unless position begins with a '+',  in  which  case
            the channel is hidden.

       -a <channel>
            Active, or selected, channel.

       -r <rate>
            Sampling  Rate  in  samples per second.  For the sound card, current valid values are
            8000, 11025, 22050, or 44100.

       -s <scale>
            Time Scale factor from 1/500000 to 2000 (2 ns/div - 2 s/div) expressed as a  fraction
            where 1/1 is 1 ms/div.

       -t <trigger>
            Trigger  conditions.   Trigger  can  have  up  to  three fields, separated by colons:
            position[:type[:channel]].  Position is the number  of  pixels  above  (positive)  or
            below  (negative) the center of the display.  Type is a number indicating the kind of
            trigger, 0 = automatic, 1 = rising edge, 2 = falling edge.  Channel should be x or y.

       -l <cursors>
            Manual cursor Line positions.  Cursors can have up  to  three  fields,  separated  by
            colons:  first[:second[:on?]].   First  is  the  sample position of the first cursor.
            Second is the sample position of the second cursor.  The final field is  weather  the
            manual cursors are displayed (1) or the not displayed (0).

       -p <type>
            Plot type.  0 = point, 1 = point accumulate, 2 = line, 3 = line accumulate, 4 = step,
            5 = step accumulate.

       -g <style>
            Graticule style.  0 = none, 1 = minor divisions only, 2 = minor and major divisions.

       -b   Whether the graticule is drawn Behind or in front of the signals.

       -v   Whether the Verbose key help is displayed.

       file The name of a file to load upon startup.  This should be a file previously  saved  by
            xoscope.

EXAMPLES

       xoscope -1 80 -2 -80 -3 0:1/5:6 -4 -160:1/5:7

            This runs xoscope with channel 1 above and channel 2 below the center of the display.
            Also channel 3 and 4 are made visible to show the FFT of channel 1 and 2 respectively
            at a reduced scale of 1/5.

       xoscope oscope.dat

            This  runs  xoscope, loading settings and memory buffers from a previously saved data
            file called "oscope.dat".

FILES

       Xoscope creates readable text data files.  The files contain at  least  a  comment  header
       which holds the current settings of xoscope.  Loading the file causes these saved settings
       to be restored.

       To record your signals permanently first store them into memory buffers, optionally recall
       them  to  channels, and then save the file.  All non-empty memory buffers are written to a
       column of the file following the comment header.  Columns are separated by tab characters.
       These  are  stored  back  into  the  memory buffers when the file is later loaded.  Simply
       recall them to channels to view them.

       This format could also be read by some spreadsheet or plotting programs.  For example, the
       gnuplot (1) command

       plot "oscope.dat" using 0:1, "oscope.dat" using 0:2

       would plot the first and second columns of the "oscope.dat" data file.

ENVIRONMENT

       OSCOPEPATH
            The  path  to  use  when  looking for external math commands.  If unset, the built-in
            default is used.

       ESPEAKER
            The host:port of the EsounD to connect to if built with EsounD  support.   If  unset,
            localhost  is  assumed.   If  no  EsounD  connection is made or if there is no EsounD
            support compiled in, then xoscope will try to read /dev/dsp directly.

LIMITATIONS

       The sound card should be capable of 44100 Hz sampling via the sound drivers.  You must use
       an  external  mixer  program  to  select the input source device, level, etc.  Since these
       unknowns affect the amplitude, there is no reference to voltage on the Y axis;  it  is  in
       fact,  unknown.   Instead you're given the scale in pixels per sample unit.  Note that the
       serial oscilloscope devices don't have this limitation.  They have real voltage labels  on
       the Y axis.

       Signal  math  is  only valid if Channel 1 and 2 contain signals of the same sampling rate.
       It is up to you to make sure this is the case. Doing math on signals of  different  sample
       rates will produce incorrect results!

       The  automatic measurements count zero crossings and divide to determine the frequency and
       period.  If these zero crossings are not "regularly-periodic", these measurements could be
       invalid.   Xoscope  does  understand how to measure the built-in FFT functions by locating
       the peak frequency.  Use manual cursor positioning to get more precise measurements.

       Your sound card is most-likely AC coupled so you  will  never  see  any  DC  offset.   You
       probably  can't  get DC coupling by just shorting the input capacitors on your sound card.
       Use serial hardware to see DC offsets.

       The display may not be able to keep up if you give it too much to plot, depending on  your
       sound  card,  graphics card, and processor speed.  External math commands are particularly
       expensive since the kernel must then  split  the  available  CPU  cycles  across  multiple
       processes.   To  maximize  refresh  speed,  hide all unneeded channels, use point or point
       accumulate mode, zoom in on Sec/Div as much as possible, and turn off the graticule.

BUGS

       The keyboard interface may be confusing.

AUTHOR

       Oscope was written by Tim Witham (twitham@quiknet.com), originally  based  on  "scope"  by
       Jeff   Tranter   (Jeff_Tranter@Mitel.COM).    Most   recent   work  is  by  Brent  Baccala
       (cosine@freesoft.org).  ALSA support  by  Gerhard  Schiller  (gerhard.schiller@gmail.com).
       Xoscope is released under the conditions of the GNU General Public License.  See the files
       README and COPYING in the distribution for details.