TPP accepts I/Q audio data from a sound card (typically a USB sound card with 48 kHz sampling) and produces a spectrum and waterfall plot. The DVB-T "RTL" receiver USB dongle is also supported for sampling rates up to about 2 MHz.
Starting point and requirements for this project:
- Receiver that provides I/Q audio IF signals. (SoftRock, Elecraft KX3, etc.) Note that traditional receivers do not provide I/Q.
- OR RTL-SDR dongle -- see http://sdr.osmocom.org/trac/wiki/rtl-sdr.
- Linux-based computer -- PC or micro, such as BeagleBone Black or Raspberry Pi.
- Internet access via Ethernet and home router (for downloading and debugging)
TPP in action at DL4JLM, Lars Mesow
Code on SourceForge
[6/9/2014: Latest version is 0.3.6, adding support for the Si570 VCXO VFO.]
The TPP code is now an open-source project hosted on SourceForge. SourceForge provides many services for project developers, including file servers for downloading, mailing lists for support, and git repositories for collaborative code development. For our TPP SourceForge project (called "tinypythonpanadapter"), we have the following features:
- Download latest releases. The latest released version is provided in the files download area. The updated supplementary document accompanying the QST article is also available in this area. (This has all the details and some corrections that did not get into the QST print article. There are more step-by-step instructions for setting up your microcomputer, how to build rtlsdr, etc.)
- Git Repository. Git is a software version control system. The complete development tree of software revisions and release versions (since May 1, 2014) is being managed on SourceForge's Git server. You can download the full Git tree with the following command:
git clone git://git.code.sf.net/p/tinypythonpanadapter/code tinypythonpanadapter-code
This is mainly aimed at people who are helping to develop the TPP code, but anyone can get (i.e. clone) the repository. - Mailing List. (The mailing list is now inactive.) Please contact AA6E directly for more information.
Notes
Blog Discussions. See my Amateur Radio blog for occasional articles relating to the TPP project.
To get the actual code from a released zip file, you unzip the whole file and place the 'iq' directory (and its contents) to a convenient place on your computer, such as your home directory. The main program is iq/iq.py. Because it's all Python, you can browse the files with any convenient text editor to familiarize yourself with what's there.
Note that all text and Python files are in the Linux/Unix format. Lines will be jumbled up if you try to view them with simple Windows programs like 'type' or Notepad. If you want to view them correctly in Windows, you can use Word, OpenOffice/LibreOffice, and (maybe) Wordpad.
What Platform Should I Use?
Almost any computer system that will run one of the common Linux distributions should be usable for this project, although we have focused on the BeagleBone Black, Raspberry Pi, and full-size PCs. (In other words, ARM and i386 architectures.)
Asking which is "best" could start a big discussion, but we'll keep it short. As the article suggests, in this application (TPP), the additional processing power of the Beaglebone Black (up to 2X) is very welcome compared with the Raspberry Pi. The Pi has a tough time with continuous fast USB sound card I/O. If you're thinking of other applications, especially video, you may come to a different conclusion. Here is an interesting comparison of the two boards.
There are many other products in the small-linux-system-board market using ARM or other architectures, for example the Minnowboard based on the Intel Atom processor. This project should be portable to most of them, but I can't provide much support. Users should evaluate a board's online support community, which is vital if (when!) you run into problems. Generally, each board will require a different customized kernel to support its specific hardware environment, but once that is available you should be able to install the full Linux system to support TPP and any other applications of interest.
Which Linux Should I Use?
You have choices, depending on which hardware you're going to use. Keep in mind that all of these are largely repackaging the same software: the Linux kernel, and the many applications and utilities.
- Raspberry Pi. Raspbian is a variant of Debian. It's the obvious choice for TPP on the Pi.
- BeagleBone Black. You need to use a kernel that is tailored for this processor. There several choices, but I landed on Debian. (Debian is father to Ubuntu, and Ubuntu ought to work just as well. However, I had problems with a particular Ubuntu kernel on the BBB.)
- Other Hardware. You have many choices. If you're running i386 Intel-compatible hardware (or x64), you have many choices. I gravitate toward Ubuntu, which is the most widely used. It has excellent on-line support, and it works with a broad range of peripherals. If you are using ARM or other non Intel-compatible processors, the choices are fewer. In general, Debian provides versions for the greatest number of platforms.
There are literally 100s of Linux distributions ("distros") -- all with their particular qualities! You can check DistroWatch for an overview. Most have small user communities. Life is too short to try very many of them!
'''Flavors of Ubuntu for i386/x64'''. Ubuntu (the main offering) is aimed at typical modern PCs that have generous CPU and RAM available. If you have an older or lower-power environment, you might want to check some of the alternative Ubuntu distributions, lubuntu or xubuntu. These versions use simpler desktop/ X windows environments that may be a better fit for your system.
General Issues
Some problems may apply to more than one TPP "platform":
Building rtl-sdr
The instructions say to follow the procedures at https://osmocom.org/projects/rtl-sdr/wiki/Rtl-sdr. That web page may be a little confusing to some readers. I have condensed the instructions relevant to our project for Raspberry Pi and BBB users in rtl-sdr build procedure. Typical results (on a Pi) are provided in rtl-sdr output.
Another recipe, specifically for the Raspberry Pi, is available at http://zr6aic.blogspot.com/2013/02/setting-up-my-raspberry-pi-as-sdr-server.html. (Thanks W3IPO!)
RTL-SDR driver conflict
The current Linux releases may contain a new driver for DVB-T devices. Unfortunately, this can conflict with the rtl-sdr software we are recommending for TPP. (Use "lsmod" to view the loaded driver modules. You may see one for dvb_usb_rtl28xxu or similar if your RTL dongle is plugged in. You can quickly dispose of it with the command "sudo rmmod dvb_usb_rtl28xxu", but this only works until the next reboot.) The problem is permanently fixed by installing a file in the directory /etc/modprobe.d. You can use any editor for this, but use 'sudo' to allow it to edit a system file. Here is a way to do it simply with 'cat'. Enter the following 4 lines into your command line (terminal emulator), then reboot:
sudo cat <<EOF > /etc/modprobe.d/aa6e-blacklist.conf# Eliminate rtl-sdr driver conflictblacklist dvb_usb_rtl28xxuEOF
Warning: It's 'rtl' (letter l, not numeral 1). Verify the file's contents with the command 'cat /etc/modprobe.d/aa6e-blacklist.conf'. If all is OK, reboot the computer. Check that the "bad" driver is no longer there by checking with 'lsmod'.
Soundcard or RTL-SDR Dongle?
The TPP code supports two different input devices for I/Q signals. Use one or both:
- A soundcard, such as a USB soundcard running at 48 kHz, 16 bit sampling. The soundcard converts I/Q analog IF signals to 16-bit digital samples. You need a radio with I/Q outputs -- see next section.
- The RTL-SDR dongle, which is a complete VHF/UHF receiver on a USB dongle. It has its own 8-bit A/D converter, so no other soundcard is required.
If you want, you can leave a soundcard and an RTL-SDR dongle attached to your computer and choose which one to use when you start the software.
My Radio has no I/Q Outputs!
Most radios don't provide an IF output, let alone an "I/Q" IF output. How can I use this TPP stuff in that case?
If you want to receive off the air, or if you want a panadapter display of the IF of your existing rig, the simplest answer is a quadrature detector -- a direct-conversion receiver that provides I/Q (In-phase and Quadrature) IF outputs. Fortunately, these can be built inexpensively. For example, Five Dash Inc. currently sells the SoftRock Lite II Combined Receiver kit for $21 (3/2014). It receives upper and lower sidebands (+/- 24 kHz or more) around a crystal-controlled local oscillator frequency. You can select a crystal for one of several different ham bands, or you can choose one that matches the IF of your existing radio. (More elaborate SoftRocks are available to provide digital VFO control and transceive operation.)
To operate as a panadapter with your existing radio, you will probably have to go into the radio and bring out the IF for your external SoftRock. (Or maybe find room inside the radio for the SoftRock card.) That output connection should be carefully buffered so as not to affect the normal operation of your radio. There may be modification data for your radio already on the web. (Google is your friend!)
Some radios that are known to provide an I/Q baseband IF output:
- SoftRock kits
- Elecraft KX3
- Alinco DX-SR9
(Know of others? Send me the info.)
Sound Cards
In the article, we focus on some inexpensive sound card options. This might seem to go against the common advice that you need the best sound cards you can afford to do SDR well. However, we are focusing on the panadapter application, where we can be a little more relaxed than if we were making a high-performance SDR receiver.
Better sound cards in general will give better signal to noise (lower input noise level), higher dynamic range (up to 24 bit sampling) and better (flatter) amplitude and phase vs frequency that translates to better image rejection. (For very best image rejection, we should calibrate amplitude and phase response vs frequency. Calibration for a better sound card should be easier and perhaps more stable than for a cheap card.)
Better sound cards may give you higher maximum sample rates (96 or even 192 kHz). You would think that sample rate would translate to wider bandwidth for SDR, but this is not necessarily so. Sound cards are designed for sound, after all. The audio input amplifiers will typically be limited to 20 kHz or somewhat more, even for the higher sample rates. (A higher sample rate may be useful in digital audio systems for accurate filtering and mixing operations, but there is little if any signal power above ~20 kHz -- unless you're a dog!) An off-the-shelf sound card is unlikely to give you an SDR/panadapter passband of greater than +/- 20-40 kHz.
More careful evaluation of available sound cards for SDR/panadapter use at different price points would be welcome.
Note: You must use a soundcard that provides stereo (2 channel) input. There are cheap USB audio interface devices available that support stereo for output, but their input is mono only. They may be listed as "stereo" devices, but they won't do stereo input. (They're designed to support a stereo headset with a mono microphone.)
Hamlib
Hamlib is a C-based library and collection of utilities that allows your application program (like TPP) to communicate with CAT controllable amateur rigs. For TPP specifically, we use the Python bindings that are provided in the python-libhamlib2 package, as it is known in the Raspbian repository. Installing this package also installs libhamlib2, which is the C library itself. That's the minimum that TPP needs if you want to use Hamlib at all.
Hamlib has a lot of additional capabilities that might be handy, if you want to go deeper into rig communication. You can install the hamlib-utils, hamlib-doc, and related packages to see what's there. In particular, you might want to try the rigctl application that lets you talk to your rig from a command-line interface. Try
apt-get search hamlib
to see the available related packages. (If you don't have aptitude, use
apt-get install aptitude
to get it.)
Hamlib Issues
The TPP code uses the python-libhamlib2 package, as mentioned above. The Python package is built using SWIG applied to the Hamlib library, which is written in C. Because of Hamlib's tricky calling sequences, along with the major differences between Python and C (e.g. no pointers!), and SWIG's operation, the code you need to invoke Hamlib from Python can be troublesome. (It's not fully documented, to my knowledge.)
The code in the current version of TPP opens a Hamlib channel to the rig based on the "rig type". (The type codes are available in the Hamlib documentation.) The serial CAT interface is generally set up with default baud_rate, stop_bits, etc. If Hamlib does not have the right default settings for your situation, you may need to insert additional setup calls in the Python code. (We are working on this issue as of 9/2014.)
Raspberry Pi Issues
Please read the supplementary info mentioned above! Let the mailing list know any issues you have with the Pi, and they may be the subject of another paragraph or two in this section.
A few more places to look for information on the RPi:
- elinux.org Raspberry Pi Hub
- Adafruit raspberry lesson 1 (pdf)
- Wikipedia article on Raspberry Pi
Important: For all Pi Users -- Fixing the "Freeze" problem
The Raspberry Pi has serious problems running with a high-speed USB soundcard. I have found that there is no "stable" (hangup-free) configuration with the following configuration: latest Raspian (2014-01-07), X11 (startx), 48,000 Hz sampling, UCA202 or iMic soundcards, HDMI display. Using 44,100 Hz sampling may be a little better, but 22,050 works fine. (The Pi appears to be just too slow to handle the continuous data flow. This has been noted for data output. See this , and this .)
Confirming these Internet hints, it turns out the key problem is that the Pi cannot run USB 2.0 reliably for our purposes -- continuous 48 kHz or higher sampling rates. (The data rate is about 48K x 2 x 2 = 192 kB/s, much less than USB 2.0's theoretical maximum of 35 MB/s. Still, it seems to be too fast for the Pi to control reliably.)
We can slow down the USB transactions dramatically by dropping back to USB 1.0 (theoretical maximum speed 1.5 MB/s). This is accomplished by editing the Pi's boot file /boot/cmdline.txt. Insert the parameter 'dwc_otg.speed=1 ' at the beginning of the line. In my case, I then have
dwc_otg.speed=1 dwc_otg.lpm_enable=0 console=ttyAMA0,115200 kgdboc=ttyAMA0,115200 console=tty1 root=/dev/mmcblk0p2 rootfstype=ext4 elevator=deadline rootwait
You will need to reboot to have this become effective.
With this change, the Raspberry Pi will run TPP very much better. But there are a couple of catches:
- With your Pi's USB bus on version 1, many keyboards and mice will not operate. They often assume USB 2.0. Fortunately, the Ethernet connection is still available. If you can't find a compatible keyboard and mouse, you will have to connect with SSH from another device.
- If you want to use the RTL-SDR option, chances are that your DVB-T / RTL dongle requires USB 2.0! So if you want to mix RTL-SDR and Audio soundcard 48 kHz operation, you have a problem. For now, you need to edit /boot/cmdline.txt and reboot to switch from one to the other. Or spend $35 for another Raspberry Pi...
TPP on the Raspberry Pi with Adafruit 2.8" Touch Screen
Josh Murray, M0JMO, has got the Pi going with the Adafruit LCD display. Read his blog about his experience, and get his step-by-step PDF procedure. This makes a very nice mini Pi Panadapter.
How can I format the SD card for the Pi, if I'm running Windows?
The article focuses on how to do this assuming you have a Linux desktop, but it is quite possible to do it from Windows. Please check:
- Raspberry Pi Downloads web, using SD Formatter 4.0 software, and/or
- Another procedure that uses Win32DiskImager software.
Also note that, notwithstanding earlier information, a 4 GB SD card is not quite large enough to hold the Debian distribution if you use the "NOOB" procedure. Use 8 GB or larger!
Error: Python.h missing
A few people have reported that when they are compiling PyAudio, an error like the following appears:
src/_portaudiomodule.c:28:20: fatal error: Python.h: No such file or directory
On a "virgin" NOOB Raspbian install, following my instructions as printed, I don't see this problem. My system has the file /usr/include/python2.7/Python.h, which is the one that that gcc is looking for.
If anyone tracks down the source of this problem, please let me know. I generally advise to be sure that the python-dev package is loaded.
GPU-based FFT
I am aware of an FFT routine using the Pi's internal GPU (graphics processing unit) that speeds up the FFT calculation, though I have not tried it myself. See this article. It is probably not Python callable without a bit of work. For better or worse, FFT processing actually does not take a large fraction of the CPU in TPP.
Over-clocking?
If you've checked raspi-config or read something on the web about getting more out of your Pi by over-clocking, well so did I. I've just lost a number of hours recreating my system (keep backups!) after experimenting with overclocking. As the documentation says, operation is not guaranteed, and your system may be damaged. But...
You will want to have cpufrequtils package to let you see what Linux is trying to do. Using raspi-config or cpufreq-set, you can set the maximum clock frequency to 700 (default), 800, 900, 950, or 1000 MHz.
I found that 1000 MHz really won't work on my board. I got a kernel panic -- and I got a corrupted SD card. You might want to experiment with a throwaway system image! At least the hardware wasn't fried -- it did not run long enough.
Runnning at 900 MHz seemed to work for some tests, but you'd have to have a longer run to check for reliability and possible over-temperature of the CPU. Use the "ondemand" governor option (default). This bumps the operating frequency higher as needed, but returns to 700 MHz when demand is light. Choosing "performance" only gave a percent or so improvement. (In performance mode, you may not be able to reboot at the lower clock rate when you run into problems.)
So what results did I see? I ran the fft_bench.ipy benchmark. With 900 MHz max and 700 MHz min clock rates (theoretically 28.5% faster than default), I saw a 13-18% speedup. Presumably memory access or other factors limit the performance. Is that increase worth the possible reliability issues? You decide.
BeagleBone Issues
How can I format the SD card for the BBB, if I'm running Windows?
The article focuses on how to do this assuming you have a Linux desktop, but it is quite possible to do it from Windows. In addition to the R Pi methods discussed above, you can consult this article.
Can I use a BeagleBone "White" instead of the BBB?
The original BB (white mask card) should work for TPP, although there may be some small differences. (I haven't tested it.) You can also use the BeagleBoard XM, which is great because it has a good built-in sound card. The BeagleBoard XM and the original BeagleBone are made in smaller production runs, and therefore sell at a higher price point. Consult http://beagleboard.org for more product info.
BeagleBone Black Supply News
The BBB has been so popular that it is in short supply as of April, 2014, hopefully to be relieved in May. You could try placing an order to get yourself in the queue at Digikey, Adafruit, or your favorite distributor. The situation is discussed further here.
The TPP article and BBB procedures are based on the current Revision B board from CircuitCo. The new Rev. C board should be even better, with a 4 GB on-board flash (eMMC) that will allow full operation without any additional SD card, but the setup details will change somewhat. An announced new BBB production source through Element14 is also promising.
Si570 Programmable Oscillator Interface
(6/19/2014)
A recent addition to the TPP system is an interface for the Si570 chip, as used in the SoftRock Ensemble II and other SDR radios. See the Si570 Datasheet.
The Si570 is capable of generating stable frequencies between 10 and 169 MHz (for the inexpensive CMOS version). It is controlled through an I2S interface. To make this available to a general purpose computer, PE0FKO developed a special USB to I2C interface program to run on an inexpensive ATtiny85 controller chip. For further description, see [http://pe0fko.nl/SR-V9-Si570/ Firmware USB AVR Si570 controller] and [https://code.google.com/p/usbavrsi570/ Firmware to control a Si570 chip over the USB port].
There is a nice GUI control panel (CFGSR) for the USB-connected Si570 available for Windows. However, Linux users may want to use the command-line VK6JBL USB Softrock package. (You need to subscribe to the Yahoo group Softrock40 to access these files.) This is a standalone CLI utility program implemented in C.
The new TPP module Si570.py is an adaptation of the VK6JBL software for Python.
Additional Reference:
The Code
The Python code and associated files should be downloaded from SourceForge, as described above. The files provided at arrl.org/qst-in-depth may be usable, but they could be out of date.
We wish we could say the code is fully self-documenting. It may not be, if you're new to Python and Linux.
But if you have some grounding in these areas, you should be able to follow the essential parts.
User Contributions
Helpful contributions that may be of general interest:
- From Ric, KF3EB - [[KF3EB_1|Suggestions for better default sampling rate for the RTL-SDR and some additional commands]].
If you would like to add new functions to TPP, or if you have bug fixes to contribute, you are encouraged to submit patches or git pull requests to the author.
Future Directions
Here are a few possibilities for future work with the TPP system. Suggestions or code contributions? Let me know.
- Improve LCD4 user interface. (Touch screen input? Additional help screens?)
- Add SDR demodulation and sound output for one channel. (Requires second audio device)
- SDR transceive operation (a big change)
- performance enhancements (DSP based FFT on R Pi, simplify graphics or off-load to 2nd processor)