{"id":19361577,"url":"https://github.com/mxk/burble","last_synced_at":"2025-04-23T12:32:38.869Z","repository":{"id":142265784,"uuid":"543603615","full_name":"mxk/burble","owner":"mxk","description":"Blackrock User-Mode Bluetooth LE Library","archived":false,"fork":false,"pushed_at":"2023-06-02T18:51:29.000Z","size":947,"stargazers_count":29,"open_issues_count":10,"forks_count":2,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-04-13T03:49:39.985Z","etag":null,"topics":["ble","bluetooth","bluetooth-low-energy","libusb","rust"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mxk.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2022-09-30T13:03:19.000Z","updated_at":"2025-03-14T22:52:21.000Z","dependencies_parsed_at":null,"dependency_job_id":"bd1742fb-c7a9-47c4-9f82-c7bd9e1d1770","html_url":"https://github.com/mxk/burble","commit_stats":null,"previous_names":["blackrockneurotech/burble"],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mxk%2Fburble","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mxk%2Fburble/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mxk%2Fburble/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mxk%2Fburble/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mxk","download_url":"https://codeload.github.com/mxk/burble/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250435148,"owners_count":21430226,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ble","bluetooth","bluetooth-low-energy","libusb","rust"],"created_at":"2024-11-10T07:23:59.100Z","updated_at":"2025-04-23T12:32:35.679Z","avatar_url":"https://github.com/mxk.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"Blackrock User-Mode Bluetooth LE Library\n========================================\n\n[![crates.io](https://img.shields.io/crates/v/burble?style=for-the-badge)](https://crates.io/crates/burble)\n[![docs.rs](https://img.shields.io/badge/docs.rs-burble-66c2a5?style=for-the-badge\u0026logo=docs.rs)](https://docs.rs/burble)\n[![License](https://img.shields.io/crates/l/burble?style=for-the-badge)](https://choosealicense.com/licenses/mpl-2.0/)\n\nA cross-platform user-mode BLE stack implementation starting from the USB transport layer via [libusb].\n\n[libusb]: https://github.com/libusb/libusb\n\n**Project status:** Under active development. Tested on Linux, macOS, and Windows. Not accepting external contributions at this time. The library implements all components for a BLE GATT server (peripheral role) and LE Secure Connections pairing. Minimum supported Bluetooth version is 5.0. All APIs are subject to change prior to v1.0.\n\nBurble exposes the full functionality of a BLE controller, so some familiarity with the Bluetooth Core Specification and other relevant documents is expected.\n\nReference documents:\n\n* [Bluetooth Core Specification v5.4][Core] (LE Core Configuration as defined in [Vol 0] Part B, Section 4.4)\n* [Core Specification Supplement v11][CSS]\n* [Assigned Numbers][AN]\n* [GATT Specification Supplement][GSS]\n\n[Core]: https://www.bluetooth.com/specifications/specs/core-specification-5-4/\n[CSS]: https://www.bluetooth.com/specifications/specs/core-specification-supplement-11/\n[AN]: https://www.bluetooth.com/specifications/specs/assigned-numbers/\n[GSS]: https://www.bluetooth.com/specifications/specs/gatt-specification-supplement/\n\nProfiles and services:\n\n* [Battery Service][BAS]\n* [Device Information Service][DIS]\n* [HID over GATT Profile][HOGP]\n\n[BAS]: https://www.bluetooth.com/specifications/specs/battery-service/\n[DIS]: https://www.bluetooth.com/specifications/specs/device-information-service-1-1/\n[HOGP]: https://www.bluetooth.com/specifications/specs/hid-over-gatt-profile-1-0/\n\nGetting Started\n---------------\n\nThe [server] example brings up a demo GATT server to test controller functionality. See OS-specific sections below for instructions on allowing `libusb` to access the controllers from user-space.\n\n[server]: https://github.com/BlackrockNeurotech/burble/blob/main/examples/server.rs\n\n### Listing available Bluetooth controllers\n\n```text\n$ cargo run --example server\nAvailable controllers (pass 'ID \u003cVID\u003e:\u003cPID\u003e' to '--vid' and '--pid' options):\nBus 002 Device 012: ID 7392:c611\nBus 002 Device 003: ID 8087:0033\n```\n\n### Running the server\n\nStart the server and look for \"Burble\" Bluetooth device on the client. You can use [nRF Connect for Mobile][nRF] to get more details about the server advertisements and GATT services.\n\nSome clients may not support extended LE advertising. Use the `--legacy` option to switch to legacy advertising PDUs.\n\n[nRF]: https://play.google.com/store/apps/details?id=no.nordicsemi.android.mcp\n\n```text\n$ RUST_LOG=debug cargo run --example server -- --vid 7392 --pid c611\n INFO burble::host::usb::libusb: libusb version: 1.0.26.11724\nDEBUG burble::host::usb::libusb: - LIBUSB_CAP_HAS_CAPABILITY = true\nDEBUG burble::host::usb::libusb: - LIBUSB_CAP_HAS_HOTPLUG = false\nDEBUG burble::host::usb::libusb: - LIBUSB_CAP_SUPPORTS_DETACH_KERNEL_DRIVER = false\n INFO burble::host::usb::libusb: Using WinUSB backend\n INFO burble::host::usb: Opening device ID 7392:C611\nDEBUG burble::host::usb: Event thread started\n INFO burble::host::usb::libusb: Resetting Bus 002 Device 012: ID 7392:c611\nDEBUG burble::host::usb: Bluetooth device at Bus 002 Device 012: ID 7392:c611\nDEBUG burble::host::usb: Claiming main interface\nDEBUG burble::host::usb: Claiming isochronous interface\nDEBUG burble::host::usb: Setting isochronous interface alt setting to 0\nDEBUG burble::hci: Event loop started\nDEBUG burble::hci: HCI reset...\nDEBUG burble::hci: Controller version: LocalVersion { hci_version: v5.1, hci_subversion: 11, lmp_version: v5.1, company_id: CompanyId(0x005D =\u003e \"Realtek Semiconductor Corporation\"), lmp_subversion: 34657 }\nDEBUG burble::hci: Controller LMP features: LmpFeature(LE_SUPPORTED | EXTENDED_FEATURES | 0x77bfd9bfeffffff)\nDEBUG burble::hci: Controller LE features: LeFeature(ENCRYPTION | EXTENDED_REJECT_INDICATION | PERIPHERAL_INITIATED_FEATURES_EXCHANGE | PING | DATA_PACKET_LENGTH_EXTENSION | LL_PRIVACY | EXTENDED_SCANNING_FILTER_POLICIES | LE_2M_PHY | STABLE_MODULATION_INDEX_TRANSMITTER | STABLE_MODULATION_INDEX_RECEIVER | LE_CODED_PHY | EXTENDED_ADVERTISING | CHANNEL_SELECTION_ALGORITHM_2 | CONNECTION_CTE_REQUEST | CONNECTION_CTE_RESPONSE | ANTENNA_SWITCHING_DURING_CTE_TRANSMISSION | ANTENNA_SWITCHING_DURING_CTE_RECEPTION)\nDEBUG burble::hci: Controller LE states: 0b111111111111111111111111111111111111111111\nDEBUG burble::hci: Controller LE buffers: LeBufferSize { acl_data_len: 251, acl_num_pkts: 8, iso_data_len: 0, iso_num_pkts: 0 }\nDEBUG burble::hci: Controller address: Public(08:BE:AC:2E:0D:EE)\nDEBUG burble::gatt::db: GATT database:\nDEBUG burble::gatt::db: [0x0001] Service(GenericAttribute) \u003c0x1801\u003e\nDEBUG burble::gatt::db: [0x0002] |__ Characteristic(ServiceChanged) \u003c0x2A05\u003e\nDEBUG burble::gatt::db: [0x0003] |   |__ [Value \u003c0x2A05\u003e]\nDEBUG burble::gatt::db: [0x0004] |   |__ Descriptor(ClientCharacteristicConfiguration) \u003c0x2902\u003e\n...\n INFO server: Enabling advertisements\n```\n\nLinux\n-----\n\nBurble requires read/write access to the USB device node, which is normally restricted to root. On systems with [udev], the following rules file can be used to provide access to the logged-in user (adjust the example as needed to restrict access, and set `vendor_id` and `product_id`):\n\n```text\n/etc/udev/rules.d/99-burble.rules:\n\nSUBSYSTEMS==\"usb\", ATTRS{idVendor}==\"vendor_id\", ATTRS{idProduct}==\"product_id\", MODE=\"0660\", TAG+=\"uaccess\"\n```\n\nUse `sudo udevadm control --reload-rules \u0026\u0026 sudo udevadm trigger` to apply the permissions.\n\n[udev]: https://wiki.archlinux.org/title/udev\n\nWindows\n-------\n\nEither use [Zadig] to install the [libusbK] driver for a specific Bluetooth device (recommended), or install [UsbDk], which has some known issues, but doesn't require changing device drivers. See [libusb Windows wiki page][libusb-Windows] for more info.\n\n[Zadig]: https://zadig.akeo.ie/\n[libusbK]: https://github.com/mcuee/libusbk\n[UsbDk]: https://github.com/daynix/UsbDk/releases\n[libusb-Windows]: https://github.com/libusb/libusb/wiki/Windows#driver-installation\n\n### Using Zadig\n\n1. Run Zadig and enable Options → List All Devices.\n2. Select the target controller.\n3. Install either [libusbK] or [WinUSB] driver. The former is recommended because it can reset the USB device. Each driver has some known issues, so if you're having problems with one, try the other.\n\n[WinUSB]: https://learn.microsoft.com/en-us/windows-hardware/drivers/usbcon/winusb-installation\n\n### UsbDk Known Issues\n\nUnfortunately, UsbDk appears to be unmaintained, so its use is discouraged.\n\n#### Hanging libusb_open\n\nIf a redirected device is not closed on exit (e.g. after a crash), subsequent attempts to open it may cause the process to hang for about two minutes, followed by a \"Redirector startup failed\" libusb error message. See [daynix/UsbDk#105].\n\n[daynix/UsbDk#105]: https://github.com/daynix/UsbDk/issues/105\n\n#### WDF_VIOLATION BSOD\n\nA `WDF_VIOLATION` [BSOD] may be caused by having multiple [multiple power policy owners] enabled for the Bluetooth USB device. There are two workarounds:\n\n1. Disable the device in the Device Manager.\n2. Uncheck the option to \"Allow the computer to turn off this device to save power\" in Device Properties -\u003e Power Management tab.\n\n[BSOD]: https://github.com/daynix/UsbDk/issues/115\n[multiple power policy owners]: https://sourceforge.net/p/libusb-win32/mailman/message/25823294/\n\nFAQ\n---\n\n### What are the goals of this project?\n\nBurble aims to become a feature-complete Bluetooth LE library, implementing HCI, L2CAP, GAP, ATT, GATT, and SMP layers for both the Central and Peripheral roles.\n\n### How is this different from other Bluetooth libraries?\n\nMost libraries use OS-specific APIs and drivers to access the controller. Burble communicates with the controller directly over USB (or another transport), bypassing all OS-specific functionality.\n\n### What are the downsides to this approach?\n\nBurble requires exclusive access to the controller. The OS and other applications cannot use the controller at the same time. On Windows, this means installing a libusb-compatible driver which prevents the OS from identifying the controller as a Bluetooth device. On Linux and macOS, the driver is automatically detached while Burble is using the controller.\n\nAnother potential downside is loss of vendor-specific functionality. Though this can be added for individual controllers, Burble focuses on implementing the Core Bluetooth Specification that is common to all controllers.\n\n### What are the advantages?\n\nBurble supports all major operating systems and can take advantage of the features introduced in the most recent versions of the Bluetooth Core Specification (subject to controller support). Having exclusive controller access allows complete control over all aspects of the controller operation, such as advertising, scanning, and GATT services. This is particularly useful for implementing the peripheral role when you need specific configuration for GAP and GATT services.\n\n### What is Burble's approach to security?\n\nBurble places heavy emphasis on security and correctness. Legacy features that can lead to insecure operation are simply not implemented (e.g. LE legacy pairing, \u003c 128-bit encryption keys). All cryptographic primitives used by the Security Manager are implemented in a [separate package][crypto] that forbids unsafe code to facilitate auditing.\n\n[crypto]: https://github.com/BlackrockNeurotech/burble/tree/main/crypto\n\n### Can Burble be used in embedded (`no_std`) systems?\n\nCurrently, no, but this is an eventual goal. A few components, like the libusb event thread, currently require `std`. These will be put behind feature flags or redesigned to allow Burble core to function on any system that can implement the `host::Transport` trait.\n\nTested Controllers\n------------------\n\nBelow is a list of Bluetooth controllers that have been tested with this library.\n\n### Server\n\n| Device         | VID:PID   | BLE Version |    Chip    | ACL Buffers |\n|----------------|-----------|:-----------:|:----------:|:-----------:|\n| Edimax BT-8500 | 7392:C611 |     5.1     | RTL8761BUV |  8 * 251B   |\n| Intel AX210    | 8087:0032 |     5.3     |     -      |  3 * 251B   |\n| Intel AX211    | 8087:0033 |     5.3     |     -      |  3 * 251B   |\n\n### Client\n\n| Device         | VID:PID   | BLE Version |    Chip    |\n|----------------|-----------|:-----------:|:----------:|\n| Edimax BT-8500 | 7392:C611 |     5.1     | RTL8761BUV |\n| Intel AX210    | 8087:0032 |     5.3     |     -      |\n| Intel AX211    | 8087:0033 |     5.3     |     -      |\n\nLegal\n-----\n\nCopyright 2023 Blackrock Neurotech. Licensed under the Mozilla Public License 2.0.\n\n**This is not an officially supported Blackrock Neurotech product.**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmxk%2Fburble","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmxk%2Fburble","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmxk%2Fburble/lists"}