sdrx User Manual

Sdrx User Manual

Introduction
Compilation
Operation
Spectrum Displays
Stations List
Bugs and annoyances
Version history
Copying

1. Introduction
Currently sdrx is mainly a project intended for teaching myself the development of Software Defined Radio functions and Digital Signal Processing. I have built into sdrx an FFT-based Spectrum Display and demodulators for Frequency Modulated and Amplitude Modulated radio transmissions, Single Sideband (USB/LSB) signals and for CW (Morse code) transmissions. Sdrx has Controls for setting up RTL2832x-based SDR receivers via librtlsdr, Mirics-based SDR receivers via libmirsdrapi-rsp, Perseus SDR receivers via libperseus-sdr, Airspy R2 and Mini receivers via libairspy and now the ANAN 7000DLE MkII, an HPSDR derivative, via Ethernet and the sockets API.

These include the Center Frequency Spin Dial and direct Text Entry widget for entering the Receiver Center Frequency, selectable Automatic Frequency Control (AFC), Signal Strength Indicator (of progress bar type), Combo Boxes for selecting ADC Sampling Rate, FFT/Spectrum display Frame Rate, FFT/Spectrum Bandwidth, Modulation Mode, Weaver Frequency and Demodulator Bandwidth. Receiver Gain Mode (Manual/Auto/Audio Derived) can be selected by activating the relevant Radio Button and a Slider Control is available for setting the Receiver Gain manually. The decay rate of the Audio Derived AGC (ADAGC system) can be set by a Slider Control, from very slow to very fast as needed. A selectable Noise Activated Squelch with a Slider Control is available but in FM mode only.

As of version 0.9-beta, Sdrx includes functions for receiving and decoding Time Signal stations on VLF and Long Wave. Currently Sdrx can receive time and date data from MSF on 60kHz, RBU on 66.667kHz, DCF77 on 77.5kHz and TDF/Allouis on 162kHz. The detection of data bits and the synchronization signals is done by pattern matching rather than hard thresholding, so that Sdrx can successfully copy weak time station signals even well outside the official range. For example, the MSF signal on 60kHz can quite often be received and decoded even though it is about 3500km away! Development of time station receiving and decoding functions was done using a Perseus SDR receiver and a 1/4l GP antenna for the 30m amateur band (7.5m high).

Sdrx includes a Chebyshev Low Pass Filter which is used as a Low Pass "Roofing Filter" of the Sample Stream from the SDR device and also for setting the bandwidth of the FFT-based Spectrum Display. Individual demodulator functions also use Chebyshev filters to set the Demodulator Bandwidth according to the user's selection of Modulation Mode and for narrowing signal input to the AFC function. Play Back of demodulated signals is via the computer's Sound Card and by using the ALSA sound system API.

2. Compilation
Please note that I use Void Linux AMD64 which is a "bleeding edge" type distribution, so there may be compilation and/or run time difficulties, if you are using a relatively old distro. This is mostly true of the basic dependencies like GTK+-3.22 and Glade-3. Other dependencies are the RTLSDR library librtlsdr, the Mirics SDRplay_RSP_MiricsAPI-Linux library and the Perseus API. As of version 2.1, I have arranged for Autoconf/Automake to conditionally compile support for SDR devices only when its relevant API libraries above are installed on the system.

To compile the package, it may be preferable to first run the included "autogen.sh" script in the package's top directory, to produce a fresh build environment. Then the "configure" script can be run with optional parameters to override the default settings and compiler flags, e.g: ./configure --prefix=/usr CFLAGS="-g -O2" will override the default /usr/local installation prefix and the "-Wall -O2" compiler flags.

Running "make" in the package's top directory should produce the executable binary in src/. Running "make install" will install the binary into /usr/local/bin by default or under the specified prefix. At this time it is also necessary to manually copy Sdrx's working directory, .sdrx, to the user's home directory. This directory contains three files, the "sdrxrc" configuration file which will have to be edited by the user as required, the "stations" file which contains a default listing of some stations and the "sdrx.glade" GUI description file for the GTK+-3 UI Builder engine. The "stations" file must only be edited by activating the "Stations List" button and using the "Station Listing" editor window. This is described later in this documentation. Also the "sdrx.glade" file should only be edited with Glade-3, if cosmetic changes are desired to Sdrx's Graphical User Interface.

3. Operation
When sdrx is started for the first time, it will look for its configuration file sdrx.conf in the ~/.sdrx directory. If the directory is missing or the config file is missing or of an older version, then sdrx will ask the user to create a new default config file by opening a configuration dialog. The user then can specify the SDR Receiver Device from the available supported types, the device index (0 if only one device is connected), the default receiver frequency on start up, the frequency error in ppm of the receiver (e.g. the correction factor for the frequency error in the SDR receiver's reference), the modulation mode, and the ALSA PCM device name (usually hw:0,0 or hw:1,0).

Once this default configuration is applied, it will be updated each time sdrx is quit by the user. The following parameters are saved on exit to the sdrx.conf file: The config file's version number, the SDR receiver type and its device index, the current center frequency of the receiver, and the modulation mode. Additionally, sdrx saves the geometry of open windows (e.g. window size and position) for the main window, the station list, the spectrum display window and the time station window. It also saves the Audio Derived AGC setting and the spectrum bandwidth setting. When sdrx is started, it will open and place windows as they were on quitting and will also restore the saved settings.

The GTK+-3 user interface:
Sdrx's Main window contains the following widgets:

On the top row to the left, a "Spin Dial" for entering the receiver Center Frequency in Hz. It has ten digits and each is individually variable by pointing to it and scrolling the mouse or trackball or clicking the left or right button. It will only have effect if the "Spectrum" or "Playback" toggle button is active.
A "Status" indication frame, with a "yes" or "no" indicator to display the validity of the frequency entry. Please note that a "yes"-O.K. indication doesn't always mean that the dialed frequency has been accepted by the SDR device, feedback from these devices does not seem to be reliable.
In the second row from the top, the "Frequency kHz" entry widget, where the center frequency of the Tuner can be entered in kHz, as a convenience. Type the required Center Frequency and hit Enter to activate. It will only have effect if the "Spectrum" or "Playback" toggle button is active, as this also causes the opening and initialization of the SDR receiver.
The "Offset Hz" frame provides a check button for enabling or disabling the Automatic Frequency Control function for minimizing the Frequency Offset between the signal's Carrier and Sdrx's Center Frequency. This function allows for Synchronous AM demodulation if it is combined with one of the Single Side Band modes (USB/LSB) available in Sdrx.
In the third row from the top, the "Signal Strength" frame with a Progress Bar that gives some visual indication of the strength of the received signal in dBm. This was re-calibrated in Version 1.3 using a (borrowed) signal generator and has a range of -140 to 0 dBm. It seems that RTL-SDR devices do not provide gain or signal level data in normal use so this S-meter indicator does not work with such devices.
In the fourth row, there is a Button that opens a pop-up Menu from which the required Demodulation Mode can be selected. There is also a Combo Box for selecting the Weaver phasing frequency for SSB/CW demodulation and the Demodulator function's LPF bandwidth. In the fifth row, there are Combo Boxes for selecting the Sampling Rate of the Receiver, the FFT/Spectrum Frame Rate and the Bandwidth of the FFT function and Spectrum displays.
In the sixth row from the top, the Receiver Gain Control frame provides a slider that can be used to manually set the Tuner gain. This function is enabled or disabled by the "Manual" radio button, while the "Hardware" button enables the device's Gain Control and the "Audio" button enables an Audio Derived AGC (ADAGC )function. But please note that this is an experimental function and it may not work reliably with all SDR receiver types, usually due to noise spikes that seem to be generated when Gain settings are changed. For the Perseus Direct Sampling Receiver and the ANAN-7000DLE MkII, ADAGC is the default setting and seems to work fairly well.
Below this frame, the Audio AGC Decay frame contains a Slider Control to set the decays rate of ADAGC from very slow to very fast. The right setting depends on Modulation mode, e.g. Slow (low settings) for FM or AM broadcasts, Medium for SSB/CW modes and Fast if desired by the user.
The Perseus SDR frame at the bottom is specifically for Perseus receivers, e.g. enabling the Pre-amplifier and ADC Dither setting and selecting RF Attenuator values, if needed. As of Version 1.2, the "Att Auto" setting enables automatic selection of attenuators according to signal strength (it takes a very strong signal to do that). This frame appears only when the Perseus SDR is selected.
When the HPSDR ANAN-70DLE transceiver is selected, a dedicated frame appears with controls for the attenuator settings and antenna selection. When Auto Attenuator control is enabled, the attenuator settings will be automatically adjusted to avoid ADC overload. It will normally take an extremely powerful signal to do that!
Finally, in the bottom of the Sdrx window, the Time Stations toggle button opens the Time Station window for the display of time and date data from VLF/LW time stations, the Stations List button opens the Stations Listing window for managing and selecting stations to receive, the Play toggle button enables sound output via the ALSA API and the Spectrum toggle button opens the Spectrum Display window for the FFT-generated Waterfall and Scope displays.

4. FFT Spectrum Display Window
As of version 1.1, Sdrx has a separate Window for the FFT-generated Spectrum and Amplitude Displays of the incoming radio transmission. The lower display is in the "Waterfall" style and the upper in an "Oscilloscope" style. The width of both the displays corresponds to the currently selected Bandwidth of the FFT-Spectrum Filter. As of version 1.3, the Spectrum display has a frequency scale that has a range equal to the FFT bandwidth, either side of the current Center Frequency. In order to keep this in the center of the display (marked by a vertical bright cyan line), the frequency scale is shifted horizontally as required.
At the left side of the Spectrum display, there is a Relative Signal Level scale, calibrated from 0 to -80dB, relative to the strongest signal in the FFT bandwidth. This can be used to compare the Signal strength of different stations or signals in the Spectrum display. As of version 1.8, there is a vertical scale to the left of the waterfall display which shows elapsed seconds from the top of the display. This can be used to time repetitive signals registering on the waterfall display.

5. Stations List
As of version 0.8-beta, Sdrx includes a "Stations List" window, which can be opened by clicking the "Stations List" Button at the bottom left of the Sdrx main window. This window can be used to select a Station that is already saved in the ~/.sdrx/stations file, make and save a new Stations List entry, edit an existing entry and delete it if so desired. Clicking on a row in this window will enter the Frequency and Mode of the Station into Srdx and into the Receiver, if already activated. Also, clicking the "Up" or "Down" buttons will move the selection accordingly, to the next or previous row, again entering Station data into Sdrx and the Receiver. The "Delete" button removes the selected Row from the List, while the "New" button enters a new blank row into the list, to be edited by the user. This can be done manually, by selecting the blank row and entering the Station Name, the Frequency and the Mode. It is also possible to enter the last two from the current settings of Sdrx, by clicking with the middle button on to the blank row. The Name of the Station will still have to be entered manually. Finally, clicking the "Save" button will save all entries in the Stations List window to the ~/.sdrx/stations file in the user's directory.

As of version 0.9 beta, Sdrx has functions to receive, decode and display the Date, Time, Summer Time in Effect, Leap Second, DUT1, Parity Bit status and other data as transmitted by Time and Frequency Reference stations on VLF frequencies. Currently Sdrx can receive such data from the German DCF77 on 77.5kHz, the Russian RBU on 66.667kHz and British MSF on 60kHz. Currently development of this functionality is done using the Perseus SDR receiver and a Ground Plane antenna for the 10 MHz band (7.5m high). The first two stations are about 2500km away and MSF is 3500km away but in good weather conditions (no thunderstorms) it can be received and decoded successfully!
The time decoding function is activated from the Time Stations toggle button, which opens the Time Stations window for further action. In this window, the Time Station Combo Box allows selection of the Time station, while the Receive toggle button starts the relevant receiving and decoding functions. The Time Stations window has a display for the Date and Time, as well as many indicators for Status decodes and error conditions, depending on the Time Station. Some stations (e.g. RBU and MSF) transmit DUT1 too, while RBU transmits Julian Day and DUT data also.
Please note that even in good conditions, it takes a few minutes for Sdrx to sync with the time station and correctly decode date and time data.

6. Bugs and annoyances
I have fixed whatever bugs I came across testing sdrx but there may be some hiding, waiting for the right conditions to appear.

7. Version history
Version 0.1-beta This is the first release of sdrx and my first attempt at writing a significant DSP/SDR Receiver application. It used a 2-pole Butterworth LPF and had a WBFM demodulator. Play back was done by piping the o/p of the demodulator to "aplay"

Version 0.2-beta I added a demodulator for AM transmissions and Playback functionality by ALSA sound API. Changed the synchronization method between the async streaming function and the rest of sdrx, from a polling loop to using mutexes under pthreads.

Version 0.3-beta Added Demodulators for SSB and CW, using the Weaver Detector method. I also changed the Low Pass Filter to a 6-pole Chebyshev type for sharper cutoff and for operation with the Weaver SSB Demodulator.

Version 0.4-beta Added a "Spin Dial" for entering the Tuner center frequency. It has ten digits and each is individually variable by pointing to it and scrolling the mouse or trackball.

Version 0.5-beta Added support for the SDRPlay RSP1 SDR Receiver via the SDRplay_RSP_MiricsAPI-Linux library.

Version 0.6-beta Added additional GUI widgets (combo boxes, radio buttons, entry widgets and sliders) to give the user more choice and control over the parameters and settings affecting the operation of Sdrx. Made some changes to the AFC code to improve stability and facilitate Synchronous AM Demodulation by locking the Sdrx center frequency to the incoming AM signal's carrier frequency. Added a simple Signal Strength indicator widget (progress bar).

Version 0.7-beta Added support for the Mikrotelecom Perseus direct sampling SDR Receiver, via the libperseus-sdr library. Also improved the Audio Derived AGC function since it is the only way to automatically control the "Gain" (more correctly scale the audio output) of direct sampling receivers.

Version 0.8-beta Added a Stations List window, to allow saving station data to a file (~/.sdrx/stations) and loading and selecting stations from this file as desired by the user.

Version 0.9-beta I have modified the GUI to increase the size of the "Scope" display and re-organize the various widgets in the main window. Developed functions to receive, decode and display Date, Time, DUT1, Julian Day and other data and status flags from VLF Time stations (DCF77 on 77.5kHz, RBU on 66.667kHz and MSF on 60kHz) and TDF/Allouis on 162kHz LW.

Version 0.9 Fixed a bug that caused seg faults when Sdrx was run under different window managers than my own (openbox). This happened when the spectrum/waterfall display was enabled, because the final size of the spectrum/waterfall drawing areas was different to the original size request, possibly due to the different sizes of window decorations under different window managers.

Version 1.0 Fixed a bug in the function that tunes Sdrx to a frequency selected by clicking on the Spectrum display. It was possible to end up with a negative center frequency request that naturally resulted in an error message.

Version 1.1 Fixed a bug in the function that displays the waterfall. Pixel values were calculated incorrectly and so the pseudo-colors in the waterfall were not right. Also moved the Waterfall and Scope displays into a separate window so that they will only be displayed when the Spectrum button is toggled ON. The spectrum display can be "frozen" by toggling the Spectrum button OFF. The size of these displays has also been increased since they are now in an independent window.

Version 1.2 I calibrated the Signal Strength indicator using a borrowed signal generator, to show signal strength in dBm. I works, hopefully well enough, with the Perseus SDR and the SdrPlay RSP1 receivers. With RTL-SDR devices, there seems to be no signal strength data returned in Hardware AGC mode. I also added code that controls Perseus attenuators automatically, depending on signal strength. Fixed some obscure bugs that surfaced during this effort.

Version 1.3 I re-calibrated the Signal Strength indicator using a borrowed signal generator, to show signal strength in dBm. It works well enough, at least with the Perseus SDR and the SdrPlay RSP1 receivers. With RTL-SDR devices, there seems to be no signal strength data returned in Hardware AGC mode.
I added a Frequency scale at the bottom of the Spectrum display with a range equal to the FFT bandwidth, and a relative Level scale in dB at the left side so that signal strength of different stations can be compared. The Spectrum display is now logarithmic rather than linear
I also added code that controls Perseus attenuators automatically, depending on signal strength. Fixed some obscure bugs that surfaced during this effort.

Version 1.4 I migrated Sdrx to the latest GTK+-3.22 toolkit to bring it up to date. A lot of changes were needed to both the GUI and parts of the Sdrx source code, mainly the use of GTK3's GUI Builder for creating the user Interface and the revised drawing model of GDK for presenting the Spectrum displays.

Version 1.5: I carried out some source code clean-up and fixed a possible memory leak through the use of GtkBuilder objects.

Version 1.6: Edited the sdrx.glade file to obtain necessary widget margins and spacing with more efficient settings.

Version 1.7: I migrated the internationalization system from "intltoolize" to GNU GetText, as the former is now considered obsolete. Also replaced the autogen.sh script with a newer version.

Version 1.8: I edited some source files to silence warnings from the static "clang-analyzer" tool. The warnings did not represent real bugs in the code though, they were due to the analyzer not being able to fully trace program flow.
I also modified the spectrum display window to show vertical scales more clearly and added a vertical time scale to the left of the waterfall to show elapsed seconds from the top of the waterfall display.

Version 1.9: I arranged for the individual digits of the Center Frequency "spin button" display to be highlighted when the pointer is over one. I also changed the Spectrum Monitor display code to place the horizontal frequency scale correctly when in SSB or Synchronous AM mode. It was not taking into account the Weaver Method's frequency offset.

I have added a check button to the right of Center Frequency "spin button" display to enable the auto zeroing of digits to the right of the digit that is changed by the user. This makes it easier to tune Sdrx up or down in whole steps. I have also fixed a bug in the calculation of phase changes in the FM Detector and the Automatic Frequency Control.

Version 1.9.1: I edited Makefile.am so that make install will now place relevant application files (documentation, pixmaps, desktop file, glade UI file etc) into the right places.

Version 2.0: I fixed a bug in the calculation of phase angles with the use of the atan2() function. The discontinuity at around +/-PI was not fixed correctly so phase angles crossing the +/-PI boundary were calculated incorrectly. Also changed the way default ADC buffer sizes are calculated in order to reduce processor loading when the spectrum display is active.

Version 2.1: I arranged for Autoconf/Automake to conditionally compile support for SDR devices only when the relevant API libraries are installed on the system.

Version 2.2: I have added code to make the configuration of sdrx a little easier (by the use of a configuration dialog). Also added code to save and restore operating parameters (frequency, modulation mode, spectrum bandwidth, AGC settings etc) and the state of open windows (station list, spectrum display or time window).

Version 2.2.1: I have arranged for the configuration dialog to present existing configuration parameters when opened, rather than default values. Default values will be presented when a valid configuration file is not available. I have also fixed a bug in the configuration dialog code that sets the active SDR device in the SDR Device combo box.

Version 2.3: I have separated the FFT functions into a separate source file and I also modified the FFT() function so that the "bit reversed" sorting of input data is optional. This allows the "bit reversed" sorting to be done at the point were I/Q data is saved for the FFT() function thus saving some workload.

Version 2.3.1: I have separated the pseudo-colorization code for the waterfall into a separate function and edited it to improve the colorization algorithm.

Version 2.4: I made some changes to the code that controls RTL-SDR Receiver gain manually as it was not setting up Receiver Gain properly in Manual Gain Control mode. This has resulted in a higher Gain level at the full setting of the Manual Gain slider.

Version 2.5: I added code to support the Airspy R2 and Mini SDR Receivers, using Airspy's libairspy API. Sdrx now supports Perseus SDR, RTLSDR, SDRPlay RSP1 and Airspy R2 and Mini.

Version 2.6: Fixed a bug that was causing sdrx to suffer a segmentation fault and crash when changing samples buffer size. Also fixed a bug in the FM demodulator that resulted in only one of the two alternating raw samples buffers to be filtered. At the same time I changed the code of the FM demodulator so that sample rates are decimated by a factor of 4 to reduce workload and allow the spectrum display to work at the same time with the demodulator.

Version 2.6.1: Fixed a bug that prevented sdrx starting reception when the waterfall window was opened first. Also corrected the value of a flow control flag that might have affected saving of the station list.

Version 2.6.2: Fixed a bug in the code handling the Auto AGC/Manual AGC selection which was setting the Manual AGC slider to incorrect settings, when switching from Auto to Manual AGC. Also fixed a bug that prevented the setting of Airspy and RTL-SDR devices to Auto AGC, at the start up of Sdrx.

Version 2.7: Added support for the HPSDR-based ANAN-7000DLE MkII DDC/DUC transceiver (receive only). This support is rather limited in the sense that it only supports one ADC and DDC channel (the ANAN-7000DLE has two ADC's and four DDC channels, if the client software can support it).

Version 2.8: I have changed the way the FFT Spectrum display is timed (the Frame Rate of the FFT). Previously it was determine by the size of the Samples Buffer and that limited user choice. The Samples Buffer size is now determined by functions in sdrx and the relevant combobox is now used to select the FFT Frame Rate instead.

Version 2.8.1: Changed the installation commands in Makefile.am so that all the relevant files (desktop file, application pixmap, configuration file, executable binary etc) are installed under any location specified to the configure script by the --prefix= option. Also modified the program so that on first start up after installation, the application will create its working directory by copying files from the relevant directories under the installation prefix.

Version 2.8.2: I made minor changes in the Display_Frequency_Spin_Dial() function in display.c and in the Demodulated_Signal_Control() function in demodulate.c to silence runtime error messages from the Undefined Behavior sanitizer.

8. Copying This software package is released under the GNU Public License. Please see the COPYING file for more details.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details