.. _module-pw_bluetooth_hci:

================
pw_bluetooth_hci
================
.. pigweed-module::
   :name: pw_bluetooth_hci

The ``pw_bluetooth_hci`` module contains utilities for using the Host Controller
Interface as defined by the Bluetooth Core Specification version 5.3.

-----------
HCI Packets
-----------
This module has support to parse a the subset of the HCI packets used in the HCI
UART Transport Layer are provided as defined in the Bluetooth Core Specification
version 5.3 "Host Controller Interface Transport Layer" volume 4, part A,
meaning:

* HCI Command Packet: ``pw::bluetooth_hci::CommandPacket``

* HCI ACL Data Packet: ``pw::bluetooth_hci::AsyncDataPacket``

* HCI SCO Data Packet: ``pw::bluetooth_hci::SyncDataPacket``

* HCI Event Data Packet: ``pw::bluetooth_hci::EventPacket``

------------------------
HCI UART Transport Layer
------------------------

Decoding
========
A decoder function is provided to parse HCI packets out of a HCI UART Transport
Layer buffer which may contain multiple packets.

.. cpp:function:: StatusWithSize DecodeHciUartData(ConstByteSpan data, const DecodedPacketCallback& packet_callback);

   Parses the HCI Packets out of a HCI UART Transport Layer buffer.

   Parses as many complete HCI packets out of the provided buffer based on the
   HCI UART Transport Layer as defined by Bluetooth Core Specification version
   5.3 "Host Controller Interface Transport Layer" volume 4, part A.

   The HciPacketCallback is invoked for each full HCI packet.

   Returns the number of bytes processed and a status based on:

   * OK - No invalid packet indicator found.
   * DATA_LOSS - An invalid packet indicator was detected between packets.
     Synchronization has been lost. The caller is responsible for
     regaining synchronization

   .. note::
      The caller is responsible for detecting the lack of progress due to an
      undersized data buffer and/or an invalid length field in case a full
      buffer is passed and no bytes are processed.