liquid-dsp

Software-Defined Radio Digital Signal Processing Library

liquid-dsp is a free and open-source digital signal processing (DSP) library designed specifically for software-defined radios on embedded platforms. The aim is to provide a lightweight DSP library that does not rely on a myriad of external dependencies or proprietary and otherwise cumbersome frameworks. All signal processing elements are designed to be flexible, scalable, and dynamic, including filters, filter design, oscillators, modems, synchronizers, and complex mathematical operations.

For more information, please refer to the full documentation directory doc/ or download the pre-compiled .pdf documentation file (4.4 MB).

Installation and Dependencies

liquid-dsp only relies on libc and libm (standard C and math) libraries to run; however liquid will take advantage of other packages (such as FFTW) if they are available.

Getting the source code

There are two primary ways of obtaining the source code:

Clone the entire repository (recommended)

 $ git clone git://github.com/jgaeddert/liquid-dsp.git

or download the tarball (2.6 MB), validate the checksum, and unpack

 $ wget http://liquidsdr.org/downloads/liquid-dsp-1.2.0.tar.gz
 $ wget http://liquidsdr.org/downloads/liquid-dsp.md5
 $ md5sum --check liquid-dsp.md5
 $ tar -xf liquid-dsp-1.2.0.tar.gz

Installation

Once you have obtained a copy of the source code, you can now build the DSP library (NOTE: if you chose to clone the repository, you will need to also run the additional ./bootstrap.sh script before configuring):

$ ./bootstrap.sh     # <- only if you cloned the Git repo
$ ./configure
$ make
$ sudo make install

If you are installing on Linux for the first time, you will also need to rebind your dynamic libraries with sudo ldconfig to make the shared object available.

If you decide that you want to remove the installed DSP library, simply run

$ sudo make uninstall

Run all test scripts

Source code validation is a critical step in any software library, particulary for verifying the portability of code to different processors and platforms. Packaged with liquid-dsp are a number of automatic test scripts to validate the correctness of the source code. The test scripts are located under each module's tests/ directory and take the form of a C source file. liquid includes a framework for compiling, linking, and running the tests, and can be invoked with the make target check, viz.

$ make check

Examples

Nearly all signal processing elements have a corresponding example in the examples/ directory. Most example scripts generate an output .m file for plotting with GNU octave All examples are built as stand-alone programs and can be compiled with the make target examples:

$ make examples

Sometimes, however, it is useful to build one example individually. This can be accomplished by directly targeting its binary (e.g. make examples/modem_example). The example then can be run at the command line, viz. ./examples/modem_example.

Benchmarking tool

Packaged with liquid are benchmarks to determine the speed each signal processing element can run on your machine. Initially the tool provides an estimate of the processor's clock frequency and will then estimate the number of trials so that each benchmark will take between 50 and 500 ms to run. You can build and run the benchmark program with the following command:

$ make bench

Documentation

No serious software library would be complete without proper documentation. There are basically two ways to get it: the easy way and the hard way.

The easy way: download the pre-compiled documentation file (4.4 MB).
The hard way: build from scratch. Because all of the figures within the documentation are generated with liquid itself, the documentation must be built from scratch and requires the following free programs and packages:

pdflatex LaTeX compiler
bibtex LaTeX bibliography generator
pgf (version 2.0) LaTeX figures
epstopdf convert .eps to .pdf (necessary for figures)
gnuplot plotting program
pygments pretty syntax hilighting program

Once these dependencies are installed, you may build the documentation with the following command:

    $ make doc

Available Modules

agc: automatic gain control, squelch, received signal strength
audio: source audio encoders/decoders: cvsd, filterbanks
buffer: internal buffering, circular/static, ports (threaded)
dotprod: inner dot products (real, complex), vector sum of squares
equalization: adaptive equalizers: least mean-squares, recursive least squares, semi-blind
fec: basic forward error correction codes including several Hamming codes, single error correction/double error detection, Golay block code, as well as several checksums and cyclic redundancy checks, interleaving, soft decoding
fft: fast Fourier transforms (arbitrary length), discrete sin/cos transforms
filter: finite/infinite impulse response, polyphase, hilbert, interpolation, decimation, filter design, resampling, symbol timing recovery
framing: flexible framing structures for amazingly easy packet software radio; dynamically adjust modulation and coding on the fly with single- and multi-carrier framing structures
math: transcendental functions not in the C standard library (gamma, besseli, etc.), polynomial operations (curve-fitting, root-finding, etc.)
matrix: basic math, LU/QR/Cholesky factorization, inversion, Gauss elimination, Gram-Schmidt decomposition, linear solver, sparse matrix representation
modem: modulate, demodulate, PSK, differential PSK, QAM, optimal QAM, as well as analog and non-linear digital modulations GMSK)
multichannel: filterbank channelizers, OFDM
nco: numerically-controlled oscillator: mixing, frequency synthesis, phase-locked loops
optim: (non-linear optimization) Newton-Raphson, evoluationary algorithms, gradient descent, line search
quantization: analog/digital converters, compression/expansion
random: (random number generators) uniform, exponential, gamma, Nakagami-m, Gauss, Rice-K, Weibull
sequence: linear feedback shift registers, complementary codes, maximal-length sequences
utility: useful miscellany, mostly bit manipulation (shifting, packing, and unpacking of arrays)
experimental: artificial neural networks, communications channel modeling, threaded ports, filterbank audio synthesizer, continuous-phase modulation, direct digital synthesis, quadrature mirror filterbanks, advanced symbol timing recovery, OFDM/OQAM

Additional notes

Splatter graphics were created using GIMP with two splatter brush plug-ins.

b12mihai/liquid-dsp