Skip to content

Latest commit

 

History

History
229 lines (181 loc) · 8.68 KB

README.md

File metadata and controls

229 lines (181 loc) · 8.68 KB
Raw

liquid-dsp

Software-Defined Radio Digital Signal Processing Library - https://liquidsdr.org

Build Status MIT License Packaging status

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, complex mathematical operations, and much more.

// get in, manipulate data, get out
#include <liquid/liquid.h>
int main() {
    unsigned int M  = 4;     // interpolation factor
    unsigned int m  = 12;    // filter delay [symbols]
    float        As = 60.0f; // filter stop-band attenuation [dB]

    // create interpolator from prototype
    firinterp_crcf interp = firinterp_crcf_create_kaiser(M,m,As);
    float complex x = 1.0f;  // input sample
    float complex y[M];      // interpolated output buffer

    // repeat on input sample data as needed
    {
        firinterp_crcf_execute(interp, x, y);
    }

    // destroy interpolator object
    firinterp_crcf_destroy(interp);
    return 0;
}

For more information, please refer to the documentation online.

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 libraries (such as FFTW) if they are available.

If you build from the Git repository you will also need to install autotools for generating the configure.sh script (e.g. brew install autoconf automake on macOS, sudo apt-get install automake autoconf on Debian variants).

Installation

The recommended way to obtain the source code is to clone the entire repository from GitHub:

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

Building and installing the main library is a simple as

./bootstrap.sh
./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. This is not necessary on macOS.

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

sudo make uninstall

Seriously, I won't be offended.

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

There are currently more than 110,000 checks to verify functional correctness. Drop me a line if these aren't running on your platform.

Testing Code Coverage

In addition to the full test suite, you can configure gcc to export symbol files to check for code coverage and then use gcovr to generate a full report of precisely which lines are covered in the autotests. These symbol files aren't generated by default and need to be enabled at compile-time through a configure flag:

./configure --enable-coverage

Running the tests and generating the report through gcovr can be invoked with the coverage make target:

make coverage

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

C++

Compiling and linking to C++ programs is straightforward. Just include <complex> before <liquid/liquid.h> and use std::complex<float> in favor of float complex. Here is the same example as the one above but in C++ instead of C:

// get in, manipulate data, get out
#include <complex>
#include <liquid/liquid.h>
int main() {
    unsigned int M  = 4;     // interpolation factor
    unsigned int m  = 12;    // filter delay [symbols]
    float        As = 60.0f; // filter stop-band attenuation [dB]

    // create interpolator from prototype
    firinterp_crcf interp = firinterp_crcf_create_kaiser(M,m,As);
    std::complex<float> x = 1.0f;   // input sample
    std::complex<float> y[M];       // interpolated output buffer

    // repeat on input sample data as needed
    {
        firinterp_crcf_execute(interp, x, y);
    }

    // destroy interpolator object
    firinterp_crcf_destroy(interp);
    return 0;
}

Available Modules

  • agc: automatic gain control, received signal strength
  • audio: source audio encoders/decoders: cvsd, filterbanks
  • buffer: internal buffering, circular/static, ports (threaded)
  • channel: additive noise, multi-path fading, carrier phase/frequency offsets, timing phase/rate offsets
  • 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)
  • vector: generic vector operations

License

liquid projects are released under the X11/MIT license. Short version: this code is copyrighted to me (Joseph D. Gaeddert), I give you full permission to do wantever you want with it except remove my name from the credits. Seriously, go nuts. See the LICENSE file or https://opensource.org/licenses/MIT for specific terms.