This version of btleplug is being uploaded to crates to secure the module name in the packaging system. This version is functionally similar to rumble, and has all of the Linux and some basic Win10 support. However, it is still extremely experimental. We recommend waiting until 0.4.0 (hopefully out Late Jan-Early Feb 2020) to start actually using the library.
btleplug is a fork of the seemingly-abandoned rumble Rust BLE library. Our goal is the bring in some of the outstanding PRs from that project, expand the platform support to MacOS (Partial WinRT/UWP support is already in thanks to PRs in rumble), and possibly make the API surface more ergonomic for being a truly cross-platform library.
Oh and async might happen to because why not.
btleplug is meant to be host mode only. If you are interested in peripheral BTLE (i.e. acting like a Bluetooth LE device instead of connecting to one), check out bluster.
This library DOES NOT SUPPORT BLUETOOTH 2/CLASSIC. There are no plans to add BT2/Classic support.
At the moment, and probably for the foreseeable future, very little of what is included in BTLEPlug will be new or original code. The goal for the moment is to get a single library that works everywhere, then start bending the API surface around the different platform requirements once we can at least bring up adapters and start finding devices everywhere.
The libraries we're forking include:
In addition, here's the libraries we'll be referencing/cribbing from for updating APIs.
The issues in this repo reflect the development goals of the project. First and foremost is getting as many platforms as possible up and running enough to support our main usage of this library. For the time being we'll most likely keep the rumble API surface model, just so we don't have to change large portions of the code as we go.
Beyond that, some of our other goals are:
| Feature | Windows | MacOS | Linux | |---------|---------|-------|-------| | Bring Up Adapter |X||X| | Handle Multiple Adapters |||X| | Discover Devices |X||X| | └ Discover Services ||| O | | └ Discover Name |X||X| | └ Discover Manufacturer Data |X||X| | GATT Server Connect |X||X| | GATT Server Connect Event |X||X| | GATT Server Disconnect |X||X| | GATT Server Disconnect Event |X||X| | Write to Characteristic (Sync) |X||X| | Read from Characteristic (Async) |||X| | Write to Characteristic (Sync) |X||X| | Read from Characteristic (Async) |X||| | Subscribe to Characteristic (Sync) |X||X| | Subscribe to Characteristic (Async) |||| | Unsubscribe from Characteristic (Sync) |||| | Unsubscribe from Characteristic (Async) |||| | Get Characteristic Notification Event |X||X| | Read Descriptor |||| | Write Descriptor ||||
Rumble is a Bluetooth Low Energy (BLE) central module library for Rust. Currently only Linux (with the BlueZ bluetooth library) is supported, although other operating systems may be supported in the future. Rumble interfaces with BlueZ using its socket interface rather than DBus. This offers much more control and reliability over the DBus interface, and does not require running BlueZ in experimental mode for BLE.
As of version 0.2, the API is becoming more stable and the library itself more useful. You should still expect to encounter bugs, limitations, and odd behaviors. Pull requests (and wireshark traces) welcome!
An example of how to use the library to control some BLE smart lights:
```rust extern crate rumble; extern crate rand;
use std::thread; use std::time::Duration; use rand::{Rng, thread_rng}; use rumble::bluez::manager::Manager; use rumble::api::{UUID, Central, Peripheral};
pub fn main() { let manager = Manager::new().unwrap();
// get the first bluetooth adapter
let adapters = manager.adapters().unwrap();
let mut adapter = adapters.into_iter().nth(0).unwrap();
// reset the adapter -- clears out any errant state
adapter = manager.down(&adapter).unwrap();
adapter = manager.up(&adapter).unwrap();
// connect to the adapter
let central = adapter.connect().unwrap();
// start scanning for devices
central.start_scan().unwrap();
// instead of waiting, you can use central.on_event to be notified of
// new devices
thread::sleep(Duration::from_secs(2));
// find the device we're interested in
let light = central.peripherals().into_iter()
.find(|p| p.properties().local_name.iter()
.any(|name| name.contains("LEDBlue"))).unwrap();
// connect to the device
light.connect().unwrap();
// discover characteristics
light.discover_characteristics().unwrap();
// find the characteristic we want
let chars = light.characteristics();
let cmd_char = chars.iter().find(|c| c.uuid == UUID::B16(0xFFE9)).unwrap();
// dance party
let mut rng = thread_rng();
for _ in 0..20 {
let color_cmd = vec![0x56, rng.gen(), rng.gen(), rng.gen(), 0x00, 0xF0, 0xAA];
light.command(&cmd_char, &color_cmd).unwrap();
thread::sleep(Duration::from_millis(200));
}
} ```
BTLEPlug is covered under a BSD 3-Clause License, with some parts from Rumble/Blurmac covered under MIT/Apache dual license, and BSD 3-Clause licenses, respectively. See LICENSE.md for more info and copyright information.