diff options
Diffstat (limited to 'en/devices/bluetooth/hci_requirements.html')
| -rw-r--r-- | en/devices/bluetooth/hci_requirements.html | 564 |
1 files changed, 303 insertions, 261 deletions
diff --git a/en/devices/bluetooth/hci_requirements.html b/en/devices/bluetooth/hci_requirements.html index 217850dc..43ffefbd 100644 --- a/en/devices/bluetooth/hci_requirements.html +++ b/en/devices/bluetooth/hci_requirements.html @@ -1,6 +1,11 @@ -<html devsite> <head> <title>HCI Requirements</title> <meta name="project_path" - value="/_project.yaml" /> <meta name="book_path" value="/_book.yaml" /> - </head> <body> +<html devsite> + <head> + <title>HCI Requirements</title> + <meta name="project_path" value="/_project.yaml" /> + <meta name="book_path" value="/_book.yaml" /> + </head> + + <body> <!-- Copyright 2017 The Android Open Source Project @@ -21,55 +26,62 @@ Bluetooth controller.</p> <p>This document provides a list of Bluetooth (BT) and Bluetooth Low - Energy (BLE) 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</p> - - <p>The Bluetooth Core 4.1 Specification, referred to in this document as - the "BT 4.1 core specification," is available on the <a - href="https://www.bluetooth.org/en-us/specification/adopted-specifications">Bluetooth - SIG website</a> along with other adopted documents.</p> + 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.</p> + + <p>This document refers to the Bluetooth Core 4.1 Specification as the + "spec." The Bluetooth Core 4.1 Specification is available on the + <a href="https://www.bluetooth.org/en-us/specification/adopted-specifications"> + Bluetooth SIG website</a> along with other adopted documents.</p> + <h2 id="general-design-overview">General design overview</h2> + <h3 id="chip-capabilities-and-configuration">Chip capabilities and configuration</h3> - <p>Android, as an open platform, has a matrix of software + + <p>As an open platform, Android has a matrix of software releases, OEMs, vendors, and platform and chip capabilities.</p> <p>To manage the varying landscape and to manage migrations, a design philosophy of allowing BT controllers to expose their capabilities - (beyond the standard BT 4.1 core specification) is described in this - document. The host BT stack can then use these capabilities to - determine which features to enable.</p> + (beyond the standard Bluetooth Core 4.1 Specification) is described + in this document. The host BT stack can then use these capabilities + to determine which features to enable.</p> <h3 id="supporting-open-standards">Supporting open standards</h3> <p> 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.</p> + <h2 id="vendor-specific-capabilities">Vendor-specific capabilities</h2> <p>Vendor-specific command: <code>LE_Get_Vendor_Capabilities_Command</code></p> - <p>OCF (OpCode Command Field): 0x153</p> + <p>OpCode Command Field (OCF): 0x153</p> <table> <tr> - <th>Command Parameter</th> + <th>Command parameter</th> <th>Size</th> <th>Purpose</th> </tr> <tr> <td></td> <td>NA</td> - <td>Empty command parameter list</td> + <td>Empty Command parameter list</td> </tr> </table> + <p> A Command Complete event will be generated for this command.</p> + <table> <tr> - <th>Return Parameter</th> - <th>Size</th> <th>Purpose</th> + <th>Return parameter</th> + <th>Size</th> + <th>Purpose</th> </tr> <tr> <td><code>Status</code></td> @@ -84,8 +96,8 @@ <tr> <td><code>offloaded_resolution_of_private-address</code></td> <td>1 octet</td> - <td>BT chip capability of RPA; if supported by a chip, - it needs enablement by the host.<br/> + <td>BT chip capability of RPA.<br/> + If supported by a chip, it needs enablement by the host.<br/> 0 = Not capable<br/> 1 = Capable</td> </tr> @@ -102,7 +114,7 @@ <tr> <td><code>filtering_support</code></td> <td>1 octet</td> - <td>Support for filtering in the controller.<br/> + <td>Support for filtering in the controller<br/> 0 = Not supported<br/> 1 = Supported</td> </tr> @@ -114,7 +126,7 @@ <tr> <td><code>activity_energy_info_support</code></td> <td>1 octet</td> - <td>Supports reporting of activity and energy information.<br/> + <td>Supports reporting of activity and energy information<br/> 0 = Not capable<br/> 1 = Capable</td> </tr> @@ -122,9 +134,9 @@ <td><code>version_supported</code></td> <td>2 octets<br/> [0x00, 0x60]</td> - <td>Specifies the version of the Google feature spec supported.<br/> - byte[0] = major number<br/> - byte[1] = minor number</td> + <td>Specifies the version of the Google feature spec supported<br/> + byte[0] = Major number<br/> + byte[1] = Minor number</td> </tr> <tr> <td><code>total_num_of_advt_tracked</code></td> @@ -146,14 +158,14 @@ <td><code>LE_address_generation_offloading_support</code></td> <td>1 octet</td> <td>0 = Not supported<br/> - 1 = supported</td> + 1 = Supported</td> </tr> </table> <p>The <code>max_advt_instances parameter</code> represents the total advertisement instances in the controller. The range of <code>advt_instance</code> IDs will be 0 to - <code>max_advt_instances-1</code>.</p> + <code>max_advt_instances</code> minus 1.</p> <p>An advertisement instance with an ID equal to 0 will map to an existing (default/standard) HCI instance. When operating on a @@ -161,6 +173,7 @@ used.</p> <h2 id="multi-advertiser-support">Multi-advertiser support</h2> + <p>The objectives of multi-advertiser support are the following:</p> <ul> @@ -182,7 +195,7 @@ <table> <tr> - <th>Command Parameter</th> + <th>Command parameter</th> <th>Size</th> <th>Purpose</th> </tr> @@ -201,7 +214,7 @@ <table> <tr> - <th>Return Parameter</th> + <th>Return parameter</th> <th>Size</th> <th>Purpose</th> </tr> @@ -222,17 +235,18 @@ </table> <h4 - id="le_multi_advt_command-set_advt_param_multi_sub_cmd">LE_Multi_Advt_Command: - Set_Advt_Param_Multi_Sub_Cmd</h4> - <p>Base reference (referred to below as "spec"): - The BT 4.1 core specification, page 964 (LE Set Advertising + id="le_multi_advt_command-set_advt_param_multi_sub_cmd"> + LE_Multi_Advt_Command: Set_Advt_Param_Multi_Sub_Cmd</h4> + + <p>Base reference: + Bluetooth Core 4.1 Specification, page 964 (LE Set Advertising Parameter Command)</p> <p>Sub OCF: 0x01</p> <table> <tr> - <th>Sub-command Parameter</th> + <th>Sub-command parameter</th> <th>Size</th> <th>Purpose</th> </tr> @@ -312,7 +326,7 @@ <table> <tr> - <th>Return Parameter</th> + <th>Return parameter</th> <th>Size</th> <th>Purpose</th> </tr> @@ -332,14 +346,14 @@ id="le_multi_advt_command-set_advt_data_multi_sub_cmd">LE_Multi_Advt_Command: Set_Advt_Data_Multi_Sub_Cmd</h4> - <p>Base reference: The BT 4.1 core specification, page 969 (LE Set - Advertising Data Command)</p> + <p>Base reference: Bluetooth Core 4.1 Specification, page 969 + (LE Set Advertising Data Command)</p> <p>Sub OCF: 0x02</p> <table> <tr> - <th>Sub-command Parameter</th> + <th>Sub-command parameter</th> <th>Size</th> <th>Purpose</th> </tr> @@ -369,7 +383,7 @@ <table> <tr> - <th>Return Parameter</th> + <th>Return parameter</th> <th>Size</th> <th>Purpose</th> </tr> @@ -388,14 +402,15 @@ <h4 id="le_multi_advt_command-set_scan_resp_data_multi_sub_cmd">LE_Multi_Advt_Command: Set_Scan_Resp_Data_Multi_Sub_Cmd</h4> - <p>Base reference: The BT 4.1 core specification, page 970 + + <p>Base reference: Bluetooth Core 4.1 Specification, page 970 (LE Set Scan Response Data Command)</p> <p>Sub OCF: 0x03</p> <table> <tr> - <th>Sub-command Parameter</th> + <th>Sub-command parameter</th> <th>Size</th> <th>Purpose</th> </tr> @@ -425,7 +440,7 @@ <table> <tr> - <th>Return Parameter</th> + <th>Return parameter</th> <th>Size</th> <th>Purpose</th> </tr> @@ -444,19 +459,19 @@ <h4 id="le_multi_advt_command-set_random_addr_multi_sub_cmd">LE_Multi_Advt_Command: Set_Random_Addr_Multi_Sub_Cmd</h4> - <p>Base reference: The BT 4.1 core specification, page 963 (LE Set - Random Address Command)</p> + <p>Base reference: Bluetooth Core 4.1 Specification, page 963 + (LE Set Random Address Command)</p> <p>Sub OCF: 0x04</p> <table> <tr> - <th>Sub-command Parameter</th> + <th>Sub-command parameter</th> <th>Size</th> <th>Purpose</th> </tr> <tr> - <td>Random Address</td> + <td><code>Random Address</code></td> <td>Per spec</td> <td>Per spec</td> </tr> @@ -472,7 +487,7 @@ <table> <tr> - <th>Return Parameter</th> + <th>Return parameter</th> <th>Size</th> <th>Purpose</th> </tr> @@ -491,14 +506,14 @@ <h4 id="le_multi_advt_command-set_advt_enable_multi_sub_cmd">LE_Multi_Advt_Command: Set_Advt_Enable_Multi_Sub_Cmd</h4> - <p>Base reference: The BT 4.1 core specification, page 971 (LE Set - Advertise Enable Command in that core specification)</p> + <p>Base reference: Bluetooth Core 4.1 Specification, page 971 + (LE Set Advertise Enable Command in that core specification)</p> <p>OCF: 0x05</p> <table> <tr> - <th>Sub-command Parameter</th> + <th>Sub-command parameter</th> <th>Size</th> <th>Purpose</th> </tr> @@ -520,7 +535,7 @@ <table> <tr> - <th>Return Parameter</th> + <th>Return parameter</th> <th>Size</th> <th>Purpose</th> </tr> @@ -538,8 +553,8 @@ <h2 id="offloaded-resolution-of-private-address">Offloaded resolution of private address</h2> - <p> This feature allows the resolution of a private address in the - controller firmware or hardware, which provides the following benefits: + <p> This feature resolves a private address in the controller firmware + or hardware, which provides the following benefits: </p> <ul> @@ -553,7 +568,7 @@ <table> <tr> - <th>Command Parameter</th> + <th>Command parameter</th> <th>Size</th> <th>Purpose</th> </tr> @@ -585,7 +600,7 @@ <table> <tr> - <th>Return Parameter</th> + <th>Return parameter</th> <th>Size</th> <th>Purpose</th> </tr> @@ -597,8 +612,8 @@ Suggested HCI status values:<br/> 0x00 Success<br/> 0x01 Unknown command (if not supported)<br/> - 0x12 Invalid command parameters (if any - parameters are outside the given range)</td> + 0x12 Invalid command parameters (if any parameters are outside + the given range)</td> </tr> </table> @@ -607,7 +622,7 @@ <table> <tr> - <th>Command Parameter</th> + <th>Command parameter</th> <th>Size</th> <th>Purpose</th> </tr> @@ -626,7 +641,7 @@ <table> <tr> - <th>Return Parameter</th> + <th>Return parameter</th> <th>Size</th> <th>Purpose</th> </tr> @@ -653,7 +668,7 @@ <table> <tr> - <th>Sub-command Parameter</th> + <th>Sub-command parameter</th> <th>Size</th> <th>Purpose</th> </tr> @@ -667,15 +682,15 @@ <p>RPA offload is required to be enabled by the host, based on the chip capability. Refer to the - <code>LE_Get_Vendor_Capabilities_Command.</code> Each chip can have - a varying <code>max_irk_list_sz </code>in the firmware. </p> + <code>LE_Get_Vendor_Capabilities_Command</code>. Each chip can have + a varying <code>max_irk_list_sz</code> in the firmware.</p> <p>A Command Complete event will be generated for this command. </p> <table> <tr> - <th>Return Parameter</th> + <th>Return parameter</th> <th>Size</th> <th>Purpose</th> </tr> @@ -696,7 +711,7 @@ <p>Sub OCF: 0x02</p> <table> <tr> - <th>Sub-command Parameter</th> + <th>Sub-command parameter</th> <th>Size</th> <th>Purpose</th> </tr> @@ -723,7 +738,7 @@ <table> <tr> - <th>Return Parameter</th> + <th>Return parameter</th> <th>Size</th> <th>Purpose</th> </tr> @@ -750,7 +765,7 @@ <table> <tr> - <th>Sub-command Parameter</th> + <th>Sub-command parameter</th> <th>Size</th> <th>Purpose</th> </tr> @@ -763,8 +778,7 @@ <tr> <td><code>LE_Device_Address</code></td> <td>6 octets</td> - <td>Public or random address that associates to - the IRK</td> + <td>Public or random address that associates to the IRK</td> </tr> </table> @@ -772,7 +786,7 @@ <table> <tr> - <th>Return Parameter</th> + <th>Return parameter</th> <th>Size</th> <th>Purpose</th> </tr> @@ -798,7 +812,7 @@ <p>Sub OCF: 0x04</p> <table> <tr> - <th>Sub-command Parameter</th> + <th>Sub-command parameter</th> <th>Size</th> <th>Purpose</th> </tr> @@ -813,7 +827,7 @@ <table> <tr> - <th>Return Parameter</th> + <th>Return parameter</th> <th>Size</th> <th>Purpose</th> </tr> @@ -841,7 +855,7 @@ <table> <tr> - <th>Sub-command Parameter</th> + <th>Sub-command parameter</th> <th>Size</th> <th>Purpose</th> </tr> @@ -857,7 +871,7 @@ <table> <tr> - <th>Return Parameter</th> + <th>Return parameter</th> <th>Size</th> <th>Purpose</th> </tr> @@ -933,7 +947,7 @@ <table> <tr> - <th>Command Parameter</th> + <th>Command parameter</th> <th>Size</th> <th>Purpose</th> </tr> @@ -952,7 +966,7 @@ <table> <tr> - <th>Return Parameter</th> + <th>Return parameter</th> <th>Size</th> <th>Purpose</th> </tr> @@ -972,12 +986,12 @@ </table> <h4 - id="le_batch_scan_command-enable-customer-specific-feature">LE_Batch_Scan_Command: - Enable Customer Specific feature</h4> + id="le_batch_scan_command-enable-customer-specific-feature"> + LE_Batch_Scan_Command: Enable Customer Specific feature</h4> <p>Sub OCF: 0x01</p> <table> <tr> - <th>Sub-command Parameter</th> + <th>Sub-command parameter</th> <th>Size</th> <th>Purpose</th> </tr> @@ -992,7 +1006,7 @@ <p>A Command Complete event will be generated for this command.</p> <table> <tr> - <th>Return Parameter</th> + <th>Return parameter</th> <th>Size</th> <th>Purpose</th> </tr> @@ -1012,32 +1026,32 @@ </table> <h4 - id="le_batch_scan_command-set-batch-scan-storage-param-subcommand">LE_Batch_Scan_Command: - Set Batch Scan Storage Param subcommand</h4> + id="le_batch_scan_command-set-batch-scan-storage-param-subcommand"> + LE_Batch_Scan_Command: Set Batch Scan Storage Param subcommand</h4> <p>Sub OCF: 0x02</p> <table> <tr> - <th>Sub-command Parameter</th> + <th>Sub-command parameter</th> <th>Size</th> <th>Purpose</th> </tr> <tr> <td><code>Batch_Scan_Full_Max</code></td> <td>1 octet</td> - <td>Max storage space (in %) allocated to full style [Range: - 0-100]</td> + <td>Max storage space (in %) allocated to full style<br/> + [Range: 0-100]</td> </tr> <tr> <td><code>Batch_Scan_Truncated_Max</code></td> <td>1 octet</td> - <td>Max storage space (in %) allocated to truncated style [Range: - 0-100]</td> + <td>Max storage space (in %) allocated to truncated style<br/> + [Range: 0-100]</td> </tr> <tr> <td><code>Batch_Scan_Notify_Threshold</code></td> <td>1 octet</td> <td>Setup notification level (in %) for individual storage pool - [Range: 0-100].<br/> + <br/>[Range: 0-100]<br/> Setting to 0 will disable notification. Vendor-specific HCI event is generated (Storage threshold breach subevent)</td> @@ -1047,7 +1061,7 @@ <p>A Command Complete event will be generated for this command.</p> <table> <tr> - <th>Return Parameter</th> + <th>Return parameter</th> <th>Size</th> <th>Purpose</th> </tr> @@ -1064,12 +1078,12 @@ </table> <h4 - id="le_batch_scan_command-set-batch-scan-param-subcommand">LE_Batch_Scan_Command: - Set Batch Scan Param subcommand</h4> + id="le_batch_scan_command-set-batch-scan-param-subcommand"> + LE_Batch_Scan_Command: Set Batch Scan Param subcommand</h4> <p>Sub OCF: 0x03</p> <table> <tr> - <th>Sub-command Parameter</th> + <th>Sub-command parameter</th> <th>Size</th> <th>Purpose</th> </tr> @@ -1110,24 +1124,25 @@ unique key for Truncated style = {<code>BD_ADDR,</code> scan_interval}. This means only one <code>BD_ADDR will</code> be recorded for each scan interval. The record to keep for Truncated - mode is the following: {<code>BD_ADDR,</code> Tx Power, RSSI, + mode is the following: {<code>BD_ADDR</code>, Tx Power, RSSI, Timestamp} </p> <p> 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 {<code>BD_ADDR,</code> 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 - <code>BA_ADDR </code>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.</p> + mode is {<code>BD_ADDR</code>, 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 + <code>BA_ADDR</code> 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. + </p> <p>A Command Complete event will be generated for this command.</p> <table> <tr> - <th>Return Parameter</th> + <th>Return parameter</th> <th>Size</th> <th>Purpose</th> </tr> @@ -1148,7 +1163,7 @@ <p>Sub OCF: 0x04</p> <table> <tr> - <th>Sub-command Parameter</th> + <th>Sub-command parameter</th> <th>Size</th> <th>Purpose</th> </tr> @@ -1159,28 +1174,30 @@ 0x02 – Full mode data</td> </tr> </table> + <p>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).</p> - - <p>Controller and host time references are not synchronized. Thus - the timestamp needs special explanation. The unit of the timestamp - is 50ms. The value of the timestamp is based off when the - <code>Read_Batch_Scan_Results_Sub_cmd </code>is given by the host. - If a command arrival time is <code>T_c</code> in the firmware, then - the actual time the timestamp was taken in the firmware is - <code>T_fw.</code> The reporting time will be: (<code>T_c</code> - - <code>T_fw)</code>. <code>T_c</code> and <code>T_fw </code>are in - the firmware time domain. This lets the host compute how long ago - the event happened.</p> + 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).</p> + + <p>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 <code>Read_Batch_Scan_Results_Sub_cmd</code> + is given by the host. If a command arrival time is + <code>T_c</code> in the firmware, then the actual time the + timestamp was taken in the firmware is <code>T_fw</code>. The + reporting time will be: (<code>T_c</code> - <code>T_fw</code>). + <code>T_c</code> and <code>T_fw </code>are in the firmware time + domain. This lets the host compute how long ago the event + happened.</p> + <table> <tr> - <th>Return Parameter</th> + <th>Return parameter</th> <th>Size</th> <th>Purpose</th> </tr> @@ -1214,7 +1231,7 @@ Tx_Pwr[0]: 1 octet<br/> RSSI[0] : 1 octet<br/> Timestamp[0]: 2 octets<br/> - [multiple records (<code>num_of_records)</code> + [multiple records (<code>num_of_records</code>) with above format]<br/> <br/> <span style="text-decoration:underline;">Full @@ -1229,9 +1246,10 @@ Scan_data_resp_len[0]: 1 octet<br/> Scan_data_resp[0]: <code>Scan_data_resp </code>octets<br/> [multiple records with above format - (<code>num_of_records)]</code></td> + (<code>num_of_records</code>)]</td> </tr> </table> + <h2 id="advertising-packet-content-filter">Advertising Packet Content Filter</h2> <p>Use this to enable/disable/setup the @@ -1241,7 +1259,7 @@ <p>OCF: 0x157</p> <table> <tr> - <th>Command Parameter</th> + <th>Command parameter</th> <th>Size</th> <th>Purpose</th> </tr> @@ -1261,7 +1279,7 @@ <p>A Command Complete event will be generated for this command.</p> <table> <tr> - <th>Return Parameter</th> + <th>Return parameter</th> <th>Size</th> <th>Purpose</th> </tr> @@ -1289,7 +1307,7 @@ <p>Sub OCF: 0x00</p> <table> <tr> - <th>Sub-command Parameter</th> + <th>Sub-command parameter</th> <th>Size</th> <th>Purpose</th> </tr> @@ -1303,7 +1321,7 @@ <p>A Command Complete event will be generated for this command.</p> <table> <tr> - <th>Return Parameter</th> + <th>Return parameter</th> <th>Size</th> <th>Purpose</th> </tr> @@ -1323,15 +1341,16 @@ <td>Enable/disable is set via <code>APCF_enable</code></td> </tr> </table> + <h4 - id="le_apcf_command-set_filtering_parameters_sub_cmd">LE_APCF_Command: - set_filtering_parameters_sub_cmd</h4> + id="le_apcf_command-set_filtering_parameters_sub_cmd"> + LE_APCF_Command: set_filtering_parameters_sub_cmd</h4> <p>This subcommand is used to add or delete a filter specification or clear a filter list for on-chip filtering.</p> <p>Sub OCF: 0x01</p> <table> <tr> - <th>Sub-command Parameter</th> + <th>Sub-command parameter</th> <th>Size</th> <th>Purpose</th> </tr> @@ -1347,8 +1366,8 @@ </tr> <tr> <td><code>APCF_Filter_Index</code></td> - <td>1 octet</td> <td>Filter index (0, - <code>max_filter-1)</code></td> + <td>1 octet</td> + <td>Filter index (0, <code>max_filter-1</code>)</td> </tr> <tr> <td><code>APCF_Feature_Selection</code></td> @@ -1365,9 +1384,9 @@ <tr> <td><code>APCF_List_Logic_Type</code></td> <td>2 octets</td> - <td>Logic operation for each feature selection - (per bit position) specified in - <code>APCF_Feature_Selection.</code><br/> + <td>Logic operation for each feature selection (per-bit + position) specified in <code>APCF_Feature_Selection</code>. + <br/> Valid only when a feature is enabled.<br/> Bit position value:<br/> 0: OR<br/> @@ -1384,14 +1403,15 @@ <td>0x00: OR<br/> 0x01: AND<br/> Note: The logic type is N/A for the first three fields - of <code>APCF_Feature_Selection,</code> which is always "AND" - logic. They are only applicable for (Bit 3 Bit 6) - four fields of <code>APCF_Feature_Selection.</code></td> + of <code>APCF_Feature_Selection</code>, which is always "AND" + logic. They are only applicable for (Bit 3 - Bit 6) + four fields of <code>APCF_Feature_Selection</code>.</td> </tr> <tr> <td><code>rssi_high_thresh</code></td> <td>1 octet</td> - <td>[In dBm] the advertiser is considered seen only if the + <td>[in dBm]<br/> + The advertiser is considered seen only if the signal is higher than the RSSI high threshold. Otherwise, the firmware must behave as if it never saw it.</td> </tr> @@ -1405,8 +1425,8 @@ <tr> <td><code>onfound_timeout</code></td> <td>2 octets</td> - <td>Valid only if <code>delivery_mode </code>is - <code>on_found</code><br/> + <td>Valid only if <code>delivery_mode</code> is + <code>on_found</code>.<br/> [in milliseconds]<br/> Time for firmware to linger and collect additional advertisements before reporting.</td> @@ -1415,19 +1435,20 @@ <td><code>onfound_timeout_cnt</code></td> <td>1 octet</td> <td>Valid only if <code>delivery_mode</code> is - <code>on_found</code><br/> + <code>on_found</code>.<br/> [count]<br/> If an advertisement in <code>onFound</code> lingers in - firmware for the <code>onfound_timeout </code>duration, + firmware for the <code>onfound_timeout</code> duration, it will collect a few advertisements and the count is checked. If the count exceeds <code>onfound_timeout_cnt</code>, - it's reported <code>OnFound</code>, + it's reported <code>OnFound</code> immediately thereafter.</td> </tr> <tr> <td><code>rssi_low_thresh</code></td> <td>1 octet</td> <td>Valid only if <code>delivery_mode</code> - is <code>on_found</code> [in dBm].<br/> + is <code>on_found</code>.<br/> + [in dBm]<br/> The advertiser packet is considered as not seen if the RSSI of the received packet is not above the RSSI low threshold.</td> @@ -1436,17 +1457,18 @@ <td><code>onlost_timeout</code></td> <td>2 octets</td> <td>Valid only if <code>delivery_mode</code> is - <code>on_found</code><br/> + <code>on_found</code>.<br/> [in milliseconds]<br/> If an advertisement, after being found, is not seen - contiguously for the <code>lost_timeout </code>period, - it will be reported lost. Reporting of lost is immediate.</td> + contiguously for the <code>lost_timeout</code> period, + it will immediately be reported lost.</td> </tr> <tr> <td><code>num_of_tracking_entries</code></td> <td>2 octets</td> <td>Valid only if <code>delivery_mode</code> is - <code>on_found</code><br/> [count]<br/> + <code>on_found</code>.<br/> + [count]<br/> Total number of advertisers to track per filter.</td> </tr> </table> @@ -1454,55 +1476,60 @@ <p> RSSI values must use 2's complement to represent negative values. </p> - <p> Host shall be able to configure multiple filters with + <p>Host shall be able to configure multiple filters with <code>APCF_Application_Address_type</code> set to 0x02 (for all broadcaster addresses) to manage various filter combinations. </p> <p> 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 (<code>delivery_mode)</code> are closely tied to filtering. + actions (<code>delivery_mode</code>) are closely tied to filtering. The delivery modes are the following: - <code>report_immediately,</code> <code>batch</code>, and - <code>onFound.</code> The <code>OnLost</code> value is related to + <code>report_immediately</code>, <code>batch</code>, and + <code>onFound</code>. The <code>OnLost</code> value is related to <code>OnFound</code> in the sense that it will come after - <code>OnFound</code> when lost. </p> + <code>OnFound</code> when lost.</p> - <p> The following processing flow depicts the conceptual model. - </p> + <p> This processing flow depicts the conceptual model:</p> <img src="images/bt_filter_batch_report.png"> <p> 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. </p> - - <p> 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 an 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. </p> + 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.</p> + + <p> 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.</p> + <p> The <code>OnFound</code> delivery mode is based on configured - filters. A combination that triggers a filter's action to succeed is - considered the entity to track for <code>onLost</code>. The - corresponding event is the LE Advt tracking subevent. </p> + filters. A combination that triggers a filter's action to succeed + is considered the entity to track for <code>onLost</code>. The + corresponding event is the LE Advt tracking subevent.</p> + <p> The <code>OnFound/OnLost</code> transition for a filter (if enabled) will look like the following: </p> <img src="images/bt_onfound_onlost.png"> - <p> A Command Complete event will be generated for this command.</p> + + <p> + A Command Complete event will be generated for this command.</p> + <table> <tr> - <th>Return Parameter</th> + <th>Return parameter</th> <th>Size</th> <th>Purpose</th> </tr> @@ -1530,12 +1557,14 @@ <h4 id="le_apcf_command-broadcast_address_sub_cmd">LE_APCF_Command: broadcast_address_sub_cmd</h4> + <p>This subcommand is used to add or delete an advertiser address or to clear the advertiser address list for on-chip filtering.</p> + <p>Sub OCF: 0x02</p> <table> <tr> - <th>Sub-command Parameter</th> + <th>Sub-command parameter</th> <th>Size</th> <th>Purpose</th> </tr> @@ -1553,7 +1582,7 @@ <tr> <td><code>APCF_Filter_Index</code></td> <td>1 octet</td> - <td>Filter index (0, <code>max_filter-1)</code></td> + <td>Filter index (0, <code>max_filter-1</code>)</td> </tr> <tr> <td><code>APCF_Broadcaster_Address</code></td> @@ -1573,7 +1602,7 @@ <p>A Command Complete event will be generated for this command.</p> <table> <tr> - <th>Return Parameter</th> + <th>Return parameter</th> <th>Size</th> <th>Purpose</th> </tr> @@ -1607,7 +1636,7 @@ <p>Sub OCF: 0x03</p> <table> <tr> - <th>Sub-command Parameter</th> + <th>Sub-command parameter</th> <th>Size</th> <th>Purpose</th> </tr> @@ -1645,7 +1674,7 @@ <p> A Command Complete event will be generated for this command.</p> <table> <tr> - <th>Return Parameter</th> + <th>Return parameter</th> <th>Size</th> <th>Purpose</th> </tr> @@ -1679,7 +1708,7 @@ <p>Sub OCF: 0x04</p> <table> <tr> - <th>Sub-command Parameter</th> + <th>Sub-command parameter</th> <th>Size</th> <th>Purpose</th> </tr> @@ -1710,13 +1739,13 @@ <td>2,4,16 octet</td> <td>The Solicitation UUID Mask (16-bit, 32-bit, or 128-bit) to add to the list. It should have the same - length as the <code>APCF_UUID.</code></td> + length as the <code>APCF_UUID</code>.</td> </tr> </table> <p>A Command Complete event will be generated for this command.</p> <table> <tr> - <th>Return Parameter</th> + <th>Return parameter</th> <th>Size</th> <th>Purpose</th> </tr> @@ -1745,12 +1774,12 @@ <h4 id="le_apcf_command-local_name_sub_cmd">LE_APCF_Command: local_name_sub_cmd</h4> - <p>This subcommand is used to add or delete a local name string or + <p>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.</p> <p>Sub OCF: 0x05</p> <table> <tr> - <th>Sub-command Parameter</th> + <th>Sub-command parameter</th> <th>Size</th> <th>Purpose</th> </tr> @@ -1776,15 +1805,18 @@ <td>A character string for local name.<br/> <br/> Notes:<br/> - i) Currently the max number of characters in a local name - string is 29<br/> - ii) Not applicable when action is "Clear" (0x2)</td> + <ul> + <li>Currently the max number of characters in a local name + string is 29</li> + <li>Not applicable when action is "Clear" (0x2)</li> + </ul> + </td> </tr> </table> <p>A Command Complete event will be generated for this command.</p> <table> <tr> - <th>Return Parameter</th> + <th>Return parameter</th> <th>Size</th> <th>Purpose</th> </tr> @@ -1807,7 +1839,7 @@ <td><code>APCF_AvailableSpaces</code></td> <td>1 octet</td> <td>Number of free entries still available in the Local name - table.</td> + table</td> </tr> </table> @@ -1819,7 +1851,7 @@ <p>Sub OCF: 0x06</p> <table> <tr> - <th>Sub-command Parameter</th> + <th>Sub-command parameter</th> <th>Size</th> <th>Purpose</th> </tr> @@ -1845,9 +1877,12 @@ <td>A character string for manufacturer data.<br/> <br/> Notes:<br/> - i) Currently the max number of characters in a local name - string is 29<br/> - ii) Not applicable when action is "Clear" (0x2)</td> + <ul> + <li>Currently the max number of characters in a local name + string is 29</li> + <li>Not applicable when action is "Clear" (0x2)</li> + </ul> + </td> </tr> <tr> <td><code>APCF_ManData_Mask</code></td> @@ -1861,7 +1896,7 @@ <p>A Command Complete event will be generated for this command.</p> <table> <tr> - <th>Return Parameter</th> + <th>Return parameter</th> <th>Size</th> <th>Purpose</th> </tr> @@ -1876,14 +1911,15 @@ <td>0x06 - APCF Manufacturer Data</td> </tr> <tr> - <td><code>APCF_Action</code></td> <td>1 octet</td> + <td><code>APCF_Action</code></td> + <td>1 octet</td> <td>Echo back command's <code>APCF_Action</code></td> </tr> <tr> <td><code>APCF_AvailableSpaces</code></td> <td>1 octet</td> <td>Number of free entries still available in the Manufacturer - Data table.</td> + Data table</td> </tr> </table> @@ -1894,7 +1930,7 @@ <p>Sub OCF: 0x07</p> <table> <tr> - <th>Sub-command Parameter</th> + <th>Sub-command parameter</th> <th>Size</th> <th>Purpose</th> </tr> @@ -1920,9 +1956,12 @@ <td>A character string for service data.<br/> <br/> Notes:<br/> - i) Currently the max number of characters in a local name - string is 29<br/> - ii) Not applicable when action is "Clear" (0x2)</td> + <ul> + <li>Currently the max number of characters in a local name + string is 29</li> + <li>Not applicable when action is "Clear" (0x2)</li> + </ul> + </td> </tr> <tr> <td><code>APCF_LocName_Mandata_or_SerData_Mask</code></td> @@ -1935,7 +1974,7 @@ <p>A Command Complete event will be generated for this command.</p> <table> <tr> - <th>Return Parameter</th> + <th>Return parameter</th> <th>Size</th> <th>Purpose</th> </tr> @@ -1958,17 +1997,17 @@ <td><code>APCF_AvailableSpaces</code></td> <td>1 octet</td> <td>Number of free entries still available for Service Data - table.</td> + table</td> </tr> </table> <h2 id="controller-activity-and-energy-information-command">Controller activity and energy information command</h2> <p>The objective of this information is for higher host system - functions to analyzethe total activities of all components, including - the BT controller and itsmacro state, in conjunction with what is - happening in the apps and framework. Todo this, the following - information is required from the BT stack and thecontroller: </p> + 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: </p> <ul> <li>BT stack: Reporting the current macro-operational state of the controller</li> @@ -1982,14 +2021,16 @@ <li>Active: [ACL link on, SCO link ongoing, sniff mode]</li> </ul> <p>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.</p> - <p>Vendor-specific command: - <code>LE_Get_Controller_Activity_Energy_Info</code> </p> + Tx time, Rx time, idle time, and total energy consumed. They are + cleared when read from the host.</p> + + <h3 id="le_get_controller_activity_energy_info"> + LE_Get_Controller_Activity_Energy_Info</h3> + <p>This is a vendor-specific command.</p>p> <p>OCF: 0x159</p> <table> <tr> - <th>Sub-command Parameter</th> + <th>Sub-command parameter</th> <th>Size</th> <th>Purpose</th> </tr> @@ -2002,7 +2043,7 @@ <p>A Command Complete event will be generated for this command.</p> <table> <tr> - <th>Return Parameter</th> + <th>Return parameter</th> <th>Size</th> <th>Purpose</th> </tr> @@ -2029,30 +2070,30 @@ <tr> <td><code>total_energy_used</code></td> <td>4 octets</td> - <td>Total energy used [product of current (mA), voltage (V) and time - (ms)]</td> + <td>Total energy used [product of current (mA), voltage (V) and + time (ms)]</td> </tr> </table> <h2 id="le-extended-set-scan-parameters-command">LE extended set scan parameters command</h2> <p>This command can be used to enable a larger scan window and interval - in the controller. Per the BT 4.1 core specification, a scan window and + in the controller. Per the BT Core 4.1 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.</p> - <p>Base reference: The BT 4.1 core specification, page 973 (LE Set Scan + <p>Base reference: BT Core 4.1 Specification, page 973 (LE Set Scan Parameters Command)</p> <p>OCF: 0x15A</p> <table> <tr> - <th>Cmd Parameter</th> + <th>Command Parameter</th> <th>Size</th> <th>Purpose</th> </tr> <tr> <td><code>LE_Ex_Scan_Type</code></td> <td>1 octet</td> - <td>0x00 - Passive scanning. No <code>SCAN_REQ </code>packets shall + <td>0x00 - Passive scanning. No <code>SCAN_REQ</code> packets shall be sent (default).<br/> 0x01 - Active scanning. <code>SCAN_REQ</code> packets may be sent.</td> @@ -2060,8 +2101,8 @@ <tr> <td><code>LE_Ex_Scan_Interval</code></td> <td>4 octets</td> - <td>Defined as the time interval from when the Controller started its - last LE scan until it begins the subsequent LE scan.<br/> + <td>Defined as the time interval from when the Controller started + its last LE scan until it began the subsequent LE scan.<br/> Range: 0x0004 to 0x00FFFFFF<br/> Default: 0x0010 (10 ms)<br/> Time = N * 0.625 ms<br/> @@ -2071,7 +2112,8 @@ <td><code>LE_Ex_Scan_Window</code></td> <td>4 octets</td> <td>The duration of the LE scan. <code>LE_Scan_Window</code> - shall be less than or equal to <code>LE_Scan_Interval</code>.<br/> + shall be less than or equal to <code>LE_Scan_Interval</code>. + <br/> Range: 0x0004 to 0xFFFF<br/> Default: 0x0010 (10 ms)<br/> Time = N * 0.625 ms<br/> @@ -2090,15 +2132,14 @@ Directed advertising packets which are not addressed for this device shall be ignored.<br/> 0x01 - Ignore advertisement packets from devices not - in the White List Only list.<br/> - Directed advertising packets which are not addressed for this - device shall be ignored.</td> + in the White List Only list. Directed advertising packets which + are not addressed for this device shall be ignored.</td> </tr> </table> <p>A Command Complete event will be generated for this command.</p> <table> <tr> - <th>Return Parameter</th> + <th>Return parameter</th> <th>Size</th> <th>Purpose</th> </tr> @@ -2113,16 +2154,16 @@ command</h2> <p>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.</p> + 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.</p> <p>OCF: 0x15B</p> <table> <tr> - <th>Cmd Parameter</th> + <th>Command parameter</th> <th>Size</th> <th>Purpose</th> </tr> @@ -2135,7 +2176,7 @@ <p>A Command Complete event will be generated for this command.</p> <table> <tr> - <th>Return Parameter</th> + <th>Return parameter</th> <th>Size</th> <th>Purpose</th> </tr> @@ -2147,9 +2188,9 @@ </table> <h2 id="hci-event-vendor-specific">HCI event (vendor-specific)</h2> <p>Vendor-specific HCI events are required in some cases. Refer to - Figure 5.4 on page 486 of the BT 4.1 core specification. Event - parameter 0 will always contain the first sub-event code, based on which - the rest of the HCI event is decoded.</p> + Figure 5.4 on page 486 of the BT Core 4.1 Specification. Event + parameter 0 will always contain the first sub-event code, based on + which the rest of the HCI event is decoded.</p> <table> <tr> <th>Event Parameter</th> @@ -2170,7 +2211,7 @@ </table> <h3 id="storage-threshold-breach-subevent">Storage threshold breach - subevent</h3> + sub-event</h3> <p>This event indicates that the storage threshold has been breached. </p> <p>Sub-event code = 0x54</p> @@ -2186,8 +2227,8 @@ <td></td> </tr> </table> - <h3 id="le-multi-advertising-state-change-subevent">LE multi-advertising - state change subevent</h3> + <h3 id="le-multi-advertising-state-change-sub-event">LE + multi-advertising state change sub-event</h3> <p>This event indicates that an advertising instance has changed its state. At this time, this event is only used to indicate which @@ -2195,15 +2236,16 @@ <p>Sub-event code = 0x55</p> <table> <tr> - <th>Sub-event Parameter</th> + <th>Sub-event parameter</th> <th>Size</th> <th>Purpose</th> </tr> <tr> <td><code>Advertising_instance</code></td> <td>1 octet</td> - <td>Identifies the specific advertising instance.<br/> - Valid values are 0 through <code>max_advt_instances</code> -1</td> + <td>Identifies the specific advertising instance<br/> + Valid values are 0 through <code>max_advt_instances</code>-1 + </td> </tr> <tr> <td><code>State_Change_Reason</code></td> @@ -2218,20 +2260,20 @@ </tr> </table> - <h3 id="le-advertisement-tracking-subevent">LE advertisement tracking - subevent</h3> + <h3 id="le-advertisement-tracking-sub-event">LE advertisement tracking + sub-event</h3> <p>This event indicates when an advertiser is found or lost.</p> <p>Sub event code = 0x56</p> <table> <tr> - <th>Sub Event Parameter</th> + <th>Sub-event Parameter</th> <th>Size</th> <th>Purpose</th> </tr> <tr> <td><code>APCF_Filter_Index</code></td> <td>1 octet</td> - <td>Filter Index (0, <code>max_filter-1)</code></td> + <td>Filter Index (0, <code>max_filter</code>-1)</td> </tr> <tr> <td><code>Advertiser_State</code></td> @@ -2242,9 +2284,9 @@ <tr> <td><code>Advt_Info_Present</code></td> <td>1 octet</td> - <td>0x00: Advertiser information (<code>Advt_Info)</code> + <td>0x00: Advertiser information (<code>Advt_Info</code>) present<br/> - 0x01: Advertiser information (<code>Advt_Info)</code> not + 0x01: Advertiser information (<code>Advt_Info</code>) not present</td> </tr> <tr> @@ -2269,18 +2311,18 @@ <code>Adv_packet_len</code> octets<br/> <code>Scan_data_resp_len[0]</code>: 1 octet<br/> <code>Scan_data_resp[0]</code>: - <code>Scan_data_resp </code>octets</td> + <code>Scan_data_resp</code> octets</td> </tr> </table> - <h3 id="controller-debug-info-subevent">Controller debug info - subevent</h3> + <h3 id="controller-debug-info-sub-event">Controller debug info + sub-event</h3> <p>This event is used by a Controller to provide binary debug information to a host.</p> - <p>Sub event code = 0x57</p> + <p>Sub-event code = 0x57</p> <table> <tr> - <th>Sub Event Parameter</th> + <th>Sub-event Parameter</th> <th>Size</th> <th>Purpose</th> </tr> |