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 generic interfaces and types 20for a Bluetooth Host API. Currently, only Low Energy APIs exist. 21 22low_energy::Central2 23==================== 24.. doxygenclass:: pw::bluetooth::low_energy::Central2 25 :members: 26 27low_energy::Peripheral2 28======================= 29.. doxygenclass:: pw::bluetooth::low_energy::Peripheral2 30 :members: 31 32low_energy::AdvertisedPeripheral2 33================================= 34.. doxygenclass:: pw::bluetooth::low_energy::AdvertisedPeripheral2 35 :members: 36 37low_energy::Connection2 38======================= 39.. doxygenclass:: pw::bluetooth::low_energy::Connection2 40 :members: 41 42low_energy::Channel 43=================== 44.. doxygenclass:: pw::bluetooth::low_energy::Channel 45 :members: 46 47 48low_energy::ChannelListenerRegistry 49=================================== 50.. doxygenclass:: pw::bluetooth::low_energy::ChannelListenerRegistry 51 :members: 52 53low_energy::ChannelListener 54=================================== 55.. doxygenclass:: pw::bluetooth::low_energy::ChannelListener 56 :members: 57 58gatt::Server2 59============= 60.. doxygenclass:: pw::bluetooth::gatt::Server2 61 :members: 62 63gatt::LocalService2 64=================== 65.. doxygenclass:: pw::bluetooth::gatt::LocalService2 66 :members: 67 68gatt::LocalServiceDelegate2 69=========================== 70.. doxygenclass:: pw::bluetooth::gatt::LocalServiceDelegate2 71 :members: 72 73gatt::Client2 74============= 75.. doxygenclass:: pw::bluetooth::gatt::Client2 76 :members: 77 78gatt::RemoteService2 79==================== 80.. doxygenclass:: pw::bluetooth::gatt::RemoteService2 81 :members: 82 83Controller2 84=========== 85.. doxygenclass:: pw::bluetooth::Controller2 86 :members: 87 88---------------------------- 89Module Configuration Options 90---------------------------- 91The following configurations can be adjusted via compile-time configuration of 92this module, see the 93:ref:`module documentation <module-structure-compile-time-configuration>` for 94more details. 95 96.. c:macro:: PW_BLUETOOTH_DESCRIPTOR_VEC_SIZE 97 98 Controls the size of ``Vector<Descriptor>`` in the above APIs. 99 100------------------------- 101Emboss Packet Definitions 102------------------------- 103``pw_bluetooth`` contains `Emboss <https://github.com/google/emboss>`_ packet 104definitions. So far, some packets and enums from the following protocols are 105defined: 106 107- HCI 108- L2CAP 109- H4 110 111.. _module-pw_bluetooth-usage: 112 113Usage 114===== 1151. Add Emboss to your project as described in 116 :ref:`module-pw_third_party_emboss`. 117 118.. tab-set:: 119 120 .. tab-item:: Bazel 121 :sync: bazel 122 123 2. Add the Emboss target you require to your build target's dependency 124 list - for example, ``@pigweed//pw_bluetooth:emboss_hci_group`` for HCI 125 packets. 126 127 .. tab-item:: GN 128 :sync: gn 129 130 2. Add the Emboss target you require to your build target's dependency 131 list - for example, ``$dir_pw_bluetooth/emboss_hci_group`` for HCI 132 packets. 133 134 .. tab-item:: CMake 135 :sync: cmake 136 137 2. Add the Emboss target you require to your build target's dependency 138 list - for example, ``pw_bluetooth.emboss_hci_group`` for HCI packets. 139 140 1413. Include the generated header files you require in your source files. 142 143.. code-block:: cpp 144 145 #include "pw_bluetooth/hci_commands.emb.h" 146 #include "pw_bluetooth/hci_android.emb.h" 147 148.. inclusive-language: disable 149 1504. Construct an Emboss view over a buffer as described in the `Emboss User Guide 151 <https://github.com/google/emboss/blob/master/doc/guide.md>`_. 152 153.. inclusive-language: enable 154 155.. literalinclude:: emboss_test.cc 156 :language: cpp 157 :start-after: [pw_bluetooth-examples-make_view] 158 :end-before: [pw_bluetooth-examples-make_view] 159 160.. note:: 161 162 When you first add generated headers, ``clangd`` may complain that the 163 generated header files do not exist. You need to build your project to 164 resolve this. Similarly, you need to rebuild in order for .emb file updates 165 to be reflected in the generated headers. 166 167.. _module-pw_bluetooth-contributing: 168 169Contributing 170============ 171Emboss ``.emb`` files can be edited to add additional packets and enums. 172 173Emboss files should be formatted by running the following from the Pigweed root. 174 175.. code-block:: bash 176 177 (export EMBOSS_PATH="environment/packages/emboss" && 178 export PYTHONPATH+=":${EMBOSS_PATH}" && 179 python3 "${EMBOSS_PATH}/compiler/front_end/format.py" pw_bluetooth/public/pw_bluetooth/*.emb) 180 181If adding files, be sure to update the GN, Bazel, and CMake build rules. 182Presubmit runs the ``emboss_test.cc`` test on all three. 183 184 185Size Report 186=========== 187Delta of +972 when constructing the first packet view and reading/writing a 188field. This includes the runtime library and the 4-byte buffer. 189 190.. include:: emboss_size_report 191 192Delta of +96 when adding a second packet view and reading/writing a field. 193 194.. include:: emboss_size_report_diff 195 196------- 197Roadmap 198------- 199- Bluetooth Proxy (WIP in in :ref:`module-pw_bluetooth_proxy`) 200- Add automated Emboss file formatting to `pw format` (:bug:`331195584`) 201- Create a backend for the Bluetooth API using Fuchsia's Bluetooth stack 202 (Sapphire). 203- Stabilize the Bluetooth API. 204- Add BR/EDR APIs. 205