Exigences HCI

L'interface de contrôleur hôte (HCI) est utilisée pour interagir avec un contrôleur Bluetooth.

Ce document fournit une liste des exigences HCI Bluetooth (BT) et Bluetooth Low Energy (BLE). L'objectif est que les fournisseurs de piles Host BT et les fournisseurs de contrôleurs BT se conforment à ces exigences de plate-forme afin d'utiliser l'ensemble de fonctionnalités décrit ci-dessous.

Ce document fait référence à la spécification Bluetooth Core 5.2 en tant que « spécification ». La spécification Bluetooth Core 5.2 est disponible sur le site Web Bluetooth SIG avec d'autres documents adoptés.

Présentation générale de la conception

Capacités et configuration de la puce

En tant que plate-forme ouverte, Android dispose d'une matrice de versions de logiciels, d'OEM, de fournisseurs et de capacités de plate-forme et de puce.

Pour gérer le paysage variable et gérer les migrations, une philosophie de conception permettant aux contrôleurs BT d'exposer leurs capacités (au-delà de la spécification Bluetooth Core 5.2 standard) est décrite dans ce document. La pile BT hôte peut ensuite utiliser ces fonctionnalités pour déterminer les fonctionnalités à activer.

Prise en charge des normes ouvertes

L'un des objectifs d'Android est de prendre en charge les normes ouvertes après ratification dans une spécification Bluetooth. Si une fonctionnalité décrite ci-dessous devient disponible dans les méthodes HCI standard dans une future spécification Bluetooth, nous pencherons pour faire de cette approche la valeur par défaut.

Capacités spécifiques au fournisseur

Commande spécifique au fournisseur : LE_Get_Vendor_Capabilities_Command

Champ de commande OpCode (OCF) : 0x153

Un événement Command Complete sera généré pour cette commande.

Regroupement des résultats d'analyse

Un objectif de conception est d'améliorer la façon dont les notifications d'événement Bluetooth LE Scan Response sont transmises à l'hôte, afin d'économiser de l'énergie dans l'hôte.

En réduisant la fréquence à laquelle le contrôleur notifie au processeur de l'application hôte d'analyser les résultats, le processeur de l'application hôte peut rester inactif/veille plus longtemps. Cela réduit la consommation d'énergie dans l'hôte. Le paramètre de retour total_scan_results_storage de LE_Get_Vendor_Capabilities_Command indique la capacité de la puce pour le stockage des résultats d'analyse.

Cette fonctionnalité se concentre sur la gestion et la configuration de la fonction de stockage des résultats de l'analyse LE dans le contrôleur Bluetooth. Le stockage est utilisé pour regrouper temporairement les données de publicité et analyser les données et les métadonnées qui sont reçues par le contrôleur pour une livraison ultérieure à l'hôte.

Le micrologiciel doit prendre en charge deux types de traitement par lots, qui peuvent être activés simultanément :

• Tronqué. Contient les éléments d'information suivants : {MAC, TX Power, RSSI, Timestamp}
• Complet. Contient les éléments d'information suivants : {MAC, TX Power, RSSI, Timestamp, Adv Data, Scan Response}

LE_Batch_Scan_Command

OCF : 0x156

Un événement Command Complete sera généré pour cette commande. L'activation de la fonction spécifique au client ne démarre pas l'analyse.

LE_Batch_Scan_Command : Activer la fonctionnalité spécifique au client

Sous-OCF : 0x01

Un événement Command Complete sera généré pour cette commande.

LE_Batch_Scan_Command : sous-commande Set Batch Scan Storage Param

Sous-OCF : 0x02

Un événement Command Complete sera généré pour cette commande.

LE_Batch_Scan_Command : sous-commande Set Batch Scan Param

Sous-OCF : 0x03

Cette sous-commande lancera l'analyse par lots, si elle est activée. Dans l'analyse tronquée, les résultats sont stockés sous forme tronquée où la clé unique pour le style tronqué = { BD_ADDR, scan_interval}. Cela signifie qu'un seul BD_ADDR will enregistré pour chaque intervalle de balayage. L'enregistrement à conserver pour le mode Tronqué est le suivant : { BD_ADDR , Tx Power, RSSI, Timestamp}

Lorsque le mode complet est activé, le balayage actif sera utilisé et les réponses du balayage seront enregistrées. La clé unique de style complet = {MAC, paquet publicitaire}, quel que soit l'intervalle d'analyse. L'enregistrement à conserver pour le mode complet est { BD_ADDR , Tx Power, RSSI, Timestamp, Ad packet, Scan Response}. Dans le style complet, le même paquet AD, lorsqu'il est vu plusieurs fois sur différents intervalles de balayage, n'est enregistré qu'une seule fois. Cependant, en mode tronqué, c'est la visibilité de BA_ADDR sur différents intervalles de balayage qui est intéressante (une fois par intervalle de balayage). Le RSSI est la valeur moyenne de tous les doublons d'une publicité unique dans un intervalle de balayage.

Un événement Command Complete sera généré pour cette commande.

LE_Batch_Scan_Command : sous-commande Lire les résultats de l'analyse par lots

Sous-OCF : 0x04

Un événement Command Complete sera généré pour cette commande. Lorsque l'hôte émet cette commande, tous les résultats du contrôleur peuvent ne pas tenir dans un événement Command Complete. L'hôte répétera l'émission de cette commande jusqu'à ce que les résultats correspondants dans l'événement Command Complete indiquent 0 dans le nombre d'enregistrements, ce qui indique que le contrôleur n'a plus d'enregistrements à communiquer à l'hôte. Chaque événement Commande terminée peut contenir plusieurs enregistrements d'un seul type de données (complet ou tronqué).

Les références temporelles du contrôleur et de l'hôte ne sont pas synchronisées. L'unité de l'horodatage est de 50 ms. La valeur de l'horodatage est basée sur le moment où Read_Batch_Scan_Results_Sub_cmd est donné par l'hôte. Si l'heure d'arrivée d'une commande est T_c dans le micrologiciel, l'heure réelle à laquelle l'horodatage a été pris dans le micrologiciel est T_fw . L'heure de rapport sera : ( T_c - T_fw ). T_c et T_fw sont dans le domaine temporel du firmware. Cela permet à l'hôte de calculer depuis combien de temps l'événement s'est produit.

Filtre de contenu de paquet publicitaire

Utilisez-le pour activer/désactiver/configurer le filtre de contenu publicitaire (APCF) dans le contrôleur. APCF filtre les rapports publicitaires dans le contrôleur mais ne filtre pas les publicités périodiques.

LE_APCF_Command

OCF : 0x157

Un événement Command Complete sera généré pour cette commande.

LE_APCF_Command : Enable_sub_cmd

Sous-OCF : 0x00

Un événement Command Complete sera généré pour cette commande.

Commande_LE_APCF : set_filtering_parameters_sub_cmd

Cette sous-commande est utilisée pour ajouter ou supprimer une spécification de filtre ou effacer une liste de filtres pour le filtrage sur puce.

Sous-OCF : 0x01

Les valeurs RSSI doivent utiliser le complément à 2 pour représenter les valeurs négatives.

L'hôte doit pouvoir configurer plusieurs filtres avec APCF_Application_Address_type défini sur 0x02 (pour toutes les adresses de diffuseur) pour gérer diverses combinaisons de filtres.

Le filtrage, le traitement par lots et la création de rapports sont des concepts interdépendants. Chaque publicité et réponse d'analyse associée devra passer par tous les filtres, l'un après l'autre. Ainsi, les actions résultantes ( delivery_mode ) sont étroitement liées au filtrage. Les modes de livraison sont les suivants : report_immediately , batch et onFound . La valeur OnLost est liée à OnFound dans le sens où elle viendra après OnFound en cas de perte.

Ce flux de traitement décrit le modèle conceptuel :

Lorsqu'une trame de publicité (ou de réponse de balayage) est reçue, elle est appliquée à tous les filtres dans l'ordre sériel. Il est possible qu'une publicité entraîne un signalement immédiat basé sur un filtre et un regroupement de celui-ci en raison d'une action de filtre différente.

Les seuils de niveau RSSI (haut et bas) permettent de contrôler le moment où la trame est visible pour le traitement du filtre, même lorsqu'un paquet valide est reçu par le contrôleur. Dans le cas où le mode de livraison est défini sur immédiat ou par lots, le RSSI d'une trame est pris en compte pour un traitement ultérieur par le contrôleur. Différentes applications nécessitent un comportement de création de rapports et de traitement par lots différent. Cela permet à plusieurs applications d'avoir des rapports directs et/ou des lots de résultats dans le micrologiciel, simultanément. Un exemple est le cas où une analyse par lots est active à partir d'une application et plus tard, une analyse LE régulière est émise par une autre application. Avant qu'une analyse par lots ne soit émise, le framework/l'application définit les filtres appropriés. Plus tard, lorsque la deuxième application émet une analyse régulière, le traitement par lots précédent se poursuit. Cependant, en raison de l'analyse régulière, cela s'apparente à l'ajout conceptuel d'un filtre nul (avec tous les filtres existants) avec la commande d'analyse LE. Les paramètres de la commande LE scan sont prioritaires lorsqu'ils sont actifs. Lorsque l'analyse LE régulière est désactivée, le contrôleur reviendra à une analyse par lots précédente, si elle existait.

Le mode de livraison OnFound est basé sur des filtres configurés. Une combinaison qui déclenche l'action d'un filtre pour réussir est considérée comme l'entité à suivre pour onLost . L'événement correspondant est le sous-événement de suivi LE Advt.

La transition OnFound/OnLost pour un filtre (si activé) ressemblera à ceci :

Un événement Command Complete sera généré pour cette commande.

LE_APCF_Command : broadcast_address_sub_cmd

Cette sous-commande est utilisée pour ajouter ou supprimer une adresse d'annonceur ou pour effacer la liste d'adresses d'annonceur pour le filtrage sur puce.

Sous-OCF : 0x02

Un événement Command Complete sera généré pour cette commande.

Commande_LE_APCF : service_uuid_sub_cmd

Cette sous-commande est utilisée pour ajouter ou supprimer un UUID de service ou pour effacer une liste d'UUID de service pour le filtrage sur puce.

Sous-OCF : 0x03

Un événement Command Complete sera généré pour cette commande.

LE_APCF_Command : solicitation_uuid_sub_cmd

Cette sous-commande est utilisée pour ajouter ou supprimer un UUID de sollicitation ou pour effacer une liste d'UUID de sollicitation pour le filtrage sur puce.

Sous-OCF : 0x04

Un événement Command Complete sera généré pour cette commande.

Commande_LE_APCF : nom_local_sub_cmd

Cette sous-commande est utilisée pour ajouter ou supprimer une chaîne de nom local ou pour effacer la liste des chaînes de nom local pour le filtrage sur puce.

Sous-OCF : 0x05

Un événement Command Complete sera généré pour cette commande.

Commande_LE_APCF : manf_data_sub_cmd

Cette sous-commande est utilisée pour ajouter ou supprimer une chaîne de données du fabricant ou pour effacer la liste des chaînes de données du fabricant pour le filtrage sur puce.

Sous-OCF : 0x06

Un événement Command Complete sera généré pour cette commande.

Commande_LE_APCF : service_data_sub_cmd

Cette sous-commande est utilisée pour ajouter ou supprimer une chaîne de données de service ou pour effacer la liste des chaînes de données de service pour le filtrage sur puce.

Sous-OCF : 0x07

Un événement Command Complete sera généré pour cette commande.

LE_APCF_Command : ad_type_sub_cmd

Cette sous-commande est utilisée pour ajouter ou supprimer un type AD ou pour effacer une liste de types AD pour le filtrage sur puce. Utilisez read_extended_features_sub_cmd pour vérifier si cette commande est prise en charge ou non.

Sous-OCF : 0x09

Un événement Command Complete sera généré pour cette commande.

Commande_LE_APCF : read_extended_features_sub_cmd

Cette sous-commande est utilisée pour lire les fonctions APCF étendues.

Sous-OCF : 0xFF

Un événement Command Complete sera généré pour cette commande.

Commande des informations sur l'activité et l'énergie du contrôleur

L'objectif de ces informations est que les fonctions supérieures du système hôte analysent les activités totales de tous les composants, y compris le contrôleur BT et son état macro, en conjonction avec ce qui se passe dans les applications et le cadre. Pour ce faire, les informations suivantes sont requises de la pile BT et du contrôleur :

• Pile BT : signalement de l'état macro-opérationnel actuel du contrôleur
• Micrologiciel : rapports sur l'activité globale et les informations sur l'énergie

États de la macro de la pile de l'hôte BT, tels que déterminés au niveau de l'utilisateur :

• Inactif : [numérisation de page, advt LE, numérisation d'enquête]
• Scan : [messagerie/requête/tentative de connexion]
• Actif : [lien ACL activé, lien SCO en cours, mode détection]

Les activités dont le contrôleur assure le suivi tout au long de sa durée de vie sont le temps Tx, le temps Rx, le temps d'inactivité et l'énergie totale consommée. Ils sont effacés lorsqu'ils sont lus depuis l'hôte.

LE_Get_Controller_Activity_Energy_Info

Il s'agit d'une commande spécifique au fournisseur.

OCF : 0x159

Un événement Command Complete sera généré pour cette commande.

Commande de paramètres d'analyse de jeu étendu LE

Cette commande peut être utilisée pour activer une fenêtre et un intervalle d'analyse plus grands dans le contrôleur. Selon la spécification BT Core 5.2, une fenêtre et un intervalle d'analyse ont une limite supérieure de 10,24 secondes, ce qui entrave les intervalles d'analyse plus longs des applications au-delà de 10,24 secondes.

Référence de base : spécification BT Core 5.2, page 2493 (commande LE Set Scan Parameters)

OCF : 0x15A

Un événement Command Complete sera généré pour cette commande.

Obtenir la commande d'informations de débogage du contrôleur

L'objectif de cet élément d'information est d'acquérir des informations de débogage du contrôleur par un hôte, sous forme binaire, pour le post-traitement et l'analyse. Cela aide à déboguer les problèmes sur le terrain et fournit aux ingénieurs une boîte à outils pour enregistrer les informations à des fins d'analyse. Un contrôleur peut fournir les informations à la demande d'un hôte via l'événement (sous-événement Controller Debug Info) ou de manière autonome lorsque le contrôleur le souhaite. Des exemples d'utilisations pourraient être de rapporter des informations sur l'état du micrologiciel, des informations de vidage sur incident, des informations de journalisation, etc.

OCF : 0x15B

Un événement Command Complete sera généré pour cette commande.

Prise en charge du déchargement matériel A2DP

La fonction de déchargement A2DP prend en charge le déchargement du processus d'encodage audio A2DP vers un processeur audio connecté au contrôleur BT. Le flux de données audio codé passe directement du processeur audio au contrôleur BT sans l'implication de l'hôte BT. L'hôte BT est toujours responsable de la configuration et du contrôle de la session A2DP.

OCF : 0x15D

Démarrer le déchargement A2DP

Sous-OCF : 0x01

Utilisez cette commande à la fois pour configurer le processus de déchargement A2DP et pour démarrer le flux A2DP.

Un événement Command Complete sera généré pour cette commande.

Arrêter le déchargement A2DP

Sous-OCF : 0x02

Cette commande est utilisée pour arrêter le flux de déchargement A2DP.

Aucun paramètre n'est défini pour cette commande.

Un événement Command Complete sera généré pour cette commande.

Commande Rapport de qualité Bluetooth

La fonction de commande de rapport de qualité BT démarre le mécanisme du contrôleur Bluetooth pour signaler les événements de qualité Bluetooth à l'hôte. Vous pouvez activer quatre options :

• Mode de surveillance de la qualité : le contrôleur envoie périodiquement un sous-événement BQR lié à la qualité de la liaison à l'hôte.
• Approche de LSTO : si aucun paquet n'est reçu du périphérique BT connecté pendant plus de la moitié de la valeur du délai de supervision de la liaison (LSTO), le contrôleur signale un événement d'approche de LSTO à l'hôte.
• A2DP Audio Choppy : Lorsque le contrôleur détecte des facteurs qui provoquent un son saccadé, le contrôleur signale un événement A2DP Audio Choppy à l'hôte.
• (e)SCO Voice Choppy : Lorsque le contrôleur détecte des facteurs qui provoquent une voix saccadée, le contrôleur signale un événement (e)SCO Voice Choppy à l'hôte.
• Inflammation de la racine : cet événement est envoyé par le contrôleur à la pile lorsque la couche HAL ou le contrôleur rencontre une erreur fatale et doit redémarrer Bluetooth.
• Suivi des messages LMP/LL : le contrôleur envoie le message LMP/LL d'établissement de liaison avec l'appareil distant à l'hôte.
• Bluetooth Multi-profile/Coex scheduling trace: The controller sends its scheduling information on handling multiple Bluetooth profiles and wireless coexistence in the 2.4 Ghz band to the host.
• Controller Debug Information mechanism: When enabled, the controller can autonomously report debug logging information through the Controller debug info sub-event to the host.

OCF: 0x15E

A Command Complete event will be generated for this command.

Dynamic Audio Buffer command

The Dynamic Audio Buffer reduces audio glitching by changing the audio buffer size in the Bluetooth controller based on various scenarios.

OCF: 0x15F

Get audio buffer time capability

Sub OCF: 0x01

Use this command to get the audio buffer time capability from the Bluetooth controller.

A Command Complete event will be generated for this command.

Set audio buffer time

Sub OCF: 0x02

Use this command to set the audio buffer time to the Bluetooth controller.

A Command Complete event will be generated for this command.

HCI event (vendor-specific)

Vendor-specific HCI events are required in some cases. Refer to Figure 5.4 on page 1897 of the BT Core 5.2 Specification. Event parameter 0 will always contain the first sub-event code, based on which the rest of the HCI event is decoded.

Storage threshold breach sub-event

This event indicates that the storage threshold has been breached.

Sub-event code = 0x54

LE multi-advertising state change sub-event

This event indicates that an advertising instance has changed its state. At this time, this event is only used to indicate which advertising instance was stopped as a result of a connection.

Sub-event code = 0x55

LE advertisement tracking sub-event

This event indicates when an advertiser is found or lost.

Sub event code = 0x56

Controller debug info sub-event

This event is used by a Controller to provide binary debug information to a host.

Sub-event code = 0x57

Bluetooth Quality Report sub-event

This event indicates one of the following: a Bluetooth quality event occurred, the controller uploaded the LMP/LL message trace and Bluetooth Multi-link/Coex scheduling trace, or the controller dumped debug information data.

Sub-event code = 0x58 [Quality_Report_Id = 0x01 ~ 0x04, Link Quality related event]

Sub-event code = 0x58 [Quality_Report_Id = 0x05, Root Inflammation event]

This event indicates that Bluetooth HAL or the controller encountered a fatal error and needs Bluetooth stack to record this situation and restart. The controller must send a Root_Inflammation_Event to Bluetooth stack before sending the first fragment of the debug info events in any case.

The Error_Code parameter contains an error code reported from HAL/Controller, 0 if it is a chipset vendor specific error. The Vendor_Specific_Error_Code contains a chipset vendor specific error code from HAL/Controller. It should set as 0 if the parameter Error_Code is not 0. The parameters Error_Code and Vendor_Specific_Error_Code should not both be 0.

Sub-event code = 0x58 [Quality_Report_Id = 0x11 ~ 0x13, Log Dump related event]

Multi-advertiser support

The objectives of multi-advertiser support are the following:

• Ability to support multiple advertisements ( max_advt_instances )
• Different transmit powers to allow for a varying range
• Different advertising content
• An individualized response for each advertiser
• Privacy (non-trackable) for each advertiser
• Connectable

To keep this specification close to existing standards, the following vendor-specific commands are provided. They are derived from the Bluetooth Core 4.1 Specification.

LE_Multi_Advt_Command

OCF: 0x154

A Command Complete event will be generated for this command.

LE_Multi_Advt_Command: Set_Advt_Param_Multi_Sub_Cmd

Base reference: Bluetooth Core 4.1 Specification, page 964 (LE Set Advertising Parameter Command)

Sub OCF: 0x01

The Own_Address parameter could be a host-configured address at the time of setting up this multi-advertisement instance. This provides the ability to have a resolvable private address at the time of the transmit of the first beacon. Advertisement on an instance will continue irrespective of the connection. The host BT stack could issue a command to start advertisement on an instance, post connection.

A Command Complete event will be generated for this command as specified in the Bluetooth Core 4.1 Specification, per the above command. The controller will respond with a non-success (invalid parameter) code if the advertising instance or Tx_Power parameters are invalid.

LE_Multi_Advt_Command: Set_Advt_Data_Multi_Sub_Cmd

Base reference: Bluetooth Core 4.1 Specification, page 969 (LE Set Advertising Data Command)

Sub OCF: 0x02

A Command Complete event will be generated for this command as specified in the Bluetooth Core 4.1 Specification, per the above command. The controller will respond with a non-success code if the advertising instance or Tx_Power parameters are invalid.

LE_Multi_Advt_Command: Set_Scan_Resp_Data_Multi_Sub_Cmd

Base reference: Bluetooth Core 4.1 Specification, page 970 (LE Set Scan Response Data Command)

Sub OCF: 0x03

A Command Complete event will be generated for this command as specified in the Bluetooth Core 4.1 Specification, per the above command. The controller will respond with a non-success code (invalid parameter) if the advertising instance or Tx_Power parameters are invalid.

LE_Multi_Advt_Command: Set_Random_Addr_Multi_Sub_Cmd

Base reference: Bluetooth Core 4.1 Specification, page 963 (LE Set Random Address Command)

Sub OCF: 0x04

A Command Complete event will be generated for this command.

LE_Multi_Advt_Command: Set_Advt_Enable_Multi_Sub_Cmd

Base reference: Bluetooth Core 4.1 Specification, page 971 (LE Set Advertise Enable Command in that core specification)

OCF: 0x05

A Command Complete event will be generated for this command.

Offloaded resolution of private address

This feature resolves a private address in the controller firmware or hardware, which provides the following benefits:

• Latency involved with the host in resolving a private address
• Saving power by refraining from waking up the host

LE_Set_RPA_Timeout

OCF: 0x15C

LE_RPA_offload_Command

OCF: 0x155

A Command Complete event will be generated for this command.

LE_RPA_offload: Enable_cust_specific_sub_Command

Sub OCF: 0x01

RPA offload is required to be enabled by the host, based on the chip capability. Refer to the LE_Get_Vendor_Capabilities_Command . Each chip can have a varying max_irk_list_sz in the firmware.

A Command Complete event will be generated for this command.

LE_RPA_offload: Add_IRK_to_list_sub_Command

Sub OCF: 0x02

A Command Complete event will be generated for this command.

LE_RPA_offload: Remove_IRK_to_list_sub_Command

Sub OCF: 0x03

A Command Complete event will be generated for this command.

LE_RPA_offload: Clear_IRK_list_sub_Command

Sub OCF: 0x04

A Command Complete event will be generated for this command.

LE_RPA_offload: Read_IRK_list_sub_Command

Sub OCF: 0x05

A Command Complete event will be generated for this command.

The Host Controller Interface (HCI) is used for interacting with a Bluetooth controller.

This document provides a list of Bluetooth (BT) and Bluetooth Low Energy (BLE) HCI requirements. The aim is for Host BT stack vendors and BT controller vendors to conform to these platform requirements in order to use the feature set described below.

This document refers to the Bluetooth Core 5.2 Specification as the "spec." The Bluetooth Core 5.2 Specification is available on the Bluetooth SIG website along with other adopted documents.

General design overview

Chip capabilities and configuration

As an open platform, Android has a matrix of software releases, OEMs, vendors, and platform and chip capabilities.

To manage the varying landscape and to manage migrations, a design philosophy of allowing BT controllers to expose their capabilities (beyond the standard Bluetooth Core 5.2 Specification) is described in this document. The host BT stack can then use these capabilities to determine which features to enable.

Supporting open standards

One goal of Android is to support open standards after ratification in a Bluetooth specification. If a feature described below becomes available in standard HCI methods in a future Bluetooth specification, we will lean towards making that approach the default.

Vendor-specific capabilities

Vendor-specific command: LE_Get_Vendor_Capabilities_Command

OpCode Command Field (OCF): 0x153

A Command Complete event will be generated for this command.

Batching of scan results

A design goal is to enhance how the Bluetooth LE Scan Response event notifications are delivered to the host, in order to save power in the host.

By reducing how often the controller notifies the host application processor to scan results, the host application processor can stay in idle/sleep longer. This reduces power consumption in the host. The return parameter total_scan_results_storage of LE_Get_Vendor_Capabilities_Command indicates the chip capability for storage of scan results.

This feature focuses on the management and configuration of the LE Scan Results storage facility in the Bluetooth controller. The storage is used to temporarily batch advertisement data and scan data and metadata that are received by the controller for later delivery to the host.

Firmware shall support two types of batching, which can be engaged simultaneously:

• Truncated. Contains the following information elements: {MAC, TX Power, RSSI, Timestamp}
• Full. Contains the following information elements: {MAC, TX Power, RSSI, Timestamp, Adv Data, Scan Response}

LE_Batch_Scan_Command

OCF: 0x156

A Command Complete event will be generated for this command. Enabling the customer-specific feature does not start the scan.

LE_Batch_Scan_Command: Enable Customer Specific feature

Sub OCF: 0x01

A Command Complete event will be generated for this command.

LE_Batch_Scan_Command: Set Batch Scan Storage Param subcommand

Sub OCF: 0x02

A Command Complete event will be generated for this command.

LE_Batch_Scan_Command: Set Batch Scan Param subcommand

Sub OCF: 0x03

This sub-command will start batch scanning, if enabled. In Truncated scanning, results are stored in truncated form where the unique key for Truncated style = { BD_ADDR, scan_interval}. This means only one BD_ADDR will be recorded for each scan interval. The record to keep for Truncated mode is the following: { BD_ADDR , Tx Power, RSSI, Timestamp}

When Full mode is enabled, active scanning will be used and Scan Responses will be recorded. The Full style unique key = {MAC, Ad packet}, irrespective of scan interval. The record to keep for Full mode is { BD_ADDR , Tx Power, RSSI, Timestamp, Ad packet, Scan Response}. In Full style, the same AD packet, when seen multiple times across different scan intervals, is recorded only once. However, in Truncated mode, it is the visibility of BA_ADDR across different scan intervals that is of interest (once per scan interval). The RSSI is the averaged value of all duplicates of a unique advertisement within a scan interval.

A Command Complete event will be generated for this command.

LE_Batch_Scan_Command: Read Batch Scan Results sub-command

Sub OCF: 0x04

A Command Complete event will be generated for this command. When the host issues this command, all the results in the controller may not fit in one Command Complete event. The host will iterate issuing this command until the corresponding results in the Command Complete event indicate 0 in the number of records, which indicates the controller has no more records to communicate to the host. Each Command Complete event could contain multiple records of only one type of data (Full or Truncated).

Controller and host time references are not synchronized. The unit of the timestamp is 50ms. The value of the timestamp is based off when the Read_Batch_Scan_Results_Sub_cmd is given by the host. If a command arrival time is T_c in the firmware, then the actual time the timestamp was taken in the firmware is T_fw . The reporting time will be: ( T_c - T_fw ). T_c and T_fw are in the firmware time domain. This lets the host compute how long ago the event happened.

Advertising Packet Content Filter

Use this to enable/disable/setup the Advertising Packet Content Filter (APCF) in the controller. APCF filters advertising reports in the controller but doesn't filter periodic advertising.

LE_APCF_Command

OCF: 0x157

A Command Complete event will be generated for this command.

LE_APCF_Command: Enable_sub_cmd

Sub OCF: 0x00

A Command Complete event will be generated for this command.

LE_APCF_Command: set_filtering_parameters_sub_cmd

This subcommand is used to add or delete a filter specification or clear a filter list for on-chip filtering.

Sub OCF: 0x01

RSSI values must use 2's complement to represent negative values.

Host shall be able to configure multiple filters with APCF_Application_Address_type set to 0x02 (for all broadcaster addresses) to manage various filter combinations.

Filtering, batching and reporting are inter-related concepts. Every advertisement and related scan response will have to go through all the filters, one after the other. Thus, resulting actions ( delivery_mode ) are closely tied to filtering. The delivery modes are the following: report_immediately , batch , and onFound . The OnLost value is related to OnFound in the sense that it will come after OnFound when lost.

This processing flow depicts the conceptual model:

When an advertisement (or scan response) frame is received, it is applied to all the filters in serial order. It's possible that an advertisement can cause immediate reporting based on one filter and batching of the same due to a different filter action.

RSSI level thresholds (high and low) give the ability to control when the frame is visible for filter processing, even when a valid packet is received by the controller. In case of delivery mode being set to immediate or batched, the RSSI of a frame is considered for further controller processing. Different apps need different reporting and batching behavior. This allows multiple apps to have direct reporting and/or batching of results in firmware, concurrently. An example is a case when a batch scan is active from one app and later a regular LE scan is issued by another app. Before a batch scan is issued, the framework/app sets appropriate filters. Later, when the second app issues a regular scan, previous batching continues. However, due to the regular scan, it is akin to conceptually adding a null filter (along with all the existing filters) along with the LE scan command. The LE scan command parameters take precedence when active. When the regular LE scan is disabled, the controller will revert back to a previous batch scan, if it existed.

The OnFound delivery mode is based on configured filters. A combination that triggers a filter's action to succeed is considered the entity to track for onLost . The corresponding event is the LE Advt tracking subevent.

The OnFound/OnLost transition for a filter (if enabled) will look like the following:

A Command Complete event will be generated for this command.

LE_APCF_Command: broadcast_address_sub_cmd

This subcommand is used to add or delete an advertiser address or to clear the advertiser address list for on-chip filtering.

Sub OCF: 0x02

A Command Complete event will be generated for this command.

LE_APCF_Command: service_uuid_sub_cmd

This subcommand is used to add or delete a service UUID or to clear a service UUID list for on-chip filtering.

Sub OCF: 0x03

A Command Complete event will be generated for this command.

LE_APCF_Command: solicitation_uuid_sub_cmd

This subcommand is used to add or delete a solicitation UUID or to clear a solicitation UUID list for on-chip filtering.

Sub OCF: 0x04

A Command Complete event will be generated for this command.

LE_APCF_Command: local_name_sub_cmd

This sub-command is used to add or delete a local name string or to clear the local name string list for on-chip filtering.

Sub OCF: 0x05

A Command Complete event will be generated for this command.

LE_APCF_Command: manf_data_sub_cmd

This subcommand is used to add or delete a manufacturer data string or to clear the manufacturer data string list for on-chip filtering.

Sub OCF: 0x06

A Command Complete event will be generated for this command.

LE_APCF_Command: service_data_sub_cmd

This subcommand is used to add or delete a service data string or to clear the service data string list for on-chip filtering.

Sub OCF: 0x07

A Command Complete event will be generated for this command.

LE_APCF_Command: ad_type_sub_cmd

This subcommand is used to add or delete an AD type or to clear an AD type list for on-chip filtering. Use read_extended_features_sub_cmd to check if this command is supported or not.

Sub OCF: 0x09

A Command Complete event will be generated for this command.

LE_APCF_Command: read_extended_features_sub_cmd

This subcommand is used to read extended APCF features.

Sub OCF: 0xFF

A Command Complete event will be generated for this command.

Controller activity and energy information command

The objective of this information is for higher host system functions to analyze the total activities of all components, including the BT controller and its macro state, in conjunction with what is happening in the apps and framework. To do this, the following information is required from the BT stack and the controller:

• BT stack: Reporting the current macro-operational state of the controller
• Firmware: Reporting aggregate activity and energy information

BT host stack macro states, as determined at the user level:

• Idle: [page scan, LE advt, inquiry scan]
• Scan: [paging/inquiry/trying to connect]
• Active: [ACL link on, SCO link ongoing, sniff mode]

The activities that the controller keeps track of over its life are Tx time, Rx time, idle time, and total energy consumed. They are cleared when read from the host.

LE_Get_Controller_Activity_Energy_Info

This is a vendor-specific command.

OCF: 0x159

A Command Complete event will be generated for this command.

LE extended set scan parameters command

This command can be used to enable a larger scan window and interval in the controller. Per the BT Core 5.2 Specification, a scan window and interval have an upper bound limit of 10.24 seconds, which hampers applications' longer scan intervals beyond 10.24 seconds.

Base reference: BT Core 5.2 Specification, page 2493 (LE Set Scan Parameters Command)

OCF: 0x15A

A Command Complete event will be generated for this command.

Get controller debug info command

The objective of this information element is to acquire controller debug information by a host, in binary form, for post-processing and analysis. This helps debug on-field issues and provides engineers with a toolkit to log information for analysis. A Controller can provide the information when requested by a host via the event (Controller Debug Info sub-event) or autonomously when desired by the controller. Example uses could be to report firmware state information, crash dump information, logging information, etc.

OCF: 0x15B

A Command Complete event will be generated for this command.

A2DP Hardware Offload Support

The A2DP Offload feature supports the offload of the A2DP audio encoding process to an audio processor attached to the BT Controller. The encoded audio data stream passes directly from the Audio processor to the BT Controller without the BT host's involvement. The BT Host is still responsible for the configuration and control of the A2DP session.

OCF: 0x15D

Start A2DP Offload

Sub OCF: 0x01

Use this command both to configure the A2DP Offload process and to start the A2DP stream.

A Command Complete event will be generated for this command.

Stop A2DP Offload

Sub OCF: 0x02

This command is used to stop the A2DP Offload stream.

No parameters are defined for this command.

A Command Complete event will be generated for this command.

Bluetooth Quality Report command

The BT Quality Report command feature starts the mechanism in the Bluetooth controller to report Bluetooth Quality events to the host. You can enable four options:

• Quality Monitoring Mode: The controller periodically sends a Link Quality related BQR sub-event to the host.
• Approaching LSTO: If no packets are received from the connected BT device for longer than half of the Link Supervision TimeOut (LSTO) value, the controller reports an Approaching LSTO event to the host.
• A2DP Audio Choppy: When the controller detects factors that cause choppy audio, the controller reports an A2DP Audio Choppy event to the host.
• (e)SCO Voice Choppy: When the controller detects factors that cause choppy voice, the controller reports an (e)SCO Voice Choppy event to the host.
• Root Inflammation: This event is sent by the controller to the stack when the HAL or the controller encounters a fatal error and needs to restart Bluetooth.
• LMP/LL message trace: The controller sends the LMP/LL message handshaking with the remote device to the host.
• Bluetooth Multi-profile/Coex scheduling trace: The controller sends its scheduling information on handling multiple Bluetooth profiles and wireless coexistence in the 2.4 Ghz band to the host.
• Controller Debug Information mechanism: When enabled, the controller can autonomously report debug logging information through the Controller debug info sub-event to the host.

OCF: 0x15E

A Command Complete event will be generated for this command.

Dynamic Audio Buffer command

The Dynamic Audio Buffer reduces audio glitching by changing the audio buffer size in the Bluetooth controller based on various scenarios.

OCF: 0x15F

Get audio buffer time capability

Sub OCF: 0x01

Use this command to get the audio buffer time capability from the Bluetooth controller.

A Command Complete event will be generated for this command.

Set audio buffer time

Sub OCF: 0x02

Use this command to set the audio buffer time to the Bluetooth controller.

A Command Complete event will be generated for this command.

HCI event (vendor-specific)

Vendor-specific HCI events are required in some cases. Refer to Figure 5.4 on page 1897 of the BT Core 5.2 Specification. Event parameter 0 will always contain the first sub-event code, based on which the rest of the HCI event is decoded.

Storage threshold breach sub-event

This event indicates that the storage threshold has been breached.

Sub-event code = 0x54

LE multi-advertising state change sub-event

This event indicates that an advertising instance has changed its state. At this time, this event is only used to indicate which advertising instance was stopped as a result of a connection.

Sub-event code = 0x55

LE advertisement tracking sub-event

This event indicates when an advertiser is found or lost.

Sub event code = 0x56

Controller debug info sub-event

This event is used by a Controller to provide binary debug information to a host.

Sub-event code = 0x57

Bluetooth Quality Report sub-event

This event indicates one of the following: a Bluetooth quality event occurred, the controller uploaded the LMP/LL message trace and Bluetooth Multi-link/Coex scheduling trace, or the controller dumped debug information data.

Sub-event code = 0x58 [Quality_Report_Id = 0x01 ~ 0x04, Link Quality related event]

Sub-event code = 0x58 [Quality_Report_Id = 0x05, Root Inflammation event]

This event indicates that Bluetooth HAL or the controller encountered a fatal error and needs Bluetooth stack to record this situation and restart. The controller must send a Root_Inflammation_Event to Bluetooth stack before sending the first fragment of the debug info events in any case.

The Error_Code parameter contains an error code reported from HAL/Controller, 0 if it is a chipset vendor specific error. The Vendor_Specific_Error_Code contains a chipset vendor specific error code from HAL/Controller. It should set as 0 if the parameter Error_Code is not 0. The parameters Error_Code and Vendor_Specific_Error_Code should not both be 0.

Sub-event code = 0x58 [Quality_Report_Id = 0x11 ~ 0x13, Log Dump related event]

Multi-advertiser support

The objectives of multi-advertiser support are the following:

• Ability to support multiple advertisements ( max_advt_instances )
• Different transmit powers to allow for a varying range
• Different advertising content
• An individualized response for each advertiser
• Privacy (non-trackable) for each advertiser
• Connectable

To keep this specification close to existing standards, the following vendor-specific commands are provided. They are derived from the Bluetooth Core 4.1 Specification.

LE_Multi_Advt_Command

OCF: 0x154

A Command Complete event will be generated for this command.

LE_Multi_Advt_Command: Set_Advt_Param_Multi_Sub_Cmd

Base reference: Bluetooth Core 4.1 Specification, page 964 (LE Set Advertising Parameter Command)

Sub OCF: 0x01

The Own_Address parameter could be a host-configured address at the time of setting up this multi-advertisement instance. This provides the ability to have a resolvable private address at the time of the transmit of the first beacon. Advertisement on an instance will continue irrespective of the connection. The host BT stack could issue a command to start advertisement on an instance, post connection.

A Command Complete event will be generated for this command as specified in the Bluetooth Core 4.1 Specification, per the above command. The controller will respond with a non-success (invalid parameter) code if the advertising instance or Tx_Power parameters are invalid.

LE_Multi_Advt_Command: Set_Advt_Data_Multi_Sub_Cmd

Base reference: Bluetooth Core 4.1 Specification, page 969 (LE Set Advertising Data Command)

Sub OCF: 0x02

A Command Complete event will be generated for this command as specified in the Bluetooth Core 4.1 Specification, per the above command. The controller will respond with a non-success code if the advertising instance or Tx_Power parameters are invalid.

LE_Multi_Advt_Command: Set_Scan_Resp_Data_Multi_Sub_Cmd

Base reference: Bluetooth Core 4.1 Specification, page 970 (LE Set Scan Response Data Command)

Sub OCF: 0x03

A Command Complete event will be generated for this command as specified in the Bluetooth Core 4.1 Specification, per the above command. The controller will respond with a non-success code (invalid parameter) if the advertising instance or Tx_Power parameters are invalid.

LE_Multi_Advt_Command: Set_Random_Addr_Multi_Sub_Cmd

Base reference: Bluetooth Core 4.1 Specification, page 963 (LE Set Random Address Command)

Sub OCF: 0x04

A Command Complete event will be generated for this command.

LE_Multi_Advt_Command: Set_Advt_Enable_Multi_Sub_Cmd

Base reference: Bluetooth Core 4.1 Specification, page 971 (LE Set Advertise Enable Command in that core specification)

OCF: 0x05

A Command Complete event will be generated for this command.

Offloaded resolution of private address

This feature resolves a private address in the controller firmware or hardware, which provides the following benefits:

• Latency involved with the host in resolving a private address
• Saving power by refraining from waking up the host

LE_Set_RPA_Timeout

OCF: 0x15C

LE_RPA_offload_Command

OCF: 0x155

A Command Complete event will be generated for this command.

LE_RPA_offload: Enable_cust_specific_sub_Command

Sub OCF: 0x01

RPA offload is required to be enabled by the host, based on the chip capability. Refer to the LE_Get_Vendor_Capabilities_Command . Each chip can have a varying max_irk_list_sz in the firmware.

A Command Complete event will be generated for this command.

LE_RPA_offload: Add_IRK_to_list_sub_Command

Sub OCF: 0x02

A Command Complete event will be generated for this command.

LE_RPA_offload: Remove_IRK_to_list_sub_Command

Sub OCF: 0x03

A Command Complete event will be generated for this command.

LE_RPA_offload: Clear_IRK_list_sub_Command

Sub OCF: 0x04

A Command Complete event will be generated for this command.

LE_RPA_offload: Read_IRK_list_sub_Command

Sub OCF: 0x05

A Command Complete event will be generated for this command.

The Host Controller Interface (HCI) is used for interacting with a Bluetooth controller.

This document provides a list of Bluetooth (BT) and Bluetooth Low Energy (BLE) HCI requirements. The aim is for Host BT stack vendors and BT controller vendors to conform to these platform requirements in order to use the feature set described below.

This document refers to the Bluetooth Core 5.2 Specification as the "spec." The Bluetooth Core 5.2 Specification is available on the Bluetooth SIG website along with other adopted documents.

General design overview

Chip capabilities and configuration

As an open platform, Android has a matrix of software releases, OEMs, vendors, and platform and chip capabilities.

To manage the varying landscape and to manage migrations, a design philosophy of allowing BT controllers to expose their capabilities (beyond the standard Bluetooth Core 5.2 Specification) is described in this document. The host BT stack can then use these capabilities to determine which features to enable.

Supporting open standards

One goal of Android is to support open standards after ratification in a Bluetooth specification. If a feature described below becomes available in standard HCI methods in a future Bluetooth specification, we will lean towards making that approach the default.

Vendor-specific capabilities

Vendor-specific command: LE_Get_Vendor_Capabilities_Command

OpCode Command Field (OCF): 0x153

A Command Complete event will be generated for this command.

Batching of scan results

A design goal is to enhance how the Bluetooth LE Scan Response event notifications are delivered to the host, in order to save power in the host.

By reducing how often the controller notifies the host application processor to scan results, the host application processor can stay in idle/sleep longer. This reduces power consumption in the host. The return parameter total_scan_results_storage of LE_Get_Vendor_Capabilities_Command indicates the chip capability for storage of scan results.

This feature focuses on the management and configuration of the LE Scan Results storage facility in the Bluetooth controller. The storage is used to temporarily batch advertisement data and scan data and metadata that are received by the controller for later delivery to the host.

Firmware shall support two types of batching, which can be engaged simultaneously:

• Truncated. Contains the following information elements: {MAC, TX Power, RSSI, Timestamp}
• Full. Contains the following information elements: {MAC, TX Power, RSSI, Timestamp, Adv Data, Scan Response}

LE_Batch_Scan_Command

OCF: 0x156

A Command Complete event will be generated for this command. Enabling the customer-specific feature does not start the scan.

LE_Batch_Scan_Command: Enable Customer Specific feature

Sub OCF: 0x01

A Command Complete event will be generated for this command.

LE_Batch_Scan_Command: Set Batch Scan Storage Param subcommand

Sub OCF: 0x02

A Command Complete event will be generated for this command.

LE_Batch_Scan_Command: Set Batch Scan Param subcommand

Sub OCF: 0x03

This sub-command will start batch scanning, if enabled. In Truncated scanning, results are stored in truncated form where the unique key for Truncated style = { BD_ADDR, scan_interval}. This means only one BD_ADDR will be recorded for each scan interval. The record to keep for Truncated mode is the following: { BD_ADDR , Tx Power, RSSI, Timestamp}

When Full mode is enabled, active scanning will be used and Scan Responses will be recorded. The Full style unique key = {MAC, Ad packet}, irrespective of scan interval. The record to keep for Full mode is { BD_ADDR , Tx Power, RSSI, Timestamp, Ad packet, Scan Response}. In Full style, the same AD packet, when seen multiple times across different scan intervals, is recorded only once. However, in Truncated mode, it is the visibility of BA_ADDR across different scan intervals that is of interest (once per scan interval). The RSSI is the averaged value of all duplicates of a unique advertisement within a scan interval.

A Command Complete event will be generated for this command.

LE_Batch_Scan_Command: Read Batch Scan Results sub-command

Sub OCF: 0x04

A Command Complete event will be generated for this command. When the host issues this command, all the results in the controller may not fit in one Command Complete event. The host will iterate issuing this command until the corresponding results in the Command Complete event indicate 0 in the number of records, which indicates the controller has no more records to communicate to the host. Each Command Complete event could contain multiple records of only one type of data (Full or Truncated).

Controller and host time references are not synchronized. The unit of the timestamp is 50ms. The value of the timestamp is based off when the Read_Batch_Scan_Results_Sub_cmd is given by the host. If a command arrival time is T_c in the firmware, then the actual time the timestamp was taken in the firmware is T_fw . The reporting time will be: ( T_c - T_fw ). T_c and T_fw are in the firmware time domain. This lets the host compute how long ago the event happened.

Advertising Packet Content Filter

Use this to enable/disable/setup the Advertising Packet Content Filter (APCF) in the controller. APCF filters advertising reports in the controller but doesn't filter periodic advertising.

LE_APCF_Command

OCF: 0x157

A Command Complete event will be generated for this command.

LE_APCF_Command: Enable_sub_cmd

Sub OCF: 0x00

A Command Complete event will be generated for this command.

LE_APCF_Command: set_filtering_parameters_sub_cmd

This subcommand is used to add or delete a filter specification or clear a filter list for on-chip filtering.

Sub OCF: 0x01

RSSI values must use 2's complement to represent negative values.

Host shall be able to configure multiple filters with APCF_Application_Address_type set to 0x02 (for all broadcaster addresses) to manage various filter combinations.

Filtering, batching and reporting are inter-related concepts. Every advertisement and related scan response will have to go through all the filters, one after the other. Thus, resulting actions ( delivery_mode ) are closely tied to filtering. The delivery modes are the following: report_immediately , batch , and onFound . The OnLost value is related to OnFound in the sense that it will come after OnFound when lost.

This processing flow depicts the conceptual model:

When an advertisement (or scan response) frame is received, it is applied to all the filters in serial order. It's possible that an advertisement can cause immediate reporting based on one filter and batching of the same due to a different filter action.

RSSI level thresholds (high and low) give the ability to control when the frame is visible for filter processing, even when a valid packet is received by the controller. In case of delivery mode being set to immediate or batched, the RSSI of a frame is considered for further controller processing. Different apps need different reporting and batching behavior. This allows multiple apps to have direct reporting and/or batching of results in firmware, concurrently. An example is a case when a batch scan is active from one app and later a regular LE scan is issued by another app. Before a batch scan is issued, the framework/app sets appropriate filters. Later, when the second app issues a regular scan, previous batching continues. However, due to the regular scan, it is akin to conceptually adding a null filter (along with all the existing filters) along with the LE scan command. The LE scan command parameters take precedence when active. When the regular LE scan is disabled, the controller will revert back to a previous batch scan, if it existed.

The OnFound delivery mode is based on configured filters. A combination that triggers a filter's action to succeed is considered the entity to track for onLost . The corresponding event is the LE Advt tracking subevent.

The OnFound/OnLost transition for a filter (if enabled) will look like the following:

A Command Complete event will be generated for this command.

LE_APCF_Command: broadcast_address_sub_cmd

This subcommand is used to add or delete an advertiser address or to clear the advertiser address list for on-chip filtering.

Sub OCF: 0x02

A Command Complete event will be generated for this command.

LE_APCF_Command: service_uuid_sub_cmd

This subcommand is used to add or delete a service UUID or to clear a service UUID list for on-chip filtering.

Sub OCF: 0x03

A Command Complete event will be generated for this command.

LE_APCF_Command: solicitation_uuid_sub_cmd

This subcommand is used to add or delete a solicitation UUID or to clear a solicitation UUID list for on-chip filtering.

Sub OCF: 0x04

A Command Complete event will be generated for this command.

LE_APCF_Command: local_name_sub_cmd

This sub-command is used to add or delete a local name string or to clear the local name string list for on-chip filtering.

Sub OCF: 0x05

A Command Complete event will be generated for this command.

LE_APCF_Command: manf_data_sub_cmd

This subcommand is used to add or delete a manufacturer data string or to clear the manufacturer data string list for on-chip filtering.

Sub OCF: 0x06

A Command Complete event will be generated for this command.

LE_APCF_Command: service_data_sub_cmd

This subcommand is used to add or delete a service data string or to clear the service data string list for on-chip filtering.

Sub OCF: 0x07

A Command Complete event will be generated for this command.

LE_APCF_Command: ad_type_sub_cmd

This subcommand is used to add or delete an AD type or to clear an AD type list for on-chip filtering. Use read_extended_features_sub_cmd to check if this command is supported or not.

Sub OCF: 0x09

A Command Complete event will be generated for this command.

LE_APCF_Command: read_extended_features_sub_cmd

This subcommand is used to read extended APCF features.

Sub OCF: 0xFF

A Command Complete event will be generated for this command.

Controller activity and energy information command

The objective of this information is for higher host system functions to analyze the total activities of all components, including the BT controller and its macro state, in conjunction with what is happening in the apps and framework. To do this, the following information is required from the BT stack and the controller:

• BT stack: Reporting the current macro-operational state of the controller
• Firmware: Reporting aggregate activity and energy information

BT host stack macro states, as determined at the user level:

• Idle: [page scan, LE advt, inquiry scan]
• Scan: [paging/inquiry/trying to connect]
• Active: [ACL link on, SCO link ongoing, sniff mode]

The activities that the controller keeps track of over its life are Tx time, Rx time, idle time, and total energy consumed. They are cleared when read from the host.

LE_Get_Controller_Activity_Energy_Info

This is a vendor-specific command.

OCF: 0x159

A Command Complete event will be generated for this command.

LE extended set scan parameters command

This command can be used to enable a larger scan window and interval in the controller. Per the BT Core 5.2 Specification, a scan window and interval have an upper bound limit of 10.24 seconds, which hampers applications' longer scan intervals beyond 10.24 seconds.

Base reference: BT Core 5.2 Specification, page 2493 (LE Set Scan Parameters Command)

OCF: 0x15A

A Command Complete event will be generated for this command.

Get controller debug info command

The objective of this information element is to acquire controller debug information by a host, in binary form, for post-processing and analysis. This helps debug on-field issues and provides engineers with a toolkit to log information for analysis. A Controller can provide the information when requested by a host via the event (Controller Debug Info sub-event) or autonomously when desired by the controller. Example uses could be to report firmware state information, crash dump information, logging information, etc.

OCF: 0x15B

A Command Complete event will be generated for this command.

A2DP Hardware Offload Support

The A2DP Offload feature supports the offload of the A2DP audio encoding process to an audio processor attached to the BT Controller. The encoded audio data stream passes directly from the Audio processor to the BT Controller without the BT host's involvement. The BT Host is still responsible for the configuration and control of the A2DP session.

OCF: 0x15D

Start A2DP Offload

Sub OCF: 0x01

Use this command both to configure the A2DP Offload process and to start the A2DP stream.

A Command Complete event will be generated for this command.

Stop A2DP Offload

Sub OCF: 0x02

This command is used to stop the A2DP Offload stream.

No parameters are defined for this command.

A Command Complete event will be generated for this command.

Bluetooth Quality Report command

The BT Quality Report command feature starts the mechanism in the Bluetooth controller to report Bluetooth Quality events to the host. You can enable four options:

• Quality Monitoring Mode: The controller periodically sends a Link Quality related BQR sub-event to the host.
• Approaching LSTO: If no packets are received from the connected BT device for longer than half of the Link Supervision TimeOut (LSTO) value, the controller reports an Approaching LSTO event to the host.
• A2DP Audio Choppy: When the controller detects factors that cause choppy audio, the controller reports an A2DP Audio Choppy event to the host.
• (e)SCO Voice Choppy: When the controller detects factors that cause choppy voice, the controller reports an (e)SCO Voice Choppy event to the host.
• Root Inflammation: This event is sent by the controller to the stack when the HAL or the controller encounters a fatal error and needs to restart Bluetooth.
• LMP/LL message trace: The controller sends the LMP/LL message handshaking with the remote device to the host.
• Bluetooth Multi-profile/Coex scheduling trace: The controller sends its scheduling information on handling multiple Bluetooth profiles and wireless coexistence in the 2.4 Ghz band to the host.
• Controller Debug Information mechanism: When enabled, the controller can autonomously report debug logging information through the Controller debug info sub-event to the host.

OCF: 0x15E

A Command Complete event will be generated for this command.

Dynamic Audio Buffer command

The Dynamic Audio Buffer reduces audio glitching by changing the audio buffer size in the Bluetooth controller based on various scenarios.

OCF: 0x15F

Get audio buffer time capability

Sub OCF: 0x01

Use this command to get the audio buffer time capability from the Bluetooth controller.

A Command Complete event will be generated for this command.

Set audio buffer time

Sub OCF: 0x02

Use this command to set the audio buffer time to the Bluetooth controller.

A Command Complete event will be generated for this command.

HCI event (vendor-specific)

Vendor-specific HCI events are required in some cases. Refer to Figure 5.4 on page 1897 of the BT Core 5.2 Specification. Event parameter 0 will always contain the first sub-event code, based on which the rest of the HCI event is decoded.

Storage threshold breach sub-event

This event indicates that the storage threshold has been breached.

Sub-event code = 0x54

LE multi-advertising state change sub-event

This event indicates that an advertising instance has changed its state. At this time, this event is only used to indicate which advertising instance was stopped as a result of a connection.

Sub-event code = 0x55

LE advertisement tracking sub-event

This event indicates when an advertiser is found or lost.

Sub event code = 0x56

Controller debug info sub-event

This event is used by a Controller to provide binary debug information to a host.

Sub-event code = 0x57

Bluetooth Quality Report sub-event

This event indicates one of the following: a Bluetooth quality event occurred, the controller uploaded the LMP/LL message trace and Bluetooth Multi-link/Coex scheduling trace, or the controller dumped debug information data.

Sub-event code = 0x58 [Quality_Report_Id = 0x01 ~ 0x04, Link Quality related event]

Sub-event code = 0x58 [Quality_Report_Id = 0x05, Root Inflammation event]

This event indicates that Bluetooth HAL or the controller encountered a fatal error and needs Bluetooth stack to record this situation and restart. The controller must send a Root_Inflammation_Event to Bluetooth stack before sending the first fragment of the debug info events in any case.

The Error_Code parameter contains an error code reported from HAL/Controller, 0 if it is a chipset vendor specific error. The Vendor_Specific_Error_Code contains a chipset vendor specific error code from HAL/Controller. It should set as 0 if the parameter Error_Code is not 0. The parameters Error_Code and Vendor_Specific_Error_Code should not both be 0.

Sub-event code = 0x58 [Quality_Report_Id = 0x11 ~ 0x13, Log Dump related event]

Multi-advertiser support

The objectives of multi-advertiser support are the following:

• Ability to support multiple advertisements ( max_advt_instances )
• Different transmit powers to allow for a varying range
• Different advertising content
• An individualized response for each advertiser
• Privacy (non-trackable) for each advertiser
• Connectable

To keep this specification close to existing standards, the following vendor-specific commands are provided. They are derived from the Bluetooth Core 4.1 Specification.

LE_Multi_Advt_Command

OCF: 0x154

A Command Complete event will be generated for this command.

LE_Multi_Advt_Command: Set_Advt_Param_Multi_Sub_Cmd

Base reference: Bluetooth Core 4.1 Specification, page 964 (LE Set Advertising Parameter Command)

Sub OCF: 0x01

The Own_Address parameter could be a host-configured address at the time of setting up this multi-advertisement instance. This provides the ability to have a resolvable private address at the time of the transmit of the first beacon. Advertisement on an instance will continue irrespective of the connection. The host BT stack could issue a command to start advertisement on an instance, post connection.

A Command Complete event will be generated for this command as specified in the Bluetooth Core 4.1 Specification, per the above command. The controller will respond with a non-success (invalid parameter) code if the advertising instance or Tx_Power parameters are invalid.