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.

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

RootCanal can be natively built or installed pre-compiled though the PyPI rootcanal package. Both options have been tested with linux-x86_64 and macos-arm64, windows is not yet supported.

Build instructions

sudo apt install bazel rustc cargo
cargo install pdl-compiler --version 0.3.2

git clone https://github.com/google/rootcanal.git
cd rootcanal
git submodule update --init
bazel run :rootcanal

Python instructions

pip install rootcanal
python -m rootcanal

Launch options

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. The format of the configuration file is defined by proto/rootcanal/configuration.proto

• --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.

Phy Channels

The physical channels use a custom protocol described in 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.

Supported features

HCI Commands

| Command name | Supported | |--------------------------------------------------------------|---------------| | Inquiry | Yes | | Inquiry Cancel | Yes | | Periodic Inquiry Mode | No | | Exit Periodic Inquiry Mode | No | | Create Connection | Yes | | Disconnect | Yes | | Add Sco Connection | Yes | | Create Connection Cancel | Yes | | Accept Connection Request | Yes | | Reject Connection Request | Yes | | Link Key Request Reply | Yes | | Link Key Request Negative Reply | Yes | | Pin Code Request Reply | Yes | | Pin Code Request Negative Reply | Yes | | Change Connection Packet Type | Yes | | Authentication Requested | Yes | | Set Connection Encryption | Yes | | Change Connection Link Key | Yes | | Central Link Key | Yes | | Remote Name Request | Yes | | Remote Name Request Cancel | No | | Read Remote Supported Features | Yes | | Read Remote Extended Features | Yes | | Read Remote Version Information | Yes | | Read Clock Offset | Yes | | Read Lmp Handle | No | | Setup Synchronous Connection | Yes | | Accept Synchronous Connection | Yes | | Reject Synchronous Connection | Yes | | Io Capability Request Reply | Yes | | User Confirmation Request Reply | Yes | | User Confirmation Request Negative Reply | Yes | | User Passkey Request Reply | Yes | | User Passkey Request Negative Reply | Yes | | Remote Oob Data Request Reply | Yes | | Remote Oob Data Request Negative Reply | Yes | | Io Capability Request Negative Reply | Yes | | Enhanced Setup Synchronous Connection | Yes | | Enhanced Accept Synchronous Connection | Yes | | Truncated Page | No | | Truncated Page Cancel | No | | Set Connectionless Peripheral Broadcast | No | | Set Connectionless Peripheral Broadcast Receive | No | | Start Synchronization Train | No | | Receive Synchronization Train | No | | Remote Oob Extended Data Request Reply | Yes | | Hold Mode | Yes | | Sniff Mode | Yes | | Exit Sniff Mode | Yes | | Qos Setup | Yes | | Role Discovery | Yes | | Switch Role | Yes | | Read Link Policy Settings | Yes | | Write Link Policy Settings | Yes | | Read Default Link Policy Settings | Yes | | Write Default Link Policy Settings | Yes | | Flow Specification | Yes | | Sniff Subrating | Yes | | Set Event Mask | Yes | | Reset | Yes | | Set Event Filter | Yes | | Flush | No | | Read Pin Type | No | | Write Pin Type | No | | Read Stored Link Key | No | | Write Stored Link Key | No | | Delete Stored Link Key | Yes | | Write Local Name | Yes | | Read Local Name | Yes | | Read Connection Accept Timeout | Yes | | Write Connection Accept Timeout | Yes | | Read Page Timeout | Yes | | Write Page Timeout | Yes | | Read Scan Enable | Yes | | Write Scan Enable | Yes | | Read Page Scan Activity | Yes | | Write Page Scan Activity | Yes | | Read Inquiry Scan Activity | Yes | | Write Inquiry Scan Activity | Yes | | Read Authentication Enable | Yes | | Write Authentication Enable | Yes | | Read Class Of Device