xref: /aosp_15_r20/external/pigweed/pw_bluetooth_hci/docs.rst (revision 61c4878ac05f98d0ceed94b57d316916de578985) 
1.. _module-pw_bluetooth_hci:
2
3================
4pw_bluetooth_hci
5================
6.. pigweed-module::
7   :name: pw_bluetooth_hci
8
9The ``pw_bluetooth_hci`` module contains utilities for using the Host Controller
10Interface as defined by the Bluetooth Core Specification version 5.3.
11
12-----------
13HCI Packets
14-----------
15This module has support to parse a the subset of the HCI packets used in the HCI
16UART Transport Layer are provided as defined in the Bluetooth Core Specification
17version 5.3 "Host Controller Interface Transport Layer" volume 4, part A,
18meaning:
19
20* HCI Command Packet: ``pw::bluetooth_hci::CommandPacket``
21
22* HCI ACL Data Packet: ``pw::bluetooth_hci::AsyncDataPacket``
23
24* HCI SCO Data Packet: ``pw::bluetooth_hci::SyncDataPacket``
25
26* HCI Event Data Packet: ``pw::bluetooth_hci::EventPacket``
27
28------------------------
29HCI UART Transport Layer
30------------------------
31
32Decoding
33========
34A decoder function is provided to parse HCI packets out of a HCI UART Transport
35Layer buffer which may contain multiple packets.
36
37.. cpp:function:: StatusWithSize DecodeHciUartData(ConstByteSpan data, const DecodedPacketCallback& packet_callback);
38
39   Parses the HCI Packets out of a HCI UART Transport Layer buffer.
40
41   Parses as many complete HCI packets out of the provided buffer based on the
42   HCI UART Transport Layer as defined by Bluetooth Core Specification version
43   5.3 "Host Controller Interface Transport Layer" volume 4, part A.
44
45   The HciPacketCallback is invoked for each full HCI packet.
46
47   Returns the number of bytes processed and a status based on:
48
49   * OK - No invalid packet indicator found.
50   * DATA_LOSS - An invalid packet indicator was detected between packets.
51     Synchronization has been lost. The caller is responsible for
52     regaining synchronization
53
54   .. note::
55      The caller is responsible for detecting the lack of progress due to an
56      undersized data buffer and/or an invalid length field in case a full
57      buffer is passed and no bytes are processed.
58