93 lines
3.3 KiB
Markdown
93 lines
3.3 KiB
Markdown
# Introduction
|
|
|
|
RootCanal is a virtual Bluetooth Controller. RootCanal aims reducing the
|
|
overhead of writing and deploying end-to-end tests on Bluetooth devices
|
|
by taking away the physical layer.
|
|
|
|
## Feature emulation
|
|
|
|
The emulation of Bluetooth features on RootCanal _is limited to features
|
|
that have direct consequences on connected hosts_. The accurate implementation
|
|
of HCI commands and events is thus critical to RootCanal's goal, while accurate
|
|
emulation of the scheduler and base-band is out of scope.
|
|
|
|
## Usage
|
|
|
|
### Emulator integration
|
|
|
|
RootCanal is natively integrated in the Cuttlefish and Goldfish emulators.
|
|
Bluetooth is enabled by default on these platforms. External hosts can connect
|
|
to the HCI port 7300 to interact with the emulated device.
|
|
|
|
### Standalone tool
|
|
|
|
RootCanal can be built and started as a standalone tool.
|
|
Instructions to build and run root-canal from an AOSP instance:
|
|
|
|
```bash
|
|
source build/envsetup.sh
|
|
lunch aosp_cf_x86_64_phone-userdebug
|
|
m root-canal
|
|
./out/host/linux-x86/bin/root-canal
|
|
```
|
|
Note: You can also find a prebuilt version inside
|
|
[cvd-host_package.tar.gz from Android CI][cvd-host_package]
|
|
The following configuration options are implemented:
|
|
|
|
* `--test_port` (default `6401`) Configure the TCP port for the test channel.
|
|
|
|
* `--hci_port` (default `6402`) Configure the TCP port for the HCI server.
|
|
|
|
* `--link_port` (default `6403`) Configure the TCP port for the link server.
|
|
|
|
* `--link_ble_port` (default `6404`) Configure the TCP port for the BLE link server.
|
|
|
|
* `--controller_properties_file` (default `""`) Configure the path to
|
|
a custom Controller configuration file. All properties defined in
|
|
`model/controller/controller_properties.h` can be edited to test with a
|
|
specific controller setup.
|
|
|
|
* `--enable_hci_sniffer` (default `false`) Capture PCAP traces for all
|
|
connected HCI hosts. The PCAP traces are saved in the current directory.
|
|
|
|
* `--enable_baseband_sniffer` (default `false`) Capture PCAP traces for all
|
|
base-band packets exchanged between connection HCI hosts. The PCAP traces are
|
|
saved in the current directory. This option is useful to inspect and debug
|
|
RootCanal's implementation.
|
|
|
|
# Architecture
|
|
|
|
All RootCanal instances expose four TCP ports:
|
|
- _HCI channel_
|
|
- _Test channel_
|
|
- _BR_EDR Phy channel_
|
|
- _LE Phy channel_
|
|
|
|
## HCI Channel
|
|
|
|
The HCI channel implements the Bluetooth UART transport protocol
|
|
(a.k.a. H4) over TCP. Each new connection on the HCI port spawns a new virtual
|
|
controller.
|
|
|
|
## Test Channel
|
|
|
|
The test channel uses a simple custom protocol to send control commands
|
|
to RootCanal. You can connect to it using [scripts/test_channel.py](scripts/test_channel.py).
|
|
|
|
### Phy Channels
|
|
|
|
The physical channels use a custom protocol described in [packets/link_layer_packets.pdl](packets/link_layer_packets.pdl).
|
|
The protocol simplifies the LL and LMP protocol packets defined in the Bluetooth
|
|
specification to abstract over negotiation details.
|
|
|
|
**Warning** The protocol can change in backward incompatible ways,
|
|
be careful when depending on it.
|
|
|
|
Controllers can exchanges link layer packets only when they are part of the
|
|
same phy. One controller can be added to multiple phys, the simplest example
|
|
begin BR/EDR and LE dual phys.
|
|
|
|
# Links
|
|
|
|
[cvd-host_package]: https://ci.android.com/builds/latest/branches/aosp-master/targets/aosp_cf_x86_64_phone-userdebug/view/cvd-host_package.tar.gz
|