1
2     _                 _     _
3    | |               | |   | |
4    | |__  _   _ ____ | |__ | | _____
5    |  _ \| | | |    \|  _ \| || ___ |
6    | |_) ) |_| | | | | |_) ) || ____|
7    |____/|____/|_|_|_|____/ \_)_____)
8
9Bluetooth Stack for Apps, Emulation, Test and Experimentation
10=============================================================
11
12<img src="docs/mkdocs/src/images/logo_framed.png" alt="Logo" width="200" height="200"/>
13
14Bumble is a full-featured Bluetooth stack written entirely in Python. It supports most of the common Bluetooth Low Energy (BLE) and Bluetooth Classic (BR/EDR) protocols and profiles, including GAP, L2CAP, ATT, GATT, SMP, SDP, RFCOMM, HFP, HID and A2DP. The stack can be used with physical radios via HCI over USB, UART, or the Linux VHCI, as well as virtual radios, including the virtual Bluetooth support of the Android emulator.
15
16## Documentation
17
18Browse the pre-built [Online Documentation](https://google.github.io/bumble/),
19or see the documentation source under `docs/mkdocs/src`, or build the static HTML site from the markdown text with:
20```
21mkdocs build -f docs/mkdocs/mkdocs.yml
22```
23
24## Usage
25
26### Getting Started
27
28For a quick start to using Bumble, see the [Getting Started](docs/mkdocs/src/getting_started.md) guide.
29
30### Dependencies
31
32To install package dependencies needed to run the bumble examples, execute the following commands:
33
34```
35python -m pip install --upgrade pip
36python -m pip install ".[test,development,documentation]"
37```
38
39### Examples
40
41Refer to the [Examples Documentation](examples/README.md) for details on the included example scripts and how to run them.
42
43The complete [list of Examples](/docs/mkdocs/src/examples/index.md), and what they are designed to do is here.
44
45There are also a set of [Apps and Tools](docs/mkdocs/src/apps_and_tools/index.md) that show the utility of Bumble.
46
47### Using Bumble With a USB Dongle
48
49Bumble is easiest to use with a dedicated USB dongle.
50This is because internal Bluetooth interfaces tend to be locked down by the operating system.
51You can use the [usb_probe](/docs/mkdocs/src/apps_and_tools/usb_probe.md) tool (all platforms) or `lsusb` (Linux or macOS) to list the available USB devices on your system.
52
53See the [USB Transport](/docs/mkdocs/src/transports/usb.md) page for details on how to refer to USB devices. Also, if your are on a mac, see [these instructions](docs/mkdocs/src/platforms/macos.md).
54
55## License
56
57Licensed under the [Apache 2.0](LICENSE) License.
58
59## Disclaimer
60
61This is not an official Google product.
62
63This library is in alpha and will be going through a lot of breaking changes. While releases will be stable enough for prototyping, experimentation and research, we do not recommend using it in any production environment yet.
64Expect bugs and sharp edges.
65Please help by trying it out, reporting bugs, and letting us know what you think!
66