DOCSEARCHbyAlgolia
Submit Docs

Bumble Bluetooth Stack

repository·main·Indexed 18 days ago

https://github.com/google/bumble

A full-featured Bluetooth stack written in Python supporting Bluetooth Low Energy (BLE) and Bluetooth Classic (BR/EDR). Designed for applications, emulation, testing, and experimentation, it includes tools for parsing HCI packets, bridging HCI transports, and an interactive TUI. The project also provides Rust wrappers and a web prototype using pyodide.

Tokens
61K
Snippets
220
Records
300
Agent score
68%

What's inside bumble

  1. Overview of Bumble Bluetooth Stack components

    main

    Bumble is a Python-based Bluetooth stack designed for emulation, testing, and experimentation. It supports both Bluetooth Low Energy (BLE) and Bluetooth Classic. The stack is built using Python coroutines and asyncio, meaning concurrent tasks run in a single thread for predictability.

    Core components include:

    • Controller: Exposes an HCI interface and connects to a link-layer bus. It can be virtual or physical.
    • Host: Connects to a controller over HCI to send commands/ACL data and receive events.
    • Link: The interface between controllers. LocalLink allows in-memory, in-process communication between multiple controllers in one app.
    • Channel Manager: Manages L2CAP channels.
    • Security Manager: Handles pairing and bonding.
    • GATT Client/Server: APIs for discovering services, characteristics, and handling reads/writes/subscriptions.
    • SDP: Implements the Service Discovery Protocol for Bluetooth Classic.
    • RFComm: Provides a bi-directional serial-port-like protocol.
    • Device: A compound object that aggregates a Host, GATT Client, GATT Server, L2CAP access, and advertising/scanning capabilities.
    • Profiles: High-level implementations of standard use cases like A2DP (audio streaming), HFP (headsets), and HID (input devices).

  2. Overview of Bumble Apps and Tools

    main

    Bumble includes several specialized applications and tools built on top of its core libraries for Bluetooth testing, emulation, and experimentation. These tools cover a range of tasks from LE Audio control to HCI packet analysis and device pairing.

    Available tools include:
* Auracast: Broadcast, receive, and control LE Audio.
* Console: Interactive text-based console.
* Bench: Speed and latency benchmarking (LE and Classic).
* Pair: Pair/bond devices (LE and Classic).
* Unbond: Remove established bonds.
* HCI Bridge: Connect and filter/snoop two HCI transports.
* Golden Gate Bridge: Bridge between GATT and UDP.
* Show: Parse and print HCI packet details in human-readable form.
* Speaker: Virtual Bluetooth speaker with CLI and browser UI.

  3. Available Bumble Hive Applications and Virtual Devices

    main

    The Bumble Hive provides several web-based tools and emulated devices. Each tool has a settings button to configure the WebSocket URL for the HCI connection.

    Applications

    • Scanner: Scans for BLE (Bluetooth Low Energy) devices.

    Virtual Devices

    • Speaker: A virtual speaker that plays audio directly in the browser page.
    • Heart Rate Monitor: A virtual heart rate monitor device.

  4. Manage Python environments for Bumble

    main

    Bumble can be installed in several types of isolated Python environments to avoid dependency conflicts with your system Python. Supported environment managers include:

    • venv: The standard Python module for creating lightweight virtual environments.
    • Pyenv: A tool for managing and switching between multiple Python versions.
    • Conda: A robust package and environment manager. Using the project's environment.yml is the recommended way to manage Bumble dependencies via Conda.

  5. Choose between `usb:` and `pyusb:` transport implementations

    main

    Bumble provides two different implementations for USB transport depending on the underlying Python bindings used for libusb:

    1. usb: (Default): Uses the libusb1 Python bindings and the asynchronous API of libusb. This is the recommended implementation.
    2. pyusb:: Uses the PyUSB library and the synchronous API of libusb.

    To use the pyusb: implementation, you must manually install the pyusb module, as it is not a default dependency of Bumble.

  7. Understand the Console app user interface

    main

    The Console app uses a three-pane layout to facilitate interactive Bluetooth operations:

    • Display Pane: Shows information based on the current mode. You can switch the viewable content using the show command.
    • Command History Pane: Displays a short history of recently executed commands and their results.
    • Command Pane: The input area where you enter commands; it supports tab completion for easier interaction.

    Additionally, a Status Bar is always visible, indicating the current scanning state and the current connection state.

  8. Test Bluetooth performance with Android BT Bench

    main

    Android BT Bench is an Android application designed to work with the Bumble bench command line application. It is used to measure and test Bluetooth throughput and latency in the following scenarios:

    1. Between two Android devices.
    2. Between an Android device and a device running the Bumble bench application.

  10. Use the PTY transport for process communication

    main
    The PTY transport allows you to communicate with another process on the host using a Unix pseudo-terminal (PTY) device. This behaves similarly to communicating over a serial port. This is useful for interfacing with processes that expect terminal-like input/output.

  11. Configure Speaker app outputs

    main

    The Speaker app supports several types of outputs for handling received audio data:

    1. Console/Web UI: By default, status and audio bandwidth graphs are displayed in the console and the web interface.
    2. File Output: You can save received audio to a file by providing a filename to the --output flag.
    3. Audio Playback via ffplay: If ffplay is installed on your host system, you can use the @ffplay output to pipe and play received audio through your computer's speakers.
    4. Multiple Outputs: You can use the --output flag multiple times to send audio to several destinations simultaneously.

  12. Understand Bumble Transports

    main
    In Bumble, Hosts and Controllers communicate via a Transport. The transport layer is responsible for the transmission and reception of HCI (Host Controller Interface) packets between these two entities. Choosing the correct transport depends on whether you are interfacing with physical hardware (like a USB dongle or serial board), emulating a controller in-process, or connecting to remote services (via TCP, UDP, or WebSockets).