1# Introduction
2
3RootCanal is a virtual Bluetooth Controller. RootCanal aims reducing the
4overhead of writing and deploying end-to-end tests on Bluetooth devices
5by taking away the physical layer.
6
7## Feature emulation
8
9The emulation of Bluetooth features on RootCanal _is limited to features
10that have direct consequences on connected hosts_. The accurate implementation
11of HCI commands and events is thus critical to RootCanal's goal, while accurate
12emulation of the scheduler and base-band is out of scope.
13
14## Usage
15
16### Emulator integration
17
18RootCanal is natively integrated in the Cuttlefish and Goldfish emulators.
19Bluetooth is enabled by default on these platforms. External hosts can connect
20to the HCI port 7300 to interact with the emulated device.
21
22### Standalone tool
23
24RootCanal can be built and started as a standalone tool.
25Instructions to build and run root-canal from an AOSP instance:
26
27```bash
28source build/envsetup.sh
29lunch aosp_cf_x86_64_phone-userdebug
30m root-canal
31./out/host/linux-x86/bin/root-canal
32```
33Note: You can also find a prebuilt version inside
34[cvd-host_package.tar.gz from Android CI][cvd-host_package]
35The following configuration options are implemented:
36
37* `--test_port` (default `6401`) Configure the TCP port for the test channel.
38
39* `--hci_port` (default `6402`) Configure the TCP port for the HCI server.
40
41* `--link_port` (default `6403`) Configure the TCP port for the link server.
42
43* `--link_ble_port` (default `6404`) Configure the TCP port for the BLE link server.
44
45* `--controller_properties_file` (default `""`) Configure the path to
46a custom Controller configuration file. All properties defined in
47`model/controller/controller_properties.h` can be edited to test with a
48specific controller setup.
49
50* `--enable_hci_sniffer` (default `false`) Capture PCAP traces for all
51connected HCI hosts. The PCAP traces are saved in the current directory.
52
53* `--enable_baseband_sniffer` (default `false`) Capture PCAP traces for all
54base-band packets exchanged between connection HCI hosts. The PCAP traces are
55saved in the current directory. This option is useful to inspect and debug
56RootCanal's implementation.
57
58# Architecture
59
60All RootCanal instances expose four TCP ports:
61- _HCI channel_
62- _Test channel_
63- _BR_EDR Phy channel_
64- _LE Phy channel_
65
66## HCI Channel
67
68The HCI channel implements the Bluetooth UART transport protocol
69(a.k.a. H4) over TCP. Each new connection on the HCI port spawns a new virtual
70controller.
71
72## Test Channel
73
74The test channel uses a simple custom protocol to send control commands
75to RootCanal. You can connect to it using [scripts/test_channel.py](scripts/test_channel.py).
76
77### Phy Channels
78
79The physical channels use a custom protocol described in [packets/link_layer_packets.pdl](packets/link_layer_packets.pdl).
80The protocol simplifies the LL and LMP protocol packets defined in the Bluetooth
81specification to abstract over negotiation details.
82
83**Warning** The protocol can change in backward incompatible ways,
84be careful when depending on it.
85
86Controllers can exchanges link layer packets only when they are part of the
87same phy. One controller can be added to multiple phys, the simplest example
88begin BR/EDR and LE dual phys.
89
90# Links
91
92[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
93