mirror of
https://github.com/google/bumble.git
synced 2026-04-16 00:25:31 +00:00
cleanup doc (+6 squashed commits)
Squashed commits: [6b97b93] add gRPC publish support for netsim [439717b] fix doc [5f679d7] fix linting and type errors [ca7b734] merge 2 [f29c909] update docs [7800ef9] cleanup (+5 squashed commits) Squashed commits: [c501eac] update to latest protos [e51a3fb] wip [d6a58fc] wip [eaa9fa6] wip [68d9490] wip wip wip wip update to latest protos cleanup
This commit is contained in:
Gilles Boccon-Gibod
committed by
Gilles Boccon-Gibod
Gilles Boccon-Gibod
parent
9af426db45
commit
5f86cddc85
@@ -9,19 +9,20 @@ 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
|
||||
Bluetooth controller, such as a USB dongle, or other HCI transport.
|
||||
|
||||
!!! 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.
|
||||
You will need version 33.1.4.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
|
||||
by exposing a 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.
|
||||
Both ways are controlled via gRPC requests to the Android emulator controller and/or
|
||||
from the Android emulator.
|
||||
|
||||
## Launching the Emulator
|
||||
|
||||
@@ -33,48 +34,82 @@ the command line.
|
||||
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.
|
||||
The `-packet-streamer-endpoint <endpoint>` command line option may be used to enable
|
||||
Bluetooth emulation and tell the emulator which virtual controller to connect to.
|
||||
|
||||
## Connecting to Root Canal
|
||||
## Connecting to Netsim
|
||||
|
||||
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
|
||||
If the emulator doesn't have Bluetooth emulation enabled by default, use the
|
||||
`-packet-streamer-endpoint default` option to tell it to connect to Netsim.
|
||||
If Netsim is not running, the emulator will start it automatically.
|
||||
|
||||
The Android emulator's virtual Bluetooth controller is called **Netsim**.
|
||||
Netsim runs as a background process and allows multiple clients to connect to it,
|
||||
each connecting to its own virtual controller instance hosted by Netsim. All the
|
||||
clients connected to the same Netsim process can then "talk" to each other over a
|
||||
virtual radio link layer.
|
||||
Netsim supports other wireless protocols than Bluetooth, but the relevant part here
|
||||
is Bluetooth. The virtual Bluetooth controller used by Netsim is sometimes referred to
|
||||
as **Root Canal**.
|
||||
|
||||
Configuring a Bumble Device instance to use netsim 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).
|
||||
To connect a Bumble host stack to a netsim virtual controller instance, use
|
||||
the Bumble `android-netsim` transport in `host` mode (the default).
|
||||
|
||||
!!! example "Run the example GATT server connected to the emulator"
|
||||
!!! example "Run the example GATT server connected to the emulator via Netsim"
|
||||
``` shell
|
||||
$ python run_gatt_server.py device1.json android-emulator
|
||||
$ python run_gatt_server.py device1.json android-netsim
|
||||
```
|
||||
|
||||
By default, the Bumble `android-netsim` transport will try to automatically discover
|
||||
the port number on which the netsim process is exposing its gRPC server interface. If
|
||||
that discovery process fails, or if you want to specify the interface manually, you
|
||||
can pass a `hostname` and `port` as parameters to the transport, as: `android-netsim:<host>:<port>`.
|
||||
|
||||
!!! example "Run the example GATT server connected to the emulator via Netsim on a localhost, port 8877"
|
||||
``` shell
|
||||
$ python run_gatt_server.py device1.json android-netsim:localhost:8877
|
||||
```
|
||||
|
||||
### Multiple Instances
|
||||
|
||||
If you want to connect multiple Bumble devices to netsim, it may be useful to give each one
|
||||
a netsim controller with a specific name. This can be done using the `name=<name>` transport option.
|
||||
For example: `android-netsim:localhost:8877,name=bumble1`
|
||||
|
||||
## 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 "Launch the emulator with VHCI forwarding"
|
||||
In this example, we launch an emulator AVD named "Tiramisu"
|
||||
```shell
|
||||
$ emulator -forward-vhci -avd Tiramisu
|
||||
```
|
||||
The first step is to run the Bumble HCI bridge, specifying netsim as the "host" end of the
|
||||
bridge, and another controller (typically a USB Bluetooth dongle, but any other supported
|
||||
transport can work as well) as the "controller" end of the bridge.
|
||||
|
||||
!!! 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`.
|
||||
To 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`.
|
||||
|
||||
!!! example "Connect the Android emulator to the first USB Bluetooth dongle, using the `hci_bridge` application"
|
||||
```shell
|
||||
$ bumble-hci-bridge android-emulator:mode=controller usb:0
|
||||
$ bumble-hci-bridge android-netsim:_:8877,mode=controller usb:0
|
||||
```
|
||||
|
||||
Then, you can start the emulator and tell it to connect to this bridge, instead of netsim.
|
||||
You 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).
|
||||
|
||||
!!! example "Launch the emulator with a netsim replacement"
|
||||
In this example, we launch an emulator AVD named "Tiramisu", with a Bumble HCI bridge running
|
||||
on port 8877.
|
||||
```shell
|
||||
$ emulator -packet-streamer-endpoint localhost:8877 -avd Tiramisu
|
||||
```
|
||||
|
||||
!!! tip
|
||||
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
|
||||
before attaching the virtual controller, then re-enable it once attached.
|
||||
|
||||
|
||||
## Other Tools
|
||||
|
||||
The `show` application that's included with Bumble can be used to parse and pretty-print the HCI packets
|
||||
|
||||
@@ -1,22 +1,41 @@
|
||||
ANDROID EMULATOR TRANSPORT
|
||||
==========================
|
||||
|
||||
The Android emulator transport either connects, as a host, to a "Root Canal" virtual controller
|
||||
("host" mode), or attaches a virtual controller to the Android Bluetooth host stack ("controller" mode).
|
||||
!!! warning
|
||||
Bluetooth support in the Android emulator has recently changed. The older mode, using
|
||||
the `android-emulator` transport name with Bumble, while still implemented, is now
|
||||
obsolete, and may not be supported by recent versions of the emulator.
|
||||
Use the `android-netsim` transport name instead.
|
||||
|
||||
|
||||
The Android "netsim" transport either connects, as a host, to a **Netsim** virtual controller
|
||||
("host" mode), or acts as a virtual controller itself ("controller" mode) accepting host
|
||||
connections.
|
||||
|
||||
## Moniker
|
||||
The moniker syntax for an Android Emulator transport is: `android-emulator:[mode=<host|controller>][<hostname>:<port>]`, where
|
||||
the `mode` parameter can specify running as a host or a controller, and `<hostname>:<port>` can specify a host name (or IP address) and TCP port number on which to reach the gRPC server for the emulator.
|
||||
Both the `mode=<host|controller>` and `<hostname>:<port>` parameters are optional (so the moniker `android-emulator` by itself is a valid moniker, which will create a transport in `host` mode, connected to `localhost` on the default gRPC port for the emulator).
|
||||
The moniker syntax for an Android Emulator "netsim" transport is: `android-netsim:[<host>:<port>][<options>]`,
|
||||
where `<options>` is a ','-separated list of `<name>=<value>` pairs`.
|
||||
The `mode` parameter name can specify running as a host or a controller, and `<hostname>:<port>` can specify a host name (or IP address) and TCP port number on which to reach the gRPC server for the emulator (in "host" mode), or to accept gRPC connections (in "controller" mode).
|
||||
Both the `mode=<host|controller>` and `<hostname>:<port>` parameters are optional (so the moniker `android-netsim` by itself is a valid moniker, which will create a transport in `host` mode, connected to `localhost` on the default gRPC port for the Netsim background process).
|
||||
|
||||
!!! example Example
|
||||
`android-emulator`
|
||||
connect as a host to the emulator on localhost:8554
|
||||
`android-netsim`
|
||||
connect as a host to Netsim on the gRPC port discovered automatically.
|
||||
|
||||
!!! example Example
|
||||
`android-emulator:mode=controller`
|
||||
connect as a controller to the emulator on localhost:8554
|
||||
`android-netsim:_:8555,mode=controller`
|
||||
Run as a controller, accepting gRPC connection on port 8555.
|
||||
|
||||
!!! example Example
|
||||
`android-emulator:localhost:8555`
|
||||
connect as a host to the emulator on localhost:8555
|
||||
`android-netsim:localhost:8555`
|
||||
connect as a host to Netsim on localhost:8555
|
||||
|
||||
!!! example Example
|
||||
`android-netsim:localhost:8555`
|
||||
connect as a host to Netsim on localhost:8555
|
||||
|
||||
!!! example Example
|
||||
`android-netsim:name=bumble1234`
|
||||
connect as a host to Netsim on the discovered gRPC port, using `bumble1234` as the
|
||||
controller instance name.
|
||||
|
||||
|
||||
@@ -16,5 +16,6 @@ Several types of transports are supported:
|
||||
* [PTY](pty.md): 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
|
||||
* [VHCI](vhci.md): used to attach a virtual controller to a Bluetooth stack on platforms that support it.
|
||||
* [HCI Socket](hci_socket.md): an HCI socket, on platforms that support it, to send/receive HCI packets to/from an HCI controller managed by the OS.
|
||||
* [Android Emulator](android_emulator.md): 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.
|
||||
* [Android Emulator](android_emulator.md): a gRPC connection to the Android emulator's "netsim"
|
||||
virtual controller, or from the Android emulator, is used to setup either an HCI interface to the emulator's "netsim" virtual controller, or serve as a virtual controller for the Android Bluetooth host stack.
|
||||
* [File](file.md): HCI packets are read/written to a file-like node in the filesystem.
|
||||
|
||||
Reference in New Issue
Block a user