1.. _module-pw_bluetooth: 2 3================ 4pw_bluetooth 5================ 6The ``pw_bluetooth`` module contains APIs and utilities for the host layer of 7Bluetooth Low Energy. 8 9-------- 10Host API 11-------- 12.. attention:: 13 14 This module is still under construction, the API is not yet stable. 15 16The headers in `public/pw_bluetooth` constitute a Bluetooth Host API. `host.h` 17is the entry point from which all other APIs are exposed. Currently, only Low 18Energy APIs exist. 19 20Host 21==== 22.. doxygenclass:: pw::bluetooth::Host 23 :members: 24 25low_energy::Central 26=================== 27.. doxygenclass:: pw::bluetooth::low_energy::Central 28 :members: 29 30low_energy::Peripheral 31====================== 32.. doxygenclass:: pw::bluetooth::low_energy::Peripheral 33 :members: 34 35low_energy::AdvertisedPeripheral 36================================ 37.. doxygenclass:: pw::bluetooth::low_energy::AdvertisedPeripheral 38 :members: 39 40low_energy::Connection 41====================== 42.. doxygenclass:: pw::bluetooth::low_energy::Connection 43 :members: 44 45low_energy::ConnectionOptions 46============================= 47.. doxygenstruct:: pw::bluetooth::low_energy::ConnectionOptions 48 :members: 49 50low_energy::RequestedConnectionParameters 51========================================= 52.. doxygenstruct:: pw::bluetooth::low_energy::RequestedConnectionParameters 53 :members: 54 55low_energy::ConnectionParameters 56================================ 57.. doxygenstruct:: pw::bluetooth::low_energy::ConnectionParameters 58 :members: 59 60gatt::Server 61============ 62.. doxygenclass:: pw::bluetooth::gatt::Server 63 :members: 64 65gatt::LocalServiceInfo 66====================== 67.. doxygenstruct:: pw::bluetooth::gatt::LocalServiceInfo 68 :members: 69 70gatt::LocalService 71================== 72.. doxygenclass:: pw::bluetooth::gatt::LocalService 73 :members: 74 75gatt::LocalServiceDelegate 76========================== 77.. doxygenclass:: pw::bluetooth::gatt::LocalServiceDelegate 78 :members: 79 80gatt::Client 81============ 82.. doxygenclass:: pw::bluetooth::gatt::Client 83 :members: 84 85gatt::RemoteService 86=================== 87.. doxygenclass:: pw::bluetooth::gatt::RemoteService 88 :members: 89 90Callbacks 91========= 92This module contains callback-heavy APIs. Callbacks must not call back into the 93``pw_bluetooth`` APIs unless otherwise noted. This includes calls made by 94destroying objects returned by the API. Additionally, callbacks must not block. 95 96------------------------- 97Emboss Packet Definitions 98------------------------- 99``pw_bluetooth`` contains `Emboss <https://github.com/google/emboss>`_ packet 100definitions. So far, packets from the following protocols are defined: 101 102- HCI 103 104Usage 105===== 1061. Set the `dir_pw_third_party_emboss` GN variable to the path of your Emboss 107checkout. 108 1092. Add `$dir_pw_bluetooth/emboss_hci` (for HCI packets) or 110`$dir_pw_bluetooth/emboss_vendor` (for vendor packets) to your dependency list. 111 1123. Include the generated header files. 113 114.. code-block:: cpp 115 116 #include "pw_bluetooth/hci.emb.h" 117 #include "pw_bluetooth/vendor.emb.h" 118 1194. Construct an Emboss view over a buffer. 120 121.. code-block:: cpp 122 123 std::array<uint8_t, 4> buffer = {0x00, 0x01, 0x02, 0x03}; 124 auto view = pw::bluetooth::emboss::MakeTestCommandPacketView(&buffer); 125 EXPECT_EQ(view.payload().Read(), 0x03); 126 127.. note:: 128 129 clangd will complain that the generated header file does not exist. 130 You need to build your project to resolve this. Similarly, you need to build 131 in order for .emb file updates to be reflected in the generated headers. 132 133Size Report 134=========== 135Delta of +972 when constructing the first packet view and reading/writing a 136field. This includes the runtime library and the 4-byte buffer. 137 138.. include:: emboss_size_report 139 140Delta of +96 when adding a second packet view and reading/writing a field. 141 142.. include:: emboss_size_report_diff 143 144------- 145Roadmap 146------- 147- Create a backend for the Bluetooth API using Fuchsia's Bluetooth stack 148 (sapphire). 149- Stabilize the Bluetooth API. 150- Add BR/EDR APIs. 151- Bazel support 152- CMake support 153