Desperado

https://docs.rs/desperado
Admin
A unified Rust library for reading I/Q samples from files, SDR devices, and streams with support for...
Tokens:82,296
Snippets:1,265
Trust Score:9.1
Update:4 months ago
Show doc for...
Tokens:
Raw
### NCO::new Example

Source: https://docs.rs/desperado/latest/src/desperado/dsp/nco.rs.html

Example of creating a new NCO instance.

```rust
use desperado::dsp::nco::Nco;

// Create NCO at 57 kHz with 171 kHz sample rate
let nco = Nco::new(57000.0, 171000.0);

```

--------------------------------

### DeviceConfig from string examples

Source: https://docs.rs/desperado/latest/src/desperado/lib.rs.html

Examples of parsing DeviceConfig from string URIs for PlutoSDR.

```rust
let config = DeviceConfig::from_str("pluto://ip:192.168.2.1?freq=1090M&rate=2.4M&gain=40").unwrap();

// PlutoSDR via USB (use triple slash for USB URIs with version numbers)
let config = DeviceConfig::from_str("pluto:///usb:1.18.5?freq=1090M&rate=2.4M&gain=40").unwrap();
```

--------------------------------

### Nco::set_pll_bandwidth Example

Source: https://docs.rs/desperado/latest/src/desperado/dsp/nco.rs.html

Example of setting the PLL bandwidth for an NCO.

```rust
use desperado::dsp::nco::Nco;

let mut nco = Nco::new(57000.0, 171000.0);

// Very narrow bandwidth for RDS (0.03 Hz as used by redsea)
nco.set_pll_bandwidth(0.03, 171000.0);

```

--------------------------------

### Example Usage

Source: https://docs.rs/desperado/latest/desperado/fn.expanduser.html

Example of how to use the expanduser function to expand a tilde path.

```rust
use std::path::PathBuf;
use desperado::expanduser;

let path = PathBuf::from("~/Documents/data.iq");
let expanded = expanduser(path);
// On Unix: /home/username/Documents/data.iq
```

--------------------------------

### Chunk Size Examples

Source: https://docs.rs/desperado/latest/index.html

Examples demonstrating how to select an appropriate chunk size for different use cases when initializing an IqSource.

```rust
// Real-time ADS-B decoding (low latency needed)
let source = IqSource::from_file(path, freq, rate, 4096, format)?;

// General SDR processing (balanced)
let source = IqSource::from_file(path, freq, rate, 16384, format)?;

// Batch file processing (maximum throughput)
let source = IqSource::from_file(path, freq, rate, 65536, format?);
```

--------------------------------

### Nco::new Example

Source: https://docs.rs/desperado/latest/desperado/dsp/nco/struct.Nco.html

Example of creating a new NCO.

```Rust
use desperado::dsp::nco::Nco;

// Create NCO at 57 kHz with 171 kHz sample rate
let nco = Nco::new(57000.0, 171000.0);
```

--------------------------------

### RTL-SDR Configuration Examples

Source: https://docs.rs/desperado/latest/src/desperado/lib.rs.html

Examples of how to parse device configuration strings for RTL-SDR devices, demonstrating the use of SI suffixes for frequency and sample rate, as well as raw Hz values and automatic gain settings.

```rust
# #[cfg(feature = "rtlsdr")]
# {
use desperado::DeviceConfig;
use std::str::FromStr;

// RTL-SDR with SI suffixes (most convenient)
let config = DeviceConfig::from_str("rtlsdr://0?freq=1090M&rate=2.4M&gain=auto").unwrap();

// RTL-SDR with raw Hz values
let config = DeviceConfig::from_str("rtlsdr://0?freq=1090000000&rate=2400000&gain=auto").unwrap();

// RTL-SDR first available device (implicit device 0)
let config = DeviceConfig::from_str("rtlsdr://?freq=1090M&rate=2.4M&gain=49.6").unwrap();
# }
```

--------------------------------

### Example: Creating a stdin-based I/Q source

Source: https://docs.rs/desperado/latest/desperado/enum.IqSource.html

Shows how to create an I/Q source from standard input.

```rust
use desperado::{IqSource, IqFormat};

// Read from piped input: cat samples.iq | my_program
let source = IqSource::from_stdin(
    100_000_000,  // 100 MHz
    2_048_000,    // 2.048 MS/s
    16384,        // 16K samples per chunk
    IqFormat::Cu8
)?;
```

--------------------------------

### Example: Creating a file-based I/Q source

Source: https://docs.rs/desperado/latest/desperado/enum.IqSource.html

Demonstrates how to create and iterate over a file-based I/Q source.

```rust
use desperado::{IqSource, IqFormat};

let source = IqSource::from_file(
    "samples.iq",
    100_000_000,  // 100 MHz center frequency
    2_048_000,    // 2.048 MS/s sample rate
    16384,        // 16K samples per chunk
    IqFormat::Cu8
)?;

for chunk in source {
    let samples = chunk?;
    println!("Read {} samples", samples.len());
}
```

--------------------------------

### Chunk Size Examples

Source: https://docs.rs/desperado

Examples demonstrating how to select the chunk size for different use cases: real-time decoding, general processing, and batch processing.

```rust
// Real-time ADS-B decoding (low latency needed)
let source = IqSource::from_file(path, freq, rate, 4096, format)?;

// General SDR processing (balanced)
let source = IqSource::from_file(path, freq, rate, 16384, format)?;

// Batch file processing (maximum throughput)
let source = IqSource::from_file(path, freq, rate, 65536, format)?;
```

--------------------------------

### StreamBuffer::len() Example

Source: https://docs.rs/desperado/latest/src/desperado/dsp/buffer.rs.html

Illustrates how to get the current number of samples in the buffer.

```rust
use desperado::dsp::buffer::StreamBuffer;

let mut buffer = StreamBuffer::new();
buffer.push_slice(&[1, 2, 3]);
assert_eq!(buffer.len(), 3);

```

--------------------------------

### PllFilter Example

Source: https://docs.rs/desperado/latest/desperado/dsp/pll_filter/index.html

Example of creating and using the PllFilter.

```Rust
use desperado::dsp::pll_filter::PllFilter;

// Create PLL filter with bandwidth 0.03 Hz at 171 kHz sample rate
let mut pll = PllFilter::from_bandwidth(0.03, 171000.0);

// Process phase error
let phase_error = 0.1; // radians
let (freq_adj, phase_adj) = pll.update(phase_error);

println!("Frequency adjustment: {}", freq_adj);
println!("Phase adjustment: {}", phase_adj);
```

--------------------------------

### RTL-SDR Configuration Examples

Source: https://docs.rs/desperado/latest/desperado/enum.DeviceConfig.html

Examples demonstrating how to parse RTL-SDR configurations using DeviceConfig::from_str, including SI suffixes and raw Hz values.

```rust
use desperado::DeviceConfig;
use std::str::FromStr;

// RTL-SDR with SI suffixes (most convenient)
let config = DeviceConfig::from_str("rtlsdr://0?freq=1090M&rate=2.4M&gain=auto").unwrap();

// RTL-SDR with raw Hz values
let config = DeviceConfig::from_str("rtlsdr://0?freq=1090000000&rate=2400000&gain=auto").unwrap();

// RTL-SDR first available device (implicit device 0)
let config = DeviceConfig::from_str("rtlsdr://?freq=1090M&rate=2.4M&gain=49.6").unwrap();
```

--------------------------------

### Basic example (synchronous version)

Source: https://docs.rs/desperado

A basic synchronous example demonstrating how to read I/Q samples from a file.

```rust
use desperado::{IqFormat, IqSource};

fn main() -> desperado::Result<()> {
    // Create an IQ source from a binary file
    let path = "sample.iq";
    let sample_rate = 96_000;
    let center_freq = 162_000_000;
    let chunk_size = 8136;
    let iq_format = IqFormat::Cu8;

    for samples in IqSource::from_file(path, center_freq, sample_rate, chunk_size, iq_format)? {
        for s in samples? {  // samples is a Result<Vec<Complex<f32>>, _>
            println!("  I: {}, Q: {}", s.re, s.im);
        }
    }
    Ok(())
}
```

--------------------------------

### Nco::set_pll_bandwidth Example

Source: https://docs.rs/desperado/latest/desperado/dsp/nco/struct.Nco.html

Example of setting the PLL loop bandwidth.

```Rust
use desperado::dsp::nco::Nco;

let mut nco = Nco::new(57000.0, 171000.0);

// Very narrow bandwidth for RDS (0.03 Hz as used by redsea)
nco.set_pll_bandwidth(0.03, 171000.0);
```

--------------------------------

### Agc::execute_batch Example

Source: https://docs.rs/desperado/latest/src/desperado/dsp/agc.rs.html

Example of how to use Agc::execute_batch to process a batch of complex samples.

```rust
let mut agc = Agc::new(0.01);
let input = vec![(0.5, 0.3), (-0.2, 0.1)];
let output = agc.execute_batch(&input);

```

--------------------------------

### PlutoSDR Configuration Example

Source: https://docs.rs/desperado/latest/src/desperado/lib.rs.html

An example of parsing a device configuration string for a PlutoSDR device, specifying the IP address, frequency, sample rate, and gain.

```rust
# #[cfg(feature = "pluto")]
# {
use desperado::DeviceConfig;
use std::str::FromStr;

// PlutoSDR with IP address
let config = DeviceConfig::from_str("pluto://192.168.2.1?freq=1090M&rate=2.4M&gain=40").unwrap();

// PlutoSDR with explicit ip: prefix

```

--------------------------------

### Agc::execute_real Example

Source: https://docs.rs/desperado/latest/src/desperado/dsp/agc.rs.html

Example of how to use Agc::execute_real to process a real sample.

```rust
let mut agc = Agc::new(0.01);
let out = agc.execute_real(0.5);

```

--------------------------------

### StreamBuffer::with_capacity() Example

Source: https://docs.rs/desperado/latest/src/desperado/dsp/buffer.rs.html

Demonstrates creating a StreamBuffer with a specified initial capacity.

```rust
use desperado::dsp::buffer::StreamBuffer;

let buffer: StreamBuffer<f32> = StreamBuffer::with_capacity(1024);
assert_eq!(buffer.capacity(), 1024);

```

--------------------------------

### Butterworth Band-pass Filter Example

Source: https://docs.rs/desperado/latest/src/desperado/dsp/filters.rs.html

Example of creating and using a band-pass Butterworth filter.

```rust
// Bandpass filter between 900 Hz and 1100 Hz
let mut bp_filter = ButterworthFilter::bandpass(900.0, 1100.0, 48_000.0, 4);
```

--------------------------------

### Search Tricks

Source: https://docs.rs/desperado/latest/help.html

Examples of search tricks in rustdoc.

```text
fn:
mod:
struct:
enum:
trait:
type:
macro:
constant:
```

```text
vec -> usize
-> vec
String, enum:Cow -> bool
```

```text
"string"
```

```text
-> [u8]
[] -> Option
```

```text
vec::Vec
```

--------------------------------

### Gain Usage Examples

Source: https://docs.rs/desperado/latest/desperado/enum.Gain.html

Examples demonstrating how to instantiate the Gain enum for automatic and manual gain control.

```rust
use desperado::Gain;

// Automatic gain control
let auto_gain = Gain::Auto;

// Manual gain of 49.6 dB
let manual_gain = Gain::Manual(49.6);
```

--------------------------------

### Gain Parsing Examples

Source: https://docs.rs/desperado/latest/desperado/enum.Gain.html

Examples showing how to parse gain settings from strings into the Gain enum, supporting 'auto', numerical values, and element-specific settings.

```rust
use desperado::Gain;

let auto = Gain::parse("auto").unwrap();
let manual = Gain::parse("48.6").unwrap();
let elements = Gain::parse("IF=8,LNA=8,MIX=0").unwrap();
```

--------------------------------

### PlutoSDR Configuration Examples

Source: https://docs.rs/desperado/latest/desperado/enum.DeviceConfig.html

Examples showing how to parse PlutoSDR configurations with DeviceConfig::from_str, covering IP addresses, explicit prefixes, and USB connections.

```rust
use desperado::DeviceConfig;
use std::str::FromStr;

// PlutoSDR with IP address
let config = DeviceConfig::from_str("pluto://192.168.2.1?freq=1090M&rate=2.4M&gain=40").unwrap();

// PlutoSDR with explicit ip: prefix
let config = DeviceConfig::from_str("pluto://ip:192.168.2.1?freq=1090M&rate=2.4M&gain=40").unwrap();

// PlutoSDR via USB (use triple slash for USB URIs with version numbers)
let config = DeviceConfig::from_str("pluto:///usb:1.18.5?freq=1090M&rate=2.4M&gain=40").unwrap();
```

--------------------------------

### StreamBuffer Example

Source: https://docs.rs/desperado/latest/src/desperado/dsp/buffer.rs.html

Demonstrates the basic usage pattern of StreamBuffer: accumulate, process, and consume samples.

```rust
use desperado::dsp::buffer::StreamBuffer;

let mut buffer = StreamBuffer::new();

// Push samples
buffer.push_slice(&[1, 2, 3, 4, 5]);
assert_eq!(buffer.len(), 5);

// Process (e.g., need groups of 3)
let available = buffer.len();
if available >= 3 {
    // Process first 3 samples
    let _processed = &buffer[0..3];
    // Remove processed samples
    buffer.consume(3);
    assert_eq!(buffer.len(), 2);
}

```

--------------------------------

### Decimator Example

Source: https://docs.rs/desperado/latest/src/desperado/dsp/decimator.rs.html

Example of using the Decimator to reduce the sample rate by a factor of 8.

```rust
use desperado::dsp::decimator::Decimator;
use desperado::dsp::DspBlock;
use num_complex::Complex;

// Decimate by a factor of 8
let mut decimator = Decimator::new(8);

let input: Vec<Complex<f32>> = (0..1024)
    .map(|i| Complex::new(i as f32, 0.0))
    .collect();

let output = decimator.process(&input);
// Output length is approximately input.len() / factor
assert!(output.len() >= 120 && output.len() <= 130);
```

--------------------------------

### Example Usage

Source: https://docs.rs/desperado/latest/desperado/dsp/symsync/index.html

Create synchronizer for RDS: 3 samples/symbol, 32 filter phases

```rust
use desperado::dsp::symsync::SymSync;

// Create synchronizer for RDS: 3 samples/symbol, 32 filter phases
let mut symsync = SymSync::new_rnyquist(
    3,      // samples per symbol
    32,     // number of filter phases
    3,      // filter semi-length (symbols)
    0.8,    // rolloff factor (beta)
    0.01,   // loop bandwidth
);

// Process samples
let input_samples = vec![(0.5, 0.3), (0.6, 0.2), (0.7, 0.4)];
let mut output = Vec::new();
for sample in input_samples {
    if let Some((i, q)) = symsync.push(sample.0, sample.1) {
        output.push((i, q));
    }
}

```

--------------------------------

### StreamBuffer::push_slice() Example

Source: https://docs.rs/desperado/latest/src/desperado/dsp/buffer.rs.html

Demonstrates adding multiple samples to the buffer from a slice.

```rust
use desperado::dsp::buffer::StreamBuffer;

let mut buffer = StreamBuffer::new();
buffer.push_slice(&[1, 2, 3]);
buffer.push_slice(&[4, 5]);
assert_eq!(buffer.len(), 5);

```

--------------------------------

### Agc::execute Example

Source: https://docs.rs/desperado/latest/src/desperado/dsp/agc.rs.html

Example of how to create and use the Agc::execute function to process a complex sample.

```rust
use desperado::dsp::agc::Agc;

let mut agc = Agc::new(0.01);
let (out_i, out_q) = agc.execute(0.5, 0.3);

```

--------------------------------

### Examples of parse_si_value usage

Source: https://docs.rs/desperado/latest/desperado/fn.parse_si_value.html

Examples demonstrating how to use parse_si_value with different numeric types and SI suffixes.

```rust
use desperado::parse_si_value;

assert_eq!(parse_si_value::<u32>("1090M").unwrap(), 1090000000);
assert_eq!(parse_si_value::<u32>("2400k").unwrap(), 2400000);
assert_eq!(parse_si_value::<u32>("1090000000").unwrap(), 1090000000);
assert_eq!(parse_si_value::<f64>("2.4M").unwrap(), 2400000.0);
assert_eq!(parse_si_value::<i64>("1090M").unwrap(), 1090000000);

```

--------------------------------

### AGC Example

Source: https://docs.rs/desperado/latest/src/desperado/dsp/agc.rs.html

Demonstrates how to create and use the Agc struct to process samples.

```rust
use desperado::dsp::agc::Agc;

// Create AGC with 0.01 bandwidth
let mut agc = Agc::new(0.01);

// Process samples
let mut samples = vec![(1.0, 0.5), (0.8, 0.6), (1.2, 0.4)];
for sample in samples.iter_mut() {
    let (out_i, out_q) = agc.execute(sample.0, sample.1);
    *sample = (out_i, out_q);
}
```

--------------------------------

### Rotate::new example

Source: https://docs.rs/desperado/latest/desperado/dsp/rotate/struct.Rotate.html

Example of creating a new Rotate DSP block with the specified rotation angle.

```rust
use desperado::dsp::rotate::Rotate;
use std::f32::consts::PI;

// Shift by 200 kHz at 2 MHz sample rate
let sample_rate = 2_000_000.0;
let freq_offset = 200_000.0;
let angle = -2.0 * PI * freq_offset / sample_rate;
let rotator = Rotate::new(angle);
```

--------------------------------

### Rotate Usage Example

Source: https://docs.rs/desperado/latest/src/desperado/dsp/rotate.rs.html

Demonstrates how to create and use the Rotate DSP block for frequency shifting.

```Rust
use num_complex::Complex;
use desperado::dsp::rotate::Rotate;
use desperado::dsp::DspBlock;

// Rotate by 0.1 radians per sample (frequency shift)
let mut rotator = Rotate::new(0.1);
let input = vec![Complex::new(1.0, 0.0); 100];
let output = rotator.process(&input);
assert_eq!(output.len(), 100);
```

--------------------------------

### StreamBuffer::new() Example

Source: https://docs.rs/desperado/latest/src/desperado/dsp/buffer.rs.html

Shows how to create a new, empty StreamBuffer.

```rust
use desperado::dsp::buffer::StreamBuffer;
use num_complex::Complex;

let buffer: StreamBuffer<Complex<f32>> = StreamBuffer::new();
assert_eq!(buffer.len(), 0);

```

--------------------------------

### Example usage of LowPassFir

Source: https://docs.rs/desperado/latest/desperado/dsp/filters/index.html

Demonstrates how to create and use a LowPassFir filter.

```Rust
use desperado::dsp::filters::LowPassFir;

// Create a low-pass filter with 15kHz cutoff at 240kHz sample rate
let filter = LowPassFir::new(15_000.0, 240_000.0, 256);

// Filter audio samples
let input = vec![0.5; 100];
let output = filter.process(&input);
assert_eq!(output.len(), 100);
```

--------------------------------

### StreamBuffer Example

Source: https://docs.rs/desperado/latest/desperado/dsp/buffer/index.html

Demonstrates the lifecycle of accumulating, processing, and consuming samples from a StreamBuffer.

```Rust
use desperado::dsp::buffer::StreamBuffer;

let mut buffer = StreamBuffer::new();

// Push samples
buffer.push_slice(&[1, 2, 3, 4, 5]);
assert_eq!(buffer.len(), 5);

// Process (e.g., need groups of 3)
let available = buffer.len();
if available >= 3 {
    // Process first 3 samples
    let _processed = &buffer[0..3];
    // Remove processed samples
    buffer.consume(3);
    assert_eq!(buffer.len(), 2);
}
```

--------------------------------

### Getting the current number of samples

Source: https://docs.rs/desperado/latest/desperado/dsp/buffer/struct.StreamBuffer.html

Example demonstrating how to get the current number of samples in the buffer after pushing some data.

```rust
use desperado::dsp::buffer::StreamBuffer;

let mut buffer = StreamBuffer::new();
buffer.push_slice(&[1, 2, 3]);
assert_eq!(buffer.len(), 3);
```

--------------------------------

### LowPassFir::coefficients Example

Source: https://docs.rs/desperado/latest/desperado/dsp/filters/struct.LowPassFir.html

Shows how to access the filter coefficients (impulse response) of a LowPassFir filter.

```rust
use desperado::dsp::filters::LowPassFir;

let filter = LowPassFir::new(15_000.0, 240_000.0, 64);
let coeffs = filter.coefficients();
assert_eq!(coeffs.len(), 64);
```

--------------------------------

### Accessing buffer as a slice

Source: https://docs.rs/desperado/latest/desperado/dsp/buffer/struct.StreamBuffer.html

Example of getting a slice reference to the internal buffer's data.

```rust
use desperado::dsp::buffer::StreamBuffer;

let mut buffer = StreamBuffer::new();
buffer.push_slice(&[1, 2, 3]);
assert_eq!(buffer.as_slice(), &[1, 2, 3]);
```

--------------------------------

### Example: Creating a stdin-based asynchronous I/Q source

Source: https://docs.rs/desperado/latest/desperado/enum.IqAsyncSource.html

Shows how to create a stdin-based asynchronous I/Q source using `IqAsyncSource::from_stdin`.

```Rust
use desperado::{IqAsyncSource, IqFormat};

let source = IqAsyncSource::from_stdin(
    100_000_000,  // 100 MHz
    2_048_000,    // 2.048 MS/s
    16384,
    IqFormat::Cu8
);
```

--------------------------------

### Example usage of StatefulLowPassFir

Source: https://docs.rs/desperado/latest/desperado/dsp/filters/struct.StatefulLowPassFir.html

Demonstrates creating and using a StatefulLowPassFir filter, showing continuity between blocks.

```rust
use desperado::dsp::filters::StatefulLowPassFir;

let mut filter = StatefulLowPassFir::new(15_000.0, 240_000.0, 257);
let block1 = vec![1.0_f32; 1024];
let block2 = vec![1.0_f32; 1024];
let out1 = filter.process(&block1);
let out2 = filter.process(&block2); // no edge artifact between blocks
```

--------------------------------

### Example: Creating a file-based asynchronous I/Q source

Source: https://docs.rs/desperado/latest/desperado/enum.IqAsyncSource.html

Demonstrates how to create and read from a file-based asynchronous I/Q source using `IqAsyncSource::from_file` and `StreamExt::next`.

```Rust
use desperado::{IqAsyncSource, IqFormat};
use futures::StreamExt;

let mut source = IqAsyncSource::from_file(
    "samples.iq",
    100_000_000,  // 100 MHz
    2_048_000,    // 2.048 MS/s
    16384,        // 16K samples per chunk
    IqFormat::Cu8
).await?;

while let Some(chunk) = source.next().await {
    let samples = chunk?;
    println!("Read {} samples", samples.len());
}
```

--------------------------------

### Creating an IqSource from standard input

Source: https://docs.rs/desperado/latest/src/desperado/lib.rs.html

This example shows how to create an IqSource that reads I/Q data from standard input, useful for piping data from other programs.

```rust
use desperado::{IqSource, IqFormat};

// Read from piped input: cat samples.iq | my_program
let source = IqSource::from_stdin(
    100_000_000,  // 100 MHz
    2_048_000,    // 2.048 MS/s
    16384,        // 16K samples per chunk
    IqFormat::Cu8
)?;
# Ok::<(), desperado::Error>(())
```

--------------------------------

### Creating an IqSource from a file

Source: https://docs.rs/desperado/latest/src/desperado/lib.rs.html

This example demonstrates how to create an IqSource from a file, specifying parameters like center frequency, sample rate, chunk size, and IQ format.

```rust
use desperado::{IqSource, IqFormat};

let source = IqSource::from_file(
    "samples.iq",
    100_000_000,  // 100 MHz center frequency
    2_048_000,    // 2.048 MS/s sample rate
    16384,        // 16K samples per chunk
    IqFormat::Cu8
)?;

for chunk in source {
    let samples = chunk?;
    println!("Read {} samples", samples.len());
}
# Ok::<(), desperado::Error>(())
```

--------------------------------

### Example Usage

Source: https://docs.rs/desperado/latest/desperado/dsp/iir/fn.filtfilt_lowpass.html

Example of how to use the filtfilt_lowpass function.

```rust
use desperado::dsp::iir::filtfilt_lowpass;

let signal = vec![1.0, 0.8, 0.6, 0.4, 0.2];
let filtered = filtfilt_lowpass(&signal, 10.0, 100.0, 2);
assert_eq!(filtered.len(), signal.len());
```

--------------------------------

### Create a new file-based asynchronous I/Q source

Source: https://docs.rs/desperado/latest/src/desperado/lib.rs.html

Demonstrates how to create an IqAsyncSource from a file, specifying parameters like center frequency, sample rate, chunk size, and IQ format. It then shows how to read chunks of samples from the source.

```rust
use desperado::{IqAsyncSource, IqFormat};
use futures::StreamExt;

# #[tokio::main]
# async fn main() -> Result<(), desperado::Error> {
let mut source = IqAsyncSource::from_file(
    "samples.iq",
    100_000_000,  // 100 MHz
    2_048_000,    // 2.048 MS/s
    16384,        // 16K samples per chunk
    IqFormat::Cu8
).await?;

while let Some(chunk) = source.next().await {
    let samples = chunk?;
    println!("Read {} samples", samples.len());
}
# Ok(())
# }

```

--------------------------------

### Example Usage

Source: https://docs.rs/desperado/latest/desperado/dsp/iir/fn.filtfilt_bandpass.html

An example demonstrating how to use the filtfilt_bandpass function.

```rust
use desperado::dsp::iir::filtfilt_bandpass;

let signal = vec![0.1, 0.2, 0.3, 0.4, 0.5];
let filtered = filtfilt_bandpass(&signal, 100.0, 200.0, 1000.0, 2);
assert_eq!(filtered.len(), signal.len());
```

--------------------------------

### Create a new stdin-based asynchronous I/Q source

Source: https://docs.rs/desperado/latest/src/desperado/lib.rs.html

Shows how to create an IqAsyncSource from standard input, similar to the file-based source but reading from stdin.

```rust
use desperado::{IqAsyncSource, IqFormat};

# #[tokio::main]
# async fn main() -> Result<(), desperado::Error> {
let source = IqAsyncSource::from_stdin(
    100_000_000,  // 100 MHz
    2_048_000,    // 2.048 MS/s
    16384,
    IqFormat::Cu8
);
# Ok(())
# }

```

--------------------------------

### Butterworth Low-pass Filter Example

Source: https://docs.rs/desperado/latest/src/desperado/dsp/filters.rs.html

Example of creating and using a low-pass Butterworth filter.

```rust
let mut filter = ButterworthFilter::lowpass(10_000.0, 48_000.0, 4);
let input = vec![0.1, 0.2, 0.3, 0.4];
let output = filter.filter(&input);
assert_eq!(output.len(), 4);
```

--------------------------------

### Rotate::process example

Source: https://docs.rs/desperado/latest/desperado/dsp/rotate/struct.Rotate.html

Example of processing a slice of complex samples with the Rotate DSP block.

```rust
use desperado::dsp::rotate::Rotate;
use desperado::dsp::DspBlock;
use num_complex::Complex;

let mut rotator = Rotate::new(0.5);
let input = vec![Complex::new(1.0, 0.0); 5];
let output = rotator.process(&input);
assert_eq!(output.len(), 5);
```

--------------------------------

### Rotate::reset example

Source: https://docs.rs/desperado/latest/desperado/dsp/rotate/struct.Rotate.html

Example of resetting the internal rotation state of a Rotate DSP block.

```rust
use desperado::dsp::rotate::Rotate;
use desperado::dsp::DspBlock;
use num_complex::Complex;

let mut rotator = Rotate::new(0.1);
let input = vec![Complex::new(1.0, 0.0); 10];
let _ = rotator.process(&input);

// Reset for new signal
rotator.reset();
```

--------------------------------

### Example usage of design_fir_filter

Source: https://docs.rs/desperado/latest/desperado/dsp/window/fn.design_fir_filter.html

Example of how to design a 31-tap Hamming window filter with a cutoff at Fs/16.

```rust
use desperado::dsp::window::{design_fir_filter, WindowType};

// Design a 31-tap Hamming window filter with cutoff at Fs/16
let filter = design_fir_filter(0.0625, 31, WindowType::Hamming);
assert_eq!(filter.len(), 31);
```

--------------------------------

### NCO Example

Source: https://docs.rs/desperado/latest/desperado/dsp/nco/index.html

Example of creating and using the NCO for mixing down a sample and stepping its phase.

```rust
use desperado::dsp::nco::Nco;

// Create NCO at 57 kHz with 171 kHz sample rate
let mut nco = Nco::new(57000.0, 171000.0);

// Set PLL bandwidth to 0.03 Hz for very narrow tracking
nco.set_pll_bandwidth(0.03, 171000.0);

// Mix a real sample down to baseband
let input_sample = 1.0f32;
let (i, q) = nco.mix_down(input_sample);

// Step the NCO phase forward
nco.step();

```

--------------------------------

### IqAsyncRead from File

Source: https://docs.rs/desperado/latest/src/desperado/iqread.rs.html

Asynchronously creates a new IqAsyncRead instance from a file.

```rust
impl IqAsyncRead<tokio::io::BufReader<tokio::fs::File>> {
    pub fn from_file<P: AsRef<Path>>(
        path: P,
        center_freq: u32,
        sample_rate: u32,
        chunk_size: usize,
        iq_format: IqFormat,
    ) -> impl std::future::Future<
        Output = error::Result<IqAsyncRead<tokio::io::BufReader<tokio::fs::File>>>, 
    > {
        let path = expanduser(path.as_ref().to_path_buf());
        async move {
            let file = tokio::fs::File::open(path).await?;
            let reader = tokio::io::BufReader::new(file);
            let config = IqConfig::new(center_freq, sample_rate, chunk_size, iq_format);
            Ok(IqAsyncRead { config, reader })
        }
    }
}
```

--------------------------------

### Create a new asynchronous I/Q source from a DeviceConfig

Source: https://docs.rs/desperado/latest/src/desperado/lib.rs.html

This is a convenience method that dispatches to the appropriate device-specific constructor based on the DeviceConfig variant.

```Rust
    #[cfg(any(
        feature = "rtlsdr",
        feature = "pluto",
        feature = "soapy",
        feature = "airspy",
        feature = "hackrf"
    ))]
    pub async fn from_device_config(config: &DeviceConfig) -> error::Result<Self> {
        match config {
            #[cfg(feature = "rtlsdr")]
            DeviceConfig::RtlSdr(cfg) => {
                let async_reader = rtlsdr::AsyncRtlSdrReader::new(cfg)?;
                Ok(IqAsyncSource::RtlSdr(async_reader))
            }
            #[cfg(feature = "pluto")]
            DeviceConfig::Pluto(cfg) => {
                let async_reader = pluto::AsyncPlutoSdrReader::new(cfg).await?;
                Ok(IqAsyncSource::PlutoSdr(async_reader))
            }
            #[cfg(feature = "soapy")]
            DeviceConfig::Soapy(cfg) => {
                let async_reader = soapy::AsyncSoapySdrReader::new(cfg)?;
                Ok(IqAsyncSource::SoapySdr(async_reader))
            }
            #[cfg(feature = "airspy")]
            DeviceConfig::Airspy(cfg) => {
                let async_reader = airspy::AsyncAirspySdrReader::new(cfg)?;
                Ok(IqAsyncSource::Airspy(async_reader))
            }
            #[cfg(feature = "hackrf")]
            DeviceConfig::HackRf(cfg) => {
                let async_reader = hackrf::AsyncHackRfReader::new(cfg)?;
                Ok(IqAsyncSource::HackRf(async_reader))
            }
        }
    }

```

--------------------------------

### Decimator::new Example

Source: https://docs.rs/desperado/latest/desperado/dsp/decimator/struct.Decimator.html

Example of creating a new Decimator instance with a specified decimation factor.

```rust
use desperado::dsp::decimator::Decimator;

let decimator = Decimator::new(4);
```

--------------------------------

### Keyboard Shortcuts

Source: https://docs.rs/desperado/latest/help.html

List of keyboard shortcuts available in rustdoc.

```text
`?`
    Show this help dialog

`S` / `/`
    Focus the search field

`↑`
    Move up in search results

`↓`
    Move down in search results

`←` / `→`
    Switch result tab (when results focused)

`⏎`
    Go to active search result

`+` / `=`
    Expand all sections

`-`
    Collapse all sections

`_`
    Collapse all sections, including impl blocks
```

--------------------------------

### Example Usage of DspBlock

Source: https://docs.rs/desperado/latest/desperado/dsp/trait.DspBlock.html

An example demonstrating how to use a `Rotate` DSP block, a concrete implementation of the `DspBlock` trait.

```rust
use desperado::dsp::{DspBlock, rotate::Rotate};
use num_complex::Complex;

let mut rotator = Rotate::new(0.1);
let input = vec![Complex::new(1.0, 0.0); 10];
let output = rotator.process(&input);
assert_eq!(output.len(), 10);
```

--------------------------------

### Decimator::with_params Example

Source: https://docs.rs/desperado/latest/desperado/dsp/decimator/struct.Decimator.html

Example of creating a new Decimator instance with custom filter parameters (factor, taps, cutoff).

```rust
use desperado::dsp::decimator::Decimator;

// Custom decimator with 63 taps and lower cutoff
let decimator = Decimator::with_params(8, 63, 0.05);
```

--------------------------------

### design_fir_filter Function Example

Source: https://docs.rs/desperado/latest/src/desperado/dsp/window.rs.html

Example usage of the `design_fir_filter` function to create a low-pass FIR filter with specified cutoff, taps, and window type.

```rust
/// Design a windowed-sinc FIR low-pass filter.
///
/// Creates FIR filter coefficients using the windowed-sinc method with the specified window type.
/// This is the primary interface for designing standard low-pass filters.
///
/// # Arguments
/// * `cutoff` - Normalized cutoff frequency (0.0 to 0.5, where 0.5 is the Nyquist frequency)
/// * `taps` - Number of filter taps (should be odd for symmetric filters)
/// * `window_type` - Type of window to apply
///
/// # Returns
/// Vector of normalized FIR filter coefficients
///
/// # Panics
/// Panics if `cutoff` is not in (0.0, 0.5], or if `taps` is 0.
///
/// # Example
/// ```
/// use desperado::dsp::window::{design_fir_filter, WindowType};
///
/// // Design a 31-tap Hamming window filter with cutoff at Fs/16
/// let filter = design_fir_filter(0.0625, 31, WindowType::Hamming);
/// assert_eq!(filter.len(), 31);
/// ```
pub fn design_fir_filter(cutoff: f32, taps: usize, window_type: WindowType) -> Vec<f32> {
    assert!(taps > 0, "Number of taps must be greater than 0");
    assert!(
        cutoff > 0.0 && cutoff <= 0.5,
        "Cutoff must be in range (0.0, 0.5]"

```

--------------------------------

### NCO with PLL Example

Source: https://docs.rs/desperado/latest/src/desperado/dsp/nco.rs.html

Demonstrates the typical usage of the Nco struct within a PLL loop, including setting bandwidth, calculating phase error, and stepping the NCO.

```rust
use desperado::dsp::nco::Nco;

let mut nco = Nco::new(57000.0, 171000.0);
nco.set_pll_bandwidth(0.03, 171000.0);

// Typical PLL loop: compute phase error, update PLL, step NCO
let received_phase = 0.1; // From received signal
let local_phase = nco.get_phase_radians();
let phase_error = received_phase - local_phase;

nco.pll_step(phase_error);
nco.step();

```

--------------------------------

### Create a new RTL-SDR-based I/Q source

Source: https://docs.rs/desperado/latest/src/desperado/lib.rs.html

This function creates a new I/Q source using an RTL-SDR device. It takes the device index, center frequency, sample rate, and an optional gain value as input.

```rust
    #[cfg(feature = "rtlsdr")]
    /// Create a new RTL-SDR-based I/Q source
    pub fn from_rtlsdr(
        device_index: usize,
        center_freq: u32,
        sample_rate: u32,
        gain: Option<i32>,
    ) -> error::Result<Self> {
        let config = rtlsdr::RtlSdrConfig {
            device: rtlsdr::DeviceSelector::Index(device_index),
            center_freq,
            sample_rate,
            gain: match gain {
                Some(g) => Gain::Manual((g as f64) / 10.0),
                None => Gain::Auto,
            },
            bias_tee: false,
            freq_correction_ppm: 0,
        };
        let source = rtlsdr::RtlSdrReader::new(&config)?;
        Ok(IqSource::RtlSdr(source))
    }
```

--------------------------------

### IqRead from File

Source: https://docs.rs/desperado/latest/src/desperado/iqread.rs.html

Creates a new IqRead instance from a file.

```rust
impl IqRead<std::io::BufReader<std::fs::File>> {
    pub fn from_file<P: AsRef<Path>>(
        path: P,
        center_freq: u32,
        sample_rate: u32,
        chunk_size: usize,
        iq_format: IqFormat,
    ) -> error::Result<Self> {
        let path = expanduser(path.as_ref().to_path_buf());
        let file = std::fs::File::open(path)?;
        let reader = std::io::BufReader::new(file);
        let config = IqConfig::new(center_freq, sample_rate, chunk_size, iq_format);
        Ok(Self { config, reader })
    }
}
```

--------------------------------

### Expand tilde (~) in path to home directory

Source: https://docs.rs/desperado/latest/src/desperado/lib.rs.html

This function expands paths starting with `~` to the user's home directory. If the path doesn't start with `~` or the home directory cannot be determined, the original path is returned unchanged.

```Rust
#![doc = include_str!("../readme.md")]
//! 
//! # API Naming Conventions
//! 
//! This library follows consistent naming conventions:
//! - **Synchronous types**: `IqSource`, `IqRead`, `RtlSdrReader`, etc.
//! - **Asynchronous types**: `IqAsyncSource`, `IqAsyncRead`, `AsyncRtlSdrReader`, etc.
//! - Async types are prefixed with `Async` or use `IqAsync` naming
//! - All async operations return `Future`s or implement the `Stream` trait

pub use error::{Error, Result};
use futures::Stream;
pub use metrics::{RfMetrics, RfMetricsCalculator, iq_level_dbfs};
use num_complex::Complex;
use serde::{Deserialize, Serialize};
use std::path::PathBuf;
use std::pin::Pin;
use std::task::{Context, Poll};

#[cfg(feature = "airspy")]
pub mod airspy;
pub mod dsp;
pub mod error;
#[cfg(feature = "hackrf")]
pub mod hackrf;
pub mod iqread;
pub mod metrics;
#[cfg(feature = "pluto")]
pub mod pluto;
#[cfg(feature = "rtlsdr")]
pub mod rtlsdr;
#[cfg(feature = "soapy")]
pub mod soapy;

/// Expand tilde (~) in path to home directory
///
/// This function expands paths starting with `~` to the user's home directory.
/// If the path doesn't start with `~` or the home directory cannot be determined,
/// the original path is returned unchanged.
///
/// # Examples
///
/// ```
/// use std::path::PathBuf;
/// use desperado::expanduser;
///
/// let path = PathBuf::from("~/Documents/data.iq");
/// let expanded = expanduser(path);
/// // On Unix: /home/username/Documents/data.iq
/// ```
pub fn expanduser(path: PathBuf) -> PathBuf {
    // Check if the path starts with "~"
    if let Some(stripped) = path.to_str().and_then(|p| p.strip_prefix("~"))
        && let Some(home_dir) = dirs::home_dir()
    {
        // Join the home directory with the rest of the path
        return home_dir.join(stripped.trim_start_matches('/'));
    }
    path
}

```

--------------------------------

### Zero-phase low-pass filter example

Source: https://docs.rs/desperado/latest/src/desperado/dsp/iir.rs.html

Apply zero-phase low-pass filter at 100 Hz cutoff, 1 kHz sample rate, 4th order.

```rust
use desperado::dsp::iir::filtfilt_lowpass;

// Apply zero-phase low-pass filter at 100 Hz cutoff, 1 kHz sample rate, 4th order
let signal = vec![0.5; 100];
let filtered = filtfilt_lowpass(&signal, 100.0, 1000.0, 4);
assert_eq!(filtered.len(), 100);
```

--------------------------------

### Installation

Source: https://docs.rs/desperado

Add Desperado to your Cargo.toml.

```toml
[dependencies]
desperado = "0.1"
```

--------------------------------

### pll_step Example

Source: https://docs.rs/desperado/latest/desperado/dsp/nco/struct.Nco.html

Example demonstrating how to update the NCO with a phase error using the pll_step method, which is the core PLL loop filter update. It adjusts NCO frequency and phase based on the phase error and loop filter constants (alpha and beta).

```rust
use desperado::dsp::nco::Nco;

let mut nco = Nco::new(57000.0, 171000.0);
nco.set_pll_bandwidth(0.03, 171000.0);

// Typical PLL loop: compute phase error, update PLL, step NCO
let received_phase = 0.1; // From received signal
let local_phase = nco.get_phase_radians();
let phase_error = received_phase - local_phase;

nco.pll_step(phase_error);
nco.step();
```

--------------------------------

### IqAsyncRead from Stdin

Source: https://docs.rs/desperado/latest/src/desperado/iqread.rs.html

Creates a new IqAsyncRead instance from standard input.

```rust
impl IqAsyncRead<tokio::io::BufReader<tokio::io::Stdin>> {
    pub fn from_stdin(
        center_freq: u32,
        sample_rate: u32,
        chunk_size: usize,
        iq_format: IqFormat,
    ) -> Self {
        let reader = tokio::io::BufReader::new(tokio::io::stdin());
        let config = IqConfig::new(center_freq, sample_rate, chunk_size, iq_format);
        Self { config, reader }
    }
}
```

--------------------------------

### LowPassFir::process Example

Source: https://docs.rs/desperado/latest/desperado/dsp/filters/struct.LowPassFir.html

Shows how to process a block of audio samples using an existing LowPassFir filter.

```rust
use desperado::dsp::filters::LowPassFir;

let filter = LowPassFir::new(15_000.0, 240_000.0, 256);
let input = vec![1.0, 0.5, 0.0, -0.5, -1.0];
let output = filter.process(&input);
assert_eq!(output.len(), 5);
```

--------------------------------

### StatefulLowPassFir::coefficients

Source: https://docs.rs/desperado/latest/desperado/dsp/filters/struct.StatefulLowPassFir.html

Gets the filter coefficients.

```rust
pub fn coefficients(&self) -> &[f32]
```
Tokens:
Raw