Struct Device 

pub struct Device { /* private fields */ }

Device struct

Implementations

impl Device

pub fn open(&mut self) -> Result<()>

Open a device

Errors

This will return an error if the device cannot be opened by librtlsdr (e.g. libusb failure or device is already open)

Examples found in repository

examples/simple.rs (line 6)

fn main() -> rtlsdr::Result<()> {
    let devices = rtlsdr::get_devices();
    println!("Found {} device(s)", devices.len());

    let mut device = devices[0];
    device.open()?;

    // Get and print the device information strings
    let (manufacturer, product, serial) = device.get_usb_device_strings()?;
    println!("Device: {manufacturer} {product} {serial}");

    // Configure the device with some common settings
    device.set_center_freq(101_700_000)?; // 101.7 MHz
    device.set_direct_sampling(rtlsdr::DirectSampling::Disabled)?;
    device.set_tuner_bandwidth(0)?;
    device.set_agc_mode(true)?;
    device.set_tuner_gain_mode(false)?;
    device.reset_buffer()?;

    // read some samples synchronously
    let mut buf = [0u8; 1024];
    let n_read = device.read(&mut buf)?;
    println!("Read {} bytes of data", n_read);

    // start asynchronous reading
    println!("Starting asynchronous reading for 3 seconds...");
    let start = std::time::Instant::now();
    device.start_reading(
        |data| {
            let avg = data.iter().map(|&b| b as u32).sum::<u32>() as f32 / data.len() as f32;

            println!(
                "Received {} bytes of data, average value: {:.2}",
                data.len(),
                avg
            );

            // return false to stop reading after 3 seconds
            start.elapsed().as_secs_f32() >= 3.0
        },
        0,
        0,
    )?;

    println!("Finished asynchronous reading.");

    Ok(())
}

pub fn close(&mut self) -> Result<()>

Close device

Errors

This will return an error if the device cannot be closed by librtlsdr (e.g. libusb failure or device is not open)

pub fn get_xtal_freq(&self) -> Result<(u32, u32)>

Get crystal oscillator frequencies used for the RTL2832 and the tuner IC Usually both ICs use the same clock.

Errors

This will return an error if the frequencies cannot be retrieved by librtlsdr (e.g. libusb failure or device is not open)

pub fn set_xtal_freq(&mut self, rtl_freq: u32, tuner_freq: u32) -> Result<()>

Set crystal oscillator frequencies used for the RTL2832 and the tuner IC. Usually both ICs use the same clock. Changing the clock may make sense if you are applying an external clock to the tuner or to compensate the frequency (and samplerate) error caused by the original (cheap) crystal.

NOTE: Call this function only if you fully understand the implications.

Errors

This will return an error if the frequencies cannot be set by librtlsdr (e.g. libusb failure or device is not open)

pub fn get_usb_device_strings(&self) -> Result<(String, String, String)>

Get USB device strings.

Returns

(manufacturer, product, serial) strings

Panics

This will panic if the retrieved strings from librtlsdr are not valid UTF-8 or if they are not null-terminated.

Errors

This will return an error if the strings cannot be retrieved by librtlsdr (e

Examples found in repository

examples/simple.rs (line 9)

fn main() -> rtlsdr::Result<()> {
    let devices = rtlsdr::get_devices();
    println!("Found {} device(s)", devices.len());

    let mut device = devices[0];
    device.open()?;

    // Get and print the device information strings
    let (manufacturer, product, serial) = device.get_usb_device_strings()?;
    println!("Device: {manufacturer} {product} {serial}");

    // Configure the device with some common settings
    device.set_center_freq(101_700_000)?; // 101.7 MHz
    device.set_direct_sampling(rtlsdr::DirectSampling::Disabled)?;
    device.set_tuner_bandwidth(0)?;
    device.set_agc_mode(true)?;
    device.set_tuner_gain_mode(false)?;
    device.reset_buffer()?;

    // read some samples synchronously
    let mut buf = [0u8; 1024];
    let n_read = device.read(&mut buf)?;
    println!("Read {} bytes of data", n_read);

    // start asynchronous reading
    println!("Starting asynchronous reading for 3 seconds...");
    let start = std::time::Instant::now();
    device.start_reading(
        |data| {
            let avg = data.iter().map(|&b| b as u32).sum::<u32>() as f32 / data.len() as f32;

            println!(
                "Received {} bytes of data, average value: {:.2}",
                data.len(),
                avg
            );

            // return false to stop reading after 3 seconds
            start.elapsed().as_secs_f32() >= 3.0
        },
        0,
        0,
    )?;

    println!("Finished asynchronous reading.");

    Ok(())
}

pub fn read_eeprom(&self, offset: u8, len: u16) -> Result<Box<[u8]>>

Read the device EEPROM

Errors

This will return an error if the EEPROM cannot be read by librtlsdr (e.g. libusb failure or device is not open)

pub fn write_eeprom(&mut self, offset: u8, buf: &mut [u8]) -> Result<()>

Write the device EEPROM

Errors

This will return an error if the EEPROM cannot be written by librtlsdr (e.g. libusb failure or device is not open)

Panics

This will panic if the buffer length exceeds the maximum EEPROM size (65535 bytes)

pub fn get_center_freq(&self) -> Result<u32>

Get actual frequency the device is tuned to in Hz

Errors

This will return an error if the frequency cannot be retrieved by librtlsdr (e.g. libusb failure or device is not open)

pub fn set_center_freq(&mut self, freq: u32) -> Result<()>

Set the frequency the device is tuned to in Hz

Errors

This will return an error if the frequency cannot be retrieved by librtlsdr (e.g. libusb failure or device is not open)

Examples found in repository

examples/simple.rs (line 13)

fn main() -> rtlsdr::Result<()> {
    let devices = rtlsdr::get_devices();
    println!("Found {} device(s)", devices.len());

    let mut device = devices[0];
    device.open()?;

    // Get and print the device information strings
    let (manufacturer, product, serial) = device.get_usb_device_strings()?;
    println!("Device: {manufacturer} {product} {serial}");

    // Configure the device with some common settings
    device.set_center_freq(101_700_000)?; // 101.7 MHz
    device.set_direct_sampling(rtlsdr::DirectSampling::Disabled)?;
    device.set_tuner_bandwidth(0)?;
    device.set_agc_mode(true)?;
    device.set_tuner_gain_mode(false)?;
    device.reset_buffer()?;

    // read some samples synchronously
    let mut buf = [0u8; 1024];
    let n_read = device.read(&mut buf)?;
    println!("Read {} bytes of data", n_read);

    // start asynchronous reading
    println!("Starting asynchronous reading for 3 seconds...");
    let start = std::time::Instant::now();
    device.start_reading(
        |data| {
            let avg = data.iter().map(|&b| b as u32).sum::<u32>() as f32 / data.len() as f32;

            println!(
                "Received {} bytes of data, average value: {:.2}",
                data.len(),
                avg
            );

            // return false to stop reading after 3 seconds
            start.elapsed().as_secs_f32() >= 3.0
        },
        0,
        0,
    )?;

    println!("Finished asynchronous reading.");

    Ok(())
}

pub fn get_freq_correction(&self) -> i32

Get actual frequency correction value of the device. Returns correction value in parts per million (ppm)

pub fn set_freq_correction(&mut self, ppm: i32) -> Result<()>

Set frequency correction value for the device in parts per million (ppm)

Errors

This will return an error if the frequency cannot be retrieved by librtlsdr (e.g. libusb failure or device is not open)

pub fn get_tuner_type(&self) -> TunerType

Get the tuner type

pub fn get_tuner_gains(&self) -> Result<Vec<i32>>

Get a list of gains supported by the tuner. Gain values in tenths of a dB, 115 means 11.5 dB

Errors

This will return an error if the frequency cannot be retrieved by librtlsdr (e.g. libusb failure or device is not open)

pub fn get_tuner_gain(&self) -> Result<i32>

Get actual (RF / HF) gain the device is configured to - excluding the IF gain. Gain in tenths of a dB, 115 means 11.5 dB.

Errors

This will return an error if the gain cannot be retrieved by librtlsdr (e.g. libusb failure or device is not open)

pub fn set_tuner_gain(&mut self, gain: i32) -> Result<()>

Set the gain for the device. Manual gain mode must be enabled for this to work. Valid gain values may be queried with Device::get_tuner_gains function. Gain in tenths of a dB, 115 means 11.5 dB

Errors

This will return an error if the gain cannot be set by librtlsdr (e.g. libusb failure or device is not open)

pub fn set_tuner_bandwidth(&mut self, bw: u32) -> Result<()>

Set the bandwidth for the device in Hz. Zero means automatic BW selection.

Errors

This will return an error if the bandwidth cannot be set by librtlsdr (e.g. libusb failure or device is not open)

Examples found in repository

examples/simple.rs (line 15)

fn main() -> rtlsdr::Result<()> {
    let devices = rtlsdr::get_devices();
    println!("Found {} device(s)", devices.len());

    let mut device = devices[0];
    device.open()?;

    // Get and print the device information strings
    let (manufacturer, product, serial) = device.get_usb_device_strings()?;
    println!("Device: {manufacturer} {product} {serial}");

    // Configure the device with some common settings
    device.set_center_freq(101_700_000)?; // 101.7 MHz
    device.set_direct_sampling(rtlsdr::DirectSampling::Disabled)?;
    device.set_tuner_bandwidth(0)?;
    device.set_agc_mode(true)?;
    device.set_tuner_gain_mode(false)?;
    device.reset_buffer()?;

    // read some samples synchronously
    let mut buf = [0u8; 1024];
    let n_read = device.read(&mut buf)?;
    println!("Read {} bytes of data", n_read);

    // start asynchronous reading
    println!("Starting asynchronous reading for 3 seconds...");
    let start = std::time::Instant::now();
    device.start_reading(
        |data| {
            let avg = data.iter().map(|&b| b as u32).sum::<u32>() as f32 / data.len() as f32;

            println!(
                "Received {} bytes of data, average value: {:.2}",
                data.len(),
                avg
            );

            // return false to stop reading after 3 seconds
            start.elapsed().as_secs_f32() >= 3.0
        },
        0,
        0,
    )?;

    println!("Finished asynchronous reading.");

    Ok(())
}

pub fn set_tuner_if_gain(&mut self, stage: i32, gain: i32) -> Result<()>

Set the intermediate frequency gain for the device.

• stage intermediate frequency gain stage number (1 to 6 for E4000)
• gain in tenths of a dB, -30 means -3.0 dB.

Errors

This will return an error if the IF gain cannot be set by librtlsdr (e.g. libusb failure or device is not open)

pub fn set_tuner_gain_mode(&mut self, manual: bool) -> Result<()>

Set the gain mode (automatic/manual) for the device. Manual gain mode must be enabled for the gain setter function to work.

Errors

This will return an error if the gain mode cannot be set by librtlsdr (e.g. libusb failure or device is not open)

Examples found in repository

examples/simple.rs (line 17)

fn main() -> rtlsdr::Result<()> {
    let devices = rtlsdr::get_devices();
    println!("Found {} device(s)", devices.len());

    let mut device = devices[0];
    device.open()?;

    // Get and print the device information strings
    let (manufacturer, product, serial) = device.get_usb_device_strings()?;
    println!("Device: {manufacturer} {product} {serial}");

    // Configure the device with some common settings
    device.set_center_freq(101_700_000)?; // 101.7 MHz
    device.set_direct_sampling(rtlsdr::DirectSampling::Disabled)?;
    device.set_tuner_bandwidth(0)?;
    device.set_agc_mode(true)?;
    device.set_tuner_gain_mode(false)?;
    device.reset_buffer()?;

    // read some samples synchronously
    let mut buf = [0u8; 1024];
    let n_read = device.read(&mut buf)?;
    println!("Read {} bytes of data", n_read);

    // start asynchronous reading
    println!("Starting asynchronous reading for 3 seconds...");
    let start = std::time::Instant::now();
    device.start_reading(
        |data| {
            let avg = data.iter().map(|&b| b as u32).sum::<u32>() as f32 / data.len() as f32;

            println!(
                "Received {} bytes of data, average value: {:.2}",
                data.len(),
                avg
            );

            // return false to stop reading after 3 seconds
            start.elapsed().as_secs_f32() >= 3.0
        },
        0,
        0,
    )?;

    println!("Finished asynchronous reading.");

    Ok(())
}

pub fn get_sample_rate(&self) -> Result<u32>

Get actual sample rate the device is configured to in Hz

Errors

This will return an error if the sample rate cannot be retrieved by librtlsdr (e.g. libusb failure or device is not open)

pub fn set_sample_rate(&mut self, rate: u32) -> Result<()>

Set the sample rate for the device in Hz

Errors

This will return an error if the sample rate cannot be set by librtlsdr (e.g. libusb failure or device is not open)

pub fn set_test_mode(&mut self, test_mode: bool) -> Result<()>

Enable test mode that returns an 8 bit counter instead of the samples. The counter is generated inside the RTL2832.

Errors

This will return an error if the test mode cannot be set by librtlsdr (e.g. libusb failure or device is not open)

pub fn set_agc_mode(&mut self, enabled: bool) -> Result<()>

Enable or disable the internal digital AGC of the RTL2832.

Errors

This will return an error if the AGC mode cannot be set by librtlsdr (e.g. libusb failure or device is not open)

Examples found in repository

examples/simple.rs (line 16)

fn main() -> rtlsdr::Result<()> {
    let devices = rtlsdr::get_devices();
    println!("Found {} device(s)", devices.len());

    let mut device = devices[0];
    device.open()?;

    // Get and print the device information strings
    let (manufacturer, product, serial) = device.get_usb_device_strings()?;
    println!("Device: {manufacturer} {product} {serial}");

    // Configure the device with some common settings
    device.set_center_freq(101_700_000)?; // 101.7 MHz
    device.set_direct_sampling(rtlsdr::DirectSampling::Disabled)?;
    device.set_tuner_bandwidth(0)?;
    device.set_agc_mode(true)?;
    device.set_tuner_gain_mode(false)?;
    device.reset_buffer()?;

    // read some samples synchronously
    let mut buf = [0u8; 1024];
    let n_read = device.read(&mut buf)?;
    println!("Read {} bytes of data", n_read);

    // start asynchronous reading
    println!("Starting asynchronous reading for 3 seconds...");
    let start = std::time::Instant::now();
    device.start_reading(
        |data| {
            let avg = data.iter().map(|&b| b as u32).sum::<u32>() as f32 / data.len() as f32;

            println!(
                "Received {} bytes of data, average value: {:.2}",
                data.len(),
                avg
            );

            // return false to stop reading after 3 seconds
            start.elapsed().as_secs_f32() >= 3.0
        },
        0,
        0,
    )?;

    println!("Finished asynchronous reading.");

    Ok(())
}

pub fn get_direct_sampling(&self) -> Result<DirectSampling>

Get state of the direct sampling mode

Errors

This will return an error if the direct sampling mode cannot be retrieved by librtlsdr (e.g. libusb failure or device is not open)

pub fn set_direct_sampling(&mut self, mode: DirectSampling) -> Result<()>

Enable or disable the direct sampling mode. When enabled, the IF mode of the RTL2832 is activated, and Device::set_center_freq() will control the IF-frequency of the DDC, which can be used to tune from 0 to 28.8 MHz (xtal frequency of the RTL2832).

Errors

This will return an error if the direct sampling mode cannot be set by librtlsdr (e.g. libusb failure or device is not open)

Examples found in repository

examples/simple.rs (line 14)

fn main() -> rtlsdr::Result<()> {
    let devices = rtlsdr::get_devices();
    println!("Found {} device(s)", devices.len());

    let mut device = devices[0];
    device.open()?;

    // Get and print the device information strings
    let (manufacturer, product, serial) = device.get_usb_device_strings()?;
    println!("Device: {manufacturer} {product} {serial}");

    // Configure the device with some common settings
    device.set_center_freq(101_700_000)?; // 101.7 MHz
    device.set_direct_sampling(rtlsdr::DirectSampling::Disabled)?;
    device.set_tuner_bandwidth(0)?;
    device.set_agc_mode(true)?;
    device.set_tuner_gain_mode(false)?;
    device.reset_buffer()?;

    // read some samples synchronously
    let mut buf = [0u8; 1024];
    let n_read = device.read(&mut buf)?;
    println!("Read {} bytes of data", n_read);

    // start asynchronous reading
    println!("Starting asynchronous reading for 3 seconds...");
    let start = std::time::Instant::now();
    device.start_reading(
        |data| {
            let avg = data.iter().map(|&b| b as u32).sum::<u32>() as f32 / data.len() as f32;

            println!(
                "Received {} bytes of data, average value: {:.2}",
                data.len(),
                avg
            );

            // return false to stop reading after 3 seconds
            start.elapsed().as_secs_f32() >= 3.0
        },
        0,
        0,
    )?;

    println!("Finished asynchronous reading.");

    Ok(())
}

pub fn get_offset_tuning(&self) -> Result<bool>

Get state of the offset tuning mode

Errors

This will return an error if the offset tuning mode cannot be retrieved by librtlsdr (e.g. libusb failure or device is not open)

pub fn set_offset_tuning(&mut self, enabled: bool) -> Result<()>

Enable or disable offset tuning for zero-IF tuners, which allows to avoid problems caused by the DC offset of the ADCs and 1/f noise.

Errors

This will return an error if the offset tuning mode cannot be set by librtlsdr (e.g. libusb failure or device is not open)

pub fn reset_buffer(&mut self) -> Result<()>

Reset buffer in RTL2832

Errors

This will return an error if the buffer cannot be reset by librtlsdr (e.g. libusb failure or device is not open)

Examples found in repository

examples/simple.rs (line 18)

fn main() -> rtlsdr::Result<()> {
    let devices = rtlsdr::get_devices();
    println!("Found {} device(s)", devices.len());

    let mut device = devices[0];
    device.open()?;

    // Get and print the device information strings
    let (manufacturer, product, serial) = device.get_usb_device_strings()?;
    println!("Device: {manufacturer} {product} {serial}");

    // Configure the device with some common settings
    device.set_center_freq(101_700_000)?; // 101.7 MHz
    device.set_direct_sampling(rtlsdr::DirectSampling::Disabled)?;
    device.set_tuner_bandwidth(0)?;
    device.set_agc_mode(true)?;
    device.set_tuner_gain_mode(false)?;
    device.reset_buffer()?;

    // read some samples synchronously
    let mut buf = [0u8; 1024];
    let n_read = device.read(&mut buf)?;
    println!("Read {} bytes of data", n_read);

    // start asynchronous reading
    println!("Starting asynchronous reading for 3 seconds...");
    let start = std::time::Instant::now();
    device.start_reading(
        |data| {
            let avg = data.iter().map(|&b| b as u32).sum::<u32>() as f32 / data.len() as f32;

            println!(
                "Received {} bytes of data, average value: {:.2}",
                data.len(),
                avg
            );

            // return false to stop reading after 3 seconds
            start.elapsed().as_secs_f32() >= 3.0
        },
        0,
        0,
    )?;

    println!("Finished asynchronous reading.");

    Ok(())
}

pub fn read(&self, buf: &mut [u8]) -> Result<i32>

Read data synchronously Returns the number of bytes read.

Errors

This will return an error if the samples cannot be read by librtlsdr (e.g. libusb failure or device is not open)

Panics

This will panic if the buffer length exceeds the maximum value of i32 (2^31 - 1) bytes

Examples found in repository

examples/simple.rs (line 22)

fn main() -> rtlsdr::Result<()> {
    let devices = rtlsdr::get_devices();
    println!("Found {} device(s)", devices.len());

    let mut device = devices[0];
    device.open()?;

    // Get and print the device information strings
    let (manufacturer, product, serial) = device.get_usb_device_strings()?;
    println!("Device: {manufacturer} {product} {serial}");

    // Configure the device with some common settings
    device.set_center_freq(101_700_000)?; // 101.7 MHz
    device.set_direct_sampling(rtlsdr::DirectSampling::Disabled)?;
    device.set_tuner_bandwidth(0)?;
    device.set_agc_mode(true)?;
    device.set_tuner_gain_mode(false)?;
    device.reset_buffer()?;

    // read some samples synchronously
    let mut buf = [0u8; 1024];
    let n_read = device.read(&mut buf)?;
    println!("Read {} bytes of data", n_read);

    // start asynchronous reading
    println!("Starting asynchronous reading for 3 seconds...");
    let start = std::time::Instant::now();
    device.start_reading(
        |data| {
            let avg = data.iter().map(|&b| b as u32).sum::<u32>() as f32 / data.len() as f32;

            println!(
                "Received {} bytes of data, average value: {:.2}",
                data.len(),
                avg
            );

            // return false to stop reading after 3 seconds
            start.elapsed().as_secs_f32() >= 3.0
        },
        0,
        0,
    )?;

    println!("Finished asynchronous reading.");

    Ok(())
}

pub fn start_reading<F>(&self, cb: F, buf_num: u32, buf_len: u32) -> Result<()>

where F: FnMut(Vec<u8>) -> bool,

Read samples from the device asynchronously. This will block until the asynchronous reading is canceled.

• cb: callback function to return received samples, which should return true to cancel further reading or false to continue reading.
• buf_num optional buffer count, buf_num * buf_len = overall buffer size set to 0 for default buffer count (15)
• buf_len optional buffer length, must be multiple of 512, should be a multiple of 16384 (URB size), set to 0 for default buffer length (16 * 32 * 512)

Errors

This will return an error if the asynchronous reading cannot be started by librtlsdr (e.g. libusb failure or device is not open)

Panics

This will panic if canceling the asynchronous reading from the callback fails

Examples found in repository

examples/simple.rs (lines 28-43)

fn main() -> rtlsdr::Result<()> {
    let devices = rtlsdr::get_devices();
    println!("Found {} device(s)", devices.len());

    let mut device = devices[0];
    device.open()?;

    // Get and print the device information strings
    let (manufacturer, product, serial) = device.get_usb_device_strings()?;
    println!("Device: {manufacturer} {product} {serial}");

    // Configure the device with some common settings
    device.set_center_freq(101_700_000)?; // 101.7 MHz
    device.set_direct_sampling(rtlsdr::DirectSampling::Disabled)?;
    device.set_tuner_bandwidth(0)?;
    device.set_agc_mode(true)?;
    device.set_tuner_gain_mode(false)?;
    device.reset_buffer()?;

    // read some samples synchronously
    let mut buf = [0u8; 1024];
    let n_read = device.read(&mut buf)?;
    println!("Read {} bytes of data", n_read);

    // start asynchronous reading
    println!("Starting asynchronous reading for 3 seconds...");
    let start = std::time::Instant::now();
    device.start_reading(
        |data| {
            let avg = data.iter().map(|&b| b as u32).sum::<u32>() as f32 / data.len() as f32;

            println!(
                "Received {} bytes of data, average value: {:.2}",
                data.len(),
                avg
            );

            // return false to stop reading after 3 seconds
            start.elapsed().as_secs_f32() >= 3.0
        },
        0,
        0,
    )?;

    println!("Finished asynchronous reading.");

    Ok(())
}

pub fn set_bias_tee(&mut self, on: bool) -> Result<()>

Enable or disable (the bias tee on) GPIO PIN 0 - if not reconfigured. This works for rtl-sdr.com v3 dongles, see http://www.rtl-sdr.com/rtl-sdr-blog-v-3-dongles-user-guide/ Note: Device::close() does not clear GPIO lines, so it leaves the (bias tee) line enabled if a client program doesn’t explictly disable it.

Errors

This will return an error if the bias tee cannot be set by librtlsdr (e.g. libusb failure or device is not open)

pub fn set_bias_tee_gpio(&mut self, gpio_pin: i32, on: bool) -> Result<()>

Enable or disable (the bias tee on) the given GPIO pin. Note: Device::close() does not clear GPIO lines, so it leaves the (bias tee) lines enabled if a client program doesn’t explictly disable it.

• gpio_pin needs to be in 0 .. 7. BUT pin 4 is connected to Tuner RESET. and for FC0012 is already connected/reserved pin 6 for switching V/U-HF.

Errors

This will return an error if the bias tee cannot be set by librtlsdr (e.g. libusb failure or device is not open)

Trait Implementations

impl Clone for Device

fn clone(&self) -> Device

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Copy for Device

impl Debug for Device

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Eq for Device

impl PartialEq for Device

fn eq(&self, other: &Device) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl StructuralPartialEq for Device