Proof-of-concept Rust wrapper

This contains Rust wrappers around enough of the Python API to implement Rust versions of the `battery_client` and `run_scanner` examples. The goal is to gather feedback on the approach, and of course to show that it is possible.

The module structure mirrors that of the Python. The Rust API is not optimally Rust-y, but given the constraints of everything having to delegate to Python, it's at least usable.

Notably, this does not yet solve the packaging problem: users must have an appropriate virtualenv, libpython, etc. [PyOxidizer](https://github.com/indygreg/PyOxidizer) may be a viable path there.

rust/examples/battery_client.rs

@@ -0,0 +1,113 @@
+// Copyright 2023 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+//! Counterpart to the Python example `battery_server.py`.
+//!
+//! Start an Android emulator from Android Studio, or otherwise have netsim running.
+//!
+//! Run the server from the project root:
+//! ```
+//! PYTHONPATH=. python examples/battery_server.py \
+//!     examples/device1.json android-netsim
+//! ```
+//!
+//! Then run this example from the `rust` directory:
+//!
+//! ```
+//! PYTHONPATH=..:/path/to/virtualenv/site-packages/ \
+//!     cargo run --example battery_client -- \
+//!     --transport android-netsim \
+//!     --target-addr F0:F1:F2:F3:F4:F5
+//! ```
+
+use bumble::wrapper::{
+    device::{Device, Peer},
+    profile::BatteryService,
+    transport::Transport,
+    PyObjectExt,
+};
+use clap::Parser as _;
+use log::info;
+use owo_colors::OwoColorize;
+use pyo3::prelude::*;
+
+#[pyo3_asyncio::tokio::main]
+async fn main() -> PyResult<()> {
+    env_logger::builder()
+        .filter_level(log::LevelFilter::Info)
+        .init();
+
+    let cli = Cli::parse();
+
+    let transport = Transport::open(cli.transport).await?;
+
+    let device = Device::with_hci(
+        "Bumble",
+        "F0:F1:F2:F3:F4:F5",
+        transport.source()?,
+        transport.sink()?,
+    )?;
+
+    device.power_on().await?;
+
+    let conn = device.connect(&cli.target_addr).await?;
+    let mut peer = Peer::new(conn)?;
+    peer.discover_services().await?;
+    for mut s in peer.services()? {
+        s.discover_characteristics().await?;
+    }
+    let battery_service = peer
+        .create_service_proxy::<BatteryService>()?
+        .ok_or(anyhow::anyhow!("No battery service found"))?;
+
+    let mut battery_level_char = battery_service
+        .battery_level()?
+        .ok_or(anyhow::anyhow!("No battery level characteristic"))?;
+    info!(
+        "{} {}",
+        "Initial Battery Level:".green(),
+        battery_level_char
+            .read_value()
+            .await?
+            .extract_with_gil::<u32>()?
+    );
+    battery_level_char
+        .subscribe(|_py, args| {
+            info!(
+                "{} {:?}",
+                "Battery level update:".green(),
+                args.get_item(0)?.extract::<u32>()?,
+            );
+            Ok(())
+        })
+        .await?;
+
+    // wait until user kills the process
+    tokio::signal::ctrl_c().await?;
+    Ok(())
+}
+
+#[derive(clap::Parser)]
+#[command(author, version, about, long_about = None)]
+struct Cli {
+    /// Bumble transport spec.
+    ///
+    /// <https://google.github.io/bumble/transports/index.html>
+    #[arg(long)]
+    transport: String,
+
+    /// Address to connect to
+    #[arg(long)]
+    target_addr: String,
+}

rust/examples/broadcast.rs

@@ -0,0 +1,96 @@
+// Copyright 2023 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+use anyhow::anyhow;
+use bumble::wrapper::{
+    adv::{AdvertisementDataBuilder, CommonDataType},
+    device::Device,
+    logging::{bumble_env_logging_level, py_logging_basic_config},
+    transport::Transport,
+};
+use clap::Parser as _;
+use pyo3::PyResult;
+use rand::Rng;
+use std::path;
+
+#[pyo3_asyncio::tokio::main]
+async fn main() -> PyResult<()> {
+    env_logger::builder()
+        .filter_level(log::LevelFilter::Info)
+        .init();
+
+    let cli = Cli::parse();
+
+    if cli.log_hci {
+        py_logging_basic_config(bumble_env_logging_level("DEBUG"))?;
+    }
+
+    let transport = Transport::open(cli.transport).await?;
+
+    let mut device = Device::from_config_file_with_hci(
+        &cli.device_config,
+        transport.source()?,
+        transport.sink()?,
+    )?;
+
+    let mut adv_data = AdvertisementDataBuilder::new();
+
+    adv_data
+        .append(
+            CommonDataType::CompleteLocalName,
+            "Bumble from Rust".as_bytes(),
+        )
+        .map_err(|e| anyhow!(e))?;
+
+    // Randomized TX power
+    adv_data
+        .append(
+            CommonDataType::TxPowerLevel,
+            &[rand::thread_rng().gen_range(-100_i8..=20) as u8],
+        )
+        .map_err(|e| anyhow!(e))?;
+
+    device.set_advertisement(adv_data)?;
+    device.power_on().await?;
+
+    println!("Advertising...");
+    device.start_advertising(true).await?;
+
+    // wait until user kills the process
+    tokio::signal::ctrl_c().await?;
+
+    println!("Stopping...");
+    device.stop_advertising().await?;
+
+    Ok(())
+}
+
+#[derive(clap::Parser)]
+#[command(author, version, about, long_about = None)]
+struct Cli {
+    /// Bumble device config.
+    ///
+    /// See, for instance, `examples/device1.json` in the Python project.
+    #[arg(long)]
+    device_config: path::PathBuf,
+    /// Bumble transport spec.
+    ///
+    /// <https://google.github.io/bumble/transports/index.html>
+    #[arg(long)]
+    transport: String,
+
+    /// Log HCI commands
+    #[arg(long)]
+    log_hci: bool,
+}

rust/examples/scanner.rs

@@ -0,0 +1,180 @@
+// Copyright 2023 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+//! Counterpart to the Python example `run_scanner.py`
+
+use bumble::wrapper::{
+    adv::CommonDataType, core::AdvertisementDataUnit, device::Device, hci::AddressType,
+    transport::Transport,
+};
+use clap::Parser as _;
+use itertools::Itertools;
+use owo_colors::{OwoColorize, Style};
+use pyo3::PyResult;
+use std::{
+    collections,
+    sync::{Arc, Mutex},
+    time,
+};
+
+#[pyo3_asyncio::tokio::main]
+async fn main() -> PyResult<()> {
+    env_logger::builder()
+        .filter_level(log::LevelFilter::Info)
+        .init();
+
+    let cli = Cli::parse();
+
+    let transport = Transport::open(cli.transport).await?;
+
+    let mut device = Device::with_hci(
+        "Bumble",
+        "F0:F1:F2:F3:F4:F5",
+        transport.source()?,
+        transport.sink()?,
+    )?;
+
+    // in practice, devices can send multiple advertisements from the same address, so we keep
+    // track of a timestamp for each set of data
+    let seen_advertisements = Arc::new(Mutex::new(collections::HashMap::<
+        Vec<u8>,
+        collections::HashMap<Vec<AdvertisementDataUnit>, time::Instant>,
+    >::new()));
+
+    let seen_adv_clone = seen_advertisements.clone();
+    device.on_advertisement(move |_py, adv| {
+        let rssi = adv.rssi()?;
+        let data_units = adv.data()?.data_units()?;
+        let addr = adv.address()?;
+
+        let show_adv = if cli.filter_duplicates {
+            let addr_bytes = addr.as_le_bytes()?;
+
+            let mut seen_adv_cache = seen_adv_clone.lock().unwrap();
+            let expiry_duration = time::Duration::from_secs(cli.dedup_expiry_secs);
+
+            let advs_from_addr = seen_adv_cache
+                .entry(addr_bytes)
+                .or_insert_with(collections::HashMap::new);
+            // we expect cache hits to be the norm, so we do a separate lookup to avoid cloning
+            // on every lookup with entry()
+            let show = if let Some(prev) = advs_from_addr.get_mut(&data_units) {
+                let expired = prev.elapsed() > expiry_duration;
+                *prev = time::Instant::now();
+                expired
+            } else {
+                advs_from_addr.insert(data_units.clone(), time::Instant::now());
+                true
+            };
+
+            // clean out anything we haven't seen in a while
+            advs_from_addr.retain(|_, instant| instant.elapsed() <= expiry_duration);
+
+            show
+        } else {
+            true
+        };
+
+        if !show_adv {
+            return Ok(());
+        }
+
+        let addr_style = if adv.is_connectable()? {
+            Style::new().yellow()
+        } else {
+            Style::new().red()
+        };
+
+        let (type_style, qualifier) = match adv.address()?.address_type()? {
+            AddressType::PublicIdentity | AddressType::PublicDevice => (Style::new().cyan(), ""),
+            _ => {
+                if addr.is_static()? {
+                    (Style::new().green(), "(static)")
+                } else if addr.is_resolvable()? {
+                    (Style::new().magenta(), "(resolvable)")
+                } else {
+                    (Style::new().default_color(), "")
+                }
+            }
+        };
+
+        println!(
+            ">>> {} [{:?}] {qualifier}:\n  RSSI: {}",
+            addr.as_hex()?.style(addr_style),
+            addr.address_type()?.style(type_style),
+            rssi,
+        );
+
+        data_units.into_iter().for_each(|(code, data)| {
+            let matching = CommonDataType::for_type_code(code).collect::<Vec<_>>();
+            let code_str = if matching.is_empty() {
+                format!("0x{}", hex::encode_upper([code.into()]))
+            } else {
+                matching
+                    .iter()
+                    .map(|t| format!("{}", t))
+                    .join(" / ")
+                    .blue()
+                    .to_string()
+            };
+
+            // use the first matching type's formatted data, if any
+            let data_str = matching
+                .iter()
+                .filter_map(|t| {
+                    t.format_data(&data).map(|formatted| {
+                        format!(
+                            "{} {}",
+                            formatted,
+                            format!("(raw: 0x{})", hex::encode_upper(&data)).dimmed()
+                        )
+                    })
+                })
+                .next()
+                .unwrap_or_else(|| format!("0x{}", hex::encode_upper(&data)));
+
+            println!("  [{}]: {}", code_str, data_str)
+        });
+
+        Ok(())
+    })?;
+
+    device.power_on().await?;
+    // do our own dedup
+    device.start_scanning(false).await?;
+
+    // wait until user kills the process
+    tokio::signal::ctrl_c().await?;
+
+    Ok(())
+}
+
+#[derive(clap::Parser)]
+#[command(author, version, about, long_about = None)]
+struct Cli {
+    /// Bumble transport spec.
+    ///
+    /// <https://google.github.io/bumble/transports/index.html>
+    #[arg(long)]
+    transport: String,
+
+    /// Filter duplicate advertisements
+    #[arg(long, default_value_t = false)]
+    filter_duplicates: bool,
+
+    /// How long before a deduplicated advertisement that hasn't been seen in a while is considered
+    /// fresh again, in seconds
+    #[arg(long, default_value_t = 10, requires = "filter_duplicates")]
+    dedup_expiry_secs: u64,
+}

rust/examples/usb_probe.rs

@@ -0,0 +1,342 @@
+// Copyright 2023 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+//! Rust version of the Python `usb_probe.py`.
+//!
+//! This tool lists all the USB devices, with details about each device.
+//! For each device, the different possible Bumble transport strings that can
+//! refer to it are listed. If the device is known to be a Bluetooth HCI device,
+//! its identifier is printed in reverse colors, and the transport names in cyan color.
+//! For other devices, regardless of their type, the transport names are printed
+//! in red. Whether that device is actually a Bluetooth device or not depends on
+//! whether it is a Bluetooth device that uses a non-standard Class, or some other
+//! type of device (there's no way to tell).
+
+use clap::Parser as _;
+use itertools::Itertools as _;
+use owo_colors::{OwoColorize, Style};
+use rusb::{Device, DeviceDescriptor, Direction, TransferType, UsbContext};
+use std::{
+    collections::{HashMap, HashSet},
+    time::Duration,
+};
+
+const USB_DEVICE_CLASS_DEVICE: u8 = 0x00;
+const USB_DEVICE_CLASS_WIRELESS_CONTROLLER: u8 = 0xE0;
+const USB_DEVICE_SUBCLASS_RF_CONTROLLER: u8 = 0x01;
+const USB_DEVICE_PROTOCOL_BLUETOOTH_PRIMARY_CONTROLLER: u8 = 0x01;
+
+fn main() -> anyhow::Result<()> {
+    let cli = Cli::parse();
+
+    let mut bt_dev_count = 0;
+    let mut device_serials_by_id: HashMap<(u16, u16), HashSet<String>> = HashMap::new();
+    for device in rusb::devices()?.iter() {
+        let device_desc = device.device_descriptor().unwrap();
+
+        let class_info = ClassInfo::from(&device_desc);
+        let handle = device.open()?;
+        let timeout = Duration::from_secs(1);
+        // some devices don't have languages
+        let lang = handle
+            .read_languages(timeout)
+            .ok()
+            .and_then(|langs| langs.into_iter().next());
+        let serial = lang.and_then(|l| {
+            handle
+                .read_serial_number_string(l, &device_desc, timeout)
+                .ok()
+        });
+        let mfg = lang.and_then(|l| {
+            handle
+                .read_manufacturer_string(l, &device_desc, timeout)
+                .ok()
+        });
+        let product = lang.and_then(|l| handle.read_product_string(l, &device_desc, timeout).ok());
+
+        let is_hci = is_bluetooth_hci(&device, &device_desc)?;
+        let addr_style = if is_hci {
+            bt_dev_count += 1;
+            Style::new().black().on_yellow()
+        } else {
+            Style::new().yellow().on_black()
+        };
+
+        let mut transport_names = Vec::new();
+        let basic_transport_name = format!(
+            "usb:{:04X}:{:04X}",
+            device_desc.vendor_id(),
+            device_desc.product_id()
+        );
+
+        if is_hci {
+            transport_names.push(format!("usb:{}", bt_dev_count - 1));
+        }
+
+        let device_id = (device_desc.vendor_id(), device_desc.product_id());
+        if !device_serials_by_id.contains_key(&device_id) {
+            transport_names.push(basic_transport_name.clone());
+        } else {
+            transport_names.push(format!(
+                "{}/{}",
+                basic_transport_name,
+                device_serials_by_id
+                    .get(&device_id)
+                    .map(|serials| serials.len())
+                    .unwrap_or(0)
+            ))
+        }
+
+        if let Some(s) = &serial {
+            if !device_serials_by_id
+                .get(&device_id)
+                .map(|serials| serials.contains(s))
+                .unwrap_or(false)
+            {
+                transport_names.push(format!("{}/{}", basic_transport_name, s))
+            }
+        }
+
+        println!(
+            "{}",
+            format!(
+                "ID {:04X}:{:04X}",
+                device_desc.vendor_id(),
+                device_desc.product_id()
+            )
+            .style(addr_style)
+        );
+        if !transport_names.is_empty() {
+            let style = if is_hci {
+                Style::new().cyan()
+            } else {
+                Style::new().red()
+            };
+            println!(
+                "{:26 }{}",
+                "  Bumble Transport Names:".blue(),
+                transport_names.iter().map(|n| n.style(style)).join(" or ")
+            )
+        }
+        println!(
+            "{:26 }{:03}/{:03}",
+            "  Bus/Device:".green(),
+            device.bus_number(),
+            device.address()
+        );
+        println!(
+            "{:26 }{}",
+            "  Class:".green(),
+            class_info.formatted_class_name()
+        );
+        println!(
+            "{:26 }{}",
+            "  Subclass/Protocol:".green(),
+            class_info.formatted_subclass_protocol()
+        );
+        if let Some(s) = serial {
+            println!("{:26 }{}", "  Serial:".green(), s);
+            device_serials_by_id
+                .entry(device_id)
+                .or_insert(HashSet::new())
+                .insert(s);
+        }
+        if let Some(m) = mfg {
+            println!("{:26 }{}", "  Manufacturer:".green(), m);
+        }
+        if let Some(p) = product {
+            println!("{:26 }{}", "  Product:".green(), p);
+        }
+
+        if cli.verbose {
+            print_device_details(&device, &device_desc)?;
+        }
+
+        println!();
+    }
+
+    Ok(())
+}
+
+fn is_bluetooth_hci<T: UsbContext>(
+    device: &Device<T>,
+    device_desc: &DeviceDescriptor,
+) -> rusb::Result<bool> {
+    if device_desc.class_code() == USB_DEVICE_CLASS_WIRELESS_CONTROLLER
+        && device_desc.sub_class_code() == USB_DEVICE_SUBCLASS_RF_CONTROLLER
+        && device_desc.protocol_code() == USB_DEVICE_PROTOCOL_BLUETOOTH_PRIMARY_CONTROLLER
+    {
+        Ok(true)
+    } else if device_desc.class_code() == USB_DEVICE_CLASS_DEVICE {
+        for i in 0..device_desc.num_configurations() {
+            for interface in device.config_descriptor(i)?.interfaces() {
+                for d in interface.descriptors() {
+                    if d.class_code() == USB_DEVICE_CLASS_WIRELESS_CONTROLLER
+                        && d.sub_class_code() == USB_DEVICE_SUBCLASS_RF_CONTROLLER
+                        && d.protocol_code() == USB_DEVICE_PROTOCOL_BLUETOOTH_PRIMARY_CONTROLLER
+                    {
+                        return Ok(true);
+                    }
+                }
+            }
+        }
+
+        Ok(false)
+    } else {
+        Ok(false)
+    }
+}
+
+fn print_device_details<T: UsbContext>(
+    device: &Device<T>,
+    device_desc: &DeviceDescriptor,
+) -> anyhow::Result<()> {
+    for i in 0..device_desc.num_configurations() {
+        println!("  Configuration {}", i + 1);
+        for interface in device.config_descriptor(i)?.interfaces() {
+            let descriptors: Vec<_> = interface.descriptors().collect();
+            for d in &descriptors {
+                let class_info =
+                    ClassInfo::new(d.class_code(), d.sub_class_code(), d.protocol_code());
+
+                println!(
+                    "      Interface: {}{} ({}, {})",
+                    interface.number(),
+                    if descriptors.len() > 1 {
+                        format!("/{}", d.setting_number())
+                    } else {
+                        String::new()
+                    },
+                    class_info.formatted_class_name(),
+                    class_info.formatted_subclass_protocol()
+                );
+
+                for e in d.endpoint_descriptors() {
+                    println!(
+                        "        Endpoint {:#04X}: {} {}",
+                        e.address(),
+                        match e.transfer_type() {
+                            TransferType::Control => "CONTROL",
+                            TransferType::Isochronous => "ISOCHRONOUS",
+                            TransferType::Bulk => "BULK",
+                            TransferType::Interrupt => "INTERRUPT",
+                        },
+                        match e.direction() {
+                            Direction::In => "IN",
+                            Direction::Out => "OUT",
+                        }
+                    )
+                }
+            }
+        }
+    }
+
+    Ok(())
+}
+
+struct ClassInfo {
+    class: u8,
+    sub_class: u8,
+    protocol: u8,
+}
+
+impl ClassInfo {
+    fn new(class: u8, sub_class: u8, protocol: u8) -> Self {
+        Self {
+            class,
+            sub_class,
+            protocol,
+        }
+    }
+
+    fn class_name(&self) -> Option<&str> {
+        match self.class {
+            0x00 => Some("Device"),
+            0x01 => Some("Audio"),
+            0x02 => Some("Communications and CDC Control"),
+            0x03 => Some("Human Interface Device"),
+            0x05 => Some("Physical"),
+            0x06 => Some("Still Imaging"),
+            0x07 => Some("Printer"),
+            0x08 => Some("Mass Storage"),
+            0x09 => Some("Hub"),
+            0x0A => Some("CDC Data"),
+            0x0B => Some("Smart Card"),
+            0x0D => Some("Content Security"),
+            0x0E => Some("Video"),
+            0x0F => Some("Personal Healthcare"),
+            0x10 => Some("Audio/Video"),
+            0x11 => Some("Billboard"),
+            0x12 => Some("USB Type-C Bridge"),
+            0x3C => Some("I3C"),
+            0xDC => Some("Diagnostic"),
+            USB_DEVICE_CLASS_WIRELESS_CONTROLLER => Some("Wireless Controller"),
+            0xEF => Some("Miscellaneous"),
+            0xFE => Some("Application Specific"),
+            0xFF => Some("Vendor Specific"),
+            _ => None,
+        }
+    }
+
+    fn protocol_name(&self) -> Option<&str> {
+        match self.class {
+            USB_DEVICE_CLASS_WIRELESS_CONTROLLER => match self.sub_class {
+                0x01 => match self.protocol {
+                    0x01 => Some("Bluetooth"),
+                    0x02 => Some("UWB"),
+                    0x03 => Some("Remote NDIS"),
+                    0x04 => Some("Bluetooth AMP"),
+                    _ => None,
+                },
+                _ => None,
+            },
+            _ => None,
+        }
+    }
+
+    fn formatted_class_name(&self) -> String {
+        self.class_name()
+            .map(|s| s.to_string())
+            .unwrap_or_else(|| format!("{:#04X}", self.class))
+    }
+
+    fn formatted_subclass_protocol(&self) -> String {
+        format!(
+            "{}/{}{}",
+            self.sub_class,
+            self.protocol,
+            self.protocol_name()
+                .map(|s| format!(" [{}]", s))
+                .unwrap_or_else(String::new)
+        )
+    }
+}
+
+impl From<&DeviceDescriptor> for ClassInfo {
+    fn from(value: &DeviceDescriptor) -> Self {
+        Self::new(
+            value.class_code(),
+            value.sub_class_code(),
+            value.protocol_code(),
+        )
+    }
+}
+
+#[derive(clap::Parser)]
+#[command(author, version, about, long_about = None)]
+struct Cli {
+    /// Show additional info for each USB device
+    #[arg(long, default_value_t = false)]
+    verbose: bool,
+}