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.