blob: f5e736356805898523e58bc2db1728d5aed5db72 [file] [log] [blame]
Robert Ly35f2fda2013-01-29 16:27:05 -08001page.title=Bluetooth
2@jd:body
3
4<!--
Clay Murphy1b77cc22014-12-17 18:20:06 -08005 Copyright 2014 The Android Open Source Project
Robert Ly35f2fda2013-01-29 16:27:05 -08006
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
28<p>Android provides a default Bluetooth stack, BlueDroid, that is divided into two layers: The Bluetooth Embedded System (BTE), which implements the core
29Bluetooth functionality and the Bluetooth Application Layer (BTA), which communicates
30with Android framework applications. A Bluetooth system service communicates with the Bluetooth stack through JNI and with applications through
31Binder IPC. The system service provides developers access to various Bluetooth profiles. The following
32diagram shows the general structure of the Bluetooth stack:
33</p>
34
Clay Murphy1b77cc22014-12-17 18:20:06 -080035<img src="images/bt.png" alt="Android Bluetooth architecture" id="figure1" />
36<p class="img-caption">
37 <strong>Figure 1.</strong> Bluetooth architecture
38</p>
Robert Ly35f2fda2013-01-29 16:27:05 -080039
40<dl>
41 <dt>Application framework</dt>
42 <dd>At the application framework level is the app's code, which utilizes the <a
43 href="http://developer.android.com/reference/android/bluetooth/package-summary.html">android.bluetooth</a>
44 APIs to interact with the bluetooth hardware. Internally, this code calls the Bluetooth process through
45 the Binder IPC mechanism.</dd>
46
47 <dt>Bluetooth system service</dt>
48 <dd>The Bluetooth system service, located in <code>packages/apps/Bluetooth</code>, is packaged as an Android
49 app and implements the Bluetooth service and profiles at the Android framework layer. This app
50 calls into the HAL layer via JNI.</p>
51
52 <dt>JNI</dt>
53 <dd>The JNI code associated with <a
54 href="http://developer.android.com/reference/android/bluetooth/package-summary.html">android.bluetooth</a> is located in
55 <code>packages/apps/Bluetooth/jni</code>. The JNI code calls into the HAL layer and receives
56 callbacks from the HAL when certain Bluetooth operations occur, such as when devices are
57 discovered.</dd>
58
59 <dt>HAL</dt>
60 <dd>The hardware abstraction layer defines the standard interface that the <a
61 href="http://developer.android.com/reference/android/bluetooth/package-summary.html">android.bluetooth</a> APIs
62 and Bluetooth process calls into and that you must implement to have your bluetooth hardware
63 function correctly. The header files for the Bluetooth HAL is located
64 in the <code>hardware/libhardware/include/hardware/bluetooth.h</code> and
65 <code>hardware/libhardware/include/hardware/bt_*.h</code> files.
66 </dd>
67
68 <dt>Bluetooth stack</dt>
69 <dd>The default Bluetooth stack is provided for you and is located in
70 <code>external/bluetooth/bluedroid</code>. The stack implements the generic Bluetooth HAL as well
71 as customizes it with extensions and configuration changes.
72 </dd>
73
74 <dt>Vendor extensions</dt>
75 <dd>To add custom extensions and an HCI layer for tracing, you can create a libbt-vendor module
76 and specify these components.
77 </dd>
78
79 </dl>
80
81
82<h2 id="implementing">Implementing the HAL</h2>
83<p>The Bluetooth HAL is located in the <code>hardware/libhardware/include/hardware/</code> directory
84 and consists of the following header files:
85
86<ul>
87 <li><code>bluetooth.h</code>: Contains the HAL for the Bluetooth hardware on the device</li>
88 <li><code>bt_av.h</code>: Contains the HAL for the advanced audio profile.</li>
89 <li><code>bt_hf.h</code>: Contains the HAL for the handsfree profile.</li>
90 <li><code>bt_hh.h</code>: Contains the HAL for the HID host profile</li>
91 <li><code>bt_hl.h</code>: Contains the HAL for the health profile</li>
92 <li><code>bt_pan.h</code>: Contains the HAL for the pan profile</li>
93 <li><code>bt_sock.h</code>: Contains the HAL for the socket profile.</li>
94</ul>
95
96</p>
97
98<p>Keep in mind that your Bluetooth implementation is not constrained to the features
99 and profiles exposed in the HAL. You can find the default implementation located
100 in the BlueDroid Bluetooth stack in the <code>external/bluetooth/bluedroid</code> directory,
101 which implements the default HAL and also extra features and customizations.</p>
102</p>
103
104<h2>Customizing the BlueDroid Stack</h2>
105
106<p>If you are using the default BlueDroid stack, but want to make a few customizations, you can
107 do the following things:</p>
108
109<ul>
110 <li>Custom Bluetooth profiles - If you want to add Bluetooth profiles that do not have
111 HAL interfaces provided by Android, you must supply an SDK add-on download to make the profile available to app developers,
112 make the APIs available in the Bluetooth system process app (<code>packages/apps/Bluetooth</code>), and add them
113 to the BlueDroid stack (<code>external/bluetooth/bluedroid</code>).</li>
114 <li>Custom vendor extensions and configuration changes - You can add things such as extra AT commands or device-specific configuration changes
115 by creating a <code>libbt-vendor</code> module. See the <code>vendor/broadcom/libbt-vendor</code> directory
116 for an example.</li>
117 <li>Host Controller Interface (HCI) - You can provide your own HCI by creating a <code>libbt-hci</code> module, which
118 is mainly used for debug tracing. See the <code>external/bluetooth/hci</code> directory for an example.</li>
119</ul>