1Bumble, a Python Bluetooth Stack 2================================ 3 4{ width=100 height=100 } 5 6A Bluetooth stack, written in Python, useful for emulation, test, experimentation, and implementation of any sort of virtual device, with virtual or physical Bluetooth controllers. 7The project initially only supported BLE (Bluetooth Low Energy), but support for Bluetooth Classic was 8eventually added. Support for BLE is therefore currently somewhat more advanced than for Classic. 9 10!!! warning 11 This project is still in an early state of development where some things are still missing or broken, and what's implemented may change and evolve frequently. 12 13Overview 14-------- 15 16The goal of this project is to offer a suite of components that can be put together to implement a number of tasks related to Bluetooth. That's fairly open-ended, but at the very least, it should be possible to: 17 18* Implement a virtual controller that can be attached to any compliant Bluetooth host that supports HCI. 19* Implement a Bluetooth host that communicates through a controller over HCI, including of course a virtual controller 20* Connect two or more virtual controllers together inside a single app, or across multiple apps over a network connection or local IPC 21* Scan, advertise, connect, pair 22* Implement a GATT client and server 23* Implement an SDP client and server 24* Create an L2CAP channel between two peers 25 26Some of the configurations that may be useful: 27 28* A virtual controller used with an emulated or simulated device 29* A GATT client and/or GATT server test application that can be connected to a real or virtual Bluetooth device 30* Simulate certain conditions, including errors, with precise control that normal Bluetooth stacks don't offer through their standard APIs 31 32See the [use cases page](use_cases/index.md) for more use cases. 33 34The project is implemented in Python (Python >= 3.8 is required). A number of APIs for functionality that is inherently I/O bound is implemented in terms of python coroutines with async IO. This means that all of the concurrent tasks run in the same thread, which makes everything much simpler and more predictable. 35 36 37 38What's Included 39--------------- 40 41Components of a Bluetooth stack: 42 43## Controller 44The (virtual) Controller component exposes an HCI interface to a host, and connects to a virtual link-layer bus. Several instances of this class can be connected to the same bus, in which case they can communicate with each other (both broadcast for advertising data and unicast for ACL data). The bus may be 45process-local, in which case all the controllers attached to the bus run in the same process, or 46it may be remote (see Remote Link), in which case several controllers in separate processes can 47communicate with each other. 48 49### Link 50The Controller component communicates with other virtual controllers through a Link interface. 51The link interface defines basic functionality like connection, disconnection, sending and 52receiving ACL data, sending and receiving advertising data, and more. 53Included in the project are two types of Link interface implementations: 54 55#### Local Link 56The LocalLink implementation is a simple object used by an application that instantiates 57more than one Controller objects and connects them in-memory and in-process. 58 59#### Remote Link 60The RemoteLink implementation communicates with other virtual controllers over a WebSocket. 61Multiple instances of RemoteLink objects communicate with each other through a simple 62WebSocket relay that can host any number of virtual 'rooms', where each 'room' is 63a set of controllers that can communicate between themselves. 64The `link_relay` app is where this relay is implemented. 65 66## Host 67The Host component connects to a controller over an HCI interface. It is responsible to sending commands and ACL data to the controller and receiving back events and ACL data. 68 69## Channel Manager 70The ChannelManager is responsible for managing L2CAP channels. 71 72## Security Manager 73The SecurityManager is responsible for pairing/bonding. 74 75## GATT Client 76The GATT Client offers an API to discover peer services and characteristics, reading and writing characteristics, subscribing to characteristics, and all other GATT client functions. 77 78## GATT Server 79The GATT Server offers an API to expose services and characteristics, responding to reads and writes on characteristics, handling subscriptions to characteristics, and all other GATT server functions. 80 81## SDP 82SDP implements the service discovery protocol for Bluetooth Classic. 83 84## RFComm 85RFComm is a bi-directional serial-port-like protocol. It is used in several profiles. 86 87## Device 88The Device component it a compound object that ties together a Host, GATT Client, GATT Server, L2CAP channel access, advertising and scanning, and more. 89 90## Profiles 91Profiles are ways of using the underlying protocols for certain well-defined used cases, like playing music, implementing a headset, and so on. 92 93### A2DP 94A2DP is the Advanced Audio Profile, which enables asynchronous streaming of audio to speakers, or from microphones. Both the "source" (typically music playback source) and "sink" (typically a speaker) functions of A2DP. 95 96### HFP 97Hands Free Profile. Used for headsets. 98 99### HID 100Human Interface Device. For keyboards, mice, etc. 101 102## Transports 103The Hosts and Controllers communicate over a transport, which is responsible for sending/receiving 104HCI packets. 105Several types of transports are supported: 106 107 * **In Process**: HCI packets are passed via a function call 108 * Serial: interface with a controller over a serial port (HCI UART, like a development board or serial Bluetooth dongle) 109 * **USB**: interface with a controller over USB (HCI USB, like a Bluetooth USB dongle) 110 * **UDP**: packets are sent to a specified host/port and received on a specified port over a UDP socket 111 * **TCP Client**: a connection to a TCP server is made, after which HCI packets are sent/received over a TCP socket 112 * **TCP Server**: listens for a TCP client on a specified port. When a client connection is made, HCI packets are sent/received over a TCP socket 113 * **WebSocket Client**: a connection to a WebSocket server is made, after which HCI packets are sent/received over the socket. 114 * **WebSocket Server**: listens for a WebSocket client on a specified port. When a client connection is made, HCI packets are sent/received over the socket. 115 * **PTY**: a PTY (pseudo terminal) is used to send/receive HCI packets. This is convenient to expose a virtual controller as if it were an HCI UART 116 * **VHCI**: used to attach a virtual controller to a Bluetooth stack on platforms that support it. 117 * **HCI** Socket: an HCI socket, on platforms that support it, to send/receive HCI packets to/from an HCI controller managed by the OS. 118 * **Android Emulator**: a gRPC connection to an Android emulator is used to setup either an HCI interface to the emulator's "Root Canal" virtual controller, or attach a virtual controller to the Android Bluetooth host stack. 119 * **File**: HCI packets are read/written to a file-like node in the filesystem. 120 121A Bumble Host object communicates with a Bumble Controller object, or external Controller, via a Transport connection. A Bumble Controller object communicates with a Bumble Host, or external Host, via a Transport connection. When both the Host and Controller are Bumble objects, they typically communicate In Process, or via a Link Relay. 122 123See the [Transports page](transports/index.md) for details. 124 125Hardware 126-------- 127The Host part of the stack can interact with Bumble's Controller implementation, but also with external hardware controllers. 128 129See the [Hardware page](hardware/index.md) for details. 130 131 132Examples 133-------- 134 135See the [Examples page](examples/index.md) 136 137Apps & Tools 138------------ 139 140See the [Apps & Tools page](apps_and_tools/index.md) 141 142Platforms 143--------- 144 145The core library should work on any platform on which you can run Python3. 146Some platforms support features that not all platforms support 147 148 * :material-apple: macOS - see the [macOS platform page](platforms/macos.md) 149 * :material-linux: Linux - see the [Linux platform page](platforms/linux.md) 150 * :material-microsoft-windows: Windows - see the [Windows platform page](platforms/windows.md) 151 * :material-android: Android - see the [Android platform page](platforms/android.md) 152 153See the [Platforms page](platforms/index.md) for details. 154 155 156Hive 157---- 158 159The Hive is a collection of example apps and virtual devices that are implemented using the 160Python Bumble API, running entirely in a web page. This is a convenient way to try out some 161of the examples without any Python installation, when you have some other virtual Bluetooth 162device that you can connect to or from, such as the Android Emulator. 163 164See the [Bumble Hive](hive/index.md) for details. 165 166Roadmap 167------- 168 169Future features to be considered include: 170 171 * More profiles 172 * More device examples 173 * Add a new type of virtual link (beyond the two existing ones) to allow for link-level simulation (timing, loss, etc) 174 * Bindings for languages other than Python 175 * RPC interface to expose most of the API for remote use 176 * (...suggest anything you want...) 177
