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 2025. See :ref:`module-pw_bluetooth`. 31 32------------ 33Architecture 34------------ 35 36Sapphire is composed of multiple libraries that implement different protocols 37in the Core specification. These libraries include: 38 39HCI: Host-Controller Interface 40 Processes data (ACL), command, and event packets exchanged between the host 41 and the controller. Note that HCI is currently split into ``hci``, 42 ``transport``, and ``hci-spec`` libraries. 43 44L2CAP: Logical Link Control and Adaptation Layer Protocol 45 Multiplexes a single ACL connection into multiple channels and manages 46 channel configuration and flow control. 47 48SDP: Service Discovery Protocol 49 Serves the BR/EDR service database and searches peers for BR/EDR services. 50 51SM: Security Manager 52 Implements LE security, including pairing. 53 54ATT: Attribute Protocol 55 Implements the ATT protocol PDUs, flow control, and database. 56 57GATT: Generic Attribute Profile 58 Implements the GATT server and client. 59 60GAP: Generic Access Profile 61 Responsible for device discovery and connection functionality. 62 63SCO: Synchronous Connection Oriented link 64 Used for audio data by the Hands-Free Profile. 65 66ISO: Isochronous Channels 67 Used for audio data in LE Audio. 68 69These libraries build on top of each other as shown in the following diagram. 70HCI is the foundation, L2CAP builds on top of HCI, ATT builds on top of L2CAP, 71etc. 72 73.. mermaid:: 74 :alt: Sapphire architecture 75 76 flowchart TB 77 subgraph HCI["HCI"] 78 TRA["Transport"] 79 HCI2["HCI"] 80 SPEC["HCI-Spec"] 81 CONT["Controllers"] 82 end 83 subgraph Host["Host"] 84 COM["Common"] 85 GATT["GATT"] 86 ISO["ISO"] 87 SCO["SCO"] 88 SM["SM"] 89 L2CAP["L2CAP"] 90 SDP["SDP"] 91 GAP["GAP"] 92 ATT["ATT"] 93 HCI 94 end 95 GAP --> GATT & ISO & SCO & SM & L2CAP & SDP & HCI2 96 GATT --> ATT 97 ATT --> L2CAP 98 L2CAP --> TRA 99 SCO --> HCI2 & TRA 100 SM --> L2CAP 101 SDP --> L2CAP 102 ISO --> TRA 103 HCI2 --> TRA 104 TRA --> CONT 105 CONT -- UART/USB --> Controller["Controller"] 106 107 108------------- 109Certification 110------------- 111The Sapphire Host stack was certified as implementing the Bluetooth Core 112Specification 5.0 by the Bluetooth SIG in 2020 as "Google Sapphire 1.0 113Bluetooth Core Host Solution". You can find its public listing and add it to 114your product certification at the `Qualification Workspace 115<https://qualification.bluetooth.com/ListingDetails/112941>`_. 116 117------------------------- 118Products running Sapphire 119------------------------- 120Sapphire is running on millions of the following devices: 121 122* Google Nest Hub (1st Gen) 123* Google Nest Hub (2nd Gen) 124* Google Nest Hub Max 125 126------------------ 127Supported features 128------------------ 129 130GAP 131=== 132.. include:: host/gap/docs.rst 133 :start-after: .. supported-features-start 134 :end-before: .. supported-features-end 135 136L2CAP 137===== 138.. include:: host/l2cap/docs.rst 139 :start-after: .. supported-features-start 140 :end-before: .. supported-features-end 141 142ATT 143=== 144.. include:: host/att/docs.rst 145 :start-after: .. supported-features-start 146 :end-before: .. supported-features-end 147 148------------ 149Contributing 150------------ 151 152.. _module-pw_bluetooth_sapphire-building: 153 154Building 155======== 156The following commands will build test binaries for the host platform. The 157tests use GoogleTest so they are not supported by the default build 158configuration. 159 160.. tab-set:: 161 162 .. tab-item:: Bazel 163 164 .. code-block:: console 165 166 bazelisk build --config googletest //pw_bluetooth_sapphire/host/... 167 168 .. tab-item:: GN 169 170 First, install the boringssl, emboss, and googletest packages with ``pw package``. 171 172 .. code-block:: console 173 174 pw package install boringssl 175 pw package install emboss 176 pw package install googletest 177 178 Next, configure the GN args for all of the packages and backends that 179 Sapphire uses. For example: 180 181 .. code-block:: console 182 183 gn args out 184 185 .. code-block:: console 186 187 dir_pw_third_party_boringssl = "/path/to/pigweed/.environment/packages/boringssl" 188 dir_pw_third_party_emboss = "/path/to/pigweed/.environment/packages/emboss" 189 dir_pw_third_party_googletest = "/path/to/pigweed/.environment/packages/googletest" 190 pw_bluetooth_sapphire_ENABLED = true 191 pw_unit_test_MAIN = "//third_party/googletest:gmock_main" 192 pw_unit_test_BACKEND = "//pw_unit_test:googletest" 193 pw_function_CONFIG = "//pw_function:enable_dynamic_allocation" 194 pw_chrono_SYSTEM_CLOCK_BACKEND = "//pw_chrono_stl:system_clock" 195 pw_chrono_SYSTEM_TIMER_BACKEND = "//pw_chrono_stl:system_timer" 196 pw_async_TASK_BACKEND = "//pw_async_basic:task" 197 pw_async_FAKE_DISPATCHER_BACKEND = "//pw_async_basic:fake_dispatcher" 198 199 Finally, build with ``pw watch``. 200 201Running tests 202============= 203.. tab-set:: 204 205 .. tab-item:: Bazel 206 207 Run all tests: 208 209 .. code-block:: console 210 211 bazelisk test --config googletest //pw_bluetooth_sapphire/host/... 212 213 Run l2cap tests with a test filter, logs, and log level filter: 214 215 .. code-block:: console 216 217 bazelisk test --config googletest //pw_bluetooth_sapphire/host/l2cap:l2cap_test \ 218 --test_arg=--gtest_filter="*InboundChannelFailure" \ 219 --test_output=all \ 220 --copt=-DPW_LOG_LEVEL_DEFAULT=PW_LOG_LEVEL_ERROR 221 222 .. tab-item:: GN 223 224 The easiest way to run GN tests is with ``pw presubmit``, which will install 225 dependencies and set GN args correctly. 226 227 .. code-block:: console 228 229 $ pw presubmit --step gn_chre_googletest_nanopb_sapphire_build 230 231 You can also use ``pw watch`` if you install required packages and set 232 your GN args as described in the :ref:`Building 233 <module-pw_bluetooth_sapphire-building>` section. 234 235Clangd support 236============== 237In order to use :ref:`module-pw_ide` to generate a compilation database for 238Clangd, you must first configure your GN args as described in the 239:ref:`Building <module-pw_bluetooth_sapphire-building>` GN tab. 240 241------- 242Roadmap 243------- 244* Support CMake 245* Implement :ref:`module-pw_bluetooth` APIs 246* Optimize memory footprint 247* Add metrics 248* Add configuration options (LE only, Classic only, etc.) 249* Add CLI for controlling stack over RPC 250 251.. toctree:: 252 :maxdepth: 1 253 254 fuchsia 255 size_report 256 reference 257 258.. _fuchsia/prebuilt/bt-host: https://chrome-infra-packages.appspot.com/p/fuchsia/prebuilt/bt-host 259.. _fuchsia/prebuilt/bt-hci-virtual: https://chrome-infra-packages.appspot.com/p/fuchsia/prebuilt/bt-hci-virtual 260.. _pigweed-linux-bazel-bthost: https://ci.chromium.org/ui/p/pigweed/builders/pigweed.ci/pigweed-linux-bazel-bthost 261.. _GN presubmit step: https://cs.opensource.google/pigweed/pigweed/+/main:pw_presubmit/py/pw_presubmit/pigweed_presubmit.py?q=gn_chre_googletest_nanopb_sapphire_build 262