How genesys-neu/ni-rf-data-recording-api works
Project Type & Purpose
• This is an open-source Python API/tool (not a web app) for automating RF data recording on NI’s USRP SDR hardware. It provides CLI scripts and a library to:
• ingest configuration files (JSON/YAML) and waveform files,
• control multiple USRP Tx/Rx devices via the UHD Python API,
• record IQ samples,
• output data in SigMF format.
File Structure & Architectural Patterns
• Top‐level directories:
• build/docker – Docker‐based build & runtime environment
• resources – static images (e.g., spectrograms)
• src/config – JSON/YAML API configuration templates + parameter‐map dictionary
• src/lib – core library modules (config parsing, waveform I/O, USRP control, SigMF writing)
• src/tests – unit tests for interfaces and plotting
• src/waveforms – pre‐generated standard waveforms by technology (LTE, NR, Radar, WiFi)
• src/*.py – entry‐point scripts (main API, Tx‐only, Rx‐only, preprocessing)
• tools – custom automation scripts
• Architectural highlights:
• MVC-style separation:
– Model: configuration files, waveform files, parameter map
– Controller: src/lib API classes and runners
– View/CLI: main_rf_data_recording_api.py, transmitter and recorder scripts
• Concurrency: one thread per Tx and Rx station
• Layering:
– CLI/Script layer
– API library layer (config interface, waveform interface, USRP executors, SigMF writer)
– Hardware driver layer (UHD Python API)
– Physical layer: USRP devices
README Insights
• Reference Architecture section clearly calls out:
• Inputs: config files, parameter‐map, waveforms
• Processing Unit: software (API code) + hardware (Linux server + USRPs)
• Outputs: SigMF data + metadata
• Key technologies & frameworks: UHD (Python binding), SigMF, JSON/YAML, threading
1) User/Operator (CLI invocation)
2) Configuration Layer
– Config files (JSON/YAML)
– Wireless Link Parameter Map (YAML)
3) Waveform Layer
– Pre-generated waveforms (TDMS, .mat, .rfws)
4) API Library
– Config Interface (rf_data_recording_config_interface.py)
– Waveform Config Reader (read_waveform_config_interface.py)
– Waveform Data Reader (read_waveform_data_interface.py)
– Config Distributor (in rf_data_recording_api_def.py)
– Executors: run_rf_replay_data_transmitter.py & run_rf_data_recorder.py
– SigMF Writer (write_rx_recorded_data_in_sigmf.py)
5) UHD Driver Layer
– UHD Python API
6) Hardware
– Linux Host
– USRP devices (Tx / Rx)
7) Outputs
– SigMF IQ Binary files
– SigMF JSON metadata
b. Relationships & Data Flow
• CLI scripts read Config Layer & Waveform Layer
• Config Interface produces a variation map (cross‐product of parameters)
• Config Distributor feeds per‐station params to Executors
• Executors spawn threads → call UHD API → control USRPs
• Waveform Data Reader provides IQ data to Tx executors
• Rx executors collect samples → SigMF Writer
• SigMF files written to disk (Output Layer)
• Optionally, Pre‐processing scripts read SigMF outputs → plots (spectrogram, time‐domain)
c. Architectural Patterns & Principles
• Layered architecture separating CLI, library, driver, hardware
• Single Responsibility: each module has a focused role
• Concurrency model: one thread per Tx/Rx, synchronizing on first‐Tx start
• Extensibility: add new waveform types by updating parameter map
• Configuration‐driven behavior: no hard‐coded RF parameters
d. Notable Technologies
• UHD Python API for USRP control
• SigMF standard for metadata + binary IQ data
• JSON/YAML for config and parameter maps
• Python threading