auracaster/bumble_mirror
3
0
Fork 1
mirror of https://github.com/google/bumble.git synced 2026-06-02 07:47:03 +00:00
Code Issues Packages Projects Releases Wiki Activity

initial import

Browse Source
This commit is contained in:
Gilles Boccon-Gibod
2022-05-16 19:42:31 -07:00
commit 6ac91f7dec
185 changed files with 32064 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/mkdocs/src/platforms/android.md
+79
View File
@@ -0,0 +1,79 @@
:material-android: ANDROID PLATFORM
===================================
Using Bumble with Android is not about running the Bumble stack on the Android
OS itself, but rather using Bumble with the Bluetooth support of the Android
emulator.
The two main use cases are:
* Connecting the Bumble host stack to the Android emulator's virtual controller.
* Using Bumble as an HCI bridge to connect the Android emulator to a physical
Bluetooth controller, such as a USB dongle
!!! warning
Bluetooth support in the Android emulator is a recent feature that may still
be evolving. The information contained here be somewhat out of sync with the
version of the emulator you are using.
You will need version 31.3.8.0 or later.
The Android emulator supports Bluetooth in two ways: either by exposing virtual
Bluetooth controllers to which you can connect a virtual Bluetooth host stack, or
by exposing an way to connect your own virtual controller to the Android Bluetooth
stack via a virtual HCI interface.
Both ways are controlled via gRPC requests to the Android emulator.
## Launching the Emulator
If the version of the emulator you are running does not yet support enabling
Bluetooth support by default or automatically, you must launch the emulator from
the command line.
!!! tip
For details on how to launch the Android emulator from the command line,
visit [this Android Studio user guide page](https://developer.android.com/studio/run/emulator-commandline)
The `-grpc <port>` command line option may be used to select a gRPC port other than the default.
## Connecting to Root Canal
The Android emulator's virtual Bluetooth controller is called **Root Canal**.
Multiple instances of Root Canal virtual controllers can be instantiated, they
communicate link layer packets between them, thus creating a virtual radio network.
Configuring a Bumble Device instance to use Root Canal as a virtual controller
allows that virtual device to communicate with the Android Bluetooth stack, and
through it with Android applications as well as system-managed profiles.
To connect a Bumble host stack to a Root Canal virtual controller instance, use
the bumble `android-emulator` transport in `host` mode (the default).
!!! example "Running the example GATT server connected to the emulator"
``` shell
$ python run_gatt_server.py device1.json android-emulator
```
## Connecting a Custom Virtual Controller
This is an advanced use case, which may not be officially supported, but should work in recent
versions of the emulator.
You will likely need to start the emulator from the command line, in order to specify the `-forward-vhci` option (unless the emulator offers a way to control that feature from a user/ui menu).
!!! example "Launching the emulator with VHCI forwarding"
In this example, we launch an emulator AVD named "Tiramisu"
```shell
$ emulator -forward-vhci -avd Tiramisu
```
!!! tip
Attaching a virtual controller use the VHCI forwarder while the Android Bluetooth stack
is running isn't supported. So you need to disable Bluetooth in your running Android guest
before attaching the virtual controller, then re-enable it once attached.
To connect a virtual controller to the Android Bluetooth stack, use the bumble `android-emulator` transport in `controller` mode. For example, using the default gRPC port, the transport name would be: `android-emulator:mode=controller`.
!!! example "connecting the Android emulator to the first USB Bluetooth dongle, using the `hci_bridge` application"
```shell
$ bumble-hci-bridge android-emulator:mode=controller usb:0
```
docs/mkdocs/src/platforms/index.md
+11
View File
@@ -0,0 +1,11 @@
PLATFORMS
=========
Most of the code included in the project should run on any platform that supports Python >= 3.8. Not all features are supported on all platforms (for example, USB dongle support is only available on platforms where the python USB library is functional).
For platform-specific information, see the following pages:
* :material-apple: macOS - see the [macOS platform page](macos.md)
* :material-linux: Linux - see the [Linux platform page](linux.md)
* :material-microsoft-windows: Windows - see the [Windows platform page](windows.md)
* :material-android: Android - see the [Android platform page](android.md)
docs/mkdocs/src/platforms/linux.md
+138
View File
@@ -0,0 +1,138 @@
:material-linux: LINUX PLATFORM
===============================
In addition to all the standard functionality available from the project by running the python tools and/or writing your own apps by leveraging the API, it is also possible on Linux hosts to interface the Bumble stack with the native BlueZ stack, and with Bluetooth controllers.
Using Bumble With BlueZ
-----------------------
A Bumble virtual controller can be attached to the BlueZ stack.
Attaching a controller to BlueZ can be done by either simulating a UART HCI interface, or by using the VHCI driver interface if available.
In both cases, the controller can run locally on the Linux host, or remotely on a different host, with a bridge between the remote controller and the local BlueZ host, which may be useful when the BlueZ stack is running on an embedded system, or a host on which running the Bumble controller is not convenient.
### Using VHCI
With the [VHCI transport](../transports/vhci.md) you can attach a Bumble virtual controller to the BlueZ stack. Once attached, the controller will appear just like any other controller, and thus can be used with the standard BlueZ tools.
!!! example "Attaching a virtual controller"
With the example app `run_controller.py`:
```
PYTHONPATH=. python3 examples/run_controller.py F6:F7:F8:F9:FA:FB examples/device1.json vhci
```
You should see a 'Virtual Bus' controller. For example:
```
$ hciconfig
hci0: Type: Primary Bus: Virtual
BD Address: F6:F7:F8:F9:FA:FB ACL MTU: 27:64 SCO MTU: 0:0
UP RUNNING
RX bytes:0 acl:0 sco:0 events:43 errors:0
TX bytes:274 acl:0 sco:0 commands:43 errors:0
```
And scanning for devices should show the virtual 'Bumble' device that's running as part of the `run_controller.py` example app:
```
pi@raspberrypi:~ $ sudo hcitool -i hci2 lescan
LE Scan ...
F0:F1:F2:F3:F4:F5 Bumble
```
### Using HCI Sockets
HCI sockets provide a way to send/receive HCI packets to/from a Bluetooth controller managed by the kernel.
The HCI device referenced by an `hci-socket` transport (`hciX`, where `X` is an integer, with `hci0` being the first controller device, and so on) must be in the `DOWN` state before it can be opened as a transport.
You can bring a HCI controller `UP` or `DOWN` with `hciconfig`.
!!! tip "List all available controllers"
The command
```
$ hciconfig
```
lists all available HCI controllers and their state.
Example:
```
pi@raspberrypi:~ $ hciconfig
hci1: Type: Primary Bus: USB
BD Address: 00:16:A4:5A:40:F2 ACL MTU: 1021:8 SCO MTU: 64:1
DOWN
RX bytes:84056 acl:0 sco:0 events:51 errors:0
TX bytes:1980 acl:0 sco:0 commands:90 errors:0
hci0: Type: Primary Bus: UART
BD Address: DC:A6:32:75:2C:97 ACL MTU: 1021:8 SCO MTU: 64:1
DOWN
RX bytes:68038 acl:0 sco:0 events:692 errors:0
TX bytes:20105 acl:0 sco:0 commands:843 errors:0
```
!!! tip "Disabling `bluetoothd`"
When the Bluetooth daemon, `bluetoothd`, is running, it will try to use any HCI controller attached to the BlueZ stack, automatically. This means that whenever an HCI socket transport is released, it is likely that `bluetoothd` will take it over, so you will get a "device busy" condition (ex: `OSError: [Errno 16] Device or resource busy`). If that happens, you can always use
```
$ hciconfig hci0 down
```
(or `hciX` with `X` being the index of the controller device you want to use), but a simpler solution is to just stop the `bluetoothd` daemon, with a command like:
```
$ sudo systemctl stop bluetooth.service
```
You can always re-start the daemon with
```
$ sudo systemctl start bluetooth.service
```
### Using a Simulated UART HCI
### Bridge to a Remote Controller
Using Bumble With Bluetooth Controllers
---------------------------------------
A Bumble application can interface with a local Bluetooth controller.
If your Bluetooth controller is a standard HCI USB controller, see the [USB Transport page](../transports/usb.md) for details on how to use HCI USB controllers.
If your Bluetooth controller is a standard HCI UART controller, see the [Serial Transport page](../transports/serial.md).
Alternatively, a Bumble Host object can communicate with one of the platform's controllers via an HCI Socket.
`<details to be filled in>`
### Raspberry Pi 4 :fontawesome-brands-raspberry-pi:
You can use the Bluetooth controller either via the kernel, or directly to the device.
#### Via The Kernel
Use an HCI Socket transport
#### Directly
In order to use the Bluetooth controller directly on a Raspberry Pi 4 board, you need to ensure that it isn't being used by the BlueZ stack (which it probably is by default).
```
$ sudo systemctl stop hciuart
```
should detach the controller from the stack, after which you can use the HCI UART with Bumble.
!!! tip "Check the device name for the UART and at what speed it should be opened"
```
$ sudo systemctl status hciuart
```
should show the speed at which the UART should be opened.
For example:
```
$ sudo systemctl status hciuart
hciuart.service - Configure Bluetooth Modems connected by UART
Loaded: loaded (/lib/systemd/system/hciuart.service; enabled; vendor preset: enabled)
Active: active (running) since Fri 2021-06-18 02:17:28 BST; 1min 10s ago
Process: 357 ExecStart=/usr/bin/btuart (code=exited, status=0/SUCCESS)
Main PID: 586 (hciattach)
Tasks: 1 (limit: 4915)
CGroup: /system.slice/hciuart.service
└─586 /usr/bin/hciattach /dev/serial1 bcm43xx 3000000 flow -
```
When run before stopping the `hciuart` service, shows that on this board, the UART device is `/dev/serial` and the speed is `3000000`
!!! example "Example: scanning"
```
python3 run_scanner.py serial:/dev/serial1,3000000
```
docs/mkdocs/src/platforms/macos.md
+14
View File
@@ -0,0 +1,14 @@
:material-apple: MACOS PLATFORM
===============================
USB HCI
-------
To use the experimental USB HCI support on macOS, you need to tell macOS not to use the USB Bluetooth
controller with its internal Bluetooth stack.
To do that, use the following command:
```
sudo nvram bluetoothHostControllerSwitchBehavior="never"
```
A reboot shouldn't be necessary after that. See [Tech Note 2295](https://developer.apple.com/library/archive/technotes/tn2295/_index.html)
docs/mkdocs/src/platforms/windows.md
+13
View File
@@ -0,0 +1,13 @@
:material-microsoft-windows: WINDOWS PLATFORM
=============================================
USB HCI
-------
To use a Bluetooth USB dongle on Windows, you need a USB dongle that does not require a vendor Windows driver (the dongle will be used directly through the [`WinUSB`](https://docs.microsoft.com/en-us/windows-hardware/drivers/usbcon/winusb) driver rather than through a vendor-supplied Windows driver).
In order to use the dongle, the `WinUSB` driver must be assigned to the USB device. It is likely that, by default, when you first plug in the dongle, it will be recognized by Windows as a Bluetooth USB device, and Windows will try to use it with its native Bluetooth stack. You will need to switch the driver, which can be done easily with the [Zadig tool](https://zadig.akeo.ie/).
In the Zadig tool, select your USB dongle device, and associate it with WinUSB.
Once the WinUSB driver is correctly assigned to your device, you can confirm that by checking the settings with the Windows Device Manager control panel. Your device should appear under "Universal Serial Bus Device" (not under "Bluetooth"), and inspecting the driver details, you should see `winusb.sys` in the list of driver files.
![USB Driver Details](winusb_driver.png)
docs/mkdocs/src/platforms/winusb_driver.png
Executable
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 66 KiB