1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
//! Device discovery, configuration and shared hardware ownership.
use crate::{
DeviceDescriptor, DirectSampling, GainConfig, Result, TunerKind,
config::{Config, ConfigBuilder, F32Iq, RawIq, SampleMode},
discovery::Selector,
maybe_future::{MaybeFutureExt, ready},
rtl2832u::Applied,
rx::RxStream,
session::{RxStreamClaim, Session},
usb::NusbTransport,
};
use nusb::MaybeFuture;
use std::sync::Arc;
/// Immutable identity captured during device initialization.
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct DeviceInfo {
/// USB identity.
pub descriptor: DeviceDescriptor,
/// Detected tuner family.
pub tuner: TunerKind,
/// Whether USB branding identifies an RTL-SDR Blog V4.
pub rtl_sdr_blog_v4: bool,
}
/// Owned device handle with a separately owned receive stream.
/// Dropping the handle does not interrupt an outstanding stream, even if stopped.
#[derive(Debug)]
pub struct Device<M: SampleMode = F32Iq> {
session: Arc<Session>,
config: Config<M>,
applied: Applied,
}
impl Device<F32Iq> {
/// List visible receivers with the standard Realtek USB IDs, without opening them.
pub fn list() -> impl MaybeFuture<Output = Result<Vec<DeviceDescriptor>>> {
crate::discovery::list()
}
/// Start a device builder with default configuration.
pub fn builder() -> DeviceBuilder {
DeviceBuilder::default()
}
/// Open the first visible receiver with default configuration.
pub fn open() -> impl MaybeFuture<Output = Result<Self>> {
Self::builder().open()
}
/// Open a device by its exact USB serial string.
pub fn open_serial(serial: impl Into<String>) -> impl MaybeFuture<Output = Result<Self>> {
Self::builder().serial(serial).open()
}
/// Ask for browser WebUSB permission from a user gesture, without opening the receiver.
#[cfg(target_arch = "wasm32")]
pub async fn request_permission() -> Result<()> {
Self::builder().request_permission().await
}
}
impl<M: SampleMode> Device<M> {
/// Immutable device metadata.
pub fn info(&self) -> &DeviceInfo {
self.session.info.get().expect("initialized metadata")
}
/// Last successfully applied configuration. A failed/canceled configuration
/// leaves this snapshot unchanged and requires a complete `configure` retry.
pub fn config(&self) -> &Config<M> {
&self.config
}
/// Last successfully programmed center frequency after divider quantization.
pub fn actual_frequency_hz(&self) -> u64 {
self.applied.frequency_hz
}
/// Last successfully programmed complex sample rate after divider quantization.
pub fn actual_sample_rate_hz(&self) -> u32 {
self.applied.sample_rate_hz
}
/// Apply a complete configuration. This also recovers from a failed or canceled
/// control operation. Controls are serialized; overlapping operations from a
/// stream return [`crate::Error::Busy`] and can be retried.
///
/// Queued samples may predate a live configuration change. Stop and restart
/// the stream when the caller needs previously queued samples discarded.
pub fn configure(&mut self, config: &Config<M>) -> impl MaybeFuture<Output = Result<()>> + '_ {
self.update(config.clone())
}
fn update(&mut self, proposed: Config<M>) -> impl MaybeFuture<Output = Result<()>> + '_ {
ready(proposed.settings.validate()).and_then(move |_| {
self.session
.configure(proposed.settings.clone())
.map(move |result| {
self.applied = result?;
self.config = proposed;
Ok(())
})
})
}
/// Tune the center frequency in Hz, preserving other settings.
pub fn set_frequency_hz(&mut self, hz: u64) -> impl MaybeFuture<Output = Result<()>> + '_ {
let mut config = self.config.clone();
config.settings.frequency_hz = hz;
self.update(config)
}
/// Set complex sample rate, preserving other settings.
pub fn set_sample_rate_hz(&mut self, hz: u32) -> impl MaybeFuture<Output = Result<()>> + '_ {
let mut config = self.config.clone();
config.settings.sample_rate_hz = hz;
self.update(config)
}
/// Change tuner gain policy, preserving other settings.
pub fn set_gain(&mut self, gain: GainConfig) -> impl MaybeFuture<Output = Result<()>> + '_ {
let mut config = self.config.clone();
config.settings.gain = gain;
self.update(config)
}
/// Reapply sample-rate and tuning dividers with a corrected crystal frequency.
pub fn set_correction_ppm(&mut self, ppm: i32) -> impl MaybeFuture<Output = Result<()>> + '_ {
let mut config = self.config.clone();
config.settings.correction_ppm = ppm;
self.update(config)
}
/// Enable or disable GPIO 0 bias power, preserving other settings.
pub fn set_bias_tee(&mut self, enabled: bool) -> impl MaybeFuture<Output = Result<()>> + '_ {
let mut config = self.config.clone();
config.settings.bias_tee = enabled;
self.update(config)
}
/// Set low-frequency direct sampling policy, preserving other settings.
pub fn set_direct_sampling(
&mut self,
mode: DirectSampling,
) -> impl MaybeFuture<Output = Result<()>> + '_ {
let mut config = self.config.clone();
config.settings.direct_sampling = mode;
self.update(config)
}
/// Claim the single receive stream. The stream starts only when `start` is
/// waited/awaited. Dormant and stopped streams retain the claim until close/drop.
pub fn rx_stream(&self) -> Result<RxStream<M>> {
self.session.ensure_configured()?;
Ok(RxStream::new(RxStreamClaim::acquire(&self.session)?))
}
/// Stop the hardware and disable RF bias power.
///
/// Returns Busy without changing lifecycle while a stream claim is held.
/// Close/drop the stream first. Unpolled shutdown has no effects; once begun,
/// shutdown is terminal, idempotent after success, and retryable on failure or
/// cancellation. All independent cleanup steps are attempted on error.
///
/// Final-owner Drop performs the same cleanup best-effort, blocking on native
/// targets and scheduling a background task on WebUSB. Explicit shutdown is
/// required to observe cleanup errors/completion.
pub fn shutdown(&mut self) -> impl MaybeFuture<Output = Result<()>> + '_ {
self.session.shutdown()
}
}
/// Select and configure a receiver. Standard IDs are `0bda:2832` and `0bda:2838`.
#[derive(Clone, Debug)]
pub struct DeviceBuilder<M: SampleMode = F32Iq> {
selector: Selector,
config: ConfigBuilder<M>,
}
impl Default for DeviceBuilder<F32Iq> {
fn default() -> Self {
Self {
selector: Selector::default(),
config: ConfigBuilder::default(),
}
}
}
impl<M: SampleMode> DeviceBuilder<M> {
/// Select by exact serial; this replaces a previously chosen index.
pub fn serial(mut self, serial: impl Into<String>) -> Self {
self.selector.serial = Some(serial.into());
self.selector.index = None;
self
}
/// Select by enumeration index; this replaces a previously chosen serial.
pub fn index(mut self, index: usize) -> Self {
self.selector.index = Some(index);
self.selector.serial = None;
self
}
/// Match a custom USB VID/PID instead of the standard Realtek IDs.
pub fn usb_id(mut self, vid: u16, pid: u16) -> Self {
self.selector.usb_id = Some((vid, pid));
self
}
/// Set center frequency in Hz.
pub fn frequency_hz(mut self, value: u64) -> Self {
self.config = self.config.frequency_hz(value);
self
}
/// Set complex sample rate in samples/s.
pub fn sample_rate_hz(mut self, value: u32) -> Self {
self.config = self.config.sample_rate_hz(value);
self
}
/// Set gain policy.
pub fn gain(mut self, value: GainConfig) -> Self {
self.config = self.config.gain(value);
self
}
/// Set crystal correction in ppm.
pub fn correction_ppm(mut self, value: i32) -> Self {
self.config = self.config.correction_ppm(value);
self
}
/// Enable or disable RF bias power.
pub fn bias_tee(mut self, value: bool) -> Self {
self.config = self.config.bias_tee(value);
self
}
/// Select low-frequency direct sampling behavior.
pub fn direct_sampling(mut self, value: DirectSampling) -> Self {
self.config = self.config.direct_sampling(value);
self
}
/// Validate the configuration without opening hardware.
pub fn config(self) -> Result<Config<M>> {
self.config.build()
}
/// Validate, open, probe, and configure the selected receiver.
/// After interface claim, failure/cancellation arms final-owner cleanup.
pub fn open(self) -> impl MaybeFuture<Output = Result<Device<M>>> {
ready(self.config.build()).and_then(move |config| {
NusbTransport::open(self.selector).and_then(move |(control, descriptor)| {
Session::initialize(control, descriptor, config.settings.clone()).map_ok(
move |(session, applied)| Device {
session,
config,
applied,
},
)
})
})
}
/// Request WebUSB permission from a browser user gesture. Opening afterwards
/// can take place in either a Window or a Worker and never prompts.
#[cfg(target_arch = "wasm32")]
pub async fn request_permission(&self) -> Result<()> {
crate::discovery::request_permission(&self.selector).await
}
}
impl DeviceBuilder<F32Iq> {
/// Select raw unsigned eight-bit I/Q blocks instead of converted floats.
pub fn raw_iq(self) -> DeviceBuilder<RawIq> {
DeviceBuilder {
selector: self.selector,
config: self.config.raw_iq(),
}
}
}