gr-qradiolink

IMPORTANT NOTICE: This is AI-generated code.

This code has not been reviewed by professional coders, it is a large task. There are tests available in the codebase, please review those and their code.

GNU Radio out-of-tree (OOT) module for QRadioLink blocks.

Branch main: GNU Radio 3.10 OOT (CMake find_package(gnuradio)). The experimental GNU Radio 4 port is on branch gnuradio4 (README_gr4.md on that branch).

Code navigation: docs/CODE_MAP.md (files, functions, block index). gr-ident ZMQ mode routing: docs/GRIDENT_ZMQ.md (gr-ident preamble on :5560).

Modulation validation

Reference IQ for modulator blocks was checked with radio-modulation-validator (2026-05-31). Summary: SOFT FAIL — 6/19 blocks passed, 13 soft fail, 0 hard fail, 3 skipped.

All tested modes were identified at the correct modulation family (FSK, PSK, AM, FM). Order-level soft fails (for example FSK predicted as CPFSK instead of 4FSK or GMSK) reflect limits of the validator's order classifier, not evidence that these modulators produce the wrong waveform family.

The scan uses built-in reference IQ (not built OOT blocks); results apply to modes listed in this README on main and are mirrored on gnuradio4.

Full per-block results: VALIDATION_REPORT.md

Publication

This project is documented in the following preprint:

Cryptographically Keyed Gaussian-Distributed Spread-Spectrum for Enhanced Covert Communications: Design, Implementation, and Simulated Performance in ITU Channel Models
IACR Cryptology ePrint Archive, Paper 2025/108456
https://eprint.iacr.org/2025/108456

Archive record timestamp: 21 March 2026.

Overview

This module provides GNU Radio blocks for various digital and analog modulation schemes, specialized for amateur radio and digital voice communications.

This module was converted from the QRadioLink application, which is a multimode SDR transceiver for GNU Radio, ADALM-Pluto, LimeSDR, USRP, and other SDR hardware. The original source code is located at https://codeberg.org/qradiolink/qradiolink.

Validation: Converted blocks that have a counterpart in QRadioLink have been validated against the original QRadioLink source (branch next, codeberg.org/qradiolink/qradiolink) so that flowgraphs, filter parameters, scaling constants, and block behaviour match. SSB and AM modulator/demodulator chains (including CESSB structure and clipper/stretcher constants) were restored to match the original where they had diverged. Some blocks in this module have no corresponding source in QRadioLink's src/gr/; their origin is stated in the table below.

Credit and origin:

• QRadioLink (Codeberg) is the origin of the following modes (validated against codeberg.org/qradiolink/qradiolink branch next, src/gr/): modulation/demodulation (2FSK, 4FSK, GMSK, BPSK, QPSK, AM, SSB, NBFM, WBFM), digital voice (FreeDV, M17, DMR), and supporting blocks (RSSI, M17 deframer, MMDVM source/sink, clipper, stretcher, zero_idle_bursts, gr_4fsk_discriminator, demod_mmdvm_multi, demod_mmdvm_multi2, mod_mmdvm_multi2). The DSP and mode behaviour for these blocks were derived from or reimplemented from the QRadioLink application.
• Blocks not from QRadioLink (no gr_* source in QRadioLink src/gr/): 8FSK, SOQPSK, CPM-4FSK, dPMR, NXDN, POCSAG, D-STAR, YSF, P25. Their origin is given in the Block origin table below.
• Additions in this module (not from QRadioLink): (1) DSSS enhancements (soft-decision metrics, AFC, adaptive correlation threshold, coarse-to-fine acquisition, timing recovery) on top of base DSSS spreading/despreading; (2) GDSS (Gaussian-Distributed Spread-Spectrum spreader/despreader), implemented from Shakeel et al., Sensors 2023 (see References below).

Block origin (validation / attribution):

The code has been fuzzed extensively using libFuzzer with over 104 million executions across multiple blocks, and no crashes or memory leaks were discovered. See fuzzing-results/results.md for coverage details.

Features

Modulation/Demodulation Blocks

• Digital Modulations: 2FSK, 4FSK, 8FSK, CPM-4FSK, GMSK, BPSK, QPSK, SOQPSK, DSSS, GDSS
  • 2FSK: Binary Frequency Shift Keying modulator/demodulator (see GRC Block, Examples)
  • 4FSK: 4-level Frequency Shift Keying modulator/demodulator (see GRC Block, Examples)
  • 8FSK: 8-level Frequency Shift Keying modulator/demodulator with 3 bits per symbol (see GRC Block, Examples)
  • CPM-4FSK: Continuous Phase Modulation 4FSK modulator (see GRC Block)
  • GMSK: Gaussian Minimum Shift Keying modulator/demodulator (see GRC Block, Examples)
  • BPSK: Binary Phase Shift Keying modulator/demodulator (see GRC Block, Examples)
  • QPSK: Quadrature Phase Shift Keying modulator/demodulator (see GRC Block, Examples)
  • SOQPSK: Shaped Offset Quadrature Phase Shift Keying modulator/demodulator (see GRC Block, Details)

SOQPSK (Shaped Offset Quadrature Phase Shift Keying)

SOQPSK is a bandwidth-efficient modulation scheme that provides improved spectral efficiency compared to standard QPSK. The implementation supports two operational modes:

Mode 1: VHF/UHF Single Channel

• 1 carrier at 14,400 bps
• Bandwidth: ~10 kHz
• Fits in 12.5 kHz allocation

Mode 2: VHF/UHF Multi-Carrier (fading resistant)

• 3 carriers at 4,800 bps each
• Spacing: 4 kHz apart
• Total bandwidth: ~12 kHz
• Better multipath resistance

HF Maximum Capability

Maximum bandwidth segments available:

• Most HF bands: 2,700 Hz max (standard digital mode segments)
• 10m band (above 29 MHz): 6,000 Hz max

SOQPSK efficiency: ~1.5 bps/Hz

Per-Carrier Capacity:

• Standard HF bands (2,700 Hz): 2,700 Hz × 1.5 bps/Hz = ~4,000 bps per carrier
• 10m band (6,000 Hz): 6,000 Hz × 1.5 bps/Hz = ~9,000 bps per carrier

VHF/UHF Specifications

Carrier specifications:

• Symbol rate: ~9,600 symbols/second (for 14,400 bps at 1.5 bps/Hz)
• Occupied bandwidth: ~9.6 kHz
• Fits comfortably in 12.5 kHz channel with guard bands
• Leaves ~2.9 kHz for filtering rolloff and guard bands

Python Bindings

All blocks are available through Python bindings, including:

• All modulation/demodulation blocks (2FSK, 4FSK, 8FSK, CPM-4FSK, GMSK, BPSK, QPSK, SOQPSK, DSSS, AM, SSB, NBFM, WBFM)
• All digital voice blocks (FreeDV, M17, DMR, dPMR, NXDN, MMDVM)
• FEC blocks (LDPC encoder/decoder, interleaver)
• Supporting blocks (RSSI, M17 deframer, MMDVM source/sink, clipper, stretcher, etc.)

The Python bindings enable use in GNU Radio Companion flowgraphs and Python scripts.

Directory Structure

gr-qradiolink/
├── CMakeLists.txt          # Top-level CMake configuration
├── include/                 # Public header files
│   └── gnuradio/
│       └── qradiolink/
├── lib/                    # Implementation files
├── python/                 # Python bindings
│   └── qradiolink/
│       └── bindings/
├── grc/                    # GNU Radio Companion block definitions
├── docs/                   # Documentation
│   ├── doxygen/
│   ├── CODE_MAP.md         # Code and function map (all modules)
│   ├── GRIDENT_ZMQ.md      # gr-ident ZMQ mode routing guide
│   ├── DSSS_BLOCKS.md      # DSSS spreader/despreader guide
│   ├── GDSS_BLOCKS.md      # GDSS spreader/despreader guide
│   └── PTT_CONTROL.md      # PTT control with gr-osmosdr
├── examples/               # Example flowgraphs
├── tests/                  # Unit tests
└── cmake/                  # CMake modules
    └── Modules/

Dependencies

See DEPENDENCIES.md for a complete list of required and optional dependencies.

Quick Summary:

• Clone with git clone --recursive (or run git submodule update --init --recursive after cloning)
• GNU Radio >= 3.10 (with vocoder component built with Codec2 support)
• CMake >= 3.16
• Boost libraries
• Volk (Vector-Optimized Library of Kernels)
• ZeroMQ (optional, for MMDVM blocks and gr-ident preamble SUB)
• Python 3.x with NumPy (for Python bindings)
• fmt library (for tests)

Testing

The module includes comprehensive unit tests for all blocks. Tests are run using CTest and Boost.Test framework.

Test Results

All tests pass successfully. See tests/results.md for C++ unit tests, Python test harness, and edge case results. See fuzzing-results/results.md for fuzzing and MMDVM protocol test details.

C++ Unit Tests:

100% tests passed

Test Breakdown:
- 12 Manual tests (with int main): test_mod_2fsk, test_mod_4fsk, test_mod_8fsk,
  test_mod_am, test_mod_gmsk, test_mod_bpsk, test_mod_mmdvm, test_mod_freedv,
  test_gdss_spreader_cc, test_gdss_despreader_cc, test_dsss_cdma_transmitter_cc,
  test_dsss_cdma_receiver_cc
- Boost.Test tests: mod_ssb, mod_qpsk, mod_nbfm, mod_wbfm, mod_dsss, all
  demodulators, rssi_tag_block (8 tests), interleaver_bb (13 tests with edge cases)
- gr-ident: test_grident_zmq (JSON parse and mode_id to demod mapping)

Test Coverage:
- Modulators: 2FSK, 4FSK, 8FSK, AM, GMSK, BPSK, SSB, QPSK, NBFM, WBFM, DSSS, M17, DMR, dPMR, NXDN
- Demodulators: 2FSK, 4FSK, 8FSK, AM, GMSK, BPSK, SSB, QPSK, NBFM, WBFM, DSSS, M17, DMR, dPMR, NXDN
- FEC: interleaver_bb (HF burst error handling, 13 tests including edge cases)
- Note: SOQPSK and CPM-4FSK blocks are implemented and available but unit tests are planned for future releases

MMDVM Protocol Tests (Python):

41 tests passed, 0 tests failed
- Protocol validation: 28 tests (all passed)
  - POCSAG: 10 tests (all passed)
  - D-STAR: 9 tests (all passed)
  - YSF: 4 tests (all passed)
  - P25: 5 tests (all passed)
- Block integration: 13 tests (all passed)
  - POCSAG: 4 tests (encoder/decoder creation, output, roundtrip)
  - D-STAR: 3 tests (encoder/decoder creation, output)
  - YSF: 3 tests (encoder/decoder creation, output)
  - P25: 3 tests (encoder/decoder creation, output)

See fuzzing-results/results.md for complete MMDVM protocol test results.

A DSSS BER simulation (examples/dsss_ber_simulation.py) runs spreader -> AWGN -> despreader and plots BER vs SNR for N=64, 128, 256, overlaying the theoretical curve 0.5erfc(sqrt(NEs/N0/2)); the curves match within simulation noise, confirming correct DSSS behaviour.

Running Tests

To build and run the test suite:

cd build
cmake ..
make
ctest --output-on-failure

Fuzzing Results

The module includes comprehensive fuzzing coverage using libFuzzer. See fuzzing-results/results.md for complete fuzzing campaign results including:

• Coverage statistics (757 edges, 893 features discovered)
• Execution metrics (104+ million executions)
• Performance analysis
• Security assessment (0 crashes, 0 memory leaks)

Python Validation Tests

The module includes Python-based validation tests for all modulation types. See fuzzing-results/results.md for validation test results. All digital voice modes (FreeDV, M17, DMR, dPMR, NXDN) now have Python bindings and validation support. SOQPSK blocks have Python bindings and are available for use; validation tests are planned for future releases.

Documentation

Block Documentation

• Code and Function Map: Index of source files, public APIs, gr-ident function tables, and links to mod/demod/DSSS modules.
• gr-ident ZMQ Integration: Wire format, endpoints, GRC wiring, and switching demod/mod banks from gr-ident mode_id.
• PTT Control Guide: Comprehensive guide on controlling PTT (Push-To-Talk) with gr-osmosdr and similar SDR hardware when using gr-qradiolink blocks.
• DSSS Blocks Guide: DSSS spreader and despreader blocks: PN sequence generation, timing recovery, soft-decision metrics, AFC, adaptive correlation threshold, coarse-to-fine acquisition, and integration examples.
• GDSS Blocks Guide: GDSS spreader and despreader blocks: sequence generation, timing recovery, soft-decision metrics, AFC, adaptive threshold, coarse-to-fine acquisition, and advantages over binary PN sequences.
• Examples Directory: Example flowgraphs and Python scripts demonstrating usage of various blocks.

Block Reference Links

All blocks have GRC (GNU Radio Companion) block definitions in the grc/ directory. Key blocks:

Digital Modulations:

• 2FSK Modulator / 2FSK Demodulator
• 4FSK Modulator / 4FSK Demodulator
• 8FSK Modulator / 8FSK Demodulator
• CPM-4FSK Modulator
• GMSK Modulator / GMSK Demodulator
• BPSK Modulator / BPSK Demodulator
• QPSK Modulator / QPSK Demodulator
• SOQPSK Modulator / SOQPSK Demodulator
• DSSS Spreader / DSSS Despreader
• DSSS-CDMA Transmitter / DSSS-CDMA Receiver

Analog Modulations:

• AM Modulator / AM Demodulator
• SSB Modulator / SSB Demodulator
• NBFM Modulator / NBFM Demodulator
• WBFM Modulator / WBFM Demodulator

Digital Voice:

• M17 Coder / M17 Decoder / M17 Deframer
• DMR Modulator / DMR Demodulator
• dPMR Modulator / dPMR Demodulator
• NXDN Modulator / NXDN Demodulator

MMDVM Protocols:

• POCSAG Encoder / POCSAG Decoder
• D-STAR Encoder / D-STAR Decoder
• YSF Encoder / YSF Decoder
• P25 Encoder / P25 Decoder

gr-ident (optional, libzmq):

• gr-ident Preamble SUB / gr-ident Mode Control

FEC:

• LDPC Encoder / LDPC Decoder (Soft-Decision)
  • Supports regular and irregular LDPC codes
  • Configurable code rates: 1/2, 2/3, 3/4, or custom
  • Configurable block lengths: 576, 1152, 2304 bits, or custom
  • Auto-selection of best matching code from available AList files
• Interleaver (HF Burst) - Block interleaver/deinterleaver for HF burst error handling

For complete list of all blocks, see the grc/ directory.

References

• GDSS (Gaussian-Distributed Spread-Spectrum): Shakeel, I.; Hilliard, J.; Zhang, W.; Rice, M. Gaussian-Distributed Spread-Spectrum for Covert Communications. Sensors 2023, 23(8), 4081. doi:10.3390/s23084081. The GDSS spreader/despreader blocks in this module implement the quadrant-preserving I/Q masking scheme (Section 3) from this paper: each chip uses independent Gaussian samples U, V with element-wise masking I = R(S)|U|, Q = Im(S)|V|.

License

This project is licensed under the GNU General Public License v3.0 or later (GPL-3.0-or-later).

See the LICENSE file in the QRadioLink repository for details.