1.. _module-pw_bluetooth_sapphire: 2 3===================== 4pw_bluetooth_sapphire 5===================== 6.. pigweed-module:: 7 :name: pw_bluetooth_sapphire 8 9.. attention:: 10 This module is still under construction. There is no public API yet. Please 11 contact the Pigweed team if you are interested in using this module. 12 13The ``pw_bluetooth_sapphire`` module provides a dual-mode Bluetooth Host stack 14that will implement the :ref:`module-pw_bluetooth` APIs. Sapphire originated as 15the Fuchsia operating system's Bluetooth stack and is used in production. The 16Sapphire Host stack has been migrated into the Pigweed project for use in 17embedded projects. However, as it was not written in an embedded context, there 18is a lot of work to be done to optimize memory usage. 19 20Why use Sapphire? 21 22* **Open source**, unlike vendor Bluetooth stacks. This makes debugging and 23 fixing issues much easier! 24* **Integrated with Pigweed**. Logs, asserts, randomness, time, async, strings, 25 and more are all using Pigweed modules. 26* **Excellent test coverage**, unlike most Bluetooth stacks. This means fewer 27 bugs and greater maintainability. 28* **Certified**. Sapphire was certified by the Bluetooth SIG after passing 29 all conformance tests. 30* **A great API**. Coming 2024. See :ref:`module-pw_bluetooth`. 31 32--------------- 33Fuchsia support 34--------------- 35``//pw_bluetooth_sapphire/fuchsia`` currently contains a stub bt-host to 36demonstrate building, running, and testing Fuchsia components and packages with 37the Fuchsia SDK. 38 39It will eventually be filled with the real `bt-host component`_ once that's 40migrated. See https://fxbug.dev/321267390. 41 42Build the package 43================= 44To build the bt-host package, use one of the following commands: 45 46.. code-block:: 47 48 bazel build //pw_bluetooth_sapphire/fuchsia/bt_host:pkg.x64 49 # OR 50 bazel build //pw_bluetooth_sapphire/fuchsia/bt_host:pkg.arm64 51 52Start an emulator 53================= 54To run an emulator, use one of the following commands: 55 56.. code-block:: 57 58 bazel run @fuchsia_products//:core.x64.emu -- --headless 59 # OR 60 bazel run @fuchsia_products//:minimal.arm64.emu -- --headless 61 62Flash a device 63============== 64To flash a vim3, use the following command: 65 66.. code-block:: 67 68 bazel run @fuchsia_products//:core.vim3.flash -- --target <device_serial_num> 69 70Run the component 71================= 72To run the bt-host component, first provision a Fuchsia target and then use one 73of the following command: 74 75.. code-block:: 76 77 bazel run //pw_bluetooth_sapphire/fuchsia/bt_host:pkg.x64.component 78 # OR 79 bazel run //pw_bluetooth_sapphire/fuchsia/bt_host:pkg.arm64.component 80 81Run unit tests 82============== 83To run the bt-host unit tests, first start an emulator and then use the 84following command: 85 86.. code-block:: 87 88 bazel run //pw_bluetooth_sapphire/fuchsia/bt_host:test_pkg 89 90Stop the emulator 91================= 92To stop the running emulator, use the following command: 93 94.. code-block:: 95 96 pw ffx emu stop --all 97 98Add a target test to presubmits 99=============================== 100To add new test packages to presubmits, add the test package targets to 101``//pw_bluetooth_sapphire/fuchsia/BUILD.bazel``. 102 103Example: 104 105.. code-block:: 106 107 # pw_bluetooth_sapphire/fuchsia/BUILD.bazel 108 109 qemu_tests = [ 110 "//pw_bluetooth_sapphire/fuchsia/bt_host:integration_test_pkg", 111 ... 112 ] 113 114Run Fuchsia presubmit tests 115=========================== 116Presubmits for bt-host are captured in a dedicated separate builder, rather than 117existing ones such as ``pigweed-linux-bazel-noenv``. 118These presubmits can be replicated with the following command: 119 120.. code-block:: 121 122 bazel run //pw_bluetooth_sapphire/fuchsia:infra.test_all 123 124.. note:: 125 You do not need to start an emulator beforehand to to run all tests this way. 126 This test target will automatically provision one before running all tests. 127 128Uploading to CIPD 129================= 130Pigweed infrastructure uploads bt-host's artifacts to 131`fuchsia/prebuilt/bt-host`_ by building bt-host's top level infra target: 132 133.. code-block:: 134 135 # Ensure all dependencies are built. 136 bazel build //pw_bluetooth_sapphire/fuchsia:infra 137 138 # Get builder manifest file. 139 bazel build --output_groups=builder_manifest //pw_bluetooth_sapphire/fuchsia:infra 140 141The resulting file contains a ``cipd_manifests`` json field which references a 142sequence of json files specifying the CIPD package path and package file 143contents. 144 145------- 146Roadmap 147------- 148* Support Bazel (In Progress) 149* Support CMake 150* Implement :ref:`module-pw_bluetooth` APIs 151* Optimize memory footprint 152* Add snoop log capture support 153* Add metrics 154* Add configuration options (LE only, Classic only, etc.) 155* Add CLI for controlling stack over RPC 156 157.. _bt-host component: https://fuchsia.googlesource.com/fuchsia/+/refs/heads/main/src/connectivity/bluetooth/core/bt-host/ 158.. _fuchsia/prebuilt/bt-host: https://chrome-infra-packages.appspot.com/p/fuchsia/prebuilt/bt-host 159