#[derive(Debug, Clone, Default, PartialEq)]
pub struct Advertisement {
pub address: String,
pub random_address: bool,
pub rssi: i8,
pub local_name: Option<String>,
pub tx_power: Option<i8>,
pub appearance: Option<u16>,
pub service_uuids: Vec<String>,
pub manufacturer_data: Option<(u16, Vec<u8>)>,
pub service_data: Vec<(String, Vec<u8>)>,
pub connectable: bool,
pub raw: Vec<u8>,
}
#[cfg(target_os = "linux")]
use crate::sys::format_address;
#[cfg(not(target_os = "linux"))]
fn format_address(wire: &[u8; 6]) -> String {
let mut out = String::with_capacity(17);
for (i, b) in wire.iter().rev().enumerate() {
if i > 0 {
out.push(':');
}
out.push_str(&format!("{b:02X}"));
}
out
}
mod ad {
pub const FLAGS: u8 = 0x01;
pub const INCOMPLETE_16: u8 = 0x02;
pub const COMPLETE_16: u8 = 0x03;
pub const INCOMPLETE_32: u8 = 0x04;
pub const COMPLETE_32: u8 = 0x05;
pub const INCOMPLETE_128: u8 = 0x06;
pub const COMPLETE_128: u8 = 0x07;
pub const SHORTENED_NAME: u8 = 0x08;
pub const COMPLETE_NAME: u8 = 0x09;
pub const TX_POWER: u8 = 0x0A;
pub const APPEARANCE: u8 = 0x19;
pub const SERVICE_DATA_16: u8 = 0x16;
pub const SERVICE_DATA_32: u8 = 0x20;
pub const SERVICE_DATA_128: u8 = 0x21;
pub const MANUFACTURER_DATA: u8 = 0xFF;
}
fn canonical_16(value: u16) -> String {
format!("0000{value:04x}-0000-1000-8000-00805f9b34fb")
}
fn canonical_32(value: u32) -> String {
format!("{value:08x}-0000-1000-8000-00805f9b34fb")
}
fn canonical_128(wire: &[u8]) -> Option<String> {
if wire.len() != 16 {
return None;
}
let hex: String = wire.iter().rev().map(|b| format!("{b:02x}")).collect();
Some(format!(
"{}-{}-{}-{}-{}",
&hex[0..8],
&hex[8..12],
&hex[12..16],
&hex[16..20],
&hex[20..32]
))
}
pub fn parse_advertising_data(data: &[u8], into: &mut Advertisement) {
into.raw.extend_from_slice(data);
let mut i = 0;
while i < data.len() {
let length = data[i] as usize;
if length == 0 {
break;
}
if i + 1 + length > data.len() {
break;
}
let ad_type = data[i + 1];
let value = &data[i + 2..i + 1 + length];
match ad_type {
ad::FLAGS => {
if let Some(flags) = value.first() {
into.connectable = flags & 0x03 != 0;
}
}
ad::SHORTENED_NAME | ad::COMPLETE_NAME => {
if let Ok(name) = std::str::from_utf8(value) {
if ad_type == ad::COMPLETE_NAME || into.local_name.is_none() {
into.local_name = Some(name.to_owned());
}
}
}
ad::TX_POWER => into.tx_power = value.first().map(|b| *b as i8),
ad::INCOMPLETE_16 | ad::COMPLETE_16 => {
for pair in value.chunks_exact(2) {
into.service_uuids
.push(canonical_16(u16::from_le_bytes([pair[0], pair[1]])));
}
}
ad::INCOMPLETE_32 | ad::COMPLETE_32 => {
for quad in value.chunks_exact(4) {
into.service_uuids.push(canonical_32(u32::from_le_bytes([
quad[0], quad[1], quad[2], quad[3],
])));
}
}
ad::INCOMPLETE_128 | ad::COMPLETE_128 => {
for block in value.chunks_exact(16) {
if let Some(uuid) = canonical_128(block) {
into.service_uuids.push(uuid);
}
}
}
ad::APPEARANCE => {
if value.len() >= 2 {
into.appearance = Some(u16::from_le_bytes([value[0], value[1]]));
}
}
ad::MANUFACTURER_DATA => {
if value.len() >= 2 {
into.manufacturer_data = Some((
u16::from_le_bytes([value[0], value[1]]),
value[2..].to_vec(),
));
}
}
ad::SERVICE_DATA_16 => {
if value.len() >= 2 {
into.service_data.push((
canonical_16(u16::from_le_bytes([value[0], value[1]])),
value[2..].to_vec(),
));
}
}
ad::SERVICE_DATA_32 => {
if value.len() >= 4 {
into.service_data.push((
canonical_32(u32::from_le_bytes([value[0], value[1], value[2], value[3]])),
value[4..].to_vec(),
));
}
}
ad::SERVICE_DATA_128 => {
if value.len() >= 16 {
if let Some(uuid) = canonical_128(&value[..16]) {
into.service_data.push((uuid, value[16..].to_vec()));
}
}
}
_ => {}
}
i += 1 + length;
}
}
pub fn parse_advertising_report(body: &[u8]) -> Vec<Advertisement> {
let mut out = Vec::new();
let Some(&count) = body.first() else {
return out;
};
let mut i = 1;
for _ in 0..count {
if i + 9 > body.len() {
break;
}
let event_type = body[i];
let address_type = body[i + 1];
let mut wire = [0u8; 6];
wire.copy_from_slice(&body[i + 2..i + 8]);
let data_len = body[i + 8] as usize;
if i + 9 + data_len + 1 > body.len() {
break;
}
let data = &body[i + 9..i + 9 + data_len];
let rssi = body[i + 9 + data_len] as i8;
let mut advertisement = Advertisement {
address: format_address(&wire),
random_address: address_type == 0x01 || address_type == 0x03,
rssi,
connectable: event_type == 0x00 || event_type == 0x01,
..Default::default()
};
parse_advertising_data(data, &mut advertisement);
out.push(advertisement);
i += 9 + data_len + 1;
}
out
}
pub fn parse_extended_advertising_report(body: &[u8]) -> Vec<Advertisement> {
const FIXED: usize = 24;
let mut out = Vec::new();
let Some(&count) = body.first() else {
return out;
};
let mut i = 1;
for _ in 0..count {
if i + FIXED > body.len() {
break;
}
let event_type = u16::from_le_bytes([body[i], body[i + 1]]);
let address_type = body[i + 2];
let mut wire = [0u8; 6];
wire.copy_from_slice(&body[i + 3..i + 9]);
let tx_power = body[i + 12] as i8;
let rssi = body[i + 13] as i8;
let data_len = body[i + FIXED - 1] as usize;
if i + FIXED + data_len > body.len() {
break;
}
let data = &body[i + FIXED..i + FIXED + data_len];
let mut advertisement = Advertisement {
address: format_address(&wire),
random_address: address_type == 0x01 || address_type == 0x03,
rssi,
connectable: event_type & 0x0001 != 0,
..Default::default()
};
parse_advertising_data(data, &mut advertisement);
if tx_power != 127 && advertisement.tx_power.is_none() {
advertisement.tx_power = Some(tx_power);
}
out.push(advertisement);
i += FIXED + data_len;
}
out
}
#[cfg(target_os = "linux")]
mod socket {
use super::{parse_advertising_report, parse_extended_advertising_report, Advertisement};
use crate::sys::{
close, errno, read, socket, write, AF_BLUETOOTH, BTPROTO_HCI, EINTR, SOCK_RAW,
};
use std::ffi::{c_int, c_long, c_ulong};
use std::sync::atomic::{AtomicBool, Ordering};
use std::sync::Arc;
const HCI_CHANNEL_RAW: u16 = 0;
const SOL_HCI: c_int = 0;
const HCI_FILTER: c_int = 2;
const HCI_EVENT_PKT: u8 = 0x04;
const EVT_LE_META: u8 = 0x3E;
const SUBEVT_LE_ADVERTISING_REPORT: u8 = 0x02;
const SUBEVT_LE_EXTENDED_ADVERTISING_REPORT: u8 = 0x0D;
const OGF_LE_CTL: u16 = 0x08;
const OCF_LE_SET_SCAN_PARAMETERS: u16 = 0x000B;
const OCF_LE_SET_SCAN_ENABLE: u16 = 0x000C;
const SOL_SOCKET: c_int = 1;
const SO_RCVTIMEO: c_int = 20;
const EAGAIN: i32 = 11;
const POLL_INTERVAL_US: c_long = 100_000;
#[repr(C)]
struct Timeval {
tv_sec: c_long,
tv_usec: c_long,
}
use crate::sys::{bind, bluetooth_setsockopt};
unsafe extern "C" {
fn ioctl(fd: c_int, request: c_ulong, ...) -> c_int;
}
#[repr(C, packed)]
struct SockAddrHci {
family: u16,
dev: u16,
channel: u16,
}
#[repr(C)]
struct HciFilter {
type_mask: u32,
event_mask: [u32; 2],
opcode: u16,
}
pub struct HciSocket {
fd: c_int,
scanning: AtomicBool,
}
impl Drop for HciSocket {
fn drop(&mut self) {
if self.scanning.load(Ordering::Acquire) {
let _ = self.set_scan_enable(false);
}
unsafe { close(self.fd) };
}
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct DeviceInfo {
pub id: u16,
pub name: String,
pub address: String,
pub powered: bool,
}
const IOC_READ: u32 = 2;
const fn ior(kind: u8, number: u8, size: u32) -> u32 {
(IOC_READ << 30) | (size << 16) | ((kind as u32) << 8) | number as u32
}
const HCIGETDEVLIST: u32 = ior(b'H', 210, 4);
const HCIGETDEVINFO: u32 = ior(b'H', 211, 4);
const HCI_UP: u32 = 1 << 0;
const DEV_INFO_LEN: usize = 128;
const DEV_INFO_NAME: usize = 2;
const DEV_INFO_BDADDR: usize = 10;
const DEV_INFO_FLAGS: usize = 16;
pub fn devices() -> Result<Vec<DeviceInfo>, String> {
let fd = unsafe { socket(AF_BLUETOOTH, SOCK_RAW, BTPROTO_HCI) };
if fd < 0 {
return Err(format!(
"could not open an HCI control socket (errno {})",
errno()
));
}
struct Fd(c_int);
impl Drop for Fd {
fn drop(&mut self) {
unsafe { close(self.0) };
}
}
let fd = Fd(fd);
const MAX: u16 = 16;
const REQ: usize = 8;
let mut buffer = vec![0u8; 4 + REQ * MAX as usize];
buffer[0..2].copy_from_slice(&MAX.to_ne_bytes());
let rc = unsafe { ioctl(fd.0, HCIGETDEVLIST as _, buffer.as_mut_ptr()) };
if rc < 0 {
return Err(format!("HCIGETDEVLIST failed (errno {})", errno()));
}
let count = u16::from_ne_bytes([buffer[0], buffer[1]]).min(MAX);
let mut out = Vec::with_capacity(count as usize);
for i in 0..count as usize {
let at = 4 + i * REQ;
let id = u16::from_ne_bytes([buffer[at], buffer[at + 1]]);
if let Some(info) = device_info(fd.0, id) {
out.push(info);
}
}
out.sort_by_key(|d| d.id);
Ok(out)
}
fn device_info(fd: c_int, id: u16) -> Option<DeviceInfo> {
let mut buffer = vec![0u8; DEV_INFO_LEN];
buffer[0..2].copy_from_slice(&id.to_ne_bytes());
let rc = unsafe { ioctl(fd, HCIGETDEVINFO as _, buffer.as_mut_ptr()) };
if rc < 0 {
return None;
}
let name = &buffer[DEV_INFO_NAME..DEV_INFO_NAME + 8];
let name = name.iter().position(|b| *b == 0).unwrap_or(name.len());
let name =
String::from_utf8_lossy(&buffer[DEV_INFO_NAME..DEV_INFO_NAME + name]).into_owned();
let flags = u32::from_ne_bytes([
buffer[DEV_INFO_FLAGS],
buffer[DEV_INFO_FLAGS + 1],
buffer[DEV_INFO_FLAGS + 2],
buffer[DEV_INFO_FLAGS + 3],
]);
Some(DeviceInfo {
id,
name: if name.is_empty() {
format!("hci{id}")
} else {
name
},
address: format_address(&buffer[DEV_INFO_BDADDR..DEV_INFO_BDADDR + 6]),
powered: flags & HCI_UP != 0,
})
}
fn format_address(bytes: &[u8]) -> String {
bytes
.iter()
.rev()
.map(|b| format!("{b:02X}"))
.collect::<Vec<_>>()
.join(":")
}
impl HciSocket {
pub fn open(device: u16) -> Result<Self, String> {
let fd = unsafe { socket(AF_BLUETOOTH, SOCK_RAW, BTPROTO_HCI) };
if fd < 0 {
return Err(format!(
"could not open an HCI socket (errno {}); this needs CAP_NET_RAW",
errno()
));
}
let socket = Self {
fd,
scanning: AtomicBool::new(false),
};
let filter = HciFilter {
type_mask: 1 << HCI_EVENT_PKT,
event_mask: [0, 1 << (EVT_LE_META - 32)],
opcode: 0,
};
let rc = unsafe {
bluetooth_setsockopt(
fd,
SOL_HCI,
HCI_FILTER,
(&raw const filter).cast(),
std::mem::size_of::<HciFilter>() as u32,
)
};
if rc < 0 {
return Err(format!("could not set the HCI filter (errno {})", errno()));
}
let addr = SockAddrHci {
family: AF_BLUETOOTH as u16,
dev: device,
channel: HCI_CHANNEL_RAW,
};
let len = std::mem::size_of::<SockAddrHci>() as u32;
let rc = unsafe { bind(fd, (&raw const addr).cast(), len) };
if rc < 0 {
return Err(format!(
"could not bind hci{device} (errno {}); is the adapter present and up?",
errno()
));
}
Ok(socket)
}
fn command(&self, ogf: u16, ocf: u16, params: &[u8]) -> Result<(), String> {
let opcode = (ogf << 10) | ocf;
let mut packet = vec![0x01];
packet.extend_from_slice(&opcode.to_le_bytes());
packet.push(params.len() as u8);
packet.extend_from_slice(params);
let n = unsafe { write(self.fd, packet.as_ptr(), packet.len()) };
if n as usize != packet.len() {
return Err(format!(
"HCI command 0x{opcode:04x} failed (errno {})",
errno()
));
}
Ok(())
}
pub fn set_scan_parameters(&self) -> Result<(), String> {
self.command(
OGF_LE_CTL,
OCF_LE_SET_SCAN_PARAMETERS,
&[0x00, 0x10, 0x00, 0x10, 0x00, 0x00, 0x00],
)
}
pub fn set_scan_enable(&self, enable: bool) -> Result<(), String> {
self.command(
OGF_LE_CTL,
OCF_LE_SET_SCAN_ENABLE,
&[u8::from(enable), 0x00],
)?;
self.scanning.store(enable, Ordering::Release);
Ok(())
}
pub fn scan(
&self,
stop: Arc<AtomicBool>,
mut on_advertisement: impl FnMut(Advertisement),
) -> Result<(), String> {
let timeout = Timeval {
tv_sec: 0,
tv_usec: POLL_INTERVAL_US,
};
let rc = unsafe {
bluetooth_setsockopt(
self.fd,
SOL_SOCKET,
SO_RCVTIMEO,
(&raw const timeout).cast(),
std::mem::size_of::<Timeval>() as u32,
)
};
if rc < 0 {
return Err(format!(
"could not set the HCI receive timeout (errno {})",
errno()
));
}
self.set_scan_parameters()?;
self.set_scan_enable(true)?;
let mut buf = [0u8; 260];
while !stop.load(Ordering::Acquire) {
let n = unsafe { read(self.fd, buf.as_mut_ptr(), buf.len()) };
if n < 0 {
match errno() {
EINTR | EAGAIN => continue,
_ => break,
}
}
let packet = &buf[..n as usize];
if packet.len() < 4 || packet[0] != HCI_EVENT_PKT || packet[1] != EVT_LE_META {
continue;
}
let body = &packet[3..];
let advertisements = match body.first() {
Some(&SUBEVT_LE_ADVERTISING_REPORT) => parse_advertising_report(&body[1..]),
Some(&SUBEVT_LE_EXTENDED_ADVERTISING_REPORT) => {
parse_extended_advertising_report(&body[1..])
}
_ => continue,
};
for advertisement in advertisements {
on_advertisement(advertisement);
}
}
let _ = self.set_scan_enable(false);
Ok(())
}
}
}
#[cfg(target_os = "linux")]
pub use socket::{devices, DeviceInfo, HciSocket};
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn addresses_are_printed_in_written_order() {
assert_eq!(
format_address(&[0xFF, 0xEE, 0xDD, 0xCC, 0xBB, 0xAA]),
"AA:BB:CC:DD:EE:FF"
);
}
#[test]
fn advertising_data_records_parse() {
let data = [
0x02, 0x01, 0x06, 0x03, 0x03, 0x0D, 0x18, 0x09, 0x09, b'P', b'o', b'l', b'a', b'r', b' ', b'H', b'1', 0x02, 0x0A, 0xF4, ];
let mut advertisement = Advertisement::default();
parse_advertising_data(&data, &mut advertisement);
assert_eq!(advertisement.local_name.as_deref(), Some("Polar H1"));
assert_eq!(
advertisement.service_uuids,
vec!["0000180d-0000-1000-8000-00805f9b34fb"]
);
assert_eq!(advertisement.tx_power, Some(-12));
assert!(advertisement.connectable);
}
#[test]
fn a_complete_name_wins_over_a_shortened_one() {
let data = [
0x03, 0x08, b'P', b'o', 0x06, 0x09, b'P', b'o', b'l', b'a', b'r', ];
let mut a = Advertisement::default();
parse_advertising_data(&data, &mut a);
assert_eq!(a.local_name.as_deref(), Some("Polar"));
}
#[test]
fn manufacturer_and_service_data_split_their_identifiers() {
let data = [
0x05, 0xFF, 0x4C, 0x00, 0x02, 0x15, 0x05, 0x16, 0x0F, 0x18, 0x5B, 0x01, ];
let mut a = Advertisement::default();
parse_advertising_data(&data, &mut a);
assert_eq!(a.manufacturer_data, Some((0x004C, vec![0x02, 0x15])));
assert_eq!(a.service_data.len(), 1);
assert_eq!(a.service_data[0].0, "0000180f-0000-1000-8000-00805f9b34fb");
assert_eq!(a.service_data[0].1, vec![0x5B, 0x01]);
}
#[test]
fn a_128_bit_service_uuid_is_reversed() {
let mut data = vec![0x11, 0x07];
data.extend_from_slice(&[
0x9E, 0xCA, 0xDC, 0x24, 0x0E, 0xE5, 0xA9, 0xE0, 0x93, 0xF3, 0xA3, 0xB5, 0x01, 0x00,
0x40, 0x6E,
]);
let mut a = Advertisement::default();
parse_advertising_data(&data, &mut a);
assert_eq!(
a.service_uuids,
vec!["6e400001-b5a3-f393-e0a9-e50e24dcca9e"]
);
}
#[test]
fn a_zero_length_record_terminates_the_payload() {
let data = [0x02, 0x01, 0x06, 0x00, 0xFF, 0xFF, 0xFF];
let mut a = Advertisement::default();
parse_advertising_data(&data, &mut a);
assert!(
a.manufacturer_data.is_none(),
"padding was decoded as a record"
);
}
#[test]
fn a_record_longer_than_the_payload_is_dropped() {
let data = [0x20, 0x09, b'x'];
let mut a = Advertisement::default();
parse_advertising_data(&data, &mut a);
assert_eq!(a.local_name, None);
}
#[test]
fn an_advertising_report_decodes() {
let mut body = vec![
0x01, 0x00, 0x00, 0xFF, 0xEE, 0xDD, 0xCC, 0xBB, 0xAA, 0x05, 0x02, 0x01, 0x06, 0x00, 0x00,
];
body.push(0xC5); let reports = parse_advertising_report(&body);
assert_eq!(reports.len(), 1);
assert_eq!(reports[0].address, "AA:BB:CC:DD:EE:FF");
assert_eq!(reports[0].rssi, -59);
assert!(reports[0].connectable);
assert!(!reports[0].random_address);
}
#[test]
fn a_truncated_report_stops_rather_than_over_reading() {
let body = [0x02, 0x00, 0x00, 1, 2, 3, 4, 5, 6, 0x00, 0xC5];
let reports = parse_advertising_report(&body);
assert_eq!(reports.len(), 1);
assert!(parse_advertising_report(&[]).is_empty());
assert!(parse_advertising_report(&[0x01, 0x00]).is_empty());
}
#[test]
fn extended_advertising_reports_parse() {
let mut body = vec![0x01]; body.extend_from_slice(&0x0013u16.to_le_bytes()); body.push(0x00); body.extend_from_slice(&[0x01, 0x02, 0x03, 0x04, 0x05, 0x06]); body.push(0x01); body.push(0x01); body.push(0x00); body.push(0xF4u8); body.push(0xC0u8); body.extend_from_slice(&0u16.to_le_bytes()); body.push(0x00); body.extend_from_slice(&[0u8; 6]); let data = [
0x03, 0x03, 0x0D, 0x18, 0x06, 0x09, b'P', b'o', b'l', b'a', b'r', ];
body.push(data.len() as u8);
body.extend_from_slice(&data);
let reports = parse_extended_advertising_report(&body);
assert_eq!(reports.len(), 1);
let a = &reports[0];
assert_eq!(a.address, "06:05:04:03:02:01");
assert_eq!(a.rssi, -64);
assert_eq!(a.tx_power, Some(-12));
assert!(a.connectable);
assert_eq!(a.local_name.as_deref(), Some("Polar"));
assert_eq!(
a.service_uuids,
vec!["0000180d-0000-1000-8000-00805f9b34fb"]
);
}
#[test]
fn a_truncated_extended_report_is_dropped_not_guessed() {
assert!(parse_extended_advertising_report(&[0x01, 0x13, 0x00, 0x00]).is_empty());
assert!(parse_extended_advertising_report(&[]).is_empty());
}
#[test]
fn a_non_connectable_extended_report_says_so() {
let mut body = vec![0x01];
body.extend_from_slice(&0x0012u16.to_le_bytes()); body.push(0x01); body.extend_from_slice(&[0u8; 6]);
body.extend_from_slice(&[0x01, 0x01, 0x00, 127, 0xC0]);
body.extend_from_slice(&0u16.to_le_bytes());
body.push(0x00);
body.extend_from_slice(&[0u8; 6]);
body.push(0);
let reports = parse_extended_advertising_report(&body);
assert_eq!(reports.len(), 1);
assert!(!reports[0].connectable);
assert!(reports[0].random_address);
assert_eq!(reports[0].tx_power, None);
}
}