Crate rustradio

Crate rustradio 

Source
Expand description

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

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

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, GraphRunner};
use rustradio::blocks::{AddConst, VectorSource, DebugSink};
use rustradio::Complex;
let (src, prev) = VectorSource::new(
    vec![
        Complex::new(10.0, 0.0),
        Complex::new(-20.0, 0.0),
        Complex::new(100.0, -100.0),
    ],
);
let (add, prev) = AddConst::new(prev, Complex::new(1.1, 2.0));
let sink = DebugSink::new(prev);
let mut g = Graph::new();
g.add(Box::new(src));
g.add(Box::new(add));
g.add(Box::new(sink));
g.run()?;

§Features

  • simd (only with nightly Rust): Enable some code using std::simd.
  • rtlsdr: Enable RtlSdrSource block, and adds the rtlsdr crate as a dependency at build time, and thus librtlsdr.so as a dependency at runtime.
  • soapysdr: Add dependency on soapysdr, for its various SDR support.
  • fast-math: Add a dependency in order to speed up some math.
  • audio: Add support for AudioSink.
  • fftw: GPL code only: Add support to use libfftw instead of rustfft.
  • async: Add support for AsyncGraph.
  • tokio-unstable: For async graphs, allow use of tokio unstable API,

tokio-unstable allows tasks to be named, which helps when running tokio-console. But it does require the user to run cargo build with the env RUSTFLAGS="--cfg tokio_unstable" set too.

Re-exports§

pub use rustradio_macros;

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.
canary
Canary runs a lambda when it exits.
circular_buffer
Test implementation of circular buffers. Full of unsafe. Full of ugly code.
cma
WIP. Completely untested.
complex_to_mag2
Convert Complex numbers to square of their magnitude.
constant_source
Generate the same value, forever.
convert
Blocks for making simple synchronous conversions/mappings.
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
fft_filter
FFT filter. Like a FIR filter, but more efficient when there are many taps.
fft_stream
FFT stream.
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.
hasher
Hash input until EOF, outputting the results.
hdlc_deframer
HDLC Deframer.
hdlc_framer
HDLC Framer.
hilbert
Hilbert transform.
iir_filter
Infinite impulse response filter.
il2p_deframer
IL2P Deframer
kiss
morse_encode
Generate a morse code signal.
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_to_stream
PDU to stream.
pdu_writer
PDU Writer
quadrature_demod
Quadrature demod, the core of an FM demodulator.
rational_resampler
Resample by a fractional amount.
reader_source
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.
strobe
Message strobe.
symbol_sync
Clock recovery implementations
tcp_source
TCP source.
tee
Tee a stream.
to_text
Turn samples into text.
vco
Voltage Controlled Oscillator.
vec_to_stream
Vector to stream block.
vector_sink
Sink values into a vector.
vector_source
Generate values from a fixed vector.
window
Window functions
wpcr
Whole packet clock recovery block.
writer_sink
xor
Xor two streams.
xor_const
Xor a constant value with every sample.
zero_crossing
Very simple clock recovery.

Macros§

blockchain
error_from

Structs§

Feature
Repeat
Repeat between zero and infinite times.

Enums§

Error
RustRadio error.

Traits§

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

Functions§

check_environment
environment_str
parse_frequency
Parse frequencies like “100k”, “2M”, etc.
parse_verbosity
Parse verbosity like “error”, “warn”, …

Type Aliases§

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