tiny-wb/examples/validate-hardware.rs

381 lines
12 KiB
Rust
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

//! Guided, conservative hardware acceptance for tinySA Basic and Ultra.
use std::{
collections::HashSet,
env,
error::Error,
fs,
io::{self, Write},
path::PathBuf,
thread,
time::Duration,
};
use tiny_wb::{
acquisition::{acquire, ScanEvent},
config::{Config, FrequencyAxis, ModelSelection, OutputConfig},
connection::open_connection,
export::save_csv,
protocol::{Sample, ScanRequest, BASIC_RAW_LEVEL_OFFSET_DB, ULTRA_RAW_LEVEL_OFFSET_DB},
transport::Shell,
};
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
enum Model {
Basic,
Ultra,
}
impl Model {
fn parse(value: &str) -> Option<Self> {
match value.to_ascii_lowercase().as_str() {
"basic" => Some(Self::Basic),
"ultra" => Some(Self::Ultra),
_ => None,
}
}
fn name(self) -> &'static str {
match self {
Self::Basic => "Basic",
Self::Ultra => "Ultra",
}
}
fn raw_level_offset_db(self) -> u16 {
match self {
Self::Basic => BASIC_RAW_LEVEL_OFFSET_DB,
Self::Ultra => ULTRA_RAW_LEVEL_OFFSET_DB,
}
}
fn scans(self) -> [(&'static str, ScanRequest, bool); 2] {
let low = ScanRequest {
start_hz: 240_000_000,
stop_hz: 300_000_000,
points: 101,
repeat: 1,
};
let second = match self {
Self::Basic => ScanRequest {
start_hz: 350_000_000,
stop_hz: 400_000_000,
..low
},
// Ultra support is experimental. Stay on the shared low-input
// command path until model-aware extended ranges are implemented.
Self::Ultra => low,
};
[("legacy", low, true), ("direct", second, false)]
}
}
struct Arguments {
model: Model,
port: Option<String>,
output: PathBuf,
}
fn usage() -> &'static str {
"usage: validate-hardware <basic|ultra> [--port DEVICE] [--output DIRECTORY]"
}
fn parse_arguments(arguments: impl IntoIterator<Item = String>) -> Result<Arguments, String> {
let mut arguments = arguments.into_iter();
let model = arguments
.next()
.as_deref()
.and_then(Model::parse)
.ok_or_else(|| usage().to_owned())?;
let mut port = None;
let mut output = PathBuf::from("hardware-validation");
while let Some(option) = arguments.next() {
let value = arguments
.next()
.ok_or_else(|| format!("missing value for {option}\n{}", usage()))?;
match option.as_str() {
"--port" if port.is_none() && !value.is_empty() => port = Some(value),
"--output" if !value.is_empty() => output = PathBuf::from(value),
_ => return Err(format!("invalid option: {option}\n{}", usage())),
}
}
Ok(Arguments {
model,
port,
output,
})
}
fn prompt(message: &str) -> io::Result<String> {
print!("{message}");
io::stdout().flush()?;
let mut answer = String::new();
io::stdin().read_line(&mut answer)?;
Ok(answer.trim().to_owned())
}
fn ports() -> Result<Vec<String>, serialport::Error> {
Ok(serialport::available_ports()?
.into_iter()
.map(|port| port.port_name)
.collect())
}
fn select_port(explicit: Option<String>) -> Result<String, Box<dyn Error>> {
if let Some(port) = explicit {
prompt("Disconnect every RF source, plug in and power on the tinySA, then press Enter: ")?;
return Ok(port);
}
prompt("Disconnect the tinySA USB cable and every RF source, then press Enter: ")?;
let before: HashSet<_> = ports()?.into_iter().collect();
prompt("Plug in and power on the tinySA, then press Enter: ")?;
thread::sleep(Duration::from_millis(500));
let available = ports()?;
let added: Vec<_> = available
.iter()
.filter(|port| !before.contains(*port))
.cloned()
.collect();
if added.len() == 1 {
println!("Detected {}", added[0]);
return Ok(added[0].clone());
}
if available.len() == 1 {
println!("Using the only available serial port: {}", available[0]);
return Ok(available[0].clone());
}
if available.is_empty() {
return Err("no serial port appeared; check the USB data cable and permissions".into());
}
println!("Select the tinySA serial port:");
for (index, port) in available.iter().enumerate() {
println!(" {}. {port}", index + 1);
}
let selection: usize = prompt("Port number: ")?.parse()?;
available
.get(
selection
.checked_sub(1)
.ok_or("port number must be at least 1")?,
)
.cloned()
.ok_or_else(|| "port number is outside the displayed list".into())
}
fn validate_samples(samples: &[Sample], request: &ScanRequest) -> Result<(), Box<dyn Error>> {
if samples.len() != request.points {
return Err(format!(
"expected {} samples, received {}",
request.points,
samples.len()
)
.into());
}
if samples.iter().any(|sample| {
!sample.frequency_mhz.is_finite()
|| !sample.level_dbm.is_finite()
|| sample.frequency_mhz < request.start_hz as f64 / 1_000_000.0
|| sample.frequency_mhz > request.stop_hz as f64 / 1_000_000.0
}) {
return Err("CSV data contains a non-finite or out-of-range value".into());
}
Ok(())
}
fn safe_identity(identity: &str) -> String {
identity
.chars()
.filter(|character| *character == '\n' || *character == '\r' || !character.is_control())
.collect()
}
fn run() -> Result<(), Box<dyn Error>> {
let arguments = parse_arguments(env::args().skip(1)).map_err(io::Error::other)?;
println!(
"tinySA {} hardware validation\nNo RF source should be connected during this communications test.",
arguments.model.name()
);
let port = select_port(arguments.port)?;
let session = arguments.output.join(format!(
"{}-{}",
arguments.model.name().to_ascii_lowercase(),
chrono::Local::now().format("%Y%m%d-%H%M%S-%6f")
));
fs::create_dir_all(&session)?;
let mut report = format!(
"requested_model={}\nport={}\nbaudrate=115200\n",
arguments.model.name(),
port
);
let mut identity = String::new();
for (name, request, legacy_pre_scan) in arguments.model.scans() {
println!(
"Running {name} scan: {}–{} MHz, {} points...",
request.start_hz / 1_000_000,
request.stop_hz / 1_000_000,
request.points
);
let mut config = Config::default();
config.port.clone_from(&port);
config.start_frequency = (request.start_hz / 1_000_000) as usize;
config.stop_frequency = (request.stop_hz / 1_000_000) as usize;
config.points = request.points;
config.repeat = request.repeat;
config.scan.device_model = match arguments.model {
Model::Basic => ModelSelection::Basic,
Model::Ultra => ModelSelection::Ultra,
};
config.scan.auto_zero_offset = true;
config.scan.zero_offset = arguments.model.raw_level_offset_db();
config.scan.frequency_axis = FrequencyAxis::Firmware;
config.scan.legacy_pre_scan = legacy_pre_scan;
config.validate()?;
let connection = open_connection(&config)?;
let mut shell = Shell::new(connection, config.serial.max_response_bytes);
let samples = acquire(
&mut shell,
&request,
&config.scan,
&config.serial,
|event| {
if let ScanEvent::InstrumentInfo(value) = event {
identity = safe_identity(&value);
}
},
)?;
validate_samples(&samples, &request)?;
let output = OutputConfig {
directory: session.clone(),
filename_prefix: format!("{}-{name}", arguments.model.name().to_ascii_lowercase()),
include_header: true,
};
let path = save_csv(&samples, &output)?;
println!(
"PASS: saved {} validated samples to {}",
samples.len(),
path.display()
);
report.push_str(&format!(
"scan={name},start_hz={},stop_hz={},points={},raw_level_offset_db={},legacy_pre_scan={},csv={}\n",
request.start_hz,
request.stop_hz,
request.points,
config.scan.zero_offset,
legacy_pre_scan,
path.display()
));
}
println!("\nInstrument identity returned by the device:\n{identity}");
let confirmed = prompt(&format!(
"Does this match a tinySA {} and is its live sweep running again? [y/N] ",
arguments.model.name()
))?;
report.push_str(&format!(
"identity=\n{identity}\noperator_confirmed={}\n",
confirmed
));
let report_path = session.join(format!(
"{}-report.txt",
arguments.model.name().to_ascii_lowercase()
));
fs::write(&report_path, report)?;
if !matches!(confirmed.as_str(), "y" | "Y" | "yes" | "YES" | "Yes") {
return Err(format!(
"operator confirmation failed; partial report: {}",
report_path.display()
)
.into());
}
println!(
"PASS: hardware validation report saved to {}",
report_path.display()
);
if arguments.model == Model::Ultra {
println!("Ultra result covers only the shared 240–300 MHz low-input path; extended ranges remain unsupported.");
}
Ok(())
}
fn main() {
if let Err(error) = run() {
eprintln!("FAIL: {error}");
std::process::exit(1);
}
}
#[cfg(test)]
mod tests {
use super::*;
use tiny_wb::device::DeviceModel;
#[test]
fn plans_keep_ultra_on_the_shared_low_input_path() {
assert_eq!(Model::Basic.raw_level_offset_db(), 128);
assert_eq!(Model::Ultra.raw_level_offset_db(), 174);
let basic = Model::Basic.scans();
assert_eq!(
DeviceModel::Basic.plan(&basic[0].1).unwrap().input_command,
"mode low input"
);
assert_eq!(
DeviceModel::Basic.plan(&basic[1].1).unwrap().input_command,
"mode high input"
);
let ultra = Model::Ultra.scans();
assert!(ultra.iter().all(|(_, request, _)| {
request.stop_hz < 350_000_000
&& DeviceModel::Ultra
.plan(request)
.is_ok_and(|plan| plan.input_command == "mode low input")
}));
assert!(ultra[0].2);
assert!(!ultra[1].2);
}
#[test]
fn sample_validation_rejects_bad_count_and_values() {
let request = ScanRequest {
start_hz: 240_000_000,
stop_hz: 300_000_000,
points: 2,
repeat: 1,
};
let valid = [
Sample {
frequency_mhz: 240.0,
level_dbm: -90.0,
},
Sample {
frequency_mhz: 270.0,
level_dbm: -80.0,
},
];
assert!(validate_samples(&valid, &request).is_ok());
assert!(validate_samples(&valid[..1], &request).is_err());
let invalid = [
valid[0],
Sample {
frequency_mhz: 270.0,
level_dbm: f64::NAN,
},
];
assert!(validate_samples(&invalid, &request).is_err());
}
#[test]
fn arguments_require_a_known_model_and_option_values() {
assert_eq!(
parse_arguments(["ultra".into(), "--port".into(), "COM7".into()])
.unwrap()
.port
.as_deref(),
Some("COM7")
);
assert!(parse_arguments(["unknown".into()]).is_err());
assert!(parse_arguments(["basic".into(), "--port".into()]).is_err());
assert!(parse_arguments(["basic".into(), "--bad".into(), "x".into()]).is_err());
}
}