Crate rustradio

This create provides a framework for running SDR (software defined radio) applications.

It’s heavily inspired by GNURadio, except of course written in Rust.

It currently has very few blocks, and is missing tags, and PDU messages.

In addition to the example applications in this crate, there’s also a sparslog project using this framework, that decodes IKEA Sparsnäs electricity meter RF signals.

Architecture overview

A RustRadio application consists of blocks that are connected by unidirectional streams. Each block has zero or more input streams, and zero or more output streams.

The signal flows through the blocks from “sources” (blocks without any input streams) to “sinks” (blocks without any output streams.

These blocks and streams are called a “graph”, like the mathematical concept of graphs that have nodes and edges.

A block does something to its input(s), and passes the result to its output(s).

A typical graph will be something like:

  [ Raw radio source ]
           ↓
      [ Filtering ]
           ↓
      [ Resampling ]
           ↓
     [ Demodulation ]
           ↓
     [ Symbol Sync ]
           ↓
[ Packet assembly and save ]

Or concretely, for sparslog:

     [ RtlSdrSource ]
           ↓
  [ RtlSdrDecode to convert from ]
  [ own format to complex I/Q    ]
           ↓
     [ FftFilter ]
           ↓
      [ RationalResampler ]
           ↓
      [ QuadratureDemod ]
           ↓
  [ AddConst for frequency offset ]
           ↓
   [ ZeroCrossing symbol sync ]
           ↓
     [ Custom Sparsnäs decoder ]
     [ block in the binary,    ]
     [ not in the framework    ]

Examples

Here’s a simple example that creates a couple of blocks, connects them with streams, and runs the graph.

use rustradio::graph::Graph;
use rustradio::blocks::{AddConst, VectorSource, DebugSink};
use rustradio::Complex;
let src = Box::new(VectorSource::new(
    vec![
        Complex::new(10.0, 0.0),
        Complex::new(-20.0, 0.0),
        Complex::new(100.0, -100.0),
    ],
));
let add = Box::new(AddConst::new(src.out(), Complex::new(1.1, 2.0)));
let sink = Box::new(DebugSink::new(add.out()));
let mut g = Graph::new();
g.add(src);
g.add(add);
g.add(sink);
g.run()?;

Links

• Main repo: https://github.com/ThomasHabets/rustradio
• crates.io: https://crates.io/crates/rustradio
• This documentation: https://docs.rs/rustradio/latest/rustradio/

Modules

• add
  Add two streams.
• add_const
  Add a constant value to every sample.
• au
  Blocks for the Au file format.
• binary_slicer
  Turn positive Float values into binary 1u8, and negative into 0u8.
• block
  RustRadio Block implementation
• blocks
  Convenient mod collecting all standard library blocks for import.
• burst_tagger
  Burst tagger.
• circular_buffer
  Test implementation of circular buffers. Full of unsafe. Full of ugly code.
• complex_to_mag2
  Convert Complex numbers to square of their magnitude.
• constant_source
  Generate the same value, forever.
• convert
  Blocks for converting from one type to another.
• correlate_access_code
  Correlate Access Code blocks.
• debug_sink
  Print values to stdout, for debugging.
• delay
  Delay stream. Good for syncing up streams.
• descrambler
  LFSR based Descrambler.
• fft_filter
  FFT filter. Like a FIR filter, but more efficient when there are many taps.
• file_sink
  Send stream to raw file.
• file_source
  Read stream from raw file.
• fir
  Finite impulse response filter.
• graph
  Graphs contain blocks connected by streams, and run them.
• hdlc_deframer
  HDLC Deframer.
• hilbert
  Hilbert transform.
• iir_filter
  Infinite impulse response filter
• il2p_deframer
  IL2P Deframer
• mtgraph
  Multithreaded version of Graph, otherwise the same as graph.rs.
• multiply_const
  Multiply stream by a constant value.
• nrzi
  NRZI — Non return to zero
• null_sink
  Discard anything written to this block.
• pdu_writer
  PDU Writer
• quadrature_demod
  Quadrature demod, the core of an FM demodulator.
• rational_resampler
  Resample by a fractional amount.
• rtlsdr_decode
  Decode RTL-SDR’s byte based format into Complex I/Q.
• sigmf
  SigMF implementation.
• signal_source
  Generate a pure signal.
• single_pole_iir_filter
  Infinite Impulse Response (IIR) filter.
• skip
  Skip samples, then stream at full speed.
• stream
  Streams connecting blocks.
• stream_to_pdu
  Stream to PDU.
• symbol_sync
  Clock recovery implementations
• tcp_source
  TCP source.
• tee
  Tee a stream
• to_text
  Turn samples into text.
• vec_to_stream
  Vector to stream block.
• vector_source
  Generate values from a fixed vector.
• window
  Window functions
• wpcr
  Whole packet clock recovery block.
• xor
  Xor two streams.
• xor_const
  Xor a constant value with every sample.
• zero_crossing
  Very simple clock recovery.

Macros

• map_block_convert_macro
  Macro to make it easier to write converting blocks.
• map_block_convert_tag_macro
  Version of map_block_convert_macro that supports adding tags.
• map_block_macro_v2
  Macro to make it easier to write one-for-one blocks.

Structs

• Error
  RustRadio error.

Traits

• Len
  Trivial trait for types that have .len().
• Sample
  A trait all sample types must implement.

Type Aliases

• Complex
  Complex (I/Q) data.
• Float
  Float type used. Usually f32, but not guaranteed.