xenial (1) xoscope.1.gz

Provided by: xoscope_2.0-3.2ubuntu1_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:

       /dev/dsp
            Audio  sound  recording via /dev/dsp.  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.

       ProbeScope / OsziFOX
            Radio Shack ProbeScope, Cat. No. 22-310 is also known as an osziFOX.  This handheld probe sends  its
            data  through  a  serial  port.   It samples one channel at 6-bits up to 20 MS/s with 128 samples of
            memory.  Real voltages are labeled in sample ranges from 1 volt to 100 volts.  If  a  ProbeScope  is
            detected, it is connected to the A input.

       Bitscope
            Bitscope  (www.bitscope.com)  is  a  mixed-signal  capture engine which is accessed through a serial
            port.  It simultaneously samples a digital 8-bit port and two analog channels at 8 bit resolution at
            up  to  25  MS/s  or  more.   If  detected, Channel A and B are connected to X and Y while the Logic
            Analyzer is connected to C.  Bitscope support is currently  under  development  and  not  yet  fully
            functional.

       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.

            See  the  -x  and  -z  options  and  the ENVIRONMENT section below for more details on how the above
            devices are detected.  Some of the controls below apply only to the sound card and  are  labeled  as
            such.   Xoscope  has  no physical control over the ProbeScope/osziFOX which is controlled by its own
            switches and built-in menus.  Please  refer  to  your  ProbeScope  or  osziFOX  Owner's  Manual  for
            operating instructions.  Bitscope will eventually be controlled through a separate dialog window.

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  dependant  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/20 to 1000 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.

       -x   Whether  the  sound  card  input  device (XY) is turned on.  This can be used to skip the attempt to
            connect to Esound or /dev/dsp.

       -z   Whether the serial input device (Z) is turned on.  This can be used to suppress  the  search  for  a
            serial scope device.

       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.

       PROBESCOPE
            The serial device your ProbeScope or osziFOX is connected to.  If unset,  /dev/probescope  is  used.
            /dev/probescope could be a symbolic link to the real device such as /dev/ttyS1.

       BITSCOPE
            The  serial  device  your Bitscope is connected to.  If unset, /dev/bitscope is used.  /dev/bitscope
            could be a symbolic link to the real device such as /dev/ttyS1.

       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).   Xoscope  is
       released under the conditions of the GNU General Public License.  See the files README and COPYING in the
       distribution for details.