153 lines
3.9 KiB
ReStructuredText
153 lines
3.9 KiB
ReStructuredText
.. _module-pw_bluetooth:
|
|
|
|
================
|
|
pw_bluetooth
|
|
================
|
|
The ``pw_bluetooth`` module contains APIs and utilities for the host layer of
|
|
Bluetooth Low Energy.
|
|
|
|
--------
|
|
Host API
|
|
--------
|
|
.. attention::
|
|
|
|
This module is still under construction, the API is not yet stable.
|
|
|
|
The headers in `public/pw_bluetooth` constitute a Bluetooth Host API. `host.h`
|
|
is the entry point from which all other APIs are exposed. Currently, only Low
|
|
Energy APIs exist.
|
|
|
|
Host
|
|
====
|
|
.. doxygenclass:: pw::bluetooth::Host
|
|
:members:
|
|
|
|
low_energy::Central
|
|
===================
|
|
.. doxygenclass:: pw::bluetooth::low_energy::Central
|
|
:members:
|
|
|
|
low_energy::Peripheral
|
|
======================
|
|
.. doxygenclass:: pw::bluetooth::low_energy::Peripheral
|
|
:members:
|
|
|
|
low_energy::AdvertisedPeripheral
|
|
================================
|
|
.. doxygenclass:: pw::bluetooth::low_energy::AdvertisedPeripheral
|
|
:members:
|
|
|
|
low_energy::Connection
|
|
======================
|
|
.. doxygenclass:: pw::bluetooth::low_energy::Connection
|
|
:members:
|
|
|
|
low_energy::ConnectionOptions
|
|
=============================
|
|
.. doxygenstruct:: pw::bluetooth::low_energy::ConnectionOptions
|
|
:members:
|
|
|
|
low_energy::RequestedConnectionParameters
|
|
=========================================
|
|
.. doxygenstruct:: pw::bluetooth::low_energy::RequestedConnectionParameters
|
|
:members:
|
|
|
|
low_energy::ConnectionParameters
|
|
================================
|
|
.. doxygenstruct:: pw::bluetooth::low_energy::ConnectionParameters
|
|
:members:
|
|
|
|
gatt::Server
|
|
============
|
|
.. doxygenclass:: pw::bluetooth::gatt::Server
|
|
:members:
|
|
|
|
gatt::LocalServiceInfo
|
|
======================
|
|
.. doxygenstruct:: pw::bluetooth::gatt::LocalServiceInfo
|
|
:members:
|
|
|
|
gatt::LocalService
|
|
==================
|
|
.. doxygenclass:: pw::bluetooth::gatt::LocalService
|
|
:members:
|
|
|
|
gatt::LocalServiceDelegate
|
|
==========================
|
|
.. doxygenclass:: pw::bluetooth::gatt::LocalServiceDelegate
|
|
:members:
|
|
|
|
gatt::Client
|
|
============
|
|
.. doxygenclass:: pw::bluetooth::gatt::Client
|
|
:members:
|
|
|
|
gatt::RemoteService
|
|
===================
|
|
.. doxygenclass:: pw::bluetooth::gatt::RemoteService
|
|
:members:
|
|
|
|
Callbacks
|
|
=========
|
|
This module contains callback-heavy APIs. Callbacks must not call back into the
|
|
``pw_bluetooth`` APIs unless otherwise noted. This includes calls made by
|
|
destroying objects returned by the API. Additionally, callbacks must not block.
|
|
|
|
-------------------------
|
|
Emboss Packet Definitions
|
|
-------------------------
|
|
``pw_bluetooth`` contains `Emboss <https://github.com/google/emboss>`_ packet
|
|
definitions. So far, packets from the following protocols are defined:
|
|
|
|
- HCI
|
|
|
|
Usage
|
|
=====
|
|
1. Set the `dir_pw_third_party_emboss` GN variable to the path of your Emboss
|
|
checkout.
|
|
|
|
2. Add `$dir_pw_bluetooth/emboss_hci` (for HCI packets) or
|
|
`$dir_pw_bluetooth/emboss_vendor` (for vendor packets) to your dependency list.
|
|
|
|
3. Include the generated header files.
|
|
|
|
.. code-block:: cpp
|
|
|
|
#include "pw_bluetooth/hci.emb.h"
|
|
#include "pw_bluetooth/vendor.emb.h"
|
|
|
|
4. Construct an Emboss view over a buffer.
|
|
|
|
.. code-block:: cpp
|
|
|
|
std::array<uint8_t, 4> buffer = {0x00, 0x01, 0x02, 0x03};
|
|
auto view = pw::bluetooth::emboss::MakeTestCommandPacketView(&buffer);
|
|
EXPECT_EQ(view.payload().Read(), 0x03);
|
|
|
|
.. note::
|
|
|
|
clangd will complain that the generated header file does not exist.
|
|
You need to build your project to resolve this. Similarly, you need to build
|
|
in order for .emb file updates to be reflected in the generated headers.
|
|
|
|
Size Report
|
|
===========
|
|
Delta of +972 when constructing the first packet view and reading/writing a
|
|
field. This includes the runtime library and the 4-byte buffer.
|
|
|
|
.. include:: emboss_size_report
|
|
|
|
Delta of +96 when adding a second packet view and reading/writing a field.
|
|
|
|
.. include:: emboss_size_report_diff
|
|
|
|
-------
|
|
Roadmap
|
|
-------
|
|
- Create a backend for the Bluetooth API using Fuchsia's Bluetooth stack
|
|
(sapphire).
|
|
- Stabilize the Bluetooth API.
|
|
- Add BR/EDR APIs.
|
|
- Bazel support
|
|
- CMake support
|