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, or other HCI transport. 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 33.1.4.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 a 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 controller and/or 25from the Android emulator. 26 27## Launching the Emulator 28 29If the version of the emulator you are running does not yet support enabling 30Bluetooth support by default or automatically, you must launch the emulator from 31the command line. 32 33!!! tip 34 For details on how to launch the Android emulator from the command line, 35 visit [this Android Studio user guide page](https://developer.android.com/studio/run/emulator-commandline) 36 37The `-packet-streamer-endpoint <endpoint>` command line option may be used to enable 38Bluetooth emulation and tell the emulator which virtual controller to connect to. 39 40## Connecting to Netsim 41 42If the emulator doesn't have Bluetooth emulation enabled by default, use the 43`-packet-streamer-endpoint default` option to tell it to connect to Netsim. 44If Netsim is not running, the emulator will start it automatically. 45 46The Android emulator's virtual Bluetooth controller is called **Netsim**. 47Netsim runs as a background process and allows multiple clients to connect to it, 48each connecting to its own virtual controller instance hosted by Netsim. All the 49clients connected to the same Netsim process can then "talk" to each other over a 50virtual radio link layer. 51Netsim supports other wireless protocols than Bluetooth, but the relevant part here 52is Bluetooth. The virtual Bluetooth controller used by Netsim is sometimes referred to 53as **Root Canal**. 54 55Configuring a Bumble Device instance to use netsim as a virtual controller 56allows that virtual device to communicate with the Android Bluetooth stack, and 57through it with Android applications as well as system-managed profiles. 58To connect a Bumble host stack to a netsim virtual controller instance, use 59the Bumble `android-netsim` transport in `host` mode (the default). 60 61!!! example "Run the example GATT server connected to the emulator via Netsim" 62 ``` shell 63 $ python run_gatt_server.py device1.json android-netsim 64 ``` 65 66By default, the Bumble `android-netsim` transport will try to automatically discover 67the port number on which the netsim process is exposing its gRPC server interface. If 68that discovery process fails, or if you want to specify the interface manually, you 69can pass a `hostname` and `port` as parameters to the transport, as: `android-netsim:<host>:<port>`. 70 71!!! example "Run the example GATT server connected to the emulator via Netsim on a localhost, port 8877" 72 ``` shell 73 $ python run_gatt_server.py device1.json android-netsim:localhost:8877 74 ``` 75 76### Multiple Instances 77 78If you want to connect multiple Bumble devices to netsim, it may be useful to give each one 79a netsim controller with a specific name. This can be done using the `name=<name>` transport option. 80For example: `android-netsim:localhost:8877,name=bumble1` 81 82## Connecting a Custom Virtual Controller 83 84This is an advanced use case, which may not be officially supported, but should work in recent 85versions of the emulator. 86 87The first step is to run the Bumble HCI bridge, specifying netsim as the "host" end of the 88bridge, and another controller (typically a USB Bluetooth dongle, but any other supported 89transport can work as well) as the "controller" end of the bridge. 90 91To connect a virtual controller to the Android Bluetooth stack, use the bumble `android-netsim` transport in `controller` mode. For example, with port number 8877, the transport name would be: `android-netsim:_:8877,mode=controller`. 92 93!!! example "Connect the Android emulator to the first USB Bluetooth dongle, using the `hci_bridge` application" 94 ```shell 95 $ bumble-hci-bridge android-netsim:_:8877,mode=controller usb:0 96 ``` 97 98Then, you can start the emulator and tell it to connect to this bridge, instead of netsim. 99You will likely need to start the emulator from the command line, in order to specify the `-packet-streamer-endpoint <hostname>:<port>` option (unless the emulator offers a way to control that feature from a user/ui menu). 100 101!!! example "Launch the emulator with a netsim replacement" 102 In this example, we launch an emulator AVD named "Tiramisu", with a Bumble HCI bridge running 103 on port 8877. 104 ```shell 105 $ emulator -packet-streamer-endpoint localhost:8877 -avd Tiramisu 106 ``` 107 108!!! tip 109 Attaching a virtual controller while the Android Bluetooth stack is running may not be well supported. So you may need to disable Bluetooth in your running Android guest 110 before attaching the virtual controller, then re-enable it once attached. 111 112 113## Other Tools 114 115The `show` application that's included with Bumble can be used to parse and pretty-print the HCI packets 116from an Android HCI "snoop log" (see [this page](https://source.android.com/devices/bluetooth/verifying_debugging) 117for details on how to obtain HCI snoop logs from an Android device). 118Use the `--format snoop` option to specify that the file is in that specific format. 119 120!!! example "Analyze an Android HCI snoop log file" 121 ```shell 122 $ bumble-show --format snoop btsnoop_hci.log 123 ``` 124