Skip to main content

hydrasdr_rs/
lib.rs

1//! Rust-native HydraSDR RFOne driver built on `nusb`.
2//!
3//! One-shot USB operations implement [`MaybeFuture`]: await them in async code,
4//! or call [`MaybeFuture::wait`] on native targets. Devices remain available
5//! while their independently owned receive stream retains a persistent USB
6//! transfer queue.
7//!
8//! The synchronous API uses [`nusb::MaybeFuture::wait`] for blocking operation.
9//! Awaited operations are executor-agnostic at this crate layer. Bulk/control
10//! transfers are natively async in `nusb`; async device discovery/open and
11//! endpoint `clear_halt` follow the support exposed by `nusb`, so applications
12//! that await those paths can enable exactly one of this crate's `tokio` or
13//! `smol` features for `nusb` IO thread integration. WebUSB does not need either
14//! runtime feature. No async runtime is forced by default.
15//!
16//! WebUSB builds must enable `web_sys_unstable_apis` as described in the
17//! [WebUSB section of the README](https://github.com/bastibl/hydrasdr-rs#webusb).
18//! Browsers only expose devices for which the page has WebUSB permission. Call
19//! `Device::request_permission` from a browser-window user gesture;
20//! [`Device::open`] can then discover and open the authorized device from
21//! either the window or a Web Worker. Opening never prompts for permission.
22//! [`MaybeFuture::wait`] is not available on `wasm32`; await device and stream
23//! operations there.
24//!
25//! # Synchronous API
26//!
27//! Open and configure real hardware with the [`Device`] builder:
28//!
29//! ```no_run
30//! use hydrasdr_rs::{Complex32, Device, GainPreset, MaybeFuture, RfPort};
31//! use std::time::Duration;
32//!
33//! fn main() -> hydrasdr_rs::Result<()> {
34//!     let mut dev = Device::builder()
35//!         .frequency_hz(100_000_000)
36//!         .sample_rate_hz(10_000_000)
37//!         .rf_port(RfPort::Rx0)
38//!         .gain(GainPreset::Linearity(12))
39//!         .open()
40//!         .wait()?;
41//!
42//!     let mut rx = dev.rx_stream()?;
43//!     rx.start().wait()?;
44//!     dev.set_frequency_hz(101_000_000).wait()?;
45//!     let mut samples = [Complex32::default(); 1024];
46//!     let count = rx
47//!         .read(&mut samples, Some(Duration::from_secs(1)))
48//!         .wait()?;
49//!     let stats = rx.close().wait()?;
50//!     println!("{count} samples");
51//!     println!("{stats:?}");
52//!     dev.shutdown().wait()?;
53//!
54//!     Ok(())
55//! }
56//! ```
57
58#![deny(missing_docs)]
59
60mod config;
61mod converter;
62mod device;
63mod discovery;
64mod errors;
65mod maybe_future;
66mod protocol;
67mod rfone;
68mod rx;
69mod session;
70mod usb;
71
72pub use config::DecimationPolicy;
73pub use config::{
74    Config, ConfigBuilder, F32Iq, GainConfig, GainPreset, RawAdc, RfPort, SampleFormat, SampleMode,
75    StageGain,
76};
77pub use device::{Device, DeviceBuilder};
78pub use device::{DeviceInfo, RfPortInfo};
79pub use discovery::DeviceDescriptor;
80pub use errors::{Error, ErrorKind, Result};
81pub use num_complex::Complex32;
82pub use nusb::MaybeFuture;
83pub use rx::MAX_F32_IQ_SAMPLES_PER_TRANSFER;
84pub use rx::StreamingStats;
85pub use rx::{RxStream, SampleBlock};
86
87#[cfg(all(test, not(target_arch = "wasm32")))]
88mod test_support;