README.md
1
2liquid-dsp
3==========
4
5Software-Defined Radio Digital Signal Processing Library -
6[https://liquidsdr.org](https://liquidsdr.org)
7
8[](https://travis-ci.org/jgaeddert/liquid-dsp)
9[](https://choosealicense.com/licenses/mit/)
10
11liquid-dsp is a free and open-source digital signal processing (DSP)
12library designed specifically for software-defined radios on embedded
13platforms. The aim is to provide a lightweight DSP library that does not
14rely on a myriad of external dependencies or proprietary and otherwise
15cumbersome frameworks. All signal processing elements are designed to be
16flexible, scalable, and dynamic, including filters, filter design,
17oscillators, modems, synchronizers, complex mathematical operations, and
18much more.
19
20For more information, please refer to the
21[documentation](https://liquidsdr.org/doc) online.
22
23Installation and Dependencies
24-----------------------------
25
26liquid-dsp only relies on `libc` and `libm` (standard C and math)
27libraries to run; however liquid will take advantage of other libraries
28(such as [FFTW](http://www.fftw.org)) if they are available.
29
30If you build from the Git repository you will also need to install autotools
31for generating the `configure.sh` script (e.g.
32`brew install autoconf automake` on macOS,
33`sudo apt-get install automake autoconf` on Debian variants).
34
35### Installation ###
36
37The recommended way to obtain the source code is to clone the entire
38[repository](https://github.com/jgaeddert/liquid-dsp) from
39[GitHub](https://github.com):
40
41 git clone git://github.com/jgaeddert/liquid-dsp.git
42
43Building and installing the main library is a simple as
44
45 ./bootstrap.sh
46 ./configure
47 make
48 sudo make install
49
50If you are installing on Linux for the first time, you will also need
51to rebind your dynamic libraries with `sudo ldconfig` to make the
52shared object available.
53This is not necessary on macOS.
54
55If you decide that you want to remove the installed DSP library, simply
56run
57
58 sudo make uninstall
59
60Seriously, I won't be offended.
61
62### Run all test scripts ###
63
64Source code validation is a critical step in any software library,
65particulary for verifying the portability of code to different
66processors and platforms. Packaged with liquid-dsp are a number of
67automatic test scripts to validate the correctness of the source code.
68The test scripts are located under each module's `tests/` directory and
69take the form of a C source file. liquid includes a framework for
70compiling, linking, and running the tests, and can be invoked with the
71make target `check`, viz.
72
73 make check
74
75There are currently more than 90,000 checks to verify functional correctness.
76Drop me a line if these aren't running on your platform.
77
78### Examples ###
79
80Nearly all signal processing elements have a corresponding example in
81the `examples/` directory. Most example scripts generate an output
82`.m` file for plotting with [GNU octave](https://www.gnu.org/software/octave/)
83All examples are built as stand-alone programs and can be compiled with
84the make target `examples`:
85
86 make examples
87
88Sometimes, however, it is useful to build one example individually.
89This can be accomplished by directly targeting its binary
90(e.g. `make examples/modem_example`). The example then can be run at the
91command line, viz. `./examples/modem_example`.
92
93### Benchmarking tool ###
94
95Packaged with liquid are benchmarks to determine the speed each signal
96processing element can run on your machine. Initially the tool provides
97an estimate of the processor's clock frequency and will then estimate
98the number of trials so that each benchmark will take between 50 and
99500 ms to run. You can build and run the benchmark program with the
100following command:
101
102 make bench
103
104Available Modules
105-----------------
106
107 * _agc_: automatic gain control, received signal strength
108 * _audio_: source audio encoders/decoders: cvsd, filterbanks
109 * _buffer_: internal buffering, circular/static, ports (threaded)
110 * _channel_: additive noise, multi-path fading, carrier phase/frequency
111 offsets, timing phase/rate offsets
112 * _dotprod_: inner dot products (real, complex), vector sum of squares
113 * _equalization_: adaptive equalizers: least mean-squares, recursive
114 least squares, semi-blind
115 * _fec_: basic forward error correction codes including several
116 Hamming codes, single error correction/double error detection,
117 Golay block code, as well as several checksums and cyclic
118 redundancy checks, interleaving, soft decoding
119 * _fft_: fast Fourier transforms (arbitrary length), discrete sin/cos
120 transforms
121 * _filter_: finite/infinite impulse response, polyphase, hilbert,
122 interpolation, decimation, filter design, resampling, symbol
123 timing recovery
124 * _framing_: flexible framing structures for amazingly easy packet
125 software radio; dynamically adjust modulation and coding on the
126 fly with single- and multi-carrier framing structures
127 * _math_: transcendental functions not in the C standard library
128 (gamma, besseli, etc.), polynomial operations (curve-fitting,
129 root-finding, etc.)
130 * _matrix_: basic math, LU/QR/Cholesky factorization, inversion,
131 Gauss elimination, Gram-Schmidt decomposition, linear solver,
132 sparse matrix representation
133 * _modem_: modulate, demodulate, PSK, differential PSK, QAM, optimal
134 QAM, as well as analog and non-linear digital modulations GMSK)
135 * _multichannel_: filterbank channelizers, OFDM
136 * _nco_: numerically-controlled oscillator: mixing, frequency
137 synthesis, phase-locked loops
138 * _optim_: (non-linear optimization) Newton-Raphson, evoluationary
139 algorithms, gradient descent, line search
140 * _quantization_: analog/digital converters, compression/expansion
141 * _random_: (random number generators) uniform, exponential, gamma,
142 Nakagami-m, Gauss, Rice-K, Weibull
143 * _sequence_: linear feedback shift registers, complementary codes,
144 maximal-length sequences
145 * _utility_: useful miscellany, mostly bit manipulation (shifting,
146 packing, and unpacking of arrays)
147 * _vector_: generic vector operations
148
149### License ###
150
151liquid projects are released under the X11/MIT license.
152Short version: this code is copyrighted to me (Joseph D. Gaeddert),
153I give you full permission to do wantever you want with it except remove my
154name from the credits.
155Seriously, go nuts.
156See the LICENSE file or
157[https://opensource.org/licenses/MIT](https://opensource.org/licenses/MIT)
158for specific terms.
159
160
){kind=link}
){kind=link}