1page.title=Bluetooth 2@jd:body 3 4<!-- 5 Copyright 2015 The Android Open Source Project 6 7 Licensed under the Apache License, Version 2.0 (the "License"); 8 you may not use this file except in compliance with the License. 9 You may obtain a copy of the License at 10 11 http://www.apache.org/licenses/LICENSE-2.0 12 13 Unless required by applicable law or agreed to in writing, software 14 distributed under the License is distributed on an "AS IS" BASIS, 15 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 16 See the License for the specific language governing permissions and 17 limitations under the License. 18--> 19<div id="qv-wrapper"> 20 <div id="qv"> 21 <h2>In this document</h2> 22 <ol id="auto-toc"> 23 </ol> 24 </div> 25</div> 26 27<img style="float: right; margin: 0px 15px 15px 15px;" src="images/ape_fwk_hal_bluetooth.png" alt="Android Bluetooth HAL icon"/> 28 29<p>Android provides a default Bluetooth stack that is divided into two layers: The Bluetooth Embedded System (BTE), 30which implements the core Bluetooth functionality, and the Bluetooth Application Layer (BTA), which 31communicates with Android framework applications.</p> 32 33<p>To fully leverage the <a href="http://developer.android.com/about/versions/android-5.0.html#BluetoothBroadcasting">Bluetooth Low Energy APIs</a> 34added in Android 5.0, you should implement the <a href="Android-6.0-Bluetooth-HCI-Reqs.pdf">Android 6.0 Bluetooth HCI Requirements</a>. 35That document initially was provided as the <a href="Android-5.0-Bluetooth-HCI-Reqs.pdf">Android 5.0 Bluetooth HCI Requirements</a>.</p> 36 37<h2 id="architecture">Architecture</h2> 38<p>A Bluetooth system service communicates with the Bluetooth stack through JNI and with applications through Binder IPC. The system service provides developers with access to various Bluetooth profiles. The following diagram shows the general structure of the Bluetooth stack: 39</p> 40 41<img src="images/ape_fwk_bluetooth.png" alt="Android Bluetooth architecture" id="figure1" /> 42<p class="img-caption"> 43 <strong>Figure 1.</strong> Bluetooth architecture 44</p> 45 46<dl> 47 <dt>Application framework</dt> 48 <dd>At the application framework level is application code, which utilizes the <a 49 href="http://developer.android.com/reference/android/bluetooth/package-summary.html">android.bluetooth</a> 50 APIs to interact with the Bluetooth hardware. Internally, this code calls the Bluetooth process through 51 the Binder IPC mechanism.</dd> 52 53 <dt>Bluetooth system service</dt> 54 <dd>The Bluetooth system service, located in <code>packages/apps/Bluetooth</code>, is packaged as an Android 55 app and implements the Bluetooth service and profiles at the Android framework layer. This app 56 calls into the HAL layer via JNI.</dd> 57 58 <dt>JNI</dt> 59 <dd>The JNI code associated with <a 60 href="http://developer.android.com/reference/android/bluetooth/package-summary.html">android.bluetooth</a> is located in 61 <code>packages/apps/Bluetooth/jni</code>. The JNI code calls into the HAL layer and receives 62 callbacks from the HAL when certain Bluetooth operations occur, such as when devices are 63 discovered.</dd> 64 65 <dt>HAL</dt> 66 <dd>The hardware abstraction layer defines the standard interface that the <a 67 href="http://developer.android.com/reference/android/bluetooth/package-summary.html">android.bluetooth</a> APIs 68 and Bluetooth process call into and that you must implement to have your Bluetooth hardware 69 function correctly. The header file for the Bluetooth HAL 70 is <code>hardware/libhardware/include/hardware/bluetooth.h</code>. Additionally, please review all of the 71 <code>hardware/libhardware/include/hardware/bt_*.h</code> files. 72 </dd> 73 74 <dt>Bluetooth stack</dt> 75 <dd>The default Bluetooth stack is provided for you and is located in 76 <code>system/bt</code>. The stack implements the generic Bluetooth HAL and 77 customizes it with extensions and configuration changes. 78 </dd> 79 80 <dt>Vendor extensions</dt> 81 <dd>To add custom extensions and an HCI layer for tracing, you can create a libbt-vendor module 82 and specify these components. 83 </dd> 84 85 </dl> 86 87<h2 id="implementing">Implementing the HAL</h2> 88<p>The Bluetooth HAL is located in <code>/hardware/libhardware/include/hardware/bluetooth.h</code>. 89Thus, the <code>bluetooth.h</code> file contains the basic interface for the Bluetooth stack, and you must implement its functions.</p> 90 91<p>Profile-specific files are located in the same directory. For details, see the <a 92href="{@docRoot}devices/halref/dir_6b11132f1a015b03f2670f21bef1d871.html">HAL File Reference</a>.</p> 93 94<p>The following is a <strong>partial</strong> list of the profile-related 95files. For the <strong>complete set</strong>, see the <code>/hardware/libhardware/include/hardware/</code> directory:</p> 96 97<ul> 98 <li><code>bt_av.h</code>: Includes the interface definition for the A2DP profile.</li> 99 <li><code>bt_gatt.h</code>, <code>bt_gatt_client.h</code>, and <code>bt_gatt_server.h</code>: These include the interface definition for the GATT profile.</li> 100 <li><code>bt_hf.h</code>: Includes the interface definition for the HFP profile.</li> 101 <li><code>bt_hh.h</code>: Includes the interface definition for the HID host profile.</li> 102 <li><code>bt_hl.h</code>: Includes the interface definition for the HDP profile.</li> 103 <li><code>bt_mce.h</code>: Includes the interface definition for the MAP profile.</li> 104 <li><code>bt_pan.h</code>: Includes the interface definition for the PAN profile.</li> 105 <li><code>bt_rc.h</code>: Includes the interface definition for the AVRCP profile.</li> 106 <li><code>bt_sock.h</code>: Includes the interface definition for RFCOMM sockets.</li> 107</ul> 108 109<p>Keep in mind that your Bluetooth implementation is not constrained to the features 110 and profiles exposed in the HAL. You can find the default implementation located 111 in the Bluetooth stack in the <code>system/bt</code> directory, 112 which implements the default HAL and also extra features and customizations.</p> 113 114 115<h2 id="customizing">Customizing the Native Bluetooth Stack</h2> 116<p>If you are using the default Bluetooth stack, but want to make a few customizations, you can 117 do the following:</p> 118<ul> 119 <li>Custom Bluetooth profiles - If you want to add Bluetooth profiles that do not have 120 HAL interfaces provided by Android, you must supply an SDK add-on download to make the profile available to app developers, make the APIs available in the Bluetooth system process app (<code>packages/apps/Bluetooth</code>), and add them to the default stack (<code>system/bt</code>).</li> 121 <li>Custom vendor extensions and configuration changes - You can add things such as extra AT commands or device-specific configuration changes 122 by creating a <code>libbt-vendor</code> module. See the <code>/hardware/broadcom/libbt</code> directory 123 for an example.</li> 124 <li>Host Controller Interface (HCI) - You can provide your own HCI by creating a <code>libbt-hci</code> module, which 125 is mainly used for debug tracing. See the <code>external/bluetooth/hci</code> directory for an example.</li> 126</ul> 127
