gr-qradiolink

중요 공지: 이 코드는 AI가 생성했습니다.

이 코드는 전문 코더가 검토하지 않았으며, 큰 작업입니다. 코드베이스에 테스트가 제공되어 있으니, 해당 테스트와 코드를 검토하시기 바랍니다.

GNU Radio out-of-tree (OOT) 모듈 (QRadioLink 블록용).

main 브랜치: GNU Radio 3.10 OOT (CMake find_package(gnuradio)). 실험적인 GNU Radio 4 포트는 gnuradio4 브랜치에 있습니다 (해당 브랜치의 README_gr4.md 참조).

코드 탐색: docs/CODE_MAP.md (파일, 함수, 블록 인덱스). gr-ident ZMQ 모드 라우팅: docs/GRIDENT_ZMQ.md (:5560 포트의 gr-ident 프리앰블).

Modulation validation

변조기 블록에 대한 참조 IQ는 radio-modulation-validator (2026-05-31)로 확인했습니다. 요약: SOFT FAIL — 6/19 블록 통과, 13 소프트 실패, 0 하드 실패, 3 건너뜀.

테스트된 모든 모드는 올바른 변조 계열(FSK, PSK, AM, FM)로 식별되었습니다. 차수 수준의 소프트 실패(예: FSK가 4FSK나 GMSK 대신 CPFSK로 예측된 경우)는 검증기의 차수 분류기의 한계를 반영할 뿐, 이 변조기들이 잘못된 파형 계열을 생성한다는 증거는 아닙니다.

스캔은 내장된 참조 IQ를 사용합니다(OOT 블록이 아님). 결과는 main의 이 README에 나열된 모드에 적용되며 **gnuradio4**에도 반영됩니다.

전체 블록별 결과: VALIDATION_REPORT.md

Publication

이 프로젝트는 다음 프리프린트에 문서화되어 있습니다:

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

아카이브 기록 타임스탬프: 2026년 3월 21일.

Overview

이 모듈은 아마추어 무선 및 디지털 음성 통신에 특화된 다양한 디지털 및 아날로그 변조 방식을 위한 GNU Radio 블록을 제공합니다.

이 모듈은 GNU Radio, ADALM-Pluto, LimeSDR, USRP 및 기타 SDR 하드웨어를 위한 멀티모드 SDR 송수신기인 QRadioLink 애플리케이션에서 변환되었습니다. 원본 소스 코드는 https://codeberg.org/qradiolink/qradiolink에 있습니다.

검증: QRadioLink에 대응하는 블록이 있는 변환된 블록은 원본 QRadioLink 소스(next 브랜치, codeberg.org/qradiolink/qradiolink)에 대해 검증되어 흐름 그래프, 필터 매개변수, 스케일링 상수 및 블록 동작이 일치합니다. SSB 및 AM 변조기/복조기 체인(CESSB 구조 및 클리퍼/스트레처 상수 포함)은 원본과 차이가 있었던 부분을 원본에 맞게 복원했습니다. 이 모듈의 일부 블록은 QRadioLink의 src/gr/에 해당 소스가 없으며, 해당 블록의 출처는 아래 표에 명시되어 있습니다.

크레딧 및 출처:

**QRadioLink (Codeberg)**는 다음 모드의 출처입니다(검증: codeberg.org/qradiolink/qradiolink next 브랜치, src/gr/): 변조/복조 (2FSK, 4FSK, GMSK, BPSK, QPSK, AM, SSB, NBFM, WBFM), 디지털 음성 (FreeDV, M17, DMR), 지원 블록 (RSSI, M17 프레이머 해제, MMDVM 소스/싱크, 클리퍼, 스트레처, zero_idle_bursts, gr_4fsk_discriminator, demod_mmdvm_multi, demod_mmdvm_multi2, mod_mmdvm_multi2). 이 블록들의 DSP 및 모드 동작은 QRadioLink 애플리케이션에서 파생되었거나 재구현되었습니다.
QRadioLink에서 가져오지 않은 블록(QRadioLink src/gr/에 gr_* 소스가 없음): 8FSK, SOQPSK, CPM-4FSK, dPMR, NXDN, POCSAG, D-STAR, YSF, P25. 해당 블록의 출처는 아래 블록 출처 표에 명시되어 있습니다.
이 모듈에서 추가된 기능(QRadioLink에서 가져오지 않음): (1) DSSS 향상(소프트 결정 메트릭, AFC, 적응형 상관 임계값, 대략적-정밀 획득, 타이밍 복원)이 기본 DSSS 확산/역확산 위에 추가됨; (2) GDSS(가우시안 분포 확산 스펙트럼 확산기/역확산기), Shakeel 등, Sensors 2023에서 구현함(아래 참고 문헌 참조).

블록 출처 (검증 / 귀속):

코드는 libFuzzer를 사용하여 여러 블록에 걸쳐 1억 400만 회 이상의 실행으로 광범위하게 퍼징되었으며, 충돌이나 메모리 누수가 발견되지 않았습니다. 적용 범위 세부 정보는 fuzzing-results/results.md를 참조하세요.

Features

Modulation/Demodulation Blocks

디지털 변조: 2FSK, 4FSK, 8FSK, CPM-4FSK, GMSK, BPSK, QPSK, SOQPSK, DSSS, GDSS
- 2FSK: 이진 주파수 편이 변조기/복조기 (GRC 블록, 예제 참조)
- 4FSK: 4레벨 주파수 편이 변조기/복조기 (GRC 블록, 예제 참조)
- 8FSK: 심볼당 3비트의 8레벨 주파수 편이 변조기/복조기 (GRC 블록, 예제 참조)
- CPM-4FSK: 연속 위상 변조 4FSK 변조기 (GRC 블록 참조)
- GMSK: 가우시안 최소 편이 변조기/복조기 (GRC 블록, 예제 참조)
- BPSK: 이진 위상 편이 변조기/복조기 (GRC 블록, 예제 참조)
- QPSK: 직교 위상 편이 변조기/복조기 (GRC 블록, 예제 참조)
- SOQPSK: 성형 오프셋 직교 위상 편이 변조기/복조기 (GRC 블록, 세부사항)
- DSSS: 향상된 확산기/역확산기 블록, PN 시퀀스 생성(m-시퀀스, Gold 코드), 타이밍 복원, 잠금 감지, 소프트 결정 메트릭, AFC 지원, 적응형 상관 임계값, 대략적-정밀 획득 기능이 포함된 직접 시퀀스 확산 스펙트럼 (DSSS 블록 가이드, 참조)

SOQPSK (Shaped Offset Quadrature Phase Shift Keying)

SOQPSK는 표준 QPSK에 비해 향상된 스펙트럼 효율을 제공하는 대역폭 효율적인 변조 방식입니다. 구현은 두 가지 작동 모드를 지원합니다:

모드 1: VHF/UHF 단일 채널

14,400 bps의 1개 캐리어
대역폭: ~10 kHz
12.5 kHz 할당 내에 적합

모드 2: VHF/UHF 다중 캐리어 (페이딩 내성)

각각 4,800 bps의 3개 캐리어
간격: 4 kHz 이격
총 대역폭: ~12 kHz
더 나은 다중 경로 저항

HF 최대 성능

사용 가능한 최대 대역폭 세그먼트:

대부분의 HF 대역: 최대 2,700 Hz (표준 디지털 모드 세그먼트)
10m 대역 (29 MHz 초과): 최대 6,000 Hz

SOQPSK 효율: ~1.5 bps/Hz

캐리어당 용량:

표준 HF 대역 (2,700 Hz): 2,700 Hz × 1.5 bps/Hz = 캐리어당 ~4,000 bps
10m 대역 (6,000 Hz): 6,000 Hz × 1.5 bps/Hz = 캐리어당 ~9,000 bps

VHF/UHF 사양

캐리어 사양:

심볼 레이트: ~9,600 심볼/초 (1.5 bps/Hz에서 14,400 bps 기준)
점유 대역폭: ~9.6 kHz
보호 대역이 있는 12.5 kHz 채널에 적합
필터 롤오프 및 보호 대역에 약 2.9 kHz 남음

Python Bindings

모든 블록은 다음을 포함한 Python 바인딩을 통해 사용할 수 있습니다:

모든 변조/복조 블록 (2FSK, 4FSK, 8FSK, CPM-4FSK, GMSK, BPSK, QPSK, SOQPSK, DSSS, AM, SSB, NBFM, WBFM)
모든 디지털 음성 블록 (FreeDV, M17, DMR, dPMR, NXDN, MMDVM)
FEC 블록 (LDPC 인코더/디코더, 인터리버)
지원 블록 (RSSI, M17 디프레이머, MMDVM 소스/싱크, 클리퍼, 스트레처 등)

Python 바인딩을 통해 GNU Radio Companion 흐름 그래프 및 Python 스크립트에서 사용할 수 있습니다.

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

필수 및 선택적 의존성의 전체 목록은 [DEPENDENCIES.md](https://github.com/supermagnum/gr-qradiolink/blob/main/DEPENDENCIES.md)를 참조하십시오.

**빠른 요약:**
- `git clone --recursive`로 복제하거나(또는 복제 후 `git submodule update --init --recursive` 실행)
- GNU Radio >= 3.10 (Codec2 지원으로 vocoder 구성 요소 빌드)
- CMake >= 3.16
- Boost 라이브러리
- Volk (벡터 최적화 커널 라이브러리)
- ZeroMQ (선택 사항, MMDVM 블록 및 gr-ident 프리앰블 SUB용)
- NumPy가 포함된 Python 3.x (Python 바인딩용)
- fmt 라이브러리 (테스트용)

## Testing

모듈은 모든 블록에 대한 포괄적인 단위 테스트를 포함합니다. 테스트는 CTest 및 Boost.Test 프레임워크를 사용하여 실행됩니다.

### Test Results

모든 테스트가 성공적으로 통과되었습니다. C++ 단위 테스트, Python 테스트 하네스 및 엣지 케이스 결과는 [tests/results.md](https://github.com/supermagnum/gr-qradiolink/blob/main/tests/results.md)를 참조하십시오. 퍼징 및 MMDVM 프로토콜 테스트 세부 사항은 [fuzzing-results/results.md](https://github.com/supermagnum/gr-qradiolink/blob/main/fuzzing-results/results.md)를 참조하십시오.

**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 프로토콜 테스트 (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](https://github.com/supermagnum/gr-qradiolink/blob/main/fuzzing-results/results.md)에서 전체 MMDVM 프로토콜 테스트 결과를 확인하세요.

**DSSS BER 시뮬레이션** ([examples/dsss_ber_simulation.py](https://github.com/supermagnum/gr-qradiolink/blob/main/examples/dsss_ber_simulation.py))은 스프레더 -> AWGN -> 디스프레더를 실행하고 N=64, 128, 256에 대해 BER 대 SNR을 플롯하며, 이론 곡선 0.5*erfc(sqrt(N*Es/N0/2))를 겹쳐 표시합니다. 곡선은 시뮬레이션 노이즈 범위 내에서 일치하므로 DSSS 동작이 올바름을 확인합니다.

### 테스트 실행

테스트 스위트를 빌드하고 실행하려면:```bash
cd build
cmake ..
make
ctest --output-on-failure

퍼징 결과

이 모듈은 libFuzzer를 사용한 포괄적인 퍼징 커버리지를 포함합니다. 전체 퍼징 캠페인 결과는 fuzzing-results/results.md를 참조하십시오. 포함 사항:

커버리지 통계 (757개 엣지, 893개 특성 발견)
실행 메트릭 (1억 4천만 회 이상 실행)
성능 분석
보안 평가 (충돌 0건, 메모리 누수 0건)

Python 검증 테스트

이 모듈은 모든 변조 유형에 대한 Python 기반 검증 테스트를 포함합니다. 검증 테스트 결과는 fuzzing-results/results.md를 참조하십시오. 모든 디지털 음성 모드(FreeDV, M17, DMR, dPMR, NXDN)는 이제 Python 바인딩과 검증 지원을 갖추고 있습니다. SOQPSK 블록은 Python 바인딩이 있으며 사용 가능합니다. 검증 테스트는 향후 릴리스에서 계획되어 있습니다.

문서

블록 문서

코드 및 함수 맵: 소스 파일, 공개 API, gr-ident 함수 테이블 및 모드/복조/DSSS 모듈 링크의 인덱스.
gr-ident ZMQ 통합: 와이어 형식, 엔드포인트, GRC 배선 및 gr-ident mode_id에서 복조/모드 뱅크 전환.
PTT 제어 가이드: gr-qradiolink 블록 사용 시 gr-osmosdr 및 유사 SDR 하드웨어로 PTT(Push-To-Talk)를 제어하는 종합 가이드.
DSSS 블록 가이드: DSSS 확산기 및 역확산기 블록: PN 시퀀스 생성, 타이밍 복원, 소프트 결정 메트릭, AFC, 적응 상관 임계값, 조대-정밀 획득 및 통합 예제.
GDSS 블록 가이드: GDSS 확산기 및 역확산기 블록: 시퀀스 생성, 타이밍 복원, 소프트 결정 메트릭, AFC, 적응 임계값, 조대-정밀 획득 및 이진 PN 시퀀스 대비 장점.
예제 디렉터리: 다양한 블록 사용법을 보여주는 예제 흐름 그래프 및 Python 스크립트.

블록 참조 링크

모든 블록은 grc/ 디렉터리에 GRC(GNU Radio Companion) 블록 정의가 있습니다. 주요 블록:

디지털 변조:

아날로그 변조:

디지털 음성:

MMDVM 프로토콜:

gr-ident (선택 사항, libzmq):

gr-ident Preamble SUB / gr-ident Mode Control

FEC:

LDPC Encoder / LDPC Decoder (Soft-Decision)
- 일반 및 불규칙 LDPC 코드 지원
- 구성 가능한 코드율: 1/2, 2/3, 3/4 또는 사용자 정의
- 구성 가능한 블록 길이: 576, 1152, 2304 비트 또는 사용자 정의
- 사용 가능한 AList 파일에서 최적 일치 코드 자동 선택
Interleaver (HF Burst) - HF 버스트 오류 처리를 위한 블록 인터리버/디인터리버

전체 블록 목록은 grc/ 디렉터리를 참조하십시오.

참고 문헌

GDSS (가우스 분포 확산 스펙트럼): Shakeel, I.; Hilliard, J.; Zhang, W.; Rice, M. Gaussian-Distributed Spread-Spectrum for Covert Communications. Sensors 2023, 23(8), 4081. doi:10.3390/s23084081. 이 모듈의 GDSS 확산기/역확산기 블록은 이 논문의 사분면 보존 I/Q 마스킹 방식(섹션 3)을 구현합니다: 각 칩은 독립적인 가우스 샘플 U, V를 사용하며 요소별 마스킹 I = R(S)|U|, Q = Im(S)|V|를 수행합니다.

라이선스

이 프로젝트는 GNU General Public License v3.0 이상 (GPL-3.0-or-later)에 따라 라이선스가 부여됩니다.

자세한 내용은 QRadioLink 저장소의 LICENSE 파일을 참조하십시오.

2FSK, 4FSK, GMSK, BPSK, QPSK, AM, SSB, NBFM, WBFM, FreeDV, M17, DMR	QRadioLink	QRadioLink `src/gr/`에 대해 검증됨 (gr_demod_, gr_mod_).
MMDVM source/sink, demod_mmdvm_multi, demod_mmdvm_multi2, mod_mmdvm_multi2, RSSI, clipper, stretcher, zero_idle_bursts, gr_4fsk_discriminator	QRadioLink	QRadioLink `src/gr/`에 대해 검증됨.
8FSK	이 모듈을 위해 구현됨	QRadioLink에 gr_demod_8fsk/gr_mod_8fsk 없음. 4FSK 스타일 설계의 확장.
SOQPSK	이 모듈을 위해 구현됨	QRadioLink에 gr_demod_soqpsk/gr_mod_soqpsk 없음. SOQPSK 문헌/사양에서 가져옴.
CPM-4FSK	이 모듈을 위해 구현됨	QRadioLink에 gr_mod_cpm_4fsk 없음.
dPMR	이 모듈을 위해 구현됨	QRadioLink에 gr_* 없음. ETSI TS 102 658에서 가져옴 (테스트 벡터 및 코드 주석).
NXDN	이 모듈을 위해 구현됨	QRadioLink에 gr_* 없음. NXDN 포럼 사양에서 가져옴; 심볼 매핑은 MMDVM 규칙을 참조.
POCSAG	이 모듈을 위해 구현됨	QRadioLink에 gr_* 없음. POCSAG/ITU-R M.584-2에서 가져옴; 프로토콜은 MMDVMHost와 호환.
D-STAR	이 모듈을 위해 구현됨	QRadioLink에 gr_* 없음. D-STAR/JARL 사양(Golay FEC)에서 가져옴; MMDVMHost와 호환.
YSF	이 모듈을 위해 구현됨	QRadioLink에 gr_* 없음. YSF 프로토콜 문서에서 가져옴; MMDVMHost와 호환.
P25	이 모듈을 위해 구현됨	QRadioLink에 gr_* 없음. P25 Phase 1 TIA-102에서 가져옴; MMDVMHost와 호환.
DSSS (base)	QRadioLink	QRadioLink gr_demod_dsss/gr_mod_dsss에 대해 검증됨.
DSSS (enhancements), GDSS	이 모듈	DSSS: QRadioLink 기본 위에 향상 기능 추가. GDSS: Shakeel 등, Sensors 2023에서 가져옴.
gr-ident ZMQ routing	이 모듈	gr-ident 프리앰블 PUB와의 상호운용; QRadioLink에서 가져오지 않음.

gr-qradiolink

인기

gr-qradiolink

Modulation validation

Publication

Overview

Features

Modulation/Demodulation Blocks

SOQPSK (Shaped Offset Quadrature Phase Shift Keying)

HF 최대 성능

VHF/UHF 사양

Python Bindings

Directory Structure```

퍼징 결과

Python 검증 테스트

문서

블록 문서

블록 참조 링크

참고 문헌

라이선스