csdr is a command line tool to carry out DSP tasks for Software Defined Radio.
It can be used to build simple signal processing flow graphs, right from the command line.
The included libcsdr library contains the DSP functions that csdr makes use of. It was designed to use auto-vectorization available in gcc.
Feel free to use it in your projects.
Most of the code is available under the permissive BSD license, with some optional parts under GPL. For additional details, see licensing.
csdr has already been used to build:
- AM, FM, SSB, CW and BPSK31 demodulators and waterfall display in OpenWebRX,
- AM, FM, SSB modulators in qtcsdr that can also be used standalone with rpitx,
- a demodulator for FSK transmissions sent with the CC1111 wireless MCU, and also a standalone RTTY demodulator.
This animation shows the Gardner timing recovery algorithm in csdr locking on a baseband BPSK signal:
(The symbol is sampled at the left red dot. The algorithm moves the middle dot as close to the symbol transition center, as possible.)
The OpenWebRX project is hosting csdr packages in their repositories. Please click the respective link for Debian or Ubuntu.
mkdir build
cd build
cmake ..
make
sudo make install
sudo ldconfig
The project was only tested on Linux. It has the following dependencies: libfftw3-dev, libsamplerate-dev
To run the examples, you will also need rtl_sdr from Osmocom, and the following packages (at least on Debian): mplayer octave gnuplot gnuplot-x11
If you compile fftw3 from sources for use with libcsdr, you need to configure it with 32-bit float support and shared libaries enabled:
./configure --enable-float --enable-shared
(This is for fftw3, not libcsdr.)
The library was written by Andras Retzler, HA7ILM <[email protected]>.
I would like to say special thanks to Péter Horváth, PhD (HA5CQA) and János Selmeczi, PhD (HA5FT) for their continous help and support.
rtl_sdr -s 240000 -f 89500000 -g 20 - | csdr convert -i char -o float | csdr fmdemod | csdr fractionaldecimator 5 | csdr deemphasis --wfm 48000 50e-6 | csdr convert -i float -o s16 | mplayer -cache 1024 -quiet -rawaudio samplesize=2:channels=1:rate=48000 -demuxer rawaudio -
- Baseband I/Q signal is coming from an RTL-SDR USB dongle, with a center frequency of
-f 104300000Hz, a sampling rate of-s 240000samples per second. - The
rtl_sdrtool outputs an unsigned 8-bit I/Q signal (one byte of I sample and one byte of Q coming after each other), butlibcsdrDSP routines internally use floating point data type, so we convert the data stream ofunsigned chartofloatbycsdr convert. - We want to listen one radio station at the frequency
-f 89500000Hz (89.5 MHz). - No other radio station is within the sampled bandwidth, so we send the signal directly to the demodulator. (This is an easy, but not perfect solution as the anti-aliasing filter at RTL-SDR DDC is too short.)
- After FM demodulation we decimate the signal by a factor of 5 to match the rate of the audio card (240000 / 5 = 48000).
- A de-emphasis filter is used, because pre-emphasis is applied at the transmitter to compensate noise at higher frequencies. The time constant for de-emphasis for FM broadcasting in Europe is 50 microseconds (hence the
50e-6). - Also,
mplayercannot play floating point audio, so we convert our signal to a stream of 16-bit integers.
rtl_sdr -s 2400000 -f 89300000 -g 20 - | csdr convert -i char -o float | csdr shift -0.085 | csdr firdecimate 10 0.05 | csdr fmdemod | csdr fractionaldecimator 5 | csdr deemphasis --wfm 48000 50e-6 | csdr convert -i float -o s16 | mplayer -cache 1024 -quiet -rawaudio samplesize=2:channels=1:rate=48000 -demuxer rawaudio -
- We want to listen to one radio station, but input signal contains multiple stations, and its bandwidth is too large for sending it directly to the FM demodulator.
- We shift the signal to the center frequency of the station we want to receive:
-0.085*2400000 = -204000, so basically we will listen to the radio station centered at 89504000 Hz. - We decimate the signal by a factor of 10. The transition bandwidth of the FIR filter used for decimation will be 10% of total bandwidth (as of parameter 0.05 is 10% of 0.5). Hamming window will be used for windowed FIR filter design.
Sample rates look like this:
2.4 Msps 240 ksps 48 ksps
I/Q source ------------> FIR decimation ------------> FM demod -> frac. decimation ---------> deemphasis -> sound card
The first parameter is the frequency in MHz, and the second optional parameter is the RTL-SDR tuner gain in dB.
rtl_sdr -s 2400000 -f 145000000 -g 20 - | csdr convert -i char -o float | csdr shift `python -c "print(float(145000000-145350000)/2400000)"` | csdr firdecimate 50 0.005 | csdr fmdemod | csdr limit | csdr deemphasis --nfm 48000 | csdr agc | csdr convert -i float -o s16 | mplayer -cache 1024 -quiet -rawaudio samplesize=2:channels=1:rate=48000 -demuxer rawaudio -
- Note that the decimation factor is higher (we want to select a ~25 kHz channel).
- Also there is a python hack to calculate the relative shift offset. The real receiver frequency is
145350000Hz. - The de-emphasis filter is a fixed FIR filter that has a passband of 400-4000 Hz, also with a roll-off of -20 dB/decade.
rtl_sdr -s 2400000 -f 145000000 -g 20 - | csdr convert -i char -o float | csdr shift `python -c "print(float(145000000-144400000)/2400000)"` | csdr firdecimate 50 0.005 | csdr amdemod | csdr dcblock | csdr agc | csdr limit | csdr convert -i float -o s16 | mplayer -cache 1024 -quiet -rawaudio samplesize=2:channels=1:rate=48000 -demuxer rawaudio -
amdemodis used as demodulator.agcshould be used for AM and SSB.
rtl_sdr -s 2400000 -f 145000000 -g 20 - | csdr convert -i char -o float | csdr shift `python -c "print(float(145000000-144400000)/2400000)"` | csdr firdecimate 50 0.005 | csdr bandpass --fft --low 0 --high 0.1 0.05 | csdr realpart | csdr agc | csdr limit | csdr convert -i float -o s16 | mplayer -cache 1024 -quiet -rawaudio samplesize=2:channels=1:rate=48000 -demuxer rawaudio -
- It is a modified Weaver-demodulator. The complex FIR filter removes the lower sideband and lets only the upper pass (USB). If you want to demodulate LSB, change
bandpass --low 0 --high 0.1tobandpass --low -0.1 --high 0.
Some basic concepts on using libcsdr:
csdr convert can convert a real/complex stream from one data format to another, to interface it with other SDR tools and the sound card.
You can use csdr convert on complex streams, too, as they are only interleaved values (I,Q,I,Q,I,Q... coming after each other).
csdr should be considered as a reference implementation on using libcsdr. For additional details on how to use the library, check csdr.cpp.
Regarding csdr, the first command-line parameter is the name of a function, others are the parameters for the given function. Compulsory parameters are noted as <parameter>, optional parameters are noted as [parameter].
All commands also provide a short help text and information about their mandatory and optional parameters when called with the --help argument.
Optional parameters have safe defaults, you can query the --help text to see what they are.
Syntax:
csdr realpart
It takes the real part of the complex signal, and throws away the imaginary part.
Syntax:
csdr limit [max_amplitude]
The input signal amplitude will not be let out of the -max_amplitude ... max_amplitude range.
Syntax:
csdr gain <gain>
It multiplies all samples by gain.
Syntax:
csdr shift <rate>
It shifts the signal in the frequency domain by rate.
rate is a floating point number between -0.5 and 0.5.
rate is relative to the sampling rate.
Internally, this function uses trigonometric addition formulas to generate sine and cosine.
Syntax:
csdr dcblock
This is a DC blocking IIR filter.
Syntax:
csdr fmdemod
It is an FM demodulator that is based on the quadri-correlator method, and it can be effectively auto-vectorized, so it should be faster.
Syntax:
csdr deemphasis [--wfm|--nfm] <sample_rate> [tau]
When used in --wfm mode, it performs de-emphasis with the given RC time constant tau.
Different parts of the world use different pre-emphasis filters for FM broadcasting: In Europe, tau should be chosen as 50e-6, and in the USA, tau should be 75e-6.
When used in --nfm mode, it uses fixed filters so it works only on predefined sample rates. See the file src/lib/predefined.h for the available rates and information on how to add others.
Syntax:
csdr amdemod
It is an AM demodulator that uses sqrt. On some architectures sqrt can be directly calculated by dedicated CPU instructions, but on others it may be slower.
Syntax:
csdr firdecimate <decimation_factor> [transition_bw] [--window=hamming]
It is a decimator that keeps one sample out of decimation_factor samples.
To avoid aliasing, it runs a filter on the signal and removes spectral components above 0.5 × nyquist_frequency × decimation_factor from the input signal.
Syntax:
csdr fractionaldecimator <decimation_rate> [--format=(complex|float)] [--numpoly=12] [--transition=0.0e] [--window=hamming] [--prefilter]
It can decimate by a floating point ratio.
It uses Lagrange interpolation, where numpoly (12 by default) input samples are taken into consideration while calculating one output sample.
This function is available for both complex and real data, --format to switch. Possible arguments: complex and float.
It can filter the signal with an anti-aliasing FIR filter before applying the Lagrange interpolation. This filter is inactive by default, but can be activated by:
- passing only the
transition, or both thetransitionand thewindowparameters of the filter, - using the
--prefilterswitch to switch this filter on with the default parameters.
Syntax:
csdr bandpass <transition_bw> <--low=low_cut> <--high=high_cut> [--window=hamming]
It performs a bandpass FIR filter on complex samples, using FFT and the overlap-add method.
low_cut and high_cut both may be between -0.5 and 0.5, and are proportional to the sampling frequency.
Syntax:
csdr agc [--format=(complex|float|s16)] [--profile=(slow|fast)] [--hangtime=t] [--reference=r] [--attack=a] [--decay=d] [--max=m] [--initial=i]
It is an automatic gain control function.
This command can process different sample formats, use --format to switch. Available formats: complex, float and s16.
--profile switches between the two sets of default values for "fast" and "slow" agc. You can still override them
with the arguments below for fine-tuning.
If no arguments are given, the agc will run with the defaults of the "fast" profile:
hang_time = 200
reference = 0.800000
attack_rate = 0.100000
decay_rate = 0.001000
max_gain = 65536.000000
initial_gain = 1.000000
All arguments below take a number as a parameter:
--hangtimeis the number of samples to wait before starting to increase the gain after a peak.--referenceis the reference level for the AGC. It tries to keep the amplitude of the output signal close to that.--attackis the rate of decreasing the signal level if it gets higher than it used to be before.--decayis the rate of increasing the signal level if it gets lower than it used to be before.- AGC won't increase the gain over
--max. --initialsets an initial gain value (best guess)
Its default parameters work best for an audio signal sampled at 48000 Hz.
Syntax:
csdr fft <fft_size> <every_n_samples> [--window=hamming]
It performs an FFT on the first fft_size samples out of every_n_samples, thus skipping every_n_samples - fft_size samples in the input.
Syntax:
csdr logpower [--add_db=0]
Calculates 10*log10(i^2+q^2)+add_db for the input complex samples. It is useful for drawing power spectrum graphs.
Syntax:
csdr adpcm <--encode|--decode> [--sync]
Encodes or decodes an ADPCM audio stream. An ADPCM audio stream uses only 25% of the bandwidth compared to the original.
Can optionally embed proprietary synchronization frames with --sync (used in OpenWebRX).
Syntax:
csdr fftadpcm <fft_size>
Encodes the FFT output vectors of fft_size. It should be used on the data output from csdr logpower.
It resets the ADPCM encoder at the beginning of every vector, and to compensate it, COMPRESS_FFT_PAD_N samples are added at beginning (these equal to the first relevant sample).
Syntax:
csdr fftswap <fft_size>
It exchanges the first and second part of the FFT vector, to prepare it for the waterfall/spectrum display. It should operate on the data output from csdr logpower.
Syntax:
csdr squelch --fifo <squelch_fifo> --outfifo <smeter_fifo> <decimation> <report_every_nth>
This is a controllable squelch, which reads the squelch level input from <squelch_fifo> and writes the power level output to <smeter_fifo>. Both input and output are in the format of %g\n. While calculating the power level, it takes only every <decimation> sample into consideration. It writes the S-meter value for every <report_every_nth> buffer to <smeter_fifo>. If the squelch level is set to 0, it it forces the squelch to be open. If the squelch is closed, it will stop outputting data.
Syntax:
csdr logaveragepower <fft_size> <avgnumber> [--add=0]
It works like csdr logpower, but it calculates the average of every avgnumber FFTs.
Syntax:
csdr varicodedecode
It expects symbols encoded as 0x00 and 0x01 bytes on the input, and extracts Varicode characters from them.
Syntax:
csdr timingrecovery [--algorithm=gardner] <decimation> [loop_gain] [max_error] [--add_q]
It implements non-data aided timing recovery (Gardner and early-late gate algorithms).
More information (section 4.4 from page 34)
Syntax:
csdr dbpskdecode
It implements a differential BPSK demodulator, with the following data flow:
The output is 0x00 or 0x01.
Some parameters can be changed while the csdr process is running. To achieve this, some csdr functions have special parameters. You have to supply a fifo previously created by the mkfifo command. Processing will only start after the first control command has been received by csdr over the FIFO.
csdr shift --fifo <fifo_path>
By writing to the given FIFO file with the syntax below, you can control the shift rate:
<shift_rate>\n
E.g. you can send -0.3\n
Processing will only start after the first control command has been received by csdr over the FIFO.
csdr bandpass --fifo <fifo_path> <transition_bw> [--window=hamming]
By writing to the given FIFO file with the syntax below, you can control the shift rate:
<low_cut> <high_cut>\n
E.g. you can send -0.05 0.02\n
csdr was tested with GNU Radio Companion flowgraphs. These flowgraphs are available under the directory grc_tests, and they require the gr-ha5kfu set of blocks for GNU Radio.
The repo also contains a command line tool called nmux, which is a TCP stream multiplexer. It reads data from the standard input, and sends it to each client connected through TCP sockets. Available command line options are:
--port (-p), --address (-a):TCP port and address to listen.--bufsize (-b), --bufcnt (-n): Internal buffer size and count.--help (-h): Show help message.
nmux was originally written for use in OpenWebRX.
The code in this library is under mixed license, with parts being provided under BSD and other parts under GPL license. Please see the individual files for details.