Manual Page: xoscope(*)
1
OSCOPE(1) User Commands OSCOPE(1)
NAME
oscope xoscope - Digital Oscilloscope via Sound Card
and/or ProbeScope/osziFOX
SYNOPSIS
oscope [oscope options] [file]
xoscope [toolkit options] [oscope options] [file]
DESCRIPTION
Oscope is a digital real-time oscilloscope. It graphically
displays signal amplitude as a function of time. The input
is via a sound card and/or a serial port connected to a
Radio Shack ProbeScope, Cat. No. 22-310. This device is
also known as an osziFOX. Either or both input devices
may be used at the same time. Signals may be displayed,
saved, recalled, and manipulated by math functions.
Some of the controls below apply only to the sound card
and are labeled as such. Oscope 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.
Oscope can be built with EsounD (Enlightened Sound Daemon)
support for sharing a sound device among programs or over
the network. See the ENVIRONMENT section below for more
details.
RUN-TIME KEYBOARD CONTROLS
Oscope 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
Linux June 1 2000 1
OSCOPE(1) User Commands OSCOPE(1)
filename and asked for confirmation to overwrite if
it already exists.
Enter
Clear and refresh the entire screen.
^ Toggle the ProbeScope input device on/off. The
ProbeScope is turned on only if it is found active on
a serial port. This may be useful if the ProbeScope
wasn't detected at startup. See the ENVIRONMENT sec
tion below for more details.
& Toggle the sound card input device on/off.
* Cycle the sound card DMA divisor: 4, 2, 1. The sound
driver will divide it's DMA buffer by this factor.
The value 4 usually gives the fastest display rate.
Under EsounD, this value instead determines whether
the connection to EsounD will block (4) or not (2 or
1). Blocking mode is nicest to CPU usage but the
oscope interface will not respond when the there is
no sound stream coming from EsounD. Nonblocking mode
will let oscope be responsive whether sound is avail
able or not, but will consume all available CPU
cycles.
(/) Decrease/increase the sound card sampling rate.
9/0 Increase/decrease the Sec/Div horizontal time scale
(zoom out/in on time).
-/= Decrease/increase the sound card trigger level.
_ Toggle the sound card trigger channel: X or Y.
+ Cycle the sound card trigger type: automatic, rising
edge, or falling edge.
Space
Cycle the trigger mode of the sound card: 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
Linux June 1 2000 2
OSCOPE(1) User Commands OSCOPE(1)
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.
</> Decrease/increase the graticule color.
' Toggle the manual cursors on/off. When manual cur
sors are displayed, the measurements between the cur
sor positions are shown. When cursors are not dis
played, 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. Measure
ments 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 Left (X) and Right (Y) sound channels, as con
trolled by an external mixer program. Channel 1 and
2 can also be used to display memory buffers or
ProbeScope (Z) input for doing math on memory or
ProbeScope signals respectively. Channel 3 through 8
are not restricted and can be used for any purpose.
Linux June 1 2000 3
OSCOPE(1) User Commands OSCOPE(1)
By default, the ProbeScope (Z) input is connected to
Channel 3. 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 dis
played. 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-W Store the currently selected channel into the corre
sponding memory buffer. Buffer X, Y and Z can't be
used because they're reserved as the Left (X) and
Right (Y) sound inputs and ProbeScope (Z) input.
a-z Recall the corresponding memory buffer or input
device to the currently selected channel. Buffer X
is the Left sound input, Y is the Right sound input,
and Z is ProbeScope input. The rest of the buffers
are available for signal memory.
MOUSE CONTROLS
Xoscope adds mouse controls to menus or around the edges
of the scope area. These should be nearly self-explana
tory. They perform the same functions as the equivalent
Linux June 1 2000 4
OSCOPE(1) User Commands OSCOPE(1)
keyboard commands above. If built with GTK+, context-sen
sitive pop-up menus are available to select channels,
change scale and position, recall and store signals and so
on. The manual measurement cursors can also be positioned
with the mouse.
COMMAND-LINE OPTIONS
The command-line options define the startup state of
oscope and have reasonable defaults. All options may be
capitalized in case they conflict with an X toolkit
option.
-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: posi
tion[.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 visi
ble unless position begins with a '+', in which case
the channel is hidden.
-a <channel>
Active, or selected, channel.
-r <rate>
Sound card sampling Rate in samples per second. Cur
rent 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>
Sound card Trigger conditions. Trigger can have up
to three fields, separated by colons: posi
tion[:type[:channel]]. Position is the number of
Linux June 1 2000 5
OSCOPE(1) User Commands OSCOPE(1)
pixels above (positive) or below (negative) the cen
ter 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[:sec
ond[: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).
-c <color>
Graticule Color, 0 - 15.
-d <dma divisor>
Divisor for sound card DMA: 1, 2, or 4. The sound
driver will divide it's DMA buffer by this factor.
The value 4 usually gives the fastest display rate.
-m <mode>
Graphics Mode to use. For xoscope, use the more
flexible -geometry instead. 0 = 640x480x16, 1 =
800x600x16, 2 = 1024x768x16, 3 = 1280x1024x16. WARN
ING: not all modes are supported by all video cards;
don't use unsupported modes!
-f Font to use. For oscope, these are listed in
/usr/lib/kbd/consolefonts. For xoscope, they're the
output of xlsfonts. The default should work best.
-p <type>
Plot type. 0 = point, 1 = point accumulate, 2 =
line, 3 = line 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.
Linux June 1 2000 6
OSCOPE(1) User Commands OSCOPE(1)
-x Whether the sound card input device (XY) is turned
on.
-z Whether the ProbeScope input device (Z) is turned on.
file The name of a file to load upon startup. This should
be a file previously saved by oscope.
EXAMPLES
oscope -1 80 -2 -80 -3 0:1/5:6 -4 -160:1/5:7
This runs oscope 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
Oscope creates readable text data files. The files con
tain at least a comment header which holds the current
settings of oscope. 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.
Linux June 1 2000 7
OSCOPE(1) User Commands OSCOPE(1)
ENVIRONMENT
OSCOPEPATH
The path to use when looking for external math com
mands. If unset, the built-in default is used.
PROBESCOPE
The serial device your ProbeScope or osziFOX is con
nected to. If no ProbeScope is found here, some
known serial devices are checked. If unset,
"/dev/probescope" is used. /dev/probescope 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 oscope 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 ProbeScope/osziFOX doesn't have this limitation.
ProbeScope signals have a real voltage label on the Y
axis.
Signal math is only valid if Channel 1 and 2 contain sig
nals 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. Oscope does understand how to measure
the built-in FFT functions by locating the peak frequency.
Use manual cursor positioning to get more precise measure
ments.
Your sound card is most-likely AC coupled so you will
never see any DC offset. You probably can't get DC cou
pling by just shorting the input capacitors on your sound
card. Use ProbeScope to see DC offsets.
Linux June 1 2000 8
OSCOPE(1) User Commands OSCOPE(1)
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 particu
larly expensive since the kernel must then split the
available CPU cycles across multiple processes. To maxi
mize 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.
Because it uses svgalib, oscope must be run as root or be
setuid to root. xoscope doesn't have this restriction.
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_Tran
ter@Mitel.COM). Oscope is released under the conditions
of the GNU General Public License. See the files README
and COPYING in the distribution for details.
Linux June 1 2000 9
Searched /usr/local/man:/usr/man/preformat:/usr/man:/usr/X11/man:/usr/openwin/man
Completed by:
man2html,v 1.5, Last modified: 1996/01/02 18:42:27 GMT
Timothy D. Witham <twitham@eng.fm.intel.com>