1:material-android: ANDROID PLATFORM 2=================================== 3 4Using Bumble with Android is not about running the Bumble stack on the Android 5OS itself, but rather using Bumble with the Bluetooth support of the Android 6emulator. 7 8The two main use cases are: 9 10 * Connecting the Bumble host stack to the Android emulator's virtual controller. 11 * Using Bumble as an HCI bridge to connect the Android emulator to a physical 12 Bluetooth controller, such as a USB dongle 13 14!!! warning 15 Bluetooth support in the Android emulator is a recent feature that may still 16 be evolving. The information contained here be somewhat out of sync with the 17 version of the emulator you are using. 18 You will need version 31.3.8.0 or later. 19 20The Android emulator supports Bluetooth in two ways: either by exposing virtual 21Bluetooth controllers to which you can connect a virtual Bluetooth host stack, or 22by exposing an way to connect your own virtual controller to the Android Bluetooth 23stack via a virtual HCI interface. 24Both ways are controlled via gRPC requests to the Android emulator. 25 26## Launching the Emulator 27 28If the version of the emulator you are running does not yet support enabling 29Bluetooth support by default or automatically, you must launch the emulator from 30the command line. 31 32!!! tip 33 For details on how to launch the Android emulator from the command line, 34 visit [this Android Studio user guide page](https://developer.android.com/studio/run/emulator-commandline) 35 36The `-grpc <port>` command line option may be used to select a gRPC port other than the default. 37 38## Connecting to Root Canal 39 40The Android emulator's virtual Bluetooth controller is called **Root Canal**. 41Multiple instances of Root Canal virtual controllers can be instantiated, they 42communicate link layer packets between them, thus creating a virtual radio network. 43Configuring a Bumble Device instance to use Root Canal as a virtual controller 44allows that virtual device to communicate with the Android Bluetooth stack, and 45through it with Android applications as well as system-managed profiles. 46To connect a Bumble host stack to a Root Canal virtual controller instance, use 47the bumble `android-emulator` transport in `host` mode (the default). 48 49!!! example "Run the example GATT server connected to the emulator" 50 ``` shell 51 $ python run_gatt_server.py device1.json android-emulator 52 ``` 53 54## Connecting a Custom Virtual Controller 55 56This is an advanced use case, which may not be officially supported, but should work in recent 57versions of the emulator. 58You 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). 59 60!!! example "Launch the emulator with VHCI forwarding" 61 In this example, we launch an emulator AVD named "Tiramisu" 62 ```shell 63 $ emulator -forward-vhci -avd Tiramisu 64 ``` 65 66!!! tip 67 Attaching a virtual controller use the VHCI forwarder while the Android Bluetooth stack 68 is running isn't supported. So you need to disable Bluetooth in your running Android guest 69 before attaching the virtual controller, then re-enable it once attached. 70 71To 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`. 72 73!!! example "Connect the Android emulator to the first USB Bluetooth dongle, using the `hci_bridge` application" 74 ```shell 75 $ bumble-hci-bridge android-emulator:mode=controller usb:0 76 ``` 77 78## Other Tools 79 80The `show` application that's included with Bumble can be used to parse and pretty-print the HCI packets 81from an Android HCI "snoop log" (see [this page](https://source.android.com/devices/bluetooth/verifying_debugging) 82for details on how to obtain HCI snoop logs from an Android device). 83Use the `--format snoop` option to specify that the file is in that specific format. 84 85!!! example "Analyze an Android HCI snoop log file" 86 ```shell 87 $ bumble-show --format snoop btsnoop_hci.log 88 ``` 89 90