# genesys-neu/ni-rf-data-recording-api architecture

> Architecture diagram of the GitHub repository genesys-neu/ni-rf-data-recording-api, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/genesys-neu/ni-rf-data-recording-api
- Repository: https://github.com/genesys-neu/ni-rf-data-recording-api

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Input Layer
    subgraph "Input Layer"
        direction TB
        User["User/Operator"]:::external
        ConfigFiles["Configuration Templates\n(JSON/YAML)"]:::config
        ParamMap["Wireless Link Parameter Map"]:::config
        Waveforms["Pre-generated Waveforms\n(LTE, NR, Radar, WiFi)"]:::config
    end

    %% API Library Layer
    subgraph "API Library Layer"
        direction TB
        ConfigInterface["Config Interface\n(variation map generator)"]:::lib
        WaveformConfigReader["Waveform Config Reader"]:::lib
        WaveformDataReader["Waveform Data Reader"]:::lib
        ConfigDistributor["Config Distributor\n(runner orchestration)"]:::lib
        TxExecutor["Tx Executor\n(replay/transmitter)"]:::lib
        RxExecutor["Rx Executor\n(data recorder)"]:::lib
        SigMFWriter["SigMF Writer\n(write IQ & metadata)"]:::lib
    end

    %% Driver & Hardware Layer
    subgraph "Driver & Hardware Layer"
        direction TB
        UHD["UHD Python API"]:::driver
        LinuxHost["Linux Host"]:::hardware
        USRPTx["USRP Device (Tx)"]:::hardware
        USRPRx["USRP Device (Rx)"]:::hardware
    end

    %% Output & Tools Layer
    subgraph "Outputs & Tools"
        direction TB
        SigMFData["SigMF IQ Binary Files"]:::output
        SigMFMeta["SigMF JSON Metadata"]:::output
        subgraph "Optional Post-Processing"
            direction TB
            PlotTime["Time-Domain & Metadata Plots"]:::optional
            PlotSpec["Spectrogram Generation"]:::optional
        end
        subgraph "Tests & Deployment"
            direction TB
            UnitTests["Unit Tests"]:::optional
            DockerEnv["Docker Build & Runtime"]:::optional
            Docs["Documentation & Diagrams"]:::optional
            Resources["Static Resources\n(spectrogram examples)"]:::optional
        end
    end

    %% Data Flows
    User -->|"invokes CLI"| ConfigFiles
    User --> ConfigInterface
    ConfigFiles -->|reads| ConfigInterface
    ParamMap -->|reads| ConfigInterface
    Waveforms -->|reads| WaveformConfigReader
    WaveformConfigReader -->|provides config| WaveformDataReader
    ConfigInterface -->|generates variation map| ConfigDistributor
    ConfigDistributor -->|spawns threads| TxExecutor
    ConfigDistributor -->|spawns threads| RxExecutor
    WaveformDataReader -->|feeds IQ data| TxExecutor
    TxExecutor -->|calls UHD API| UHD
    RxExecutor -->|calls UHD API| UHD
    UHD --> LinuxHost
    LinuxHost --> USRPTx
    LinuxHost --> USRPRx
    RxExecutor -->|passes samples| SigMFWriter
    SigMFWriter -->|writes| SigMFData
    SigMFWriter -->|writes| SigMFMeta
    SigMFMeta --> PlotTime
    SigMFData --> PlotTime
    SigMFData --> PlotSpec

    %% Click Events
    click ConfigFiles "https://github.com/genesys-neu/ni-rf-data-recording-api/tree/main/src/config/"
    click ParamMap "https://github.com/genesys-neu/ni-rf-data-recording-api/blob/main/src/config/wireless_link_parameter_map.yaml"
    click ConfigInterface "https://github.com/genesys-neu/ni-rf-data-recording-api/blob/main/src/lib/rf_data_recording_config_interface.py"
    click WaveformConfigReader "https://github.com/genesys-neu/ni-rf-data-recording-api/blob/main/src/lib/read_waveform_config_interface.py"
    click WaveformDataReader "https://github.com/genesys-neu/ni-rf-data-recording-api/blob/main/src/lib/read_waveform_data_interface.py"
    click ConfigDistributor "https://github.com/genesys-neu/ni-rf-data-recording-api/blob/main/src/lib/rf_data_recording_api_def.py"
    click TxExecutor "https://github.com/genesys-neu/ni-rf-data-recording-api/blob/main/src/lib/run_rf_replay_data_transmitter.py"
    click RxExecutor "https://github.com/genesys-neu/ni-rf-data-recording-api/blob/main/src/lib/run_rf_data_recorder.py"
    click SigMFWriter "https://github.com/genesys-neu/ni-rf-data-recording-api/blob/main/src/lib/write_rx_recorded_data_in_sigmf.py"
    click UHD "https://github.com/genesys-neu/ni-rf-data-recording-api/blob/main/src/rf_replay_data_transmitter_usrp_uhd.py"
    click UHD "https://github.com/genesys-neu/ni-rf-data-recording-api/blob/main/src/rf_data_recorder_usrp_uhd.py"
    click User "https://github.com/genesys-neu/ni-rf-data-recording-api/blob/main/src/main_rf_data_recording_api.py"
    click PlotTime "https://github.com/genesys-neu/ni-rf-data-recording-api/blob/main/src/rf_data_pre_processing_plot.py"
    click PlotSpec "https://github.com/genesys-neu/ni-rf-data-recording-api/blob/main/src/rf_data_pre_processing_spectrogram.py"
    click UnitTests "https://github.com/genesys-neu/ni-rf-data-recording-api/tree/main/src/tests/"
    click DockerEnv "https://github.com/genesys-neu/ni-rf-data-recording-api/tree/main/build/docker/"
    click Docs "https://github.com/genesys-neu/ni-rf-data-recording-api/tree/main/docs/"
    click Resources "https://github.com/genesys-neu/ni-rf-data-recording-api/tree/main/resources/"

    %% Styles
    classDef config fill:#bbdefb,stroke:#2196f3,color:#0d47a1
    classDef lib fill:#c8e6c9,stroke:#4caf50,color:#1b5e20
    classDef driver fill:#ffe0b2,stroke:#ff9800,color:#e65100
    classDef hardware fill:#ffe0b2,stroke:#ff9800,color:#e65100
    classDef output fill:#eeeeee,stroke:#9e9e9e,color:#424242
    classDef optional fill:#f5f5f5,stroke:#bdbdbd,color:#616161
    classDef external fill:#e3f2fd,stroke:#64b5f6,color:#0d47a1
```
