1.. _module-pw_bluetooth: 2 3============ 4pw_bluetooth 5============ 6.. pigweed-module:: 7 :name: pw_bluetooth 8 9The ``pw_bluetooth`` module contains APIs and utilities for the host layer of 10Bluetooth Low Energy. 11 12-------- 13Host API 14-------- 15.. attention:: 16 17 This module is still under construction, the API is not yet stable. 18 19The headers in `public/pw_bluetooth` constitute a Bluetooth Host API. `host.h` 20is the entry point from which all other APIs are exposed. Currently, only Low 21Energy APIs exist. 22 23Host 24==== 25.. doxygenclass:: pw::bluetooth::Host 26 :members: 27 28low_energy::Central 29=================== 30.. doxygenclass:: pw::bluetooth::low_energy::Central 31 :members: 32 33low_energy::Peripheral 34====================== 35.. doxygenclass:: pw::bluetooth::low_energy::Peripheral 36 :members: 37 38low_energy::AdvertisedPeripheral 39================================ 40.. doxygenclass:: pw::bluetooth::low_energy::AdvertisedPeripheral 41 :members: 42 43low_energy::Connection 44====================== 45.. doxygenclass:: pw::bluetooth::low_energy::Connection 46 :members: 47 48low_energy::ConnectionOptions 49============================= 50.. doxygenstruct:: pw::bluetooth::low_energy::ConnectionOptions 51 :members: 52 53low_energy::RequestedConnectionParameters 54========================================= 55.. doxygenstruct:: pw::bluetooth::low_energy::RequestedConnectionParameters 56 :members: 57 58low_energy::ConnectionParameters 59================================ 60.. doxygenstruct:: pw::bluetooth::low_energy::ConnectionParameters 61 :members: 62 63gatt::Server 64============ 65.. doxygenclass:: pw::bluetooth::gatt::Server 66 :members: 67 68gatt::LocalServiceInfo 69====================== 70.. doxygenstruct:: pw::bluetooth::gatt::LocalServiceInfo 71 :members: 72 73gatt::LocalService 74================== 75.. doxygenclass:: pw::bluetooth::gatt::LocalService 76 :members: 77 78gatt::LocalServiceDelegate 79========================== 80.. doxygenclass:: pw::bluetooth::gatt::LocalServiceDelegate 81 :members: 82 83gatt::Client 84============ 85.. doxygenclass:: pw::bluetooth::gatt::Client 86 :members: 87 88gatt::RemoteService 89=================== 90.. doxygenclass:: pw::bluetooth::gatt::RemoteService 91 :members: 92 93Callbacks 94========= 95This module contains callback-heavy APIs. Callbacks must not call back into the 96``pw_bluetooth`` APIs unless otherwise noted. This includes calls made by 97destroying objects returned by the API. Additionally, callbacks must not block. 98 99------------------------- 100Emboss Packet Definitions 101------------------------- 102``pw_bluetooth`` contains `Emboss <https://github.com/google/emboss>`_ packet 103definitions. So far, some packets and enums from the following protocols are 104defined: 105 106- HCI 107- L2CAP 108- H4 109 110.. _module-pw_bluetooth-usage: 111 112Usage 113===== 1141. Add Emboss to your project as described in 115 :ref:`module-pw_third_party_emboss`. 116 117.. tab-set:: 118 119 .. tab-item:: Bazel 120 :sync: bazel 121 122 2. Add the Emboss target you require to your build target's dependency 123 list - for example, ``@pigweed//pw_bluetooth:emboss_hci_group`` for HCI 124 packets. 125 126 .. tab-item:: GN 127 :sync: gn 128 129 2. Add the Emboss target you require to your build target's dependency 130 list - for example, ``$dir_pw_bluetooth/emboss_hci_group`` for HCI 131 packets. 132 133 .. tab-item:: CMake 134 :sync: cmake 135 136 2. Add the Emboss target you require to your build target's dependency 137 list - for example, ``pw_bluetooth.emboss_hci_group`` for HCI packets. 138 139 1403. Include the generated header files you require in your source files. 141 142.. code-block:: cpp 143 144 #include "pw_bluetooth/hci_commands.emb.h" 145 #include "pw_bluetooth/hci_android.emb.h" 146 147.. inclusive-language: disable 148 1494. Construct an Emboss view over a buffer as described in the `Emboss User Guide 150 <https://github.com/google/emboss/blob/master/doc/guide.md>`_. 151 152.. inclusive-language: enable 153 154.. literalinclude:: emboss_test.cc 155 :language: cpp 156 :start-after: [pw_bluetooth-examples-make_view] 157 :end-before: [pw_bluetooth-examples-make_view] 158 159.. note:: 160 161 When you first add generated headers, ``clangd`` may complain that the 162 generated header files do not exist. You need to build your project to 163 resolve this. Similarly, you need to rebuild in order for .emb file updates 164 to be reflected in the generated headers. 165 166.. _module-pw_bluetooth-contributing: 167 168Contributing 169============ 170Emboss ``.emb`` files can be edited to add additional packets and enums. 171 172Emboss files should be formatted by running the following from the Pigweed root. 173 174.. code-block:: bash 175 176 (export EMBOSS_PATH="environment/packages/emboss" && 177 export PYTHONPATH+=":${EMBOSS_PATH}" && 178 python3 "${EMBOSS_PATH}/compiler/front_end/format.py" pw_bluetooth/public/pw_bluetooth/*.emb) 179 180If adding files, be sure to update the GN, Bazel, and CMake build rules. 181Presubmit runs the ``emboss_test.cc`` test on all three. 182 183 184Size Report 185=========== 186Delta of +972 when constructing the first packet view and reading/writing a 187field. This includes the runtime library and the 4-byte buffer. 188 189.. include:: emboss_size_report 190 191Delta of +96 when adding a second packet view and reading/writing a field. 192 193.. include:: emboss_size_report_diff 194 195------- 196Roadmap 197------- 198- Bluetooth Proxy (WIP in in :ref:`module-pw_bluetooth_proxy`) 199- Add automated Emboss file formatting to `pw format` (`b/331195584 <https://pwbug.dev/331195584>`_) 200- Create a backend for the Bluetooth API using Fuchsia's Bluetooth stack 201 (Sapphire). 202- Stabilize the Bluetooth API. 203- Add BR/EDR APIs. 204