# RootCanal
Binding to the RootCanal controller implementation. Enables virtual testing
of Bluetooth applications directly in Python.
## Supported platforms
- `linux-x86_64`
- `macos-x86_64`
## Usage
```bash
python -m rootcanal [OPTION]
```
Command line options include:
- `-configuration` (controller configuration (see config.proto))
type: string
default: ""
- `-configuration_file` (controller configuration file path (see config.proto))
type: string default: ""
- `-disable_address_reuse` (prevent rootcanal from reusing device addresses)
type: bool default: false
- `-enable_baseband_sniffer` (enable baseband sniffer) type: bool
default: false
- `-enable_hci_sniffer` (enable hci sniffer) type: bool default: false
- `-enable_log_color` (enable log colors) type: bool default: false
- `-enable_pcap_filter` (enable PCAP filter) type: bool default: false
- `-hci_port` (hci server tcp port) type: uint32 default: 6402
- `-link_ble_port` (le link server tcp port) type: uint32 default: 6404
- `-link_port` (link server tcp port) type: uint32 default: 6403
- `-test_port` (test tcp port) type: uint32 default: 6401
## Example
Example python script to emulate a successful connection establishment
for an instance of the RootCanal controller.
```python
import asyncio
from rootcanal.controller import Controller, Any
from rootcanal.bluetooth import Address
from rootcanal.packets import hci
from rootcanal.packets import ll
from rootcanal.packets import llcp
from rootcanal.packets import lmp
async def test():
controller = Controller(Address("11:11:11:11:11:11"))
await controller.start()
# Send HCI Reset to the controller and wait for the response.
controller.send_cmd(hci.Reset())
_ = await controller.expect_evt(
hci.ResetComplete(status=hci.ErrorCode.SUCCESS, num_hci_command_packets=1)
)
# Check the local address.
controller.send_cmd(hci.ReadBdAddr())
_ = await controller.expect_evt(
hci.ReadBdAddrComplete(
status=hci.ErrorCode.SUCCESS,
num_hci_command_packets=1,
bd_addr=Address("11:11:11:11:11:11"),
)
)
# Enable page scan.
controller.send_cmd(hci.WriteScanEnable(scan_enable=hci.ScanEnable.PAGE_SCAN_ONLY))
_ = await controller.expect_evt(
hci.WriteScanEnableComplete(
status=hci.ErrorCode.SUCCESS, num_hci_command_packets=1
)
)
# Send classic connection request.
controller.send_ll(
ll.Page(
class_of_device=0,
allow_role_switch=0,
source_address=Address("22:22:22:22:22:22"),
destination_address=Address("11:11:11:11:11:11"),
)
)
_ = await controller.expect_evt(
hci.ConnectionRequest(
bd_addr=Address("22:22:22:22:22:22"),
class_of_device=0,
link_type=hci.ConnectionRequestLinkType.ACL,
)
)
# Accept the connection request.
controller.send_cmd(
hci.AcceptConnectionRequest(
bd_addr=Address("22:22:22:22:22:22"),
role=hci.AcceptConnectionRequestRole.REMAIN_PERIPHERAL,
)
)
_ = await controller.expect_evt(
hci.AcceptConnectionRequestStatus(
status=hci.ErrorCode.SUCCESS, num_hci_command_packets=1
)
)
_ = await controller.expect_ll(
ll.PageResponse(
source_address=Address("11:11:11:11:11:11"),
destination_address=Address("22:22:22:22:22:22"),
try_role_switch=0,
)
)
_ = await controller.expect_evt(
hci.ConnectionComplete(
status=hci.ErrorCode.SUCCESS,
connection_handle=Any(),
bd_addr=Address("22:22:22:22:22:22"),
link_type=hci.LinkType.ACL,
encryption_enabled=hci.Enable.DISABLED,
)
)
controller.stop()
asyncio.get_event_loop().run_until_complete(test())
```
Raw data
{
"_id": null,
"home_page": null,
"name": "rootcanal",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": "Henri Chataing <henrichataing@google.com>, David Duarte <licorne@google.com>",
"keywords": "Bluetooth, Controller, Emulation",
"author": null,
"author_email": null,
"download_url": null,
"platform": null,
"description": "# RootCanal\n\nBinding to the RootCanal controller implementation. Enables virtual testing\nof Bluetooth applications directly in Python.\n\n## Supported platforms\n\n- `linux-x86_64`\n- `macos-x86_64`\n\n## Usage\n\n```bash\npython -m rootcanal [OPTION]\n```\n\nCommand line options include:\n- `-configuration` (controller configuration (see config.proto))\n type: string\n default: \"\"\n- `-configuration_file` (controller configuration file path (see config.proto))\n type: string default: \"\"\n- `-disable_address_reuse` (prevent rootcanal from reusing device addresses)\n type: bool default: false\n- `-enable_baseband_sniffer` (enable baseband sniffer) type: bool\n default: false\n- `-enable_hci_sniffer` (enable hci sniffer) type: bool default: false\n- `-enable_log_color` (enable log colors) type: bool default: false\n- `-enable_pcap_filter` (enable PCAP filter) type: bool default: false\n- `-hci_port` (hci server tcp port) type: uint32 default: 6402\n- `-link_ble_port` (le link server tcp port) type: uint32 default: 6404\n- `-link_port` (link server tcp port) type: uint32 default: 6403\n- `-test_port` (test tcp port) type: uint32 default: 6401\n\n## Example\n\nExample python script to emulate a successful connection establishment\nfor an instance of the RootCanal controller.\n\n```python\nimport asyncio\nfrom rootcanal.controller import Controller, Any\nfrom rootcanal.bluetooth import Address\nfrom rootcanal.packets import hci\nfrom rootcanal.packets import ll\nfrom rootcanal.packets import llcp\nfrom rootcanal.packets import lmp\n\n\nasync def test():\n controller = Controller(Address(\"11:11:11:11:11:11\"))\n await controller.start()\n\n # Send HCI Reset to the controller and wait for the response.\n controller.send_cmd(hci.Reset())\n _ = await controller.expect_evt(\n hci.ResetComplete(status=hci.ErrorCode.SUCCESS, num_hci_command_packets=1)\n )\n\n # Check the local address.\n controller.send_cmd(hci.ReadBdAddr())\n _ = await controller.expect_evt(\n hci.ReadBdAddrComplete(\n status=hci.ErrorCode.SUCCESS,\n num_hci_command_packets=1,\n bd_addr=Address(\"11:11:11:11:11:11\"),\n )\n )\n\n # Enable page scan.\n controller.send_cmd(hci.WriteScanEnable(scan_enable=hci.ScanEnable.PAGE_SCAN_ONLY))\n _ = await controller.expect_evt(\n hci.WriteScanEnableComplete(\n status=hci.ErrorCode.SUCCESS, num_hci_command_packets=1\n )\n )\n\n # Send classic connection request.\n controller.send_ll(\n ll.Page(\n class_of_device=0,\n allow_role_switch=0,\n source_address=Address(\"22:22:22:22:22:22\"),\n destination_address=Address(\"11:11:11:11:11:11\"),\n )\n )\n _ = await controller.expect_evt(\n hci.ConnectionRequest(\n bd_addr=Address(\"22:22:22:22:22:22\"),\n class_of_device=0,\n link_type=hci.ConnectionRequestLinkType.ACL,\n )\n )\n\n # Accept the connection request.\n controller.send_cmd(\n hci.AcceptConnectionRequest(\n bd_addr=Address(\"22:22:22:22:22:22\"),\n role=hci.AcceptConnectionRequestRole.REMAIN_PERIPHERAL,\n )\n )\n _ = await controller.expect_evt(\n hci.AcceptConnectionRequestStatus(\n status=hci.ErrorCode.SUCCESS, num_hci_command_packets=1\n )\n )\n\n _ = await controller.expect_ll(\n ll.PageResponse(\n source_address=Address(\"11:11:11:11:11:11\"),\n destination_address=Address(\"22:22:22:22:22:22\"),\n try_role_switch=0,\n )\n )\n\n _ = await controller.expect_evt(\n hci.ConnectionComplete(\n status=hci.ErrorCode.SUCCESS,\n connection_handle=Any(),\n bd_addr=Address(\"22:22:22:22:22:22\"),\n link_type=hci.LinkType.ACL,\n encryption_enabled=hci.Enable.DISABLED,\n )\n )\n\n controller.stop()\n\n\nasyncio.get_event_loop().run_until_complete(test())\n```\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Virtual Bluetooth controller",
"version": "1.10.0",
"project_urls": {
"Bug Tracker": "https://github.com/google/rootcanal/issues",
"Homepage": "https://github.com/google/rootcanal"
},
"split_keywords": [
"bluetooth",
" controller",
" emulation"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "f6216d3b4f6d1b581c17c9252f5641ff97473a30dd9db3eacaecf6ac7f3d19e5",
"md5": "fb9b270d0f7d8ee805c3610f47fdfdce",
"sha256": "a3e8b451e1c2c9f7e118ed206d15167b1f3f0c7b55453f7b6eb016f2a99dc082"
},
"downloads": -1,
"filename": "rootcanal-1.10.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "fb9b270d0f7d8ee805c3610f47fdfdce",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 19690453,
"upload_time": "2024-03-25T20:30:38",
"upload_time_iso_8601": "2024-03-25T20:30:38.207910Z",
"url": "https://files.pythonhosted.org/packages/f6/21/6d3b4f6d1b581c17c9252f5641ff97473a30dd9db3eacaecf6ac7f3d19e5/rootcanal-1.10.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-25 20:30:38",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "google",
"github_project": "rootcanal",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "rootcanal"
}
JSON
