DOCSEARCHbyAlgolia
Submit Docs

liquid-dsp Documentation

repository·master·Indexed 25 days ago

https://github.com/jgaeddert/liquid-dsp

A lightweight, high-performance digital signal processing library optimized for software-defined radios on embedded platforms. It provides tools for FIR and IIR filter design, digital modems, synchronization, Forward Error Correction (FEC), CRC, and spectral analysis. The library includes a comprehensive autotest framework (xautotest) for functional validation and a flexible logging system configurable at both compile-time via CMake and run-time.

Tokens
8.2K
Snippets
19
Records
43
Agent score
81%

What's inside liquid-dsp

  1. Overview of liquid-dsp

    master
    liquid-dsp is a free and open-source digital signal processing (DSP) library specifically designed for software-defined radios (SDR) on embedded platforms. It is a lightweight library with minimal external dependencies (relying primarily on libc and libm), though it can leverage libraries like FFTW if available. It provides flexible and scalable signal processing elements including filters, oscillators, modems, and synchronizers.

  2. Understand liquid-dsp logging capabilities

    master

    The liquid-dsp library provides a baseline logging system for run-time control of terminal output (level, formatting, etc.). It is designed for minimal overhead and supports thread-safe operations, writing to files, and custom callbacks.

    Key features include:

    • Dynamic Control: Log levels can be selected at run-time.
    • Customization: Supports customizable formatting (color, file, line number, date/timestamp).
    • Performance: Ability to remove logging capabilities at compile-time to improve speed.
    • Tracing: Includes an internal static logger for tracing specific to liquid-dsp and integration with the library's error handling.
    • Extensibility: You can create loggers separate from the internal liquid-dsp logging.

  3. How error handling works in liquid-dsp

    master
    Since liquid-dsp is a C library, it does not use C++ exceptions. Instead, it relies on integer-based return values to track issues during software processing. Most methods return an error code that you should check to determine if an algorithm or method has executed successfully.

  4. Handle warnings and unstable tests

    master
    When using AUTOTEST_WARN(string), the autotest program prints the provided warning message. The framework tracks which tests elicit warnings and automatically adds them to a list of 'unstable tests'. This allows developers to identify tests that pass but exhibit non-ideal behavior.

  5. Reproduce test failures with random seeds

    master

    By default, tests use time(NULL) as a random seed, providing different coverage each run. To ensure repeatability for debugging, you can specify a fixed seed using the -R flag.

    When a test fails, the autotest seed is printed in the output. You can use this seed to re-run the suite with the exact same random sequence.

  6. License and dependency considerations

    master

    liquid-dsp is released under the X11/MIT license.

    Important Licensing Note: By default, liquid-dsp attempts to link to FFTW if available. Because FFTW (v1.3+) is licensed under GPL v2, linking to it means you cannot distribute your application without also distributing the FFTW source code.

    If you require a more permissive distribution model, you can compile liquid-dsp without FFTW. This will result in slightly slower performance and limited functionality, but avoids the GPL requirements.

  8. Use logging presets

    master

    Instead of configuring individual bit fields, you can use predefined presets to quickly set up logging styles:

    • LIQUID_LOG_COMPACT: Minimal detail (e.g., 09:25:46 [I] message)
    • LIQUID_LOG_SHORT: Default configuration (e.g., 08:18:35 [info ] message)
    • LIQUID_LOG_MEDIUM: Includes date, time, filename, and line.
    • LIQUID_LOG_FULL: Maximum available information.

  9. Configure logging at compile-time via CMake

    master

    To minimize processing overhead in performance-critical applications, you can use CMake flags to disable or restrict logging during the build process.

    Disable logging completely

    To remove the logging framework entirely, use the ENABLE_LOGGING flag. When disabled, log events below LIQUID_INFO are ignored, and events at LIQUID_INFO or higher are printed to stdout without formatting.

    Set a minimum compile-time log level

    To prevent code for lower log levels from even being compiled, use the LOGGING_LEVEL flag. This removes the overhead of the run-time level check for those levels.

    Disable ANSI color

    If your terminal does not support color, you can disable all ANSI color flags.

    Example Commands:

    # Disable logging completely
cmake -D ENABLE_LOGGING=OFF ..

# Remove trace and debug levels from the build
cmake -D LOGGING_LEVEL=info ..

# Disable color output
cmake -D ENABLE_COLOR=OFF ..

  10. Install liquid-dsp from source

    master

    To install liquid-dsp, clone the repository from GitHub and use the CMake build system.

    Note for Linux users: If this is your first time installing, you must run sudo ldconfig after installation to make the shared objects available to the system. This step is not required on macOS.

    # Clone the repository
git clone git://github.com/jgaeddert/liquid-dsp.git

# Build and install
mkdir build
cd build
cmake ..
make
sudo make install

# On Linux, rebind dynamic libraries
sudo ldconfig

  11. Implement digital modems and synchronization

    master

    Liquid-DSP provides high-level objects for communication systems:

    • Modems: Use modem_example.c for general digital modulation/demodulation or modem_arb_example.c for arbitrary signal constellation points.
    • Symbol Timing Recovery: Use the symsync_crcf family (e.g., symsync_crcf_example.c) to recover timing from symbols using matched filters.
    • Carrier Recovery: Use the nco_pll interface (nco_pll_example.c) to track complex sinusoids or recover carrier frequency in digital modems (nco_pll_modem_example.c).
    • Frame Synchronization: Use framesync64_example.c or flexframesync_example.c to encapsulate and decode data frames for over-the-air transmission.

  12. Integrate liquid-dsp into a CMake project

    master

    You can integrate liquid-dsp into your C/C++ applications using the liquid::liquid exportable interface. There are two primary methods:

    1. Local Installation: Install liquid-dsp on your system using CMake, then use find_package(liquid REQUIRED) in your CMakeLists.txt.
    2. Dynamic Fetching: Use CMake's FetchContent module to automatically download and build liquid-dsp as part of your application's build process. This is often easier for portability.

    When using FetchContent, you can disable non-essential components like tests, benchmarks, and examples to speed up your build using the following cache variables:

    • BUILD_AUTOTESTS (set to OFF to disable tests)
    • BUILD_BENCHMARKS (set to OFF to disable benchmarks)
    • BUILD_EXAMPLES (set to OFF to disable examples)
    # CMakeLists.txt - example using FetchContent
cmake_minimum_required(VERSION 3.10)
project(liquid_test C)

include(FetchContent)
FetchContent_Declare(
    liquid
    GIT_REPOSITORY https://github.com/jgaeddert/liquid-dsp.git
    GIT_TAG        v1.7.0
)

set(BUILD_AUTOTESTS  OFF CACHE INTERNAL "Disable building liquid tests")
set(BUILD_BENCHMARKS OFF CACHE INTERNAL "Disable building liquid benchmarks")
set(BUILD_EXAMPLES   OFF CACHE INTERNAL "Disable building liquid examples")
FetchContent_MakeAvailable(liquid)

add_executable(main main.c)
target_link_libraries(main liquid)