# gercap/gr-ofdm_tools architecture

> Architecture diagram of the GitHub repository gercap/gr-ofdm_tools, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/gercap/gr-ofdm_tools
- Repository: https://github.com/gercap/gr-ofdm_tools

## Overview

This repository is a collection of GNU Radio SDR tools, not one end-to-end application. A typical user runs a radio or sensing flow: sample streams are processed into OFDM communications or spectrum observations, which may then be visualized, logged, or used by cognitive-radio control. The graph preserves the README’s sensing, cognitive-radio, remote-processing, dynamic-access, plotting, and communications capabilities. Several core modules are indexed but not excerpted, so their internal calls are omitted; dashed edges mark documented capabilities whose wiring is not shown.

Main entry points: [`python/ofdm_cr_tools.py`](https://github.com/gercap/gr-ofdm_tools/blob/master/python/ofdm_cr_tools.py) (OFDM CR tools), [`python/cognitive_engine_mac.py`](https://github.com/gercap/gr-ofdm_tools/blob/master/python/cognitive_engine_mac.py) (Cognitive MAC), [`python/spectrum_sensor.py`](https://github.com/gercap/gr-ofdm_tools/blob/master/python/spectrum_sensor.py) (Spectrum sensor), [`python/flanck_detector.py`](https://github.com/gercap/gr-ofdm_tools/blob/master/python/flanck_detector.py) (Flanck detector)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_radio["Radio and OFDM"]
  node_radio_hier["OFDM radio<br/>[ofdm_radio_hier.py]"]
  node_sync_radio["Sync radio<br/>[sync_radio_hier.py]"]
  node_txrx_hier["OFDM TX/RX<br/>[ofdm_tx_rx_hier.py]"]
  node_txrx_modules["TX/RX modules"]
  node_cr_tools["OFDM CR tools<br/>[ofdm_cr_tools.py]"]
  node_chat["Chat blocks<br/>[chat_blocks.py]"]
  node_payload_source["Payload source<br/>[payload_source.py]"]
  node_payload_sink["Payload sink<br/>[payload_sink.py]"]
end

subgraph group_sense["Spectrum sensing"]
  node_sensor["Spectrum sensor<br/>[spectrum_sensor.py]"]
  node_sensor_v1["Sensor v1"]
  node_sensor_v2["Sensor v2"]
  node_flanck["Flanck detector<br/>[flanck_detector.py]"]
  node_coherence["Coherence detector"]
  node_scanner["Multichannel scanner"]
  node_sweeper["Spectrum sweeper"]
end

subgraph group_control["Cognitive control"]
  node_cognitive["Cognitive MAC"]
end

subgraph group_remote["Remote processing"]
  node_local_worker["Local FFT worker<br/>[local_worker.py]"]
  node_remote_client["ASCII remote client<br/>[remote_client.py]"]
  node_remote_qt["Qt remote client"]
  node_webserver["WebSocket server"]
  node_gateway["Local hardware gateway"]
  node_monitor["Remote monitor<br/>[remote_monitor.py]"]
end

subgraph group_tools["Visualization and tools"]
  node_ascii_plot["ASCII plotting<br/>[ascii_plot.py]"]
  node_logger["Spectrum logger<br/>[spectrum_logger.py]"]
  node_psd_logger["PSD logger<br/>[psd_logger.py]"]
  node_ascii_gnuplot["Gnuplot output<br/>[ascii_gnuplot.py]"]
end

node_user(("SDR user"))

node_user -.->|"runs radio"| node_radio_hier
node_user -.->|"runs sensing"| node_sensor
node_user -.->|"uses cognitive radio"| node_cognitive
node_user -.->|"uses remote processing"| node_local_worker
node_user -.->|"views plots"| node_ascii_plot
node_cognitive -->|"receives sensing data"| node_sensor
node_cognitive -->|"publishes radio PDUs"| node_radio_hier
node_cognitive -->|"publishes sync PDUs"| node_sync_radio
node_sensor -->|"uses analysis tools"| node_cr_tools
node_sensor_v1 -->|"uses analysis tools"| node_cr_tools
node_sensor_v2 -->|"uses analysis tools"| node_cr_tools
node_flanck -->|"uses analysis tools"| node_cr_tools
node_coherence -->|"uses analysis tools"| node_cr_tools
node_scanner -->|"uses analysis tools"| node_cr_tools
node_remote_client -->|"renders FFT data"| node_ascii_plot
node_user -.->|"uses OFDM links"| node_txrx_hier
node_user -.->|"uses communications"| node_chat
node_user -.->|"uses spectrum sensing"| node_scanner
node_user -.->|"uses spectrum sensing"| node_flanck
node_user -.->|"uses spectrum sensing"| node_coherence
node_user -.->|"uses spectrum sensing"| node_sweeper
node_user -.->|"uses remote processing"| node_remote_qt
node_user -.->|"uses remote processing"| node_webserver
node_user -.->|"uses remote processing"| node_gateway
node_user -.->|"uses remote processing"| node_monitor
node_user -.->|"logs observations"| node_logger
node_user -.->|"logs observations"| node_psd_logger
node_user -.->|"plots data"| node_ascii_gnuplot

click node_radio_hier "https://github.com/gercap/gr-ofdm_tools/blob/master/python/ofdm_radio_hier.py"
click node_sync_radio "https://github.com/gercap/gr-ofdm_tools/blob/master/python/sync_radio_hier.py"
click node_txrx_hier "https://github.com/gercap/gr-ofdm_tools/blob/master/python/ofdm_tx_rx_hier.py"
click node_txrx_modules "https://github.com/gercap/gr-ofdm_tools/blob/master/python/ofdm_txrx_modules.py"
click node_cr_tools "https://github.com/gercap/gr-ofdm_tools/blob/master/python/ofdm_cr_tools.py"
click node_chat "https://github.com/gercap/gr-ofdm_tools/blob/master/python/chat_blocks.py"
click node_payload_source "https://github.com/gercap/gr-ofdm_tools/blob/master/python/payload_source.py"
click node_payload_sink "https://github.com/gercap/gr-ofdm_tools/blob/master/python/payload_sink.py"
click node_sensor "https://github.com/gercap/gr-ofdm_tools/blob/master/python/spectrum_sensor.py"
click node_sensor_v1 "https://github.com/gercap/gr-ofdm_tools/blob/master/python/spectrum_sensor_v1.py"
click node_sensor_v2 "https://github.com/gercap/gr-ofdm_tools/blob/master/python/spectrum_sensor_v2.py"
click node_flanck "https://github.com/gercap/gr-ofdm_tools/blob/master/python/flanck_detector.py"
click node_coherence "https://github.com/gercap/gr-ofdm_tools/blob/master/python/coherence_detector.py"
click node_scanner "https://github.com/gercap/gr-ofdm_tools/blob/master/python/multichannel_scanner.py"
click node_sweeper "https://github.com/gercap/gr-ofdm_tools/blob/master/python/spectrum_sweeper.py"
click node_cognitive "https://github.com/gercap/gr-ofdm_tools/blob/master/python/cognitive_engine_mac.py"
click node_ascii_plot "https://github.com/gercap/gr-ofdm_tools/blob/master/python/ascii_plot.py"
click node_local_worker "https://github.com/gercap/gr-ofdm_tools/blob/master/python/local_worker.py"
click node_remote_client "https://github.com/gercap/gr-ofdm_tools/blob/master/python/remote_client.py"
click node_remote_qt "https://github.com/gercap/gr-ofdm_tools/blob/master/python/remote_client_qt.py"
click node_webserver "https://github.com/gercap/gr-ofdm_tools/blob/master/sdr_webserver/sdr_webserver_ws.py"
click node_gateway "https://github.com/gercap/gr-ofdm_tools/blob/master/sdr_webserver/local_hw_gateway.py"
click node_monitor "https://github.com/gercap/gr-ofdm_tools/blob/master/sdr_webserver/remote_monitor.py"
click node_logger "https://github.com/gercap/gr-ofdm_tools/blob/master/python/spectrum_logger.py"
click node_psd_logger "https://github.com/gercap/gr-ofdm_tools/blob/master/python/psd_logger.py"
click node_ascii_gnuplot "https://github.com/gercap/gr-ofdm_tools/blob/master/python/ascii_gnuplot.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_radio_hier,node_sync_radio,node_txrx_hier,node_txrx_modules,node_cr_tools,node_chat,node_payload_source,node_payload_sink,node_user toneBlue
class node_sensor,node_sensor_v1,node_sensor_v2,node_flanck,node_coherence,node_scanner,node_sweeper toneAmber
class node_cognitive toneMint
class node_local_worker,node_remote_client,node_remote_qt,node_webserver,node_gateway,node_monitor toneRose
class node_ascii_plot,node_logger,node_psd_logger,node_ascii_gnuplot toneIndigo
```

## Components

### Radio and OFDM

- [OFDM radio](https://github.com/gercap/gr-ofdm_tools/blob/master/python/ofdm_radio_hier.py): `python/ofdm_radio_hier.py`
- [Sync radio](https://github.com/gercap/gr-ofdm_tools/blob/master/python/sync_radio_hier.py): `python/sync_radio_hier.py`
- [OFDM TX/RX](https://github.com/gercap/gr-ofdm_tools/blob/master/python/ofdm_tx_rx_hier.py): `python/ofdm_tx_rx_hier.py`
- [TX/RX modules](https://github.com/gercap/gr-ofdm_tools/blob/master/python/ofdm_txrx_modules.py): `python/ofdm_txrx_modules.py`
- [OFDM CR tools](https://github.com/gercap/gr-ofdm_tools/blob/master/python/ofdm_cr_tools.py): `python/ofdm_cr_tools.py`
- [Chat blocks](https://github.com/gercap/gr-ofdm_tools/blob/master/python/chat_blocks.py): `python/chat_blocks.py`
- [Payload source](https://github.com/gercap/gr-ofdm_tools/blob/master/python/payload_source.py): `python/payload_source.py`
- [Payload sink](https://github.com/gercap/gr-ofdm_tools/blob/master/python/payload_sink.py): `python/payload_sink.py`

### Spectrum sensing

- [Spectrum sensor](https://github.com/gercap/gr-ofdm_tools/blob/master/python/spectrum_sensor.py): `python/spectrum_sensor.py`
- [Sensor v1](https://github.com/gercap/gr-ofdm_tools/blob/master/python/spectrum_sensor_v1.py): `python/spectrum_sensor_v1.py`
- [Sensor v2](https://github.com/gercap/gr-ofdm_tools/blob/master/python/spectrum_sensor_v2.py): `python/spectrum_sensor_v2.py`
- [Flanck detector](https://github.com/gercap/gr-ofdm_tools/blob/master/python/flanck_detector.py): `python/flanck_detector.py`
- [Coherence detector](https://github.com/gercap/gr-ofdm_tools/blob/master/python/coherence_detector.py): `python/coherence_detector.py`
- [Multichannel scanner](https://github.com/gercap/gr-ofdm_tools/blob/master/python/multichannel_scanner.py): `python/multichannel_scanner.py`
- [Spectrum sweeper](https://github.com/gercap/gr-ofdm_tools/blob/master/python/spectrum_sweeper.py): `python/spectrum_sweeper.py`

### Cognitive control

- [Cognitive MAC](https://github.com/gercap/gr-ofdm_tools/blob/master/python/cognitive_engine_mac.py): `python/cognitive_engine_mac.py`

### Remote processing

- [Local FFT worker](https://github.com/gercap/gr-ofdm_tools/blob/master/python/local_worker.py): `python/local_worker.py`
- [ASCII remote client](https://github.com/gercap/gr-ofdm_tools/blob/master/python/remote_client.py): `python/remote_client.py`
- [Qt remote client](https://github.com/gercap/gr-ofdm_tools/blob/master/python/remote_client_qt.py): `python/remote_client_qt.py`
- [WebSocket server](https://github.com/gercap/gr-ofdm_tools/blob/master/sdr_webserver/sdr_webserver_ws.py): `sdr_webserver/sdr_webserver_ws.py`
- [Local hardware gateway](https://github.com/gercap/gr-ofdm_tools/blob/master/sdr_webserver/local_hw_gateway.py): `sdr_webserver/local_hw_gateway.py`
- [Remote monitor](https://github.com/gercap/gr-ofdm_tools/blob/master/sdr_webserver/remote_monitor.py): `sdr_webserver/remote_monitor.py`

### Visualization and tools

- [ASCII plotting](https://github.com/gercap/gr-ofdm_tools/blob/master/python/ascii_plot.py): `python/ascii_plot.py`
- [Spectrum logger](https://github.com/gercap/gr-ofdm_tools/blob/master/python/spectrum_logger.py): `python/spectrum_logger.py`
- [PSD logger](https://github.com/gercap/gr-ofdm_tools/blob/master/python/psd_logger.py): `python/psd_logger.py`
- [Gnuplot output](https://github.com/gercap/gr-ofdm_tools/blob/master/python/ascii_gnuplot.py): `python/ascii_gnuplot.py`

### Other components

- **SDR user**

## Connections

- SDR user → OFDM radio: runs radio
- SDR user → Spectrum sensor: runs sensing
- SDR user → Cognitive MAC: uses cognitive radio
- SDR user → Local FFT worker: uses remote processing
- SDR user → ASCII plotting: views plots
- Cognitive MAC → Spectrum sensor: receives sensing data (evidence: `python/cognitive_engine_mac.py`)
- Cognitive MAC → OFDM radio: publishes radio PDUs (evidence: `python/cognitive_engine_mac.py`)
- Cognitive MAC → Sync radio: publishes sync PDUs (evidence: `python/cognitive_engine_mac.py`)
- Spectrum sensor → OFDM CR tools: uses analysis tools (evidence: `python/spectrum_sensor.py`)
- Sensor v1 → OFDM CR tools: uses analysis tools (evidence: `python/spectrum_sensor_v1.py`)
- Sensor v2 → OFDM CR tools: uses analysis tools (evidence: `python/spectrum_sensor_v2.py`)
- Flanck detector → OFDM CR tools: uses analysis tools (evidence: `python/flanck_detector.py`)
- Coherence detector → OFDM CR tools: uses analysis tools (evidence: `python/coherence_detector.py`)
- Multichannel scanner → OFDM CR tools: uses analysis tools (evidence: `python/multichannel_scanner.py`)
- ASCII remote client → ASCII plotting: renders FFT data (evidence: `python/remote_client.py`)
- SDR user → OFDM TX/RX: uses OFDM links
- SDR user → Chat blocks: uses communications
- SDR user → Multichannel scanner: uses spectrum sensing
- SDR user → Flanck detector: uses spectrum sensing
- SDR user → Coherence detector: uses spectrum sensing
- SDR user → Spectrum sweeper: uses spectrum sensing
- SDR user → Qt remote client: uses remote processing
- SDR user → WebSocket server: uses remote processing
- SDR user → Local hardware gateway: uses remote processing
- SDR user → Remote monitor: uses remote processing
- SDR user → Spectrum logger: logs observations
- SDR user → PSD logger: logs observations
- SDR user → Gnuplot output: plots data
