GNU Radio Integration

GNU Radio's stream tags are a critical mechanism for passing metadata alongside IQ sample streams. Tags are key-value pairs synchronized to specific sample indices. For ML integration, they enable:

• Burst boundary marking: Tagging the start/end of detected signals for the classifier
• Confidence score annotation: Attaching classification results as tags to the output stream
• Frequency/bandwidth context: Passing center frequency or sample rate changes to downstream blocks
• Time alignment: Using rx_time tags from hardware sources to timestamp classifications

Proper tag propagation ensures the classifier's output remains temporally aligned with the original signal data.

To meet real-time latency budgets, integration must avoid unnecessary memory copies between GNU Radio blocks and the inference engine. Zero-copy techniques pass pointers to IQ buffers directly:

• pmt::blob objects: Pass large IQ buffers as opaque binary large objects without copying
• Volk alignment: Ensure buffers are aligned to SIMD boundaries for both DSP and inference
• Circular buffer sharing: Use a shared ring buffer between the GNU Radio scheduler and the ML runtime
• GPU direct access: When using TensorRT, map GNU Radio's host memory directly to CUDA device memory

This architecture is essential for maintaining deterministic latency in wideband spectrum monitoring applications.

A well-designed GNU Radio Companion (GRC) block exposes ML model parameters as user-configurable fields. This enables rapid experimentation without recompilation:

• Model path selector: A file chooser widget to swap .tflite or .onnx model files
• Confidence threshold: A slider to set minimum softmax confidence for valid classifications
• Input normalization: Toggle for enabling Z-score normalization on IQ samples before inference
• Batch size control: Configure how many inference requests are queued before execution
• Debug ports: Optional output ports that emit raw softmax vectors for visualization in QT GUI sinks

This design pattern bridges the gap between ML engineers and RF system integrators.

For deep learning models where inference latency exceeds the sample period, a synchronous work() function will drop samples. The solution is an asynchronous architecture using GNU Radio's message passing system:

• Input: A sync block captures IQ bursts and sends them as PDU (Protocol Data Unit) messages to an inference thread
• Inference thread: A dedicated thread pool runs the ML model without blocking the GNU Radio scheduler
• Output: Classification results are posted back as messages and merged with the original stream using tags
• Backpressure: The message queue depth is bounded to prevent memory exhaustion during high signal density

This decouples the sample rate from the inference rate, critical for complex models on embedded hardware.

Validating an integrated ML classifier requires testing against real-world signal impairments. The gr-uhd interface to USRP hardware enables hardware-in-the-loop (HIL) testing:

• Replay buffers: Capture IQ data to disk, then replay through the classifier with varying SNR levels
• Channel simulation: Insert GNU Radio channel models (fading, frequency offset, phase noise) before the classifier block
• Latency measurement: Use rx_time tags and a custom probe block to measure end-to-end classification latency
• A/B comparison: Route the same signal to both the ML classifier and a traditional cumulant-based classifier for performance comparison

This methodology ensures the integrated system meets specifications before field deployment.

The core execution method where signal processing occurs. In a classification block, the general_work() or work() function consumes IQ samples from an input buffer, executes a forward pass through a neural network, and produces classification metadata on the output.

• Must respect noutput_items and ninput_items constraints
• Returns the number of items consumed and produced
• Critical for maintaining deterministic latency in real-time flows

GNU Radio's mechanisms for attaching metadata to sample streams or sending asynchronous control messages. Classification results are often propagated as tags aligned to specific sample indices or as PDU messages to downstream blocks.

• Stream tags: key-value pairs synchronized with sample position
• Message passing: asynchronous PMT dictionaries for burst-level results
• Used to annotate IQ streams with modulation type, confidence score, and SNR estimates

The Polymorphic Type system used for all inter-block messaging and tag values in GNU Radio. Classification metadata—modulation labels, softmax vectors, timestamps—must be serialized into PMT format for transport.

• pmt::mp("modulation") for symbolic keys
• pmt::from_double() for confidence scores
• pmt::make_dict() for structured classification results
• Essential for integrating with gRPC streaming sinks

ZeroMQ-based source and sink blocks that enable distributed signal processing architectures. IQ samples or classification results can be streamed across a network to decouple the RF frontend from the inference compute node.

• ZMQ PUB/SUB for one-to-many streaming of classification events
• ZMQ PUSH/PULL for pipelined processing stages
• Enables pipeline parallelism across multiple machines
• Low-latency alternative to TCP sockets for real-time SDR applications