XOSCOPE(1)

💖 XOSCOPE(1) 💖

User Commands ✨ so like, welcome to the manual page for xoscope, bestie — section 1, user commands, digital oscilloscope energy, and honestly? she ate. 🎀

---

🌸 NAME 🌸

xoscope — Digital Oscilloscope 🦋

---

✨ SYNOPSIS ✨

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

---

💅 DESCRIPTION 💅

Xoscope is a digital real-time oscilloscope. She draws signal amplitude — or bit logic — as a function of time, like a little graph gremlin who is also your bestie. Signals can be displayed, saved, recalled, and manipulated by math functions. 🧚

So what can you actually plug into her? 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 are 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. No mouse required, keyboard warriors rise up. ⌨️✨ In verbose key help mode, each available key is shown on the screen in (parentheses).

Here are the single key commands, and yes we're doing all of them, no skipping, periodt:

• ? — Toggle verbose key help display mode.
• Escape — Immediately quit the program. 💀 bye bestie
• @ — 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 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. (that's literally all she says, iykyk 🤷)
• ( / ) — 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 / Ctrl-w / Ctrl-e / Ctrl-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 / Ctrl-s / Ctrl-d / Ctrl-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 whether the manual cursors are displayed (1) or 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 🌸

Okay so xoscope writes out readable text data files and that's not just a cute bonus, it's the whole save system bestie. Every file has at least a comment header holding the current settings of xoscope, and when you load that file back up, those saved settings get restored. ✨

Wanna keep your signals forever? The order matters, so listen up:

1. Store them into memory buffers first.
2. Optionally recall them to channels.
3. Then save the file.

All the non-empty memory buffers get written to a column of the file, right after the comment header. Columns are separated by tab characters and when you load the file later they go straight back into the memory buffers. Then you just recall them to channels to view them. Simple. Slay. 💅

This format could also be read by some spreadsheet or plotting programs, which is giving main character energy. 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. Obsessed actually. 📈

---

🦋 ENVIRONMENT 🦋

• OSCOPEPATH — the path to use when looking for external math commands. If it's unset, the built-in default is used instead. She has a backup plan, periodt.
• ESPEAKER — the host:port of the EsounD to connect to, but only if xoscope was built with EsounD support. If unset, localhost is assumed. And if no EsounD connection is made, or if there's no EsounD support compiled in at all, then xoscope will try to read /dev/dsp directly. Plan C energy but we respect it. 💜

---

⚠️ LIMITATIONS ⚠️

Not me being the bearer of bad news but these are real and you should read them fr fr.

Your 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. And 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. Iconic of them, honestly. 👑

Signal math is only valid if Channel 1 and Channel 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! Like, not "a little off", incorrect. 💀

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. And 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
• turn off the graticule

That's the speedrun route. You're welcome. 🏃‍♀️💨

---

🐛 BUGS 🐛

The keyboard interface may be confusing.

That's it. That's the bug report. She said what she said. 🙈

---

👑 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. 🫶

---

And that's the whole page bestie!! This one's from the Linux source, dated May 6 2001, and it's the XOSCOPE(1) manual. Go forth and oscilloscope, you've got this. 💖✨🎀