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 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502
// btleplug Source Code File // // Copyright 2020 Nonpolynomial Labs LLC. All rights reserved. // // Licensed under the BSD 3-Clause license. See LICENSE file in the project root // for full license information. // // Some portions of this file are taken and/or modified from Rumble // (https://github.com/mwylde/rumble), using a dual MIT/Apache License under the // following copyright: // // Copyright (c) 2014 The Rust Project Developers mod adapter_manager; pub use adapter_manager::AdapterManager; use crate::{ api::UUID::{B128, B16}, Result, }; #[cfg(feature = "serde")] use serde::{Deserialize, Serialize}; use std::sync::mpsc::Receiver; use std::{ collections::BTreeSet, convert::TryFrom, fmt::{self, Debug, Display, Formatter}, str::FromStr, }; #[cfg_attr(feature = "serde", derive(Serialize, Deserialize))] #[derive(Debug, Clone, Eq, PartialEq)] pub enum AddressType { Random, Public, } impl Default for AddressType { fn default() -> Self { AddressType::Public } } impl AddressType { pub fn from_u8(v: u8) -> Option<AddressType> { match v { 1 => Some(AddressType::Public), 2 => Some(AddressType::Random), _ => None, } } pub fn num(&self) -> u8 { match *self { AddressType::Public => 1, AddressType::Random => 2, } } } /// Stores the 6 byte address used to identify Bluetooth devices. #[cfg_attr(feature = "serde", derive(Serialize, Deserialize))] #[derive(Copy, Clone, Hash, Eq, PartialEq, Default)] #[repr(C)] pub struct BDAddr { pub address: [u8; 6usize], } impl Display for BDAddr { fn fmt(&self, f: &mut Formatter) -> fmt::Result { let a = self.address; write!( f, "{:02X}:{:02X}:{:02X}:{:02X}:{:02X}:{:02X}", a[5], a[4], a[3], a[2], a[1], a[0] ) } } impl Debug for BDAddr { fn fmt(&self, f: &mut Formatter) -> fmt::Result { (self as &dyn Display).fmt(f) } } type ParseBDAddrResult<T> = std::result::Result<T, ParseBDAddrError>; #[derive(Debug, Fail, Clone, PartialEq)] pub enum ParseBDAddrError { #[fail(display = "Bluetooth address has to be 6 bytes long")] IncorrectByteCount, #[fail(display = "Malformed integer in Bluetooth address")] InvalidInt, } impl FromStr for BDAddr { type Err = ParseBDAddrError; fn from_str(s: &str) -> ParseBDAddrResult<Self> { let bytes = s .split(':') .map(|part: &str| { u8::from_str_radix(part, 16).map_err(|_| ParseBDAddrError::InvalidInt) }) .collect::<ParseBDAddrResult<Vec<u8>>>()?; if let Ok(mut address) = <[u8; 6]>::try_from(bytes.as_slice()) { address.reverse(); Ok(BDAddr { address }) } else { Err(ParseBDAddrError::IncorrectByteCount) } } } /// A notification sent from a peripheral due to a change in a value. #[derive(Clone, Debug, Eq, PartialEq)] pub struct ValueNotification { /// UUID of the characteristic that fired the notification. pub uuid: UUID, /// The handle that has changed. Only valid on Linux, will be None on all /// other platforms. pub handle: Option<u16>, /// The new value of the handle. pub value: Vec<u8>, } pub type Callback<T> = Box<dyn Fn(Result<T>) + Send>; pub type CommandCallback = Callback<()>; pub type RequestCallback = Callback<Vec<u8>>; pub type NotificationHandler = Box<dyn FnMut(ValueNotification) + Send>; /// A Bluetooth UUID. These can either be 2 bytes or 16 bytes long. UUIDs uniquely identify various /// objects in the Bluetooth universe. #[cfg_attr(feature = "serde", derive(Serialize, Deserialize))] #[derive(Ord, PartialOrd, Eq, PartialEq, Copy, Clone, Hash)] pub enum UUID { B16(u16), B128([u8; 16]), } impl UUID { pub fn size(&self) -> usize { match *self { B16(_) => 2, B128(_) => 16, } } } impl Display for UUID { fn fmt(&self, f: &mut Formatter) -> fmt::Result { match *self { B16(u) => write!(f, "{:02X}:{:02X}", u >> 8, u & 0xFF), B128(a) => { for i in (1..a.len()).rev() { write!(f, "{:02X}:", a[i])?; } write!(f, "{:02X}", a[0]) } } } } impl Debug for UUID { fn fmt(&self, f: &mut Formatter) -> fmt::Result { (self as &dyn Display).fmt(f) } } type ParseUUIDResult<T> = std::result::Result<T, ParseUUIDError>; #[derive(Debug, Fail, Clone, PartialEq)] pub enum ParseUUIDError { #[fail(display = "UUID has to be either 2 or 16 bytes long")] IncorrectByteCount, #[fail(display = "Malformed integer in UUID")] InvalidInt, } impl FromStr for UUID { type Err = ParseUUIDError; fn from_str(s: &str) -> ParseUUIDResult<Self> { let bytes = s .chars() .filter(|ch| ch.is_ascii_alphanumeric()) .collect::<Vec<char>>() .chunks(2) .map(|chunk| { u8::from_str_radix(chunk.iter().collect::<String>().as_str(), 16) .map_err(|_| ParseUUIDError::InvalidInt) }) .collect::<ParseUUIDResult<Vec<u8>>>()?; if let Ok(bytes) = <[u8; 2]>::try_from(bytes.as_slice()) { Ok(UUID::B16(u16::from_be_bytes(bytes))) } else if let Ok(mut bytes) = <[u8; 16]>::try_from(bytes.as_slice()) { bytes.reverse(); Ok(UUID::B128(bytes)) } else { Err(ParseUUIDError::IncorrectByteCount) } } } bitflags! { /// A set of properties that indicate what operations are supported by a Characteristic. pub struct CharPropFlags: u8 { const BROADCAST = 0x01; const READ = 0x02; const WRITE_WITHOUT_RESPONSE = 0x04; const WRITE = 0x08; const NOTIFY = 0x10; const INDICATE = 0x20; const AUTHENTICATED_SIGNED_WRITES = 0x40; const EXTENDED_PROPERTIES = 0x80; } } impl CharPropFlags { pub fn new() -> Self { Self { bits: 0 } } } /// A Bluetooth characteristic. Characteristics are the main way you will interact with other /// bluetooth devices. Characteristics are identified by a UUID which may be standardized /// (like 0x2803, which identifies a characteristic for reading heart rate measurements) but more /// often are specific to a particular device. The standard set of characteristics can be found /// [here](https://www.bluetooth.com/specifications/gatt/characteristics). /// /// A characteristic may be interacted with in various ways depending on its properties. You may be /// able to write to it, read from it, set its notify or indicate status, or send a command to it. #[derive(Debug, Ord, PartialOrd, Eq, PartialEq, Clone)] pub struct Characteristic { /// The start of the handle range that contains this characteristic. Only /// valid on Linux, will be 0 on all other platforms. pub start_handle: u16, /// The end of the handle range that contains this characteristic. Only /// valid on Linux, will be 0 on all other platforms. pub end_handle: u16, /// The value handle of the characteristic. Only /// valid on Linux, will be 0 on all other platforms. pub value_handle: u16, /// The UUID for this characteristic. This uniquely identifies its behavior. pub uuid: UUID, /// The set of properties for this characteristic, which indicate what functionality it /// supports. If you attempt an operation that is not supported by the characteristics (for /// example setting notify on one without the NOTIFY flag), that operation will fail. pub properties: CharPropFlags, } impl Display for Characteristic { fn fmt(&self, f: &mut Formatter) -> fmt::Result { write!( f, "uuid: {:?}, char properties: {:?}", self.properties, self.uuid ) } } /// The properties of this peripheral, as determined by the advertising reports we've received for /// it. #[derive(Debug, Default, Clone)] pub struct PeripheralProperties { /// The address of this peripheral pub address: BDAddr, /// The type of address (either random or public) pub address_type: AddressType, /// The local name. This is generally a human-readable string that identifies the type of device. pub local_name: Option<String>, /// The transmission power level for the device pub tx_power_level: Option<i8>, /// Unstructured data set by the device manufacturer pub manufacturer_data: Option<Vec<u8>>, /// Number of times we've seen advertising reports for this device pub discovery_count: u32, /// True if we've discovered the device before pub has_scan_response: bool, } /// Peripheral is the device that you would like to communicate with (the "server" of BLE). This /// struct contains both the current state of the device (its properties, characteristics, etc.) /// as well as functions for communication. pub trait Peripheral: Send + Sync + Clone + Debug { /// Returns the address of the peripheral. fn address(&self) -> BDAddr; /// Returns the set of properties associated with the peripheral. These may be updated over time /// as additional advertising reports are received. fn properties(&self) -> PeripheralProperties; /// The set of characteristics we've discovered for this device. This will be empty until /// `discover_characteristics` or `discover_characteristics_in_range` is called. fn characteristics(&self) -> BTreeSet<Characteristic>; /// Returns true iff we are currently connected to the device. fn is_connected(&self) -> bool; /// Creates a connection to the device. This is a synchronous operation; if this method returns /// Ok there has been successful connection. Note that peripherals allow only one connection at /// a time. Operations that attempt to communicate with a device will fail until it is connected. fn connect(&self) -> Result<()>; /// Terminates a connection to the device. This is a synchronous operation. fn disconnect(&self) -> Result<()>; /// Discovers all characteristics for the device. This is a synchronous operation. fn discover_characteristics(&self) -> Result<Vec<Characteristic>>; /// Discovers characteristics within the specified range of handles. This is a synchronous /// operation. fn discover_characteristics_in_range( &self, start: u16, end: u16, ) -> Result<Vec<Characteristic>>; /// Sends a command (`write-without-response`) to the characteristic. Takes an optional callback /// that will be notified in case of error or when the command has been successfully acked by the /// device. fn command_async( &self, characteristic: &Characteristic, data: &[u8], handler: Option<CommandCallback>, ); /// Sends a command (write without response) to the characteristic. Synchronously returns a /// `Result` with an error set if the command was not accepted by the device. fn command(&self, characteristic: &Characteristic, data: &[u8]) -> Result<()>; /// Sends a request (write) to the device. Takes an optional callback with either an error if /// the request was not accepted or the response from the device. fn request_async( &self, characteristic: &Characteristic, data: &[u8], handler: Option<RequestCallback>, ); /// Sends a request (write) to the device. Synchronously returns either an error if the request /// was not accepted or the response from the device. fn request(&self, characteristic: &Characteristic, data: &[u8]) -> Result<Vec<u8>>; /// Sends a request (read) to the device. Takes an optional callback with either an error if /// the request was not accepted or the response from the device. fn read_async(&self, characteristic: &Characteristic, handler: Option<RequestCallback>); /// Sends a request (read) to the device. Synchronously returns either an error if the request /// was not accepted or the response from the device. fn read(&self, characteristic: &Characteristic) -> Result<Vec<u8>>; /// Sends a read-by-type request to device for the range of handles covered by the /// characteristic and for the specified declaration UUID. See /// [here](https://www.bluetooth.com/specifications/gatt/declarations) for valid UUIDs. /// Takes an optional callback that will be called with an error or the device response. fn read_by_type_async( &self, characteristic: &Characteristic, uuid: UUID, handler: Option<RequestCallback>, ); /// Sends a read-by-type request to device for the range of handles covered by the /// characteristic and for the specified declaration UUID. See /// [here](https://www.bluetooth.com/specifications/gatt/declarations) for valid UUIDs. /// Synchronously returns either an error or the device response. fn read_by_type(&self, characteristic: &Characteristic, uuid: UUID) -> Result<Vec<u8>>; /// Enables either notify or indicate (depending on support) for the specified characteristic. /// This is a synchronous call. fn subscribe(&self, characteristic: &Characteristic) -> Result<()>; /// Disables either notify or indicate (depending on support) for the specified characteristic. /// This is a synchronous call. fn unsubscribe(&self, characteristic: &Characteristic) -> Result<()>; /// Registers a handler that will be called when value notification messages are received from /// the device. This method should only be used after a connection has been established. Note /// that the handler will be called in a common thread, so it should not block. fn on_notification(&self, handler: NotificationHandler); } #[cfg_attr(feature = "serde", derive(Serialize, Deserialize))] #[derive(Debug, Copy, Clone)] pub enum CentralEvent { DeviceDiscovered(BDAddr), DeviceLost(BDAddr), DeviceUpdated(BDAddr), DeviceConnected(BDAddr), DeviceDisconnected(BDAddr), } /// Central is the "client" of BLE. It's able to scan for and establish connections to peripherals. pub trait Central<P: Peripheral>: Send + Sync + Clone { /// Retreive the Event [Receiver] for the event channel. This channel /// receiver will receive notifications when events occur for this Central /// module. As this uses an std::channel which cannot be cloned, after the /// first call (which will contain Some<Receiver<CentralEvent>>), all /// subsequent calls will return None. See [`Event`](enum.CentralEvent.html) /// for the full set of events returned. fn event_receiver(&self) -> Option<Receiver<CentralEvent>>; /// Starts a scan for BLE devices. This scan will generally continue until explicitly stopped, /// although this may depend on your bluetooth adapter. Discovered devices will be announced /// to subscribers of `on_event` and will be available via `peripherals()`. fn start_scan(&self) -> Result<()>; /// Control whether to use active or passive scan mode to find BLE devices. Active mode scan /// notifies advertises about the scan, whereas passive scan only receives data from the /// advertiser. Defaults to use active mode. fn active(&self, enabled: bool); /// Control whether to filter multiple advertisements by the same peer device. Receving /// can be useful for some applications. E.g. when using scan to collect information from /// beacons that update data frequently. Defaults to filter duplicate advertisements. fn filter_duplicates(&self, enabled: bool); /// Stops scanning for BLE devices. fn stop_scan(&self) -> Result<()>; /// Returns the list of [`Peripherals`](trait.Peripheral.html) that have been discovered so far. /// Note that this list may contain peripherals that are no longer available. fn peripherals(&self) -> Vec<P>; /// Returns a particular [`Peripheral`](trait.Peripheral.html) by its address if it has been /// discovered. fn peripheral(&self, address: BDAddr) -> Option<P>; } #[cfg(test)] mod tests { use super::*; #[test] fn parse_uuid() { let values = vec![ ("2A:00", Ok(UUID::B16(0x2A00))), ( "00:00:15:32:12:12:EF:DE:15:23:78:5F:EA:BC:D1:23", Ok(UUID::B128([ 0x23, 0xD1, 0xBC, 0xEA, 0x5F, 0x78, 0x23, 0x15, 0xDE, 0xEF, 0x12, 0x12, 0x32, 0x15, 0x00, 0x00, ])), ), ("2A:00:00", Err(ParseUUIDError::IncorrectByteCount)), ("2A:100", Err(ParseUUIDError::IncorrectByteCount)), ("ZZ:00", Err(ParseUUIDError::InvalidInt)), ]; for (input, expected) in values { let result: ParseUUIDResult<UUID> = input.parse(); assert_eq!(result, expected); if let Ok(uuid) = result { assert_eq!(input, uuid.to_string()); } } let expected_uuid = Ok(UUID::B128([ 0x8a, 0xf7, 0x15, 0x02, 0x9c, 0x00, 0x49, 0x8a, 0x24, 0x10, 0x8a, 0x33, 0x02, 0x00, 0xfa, 0x99, ])); let result: ParseUUIDResult<UUID> = "99:fa:00:02:33:8a:10:24:8a:49:00:9c:02:15:f7:8a".parse(); assert_eq!(result, expected_uuid); let result: ParseUUIDResult<UUID> = "99fa0002-338a-1024-8a49-009c0215f78a".parse(); assert_eq!(result, expected_uuid); let result: ParseUUIDResult<UUID> = "99fa0002338a10248a49009c0215f78a".parse(); assert_eq!(result, expected_uuid); } #[test] fn parse_addr() { let values = vec![ ( "2A:00:AA:BB:CC:DD", Ok(BDAddr { address: [0xDD, 0xCC, 0xBB, 0xAA, 0x00, 0x2A], }), ), ("2A:00:00", Err(ParseBDAddrError::IncorrectByteCount)), ("2A:00:AA:BB:CC:ZZ", Err(ParseBDAddrError::InvalidInt)), ]; for (input, expected) in values { let result: ParseBDAddrResult<BDAddr> = input.parse(); assert_eq!(result, expected); if let Ok(uuid) = result { assert_eq!(input, uuid.to_string()); } } } }