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.