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 //pw_bluetooth_sapphire/host/... \ 167 --platforms=//pw_unit_test:googletest_platform \ 168 --@pigweed//pw_unit_test:backend=@pigweed//pw_unit_test:googletest 169 170 .. tab-item:: GN 171 172 First, install the boringssl, emboss, and googletest packages with ``pw package``. 173 174 .. code-block:: console 175 176 pw package install boringssl 177 pw package install emboss 178 pw package install googletest 179 180 Next, configure the GN args for all of the packages and backends that 181 Sapphire uses. For example: 182 183 .. code-block:: console 184 185 gn args out 186 187 .. code-block:: console 188 189 dir_pw_third_party_boringssl = "/path/to/pigweed/.environment/packages/boringssl" 190 dir_pw_third_party_emboss = "/path/to/pigweed/.environment/packages/emboss" 191 dir_pw_third_party_googletest = "/path/to/pigweed/.environment/packages/googletest" 192 pw_bluetooth_sapphire_ENABLED = true 193 pw_unit_test_MAIN = "//third_party/googletest:gmock_main" 194 pw_unit_test_BACKEND = "//pw_unit_test:googletest" 195 pw_function_CONFIG = "//pw_function:enable_dynamic_allocation" 196 pw_chrono_SYSTEM_CLOCK_BACKEND = "//pw_chrono_stl:system_clock" 197 pw_chrono_SYSTEM_TIMER_BACKEND = "//pw_chrono_stl:system_timer" 198 pw_async_TASK_BACKEND = "//pw_async_basic:task" 199 pw_async_FAKE_DISPATCHER_BACKEND = "//pw_async_basic:fake_dispatcher" 200 201 Finally, build with ``pw watch``. 202 203Running tests 204============= 205.. tab-set:: 206 207 .. tab-item:: Bazel 208 209 Run all tests: 210 211 .. code-block:: console 212 213 bazelisk test //pw_bluetooth_sapphire/host/... \ 214 --platforms=//pw_unit_test:googletest_platform \ 215 --@pigweed//pw_unit_test:backend=@pigweed//pw_unit_test:googletest 216 217 Run l2cap tests with a test filter, logs, and log level filter: 218 219 .. code-block:: console 220 221 bazelisk test //pw_bluetooth_sapphire/host/l2cap:l2cap_test \ 222 --platforms=//pw_unit_test:googletest_platform \ 223 --@pigweed//pw_unit_test:backend=@pigweed//pw_unit_test:googletest \ 224 --test_arg=--gtest_filter="*InboundChannelFailure" \ 225 --test_output=all \ 226 --copt=-DPW_LOG_LEVEL_DEFAULT=PW_LOG_LEVEL_ERROR 227 228 .. tab-item:: GN 229 230 The easiest way to run GN tests is with ``pw presubmit``, which will install 231 dependencies and set GN args correctly. 232 233 .. code-block:: console 234 235 $ pw presubmit --step gn_chre_googletest_nanopb_sapphire_build 236 237 You can also use ``pw watch`` if you install required packages and set 238 your GN args as described in the :ref:`Building 239 <module-pw_bluetooth_sapphire-building>` section. 240 241Clangd support 242============== 243In order to use :ref:`module-pw_ide` to generate a compilation database for 244Clangd, you must first configure your GN args as described in the 245:ref:`Building <module-pw_bluetooth_sapphire-building>` GN tab. 246 247------- 248Roadmap 249------- 250* Support CMake 251* Implement :ref:`module-pw_bluetooth` APIs 252* Optimize memory footprint 253* Add snoop log capture support 254* Add metrics 255* Add configuration options (LE only, Classic only, etc.) 256* Add CLI for controlling stack over RPC 257 258.. toctree:: 259 :maxdepth: 1 260 261 fuchsia 262 size_report 263 reference 264 265.. _fuchsia/prebuilt/bt-host: https://chrome-infra-packages.appspot.com/p/fuchsia/prebuilt/bt-host 266.. _fuchsia/prebuilt/bt-hci-virtual: https://chrome-infra-packages.appspot.com/p/fuchsia/prebuilt/bt-hci-virtual 267.. _pigweed-linux-bazel-bthost: https://ci.chromium.org/ui/p/pigweed/builders/pigweed.ci/pigweed-linux-bazel-bthost 268.. _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 269