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