pdk/docs/porting/bluetooth.jd - platform/development - Git at Google

 page.title=Bluetooth
 pdk.version=1.0
 doc.type=porting
 @jd:body

 <div id="qv-wrapper">
 <div id="qv">
 <h2>In this document</h2>
 <a name="toc"/>
 <ul>
 <li><a href="#androidBluetoothPorting">Porting</a></li>
 <li><a href="#androidBluetoothCompiling">Compiling</a></li>
 <li><a href="#androidBluetoothTroubleshooting">Troubleshooting</a></li>
 <li><a href="#androidBluetoothTools">Tools</a></li>
 <li><a href="#androidBluetoothFeatures">Feature Support</a></li>
 </ul>
 </div>
 </div>

 <p>Android's Bluetooth stack uses BlueZ as the host stack.</p>

 <p>Bluez is GPL licensed, so the Android framework interacts with userspace bluez code through D-BUS IPC to avoid proprietary code.</p>

 <p>The qualification notes mentioned below are example qualifications of the particular device in question. Each company has to re-qualify their product with Bluetooth SIG even if no changes are made to the Bluetooth stack.</p>

 <p>Headset and Handsfree (v1.5) profiles are implemented in the Android framework and are both tightly coupled with the Phone App. Profiles like OPP and PBAP are based on java obex. These profiles open a rfcomm socket connection into Bluez kernel bypassing the Bluez userspace stack.</p>

 <p> Profiles like A2DP, AVRCP, HID, PAN and other bluetooth functionality like pairing and scanning use the Bluez userspace stack.</p>

 <p>The diagram below offers a library-oriented view of the Bluetooth stack. Click <a href="bluetooth/bluetooth_process.html">Bluetooth Process Diagram</a> for a process-oriented view.</p>

 <p><img src="images/androidBluetooth.gif"></p>

 Solid elements represent Android blocks and dashed elements represent partner-specific blocks.


 <a name="androidBluetoothPorting"></a><h3>Porting</h3>

 <p>BlueZ is Bluetooth 2.1 compatible and should work with any 2.1 chipset and is backward compatibile with older Bluetooth versions. There are two integration points:</p>
 <p><ul>
 <li>UART driver</li>
 <li>Bluetooth Power On / Off</li>
 </ul>
 </p>


 <a name="androidBluetoothPortingDriver"></a><h4>UART Driver</h4>

 <p>The BlueZ kernel sub-system attaches to your hardware-specific UART driver using the <code>hciattach</code> daemon.</p>
 <p>For example, for MSM7201A, this is <code>drivers/serial/msm_serial.c</code>. You may also need to edit command line options to <code>hciattach</code> via <code>init.rc</code>.</p>


 <a name="androidBluetoothPortingPowerOnOff"></a><h4>Bluetooth Power On / Off</h4>

 <p>The method for powering on and off your bluetooth chip varies from Android V 1.0 to post 1.0.</p>

 <p><ul>
 <li><b>1.0</b>: Android framework writes a 0 or 1 to <code>/sys/modules/board_[PLATFORM]/parameters/bluetooth_power_on</code>.</li>

 <li><b>Post 1.0</b>: Android framework uses the linux <code>rfkill</code> API. See <code>arch/arm/mach-msm/board-trout-rfkill.c</code> for an example.</li>
 </ul>
 </p>

 <a name="androidBluetoothCompiling"></a><h4>Compiling</h4>

 <p>To compile Android with Bluetooth support enabled, add the following line to <code>BoardConfig.mk</code>.
 <pre>
 BOARD_HAVE_BLUETOOTH := true
 </pre>

 <a name="androidBluetoothTroubleshooting"></a><h3>Troubleshooting</h3>
 <p><strong>Debugging</strong></p>
 <p>To debug your bluetooth implementation, start by reading the logs (<code>adb logcat</code>) and look for ERRROR and WARNING messages regarding Bluetooth.
   Andoird uses Bluez, which comes with some useful debugging tools. The snippet below provides examples in a suggested order:</p>
 <pre>
 hciconfig -a  			# print BT chipset address and features. Useful to check if you can communicate with your BT chipset.
 hcidump -XVt  			# print live HCI UART traffic.
 hcitool scan  			# scan for local devices. Useful to check if RX/TX works.
 l2ping ADDRESS  		# ping another BT device. Useful to check if RX/TX works.
 sdptool records ADDRESS # request the SDP records of another BT device.
 </pre>

 <p><strong>Deamon Logs</strong></p>
 <p>Deamon logs for <code>bluetoothd</code> (<code>STDOUT</code>) and <code>hciattach</code> (<code>STDERR</code>) are sent to <code>/dev/null</code> by default. Edit <code>init.rc</code></span> and <code>init.PLATFORM.rc</code></span> to run these daemons under <code>logwrapper</code>, which redirects output to <code>logcat</code>.</p>
 <p><strong>hciconfig -a and hcitool</strong></p>
 <p>If you compile your own system.img for Android, and <code>hciconfig -a</code> works but <code>hcitool</code> scan doesn't, try installing the firmware for the Bluetooth chipset. This firmware isn't yet available in the open source codebase, but you can <code>adb pull</code> and then <code>adb push</code>it from a stock T-Mobile G1 (located in <code>/etc/firmware/brf6300.bin</code>).<br />
   <a name="androidBluetoothTools"></a></p>
 <h3>Tools</h3>

 <p>BlueZ provides a rich set of command line tools for debugging and interacting with the Bluetooth sub-system, including:</p>
 <p><ul>
 <li><code>hciconfig</code></li>
 <li><code>hcitool</code></li>
 <li><code>hcidump</code></li>
 <li><code>sdptool</code></li>
 <li><code>dbus-send</code></li>
 <li><code>dbus-monitor</code></li>
 </ul>
 </p>

 <a name="androidBluetoothFeatures"></a>
 <h3>Feature Support</h3>
 <p>This section provides a change history of Bluetooth features added in each Android release and provides some rough guidance as to future features. </p>
 <h4>Android 1.0 release</h4>
 <h5>Platform features</h5>
 <ul>
   <li>Based on Bluez 3.36 and Linux Kernel 2.6.25</li>
   <li>Bluetooth 2.0+EDR host stack</li>
   <li>Headset Profile 1.0 in Audio Gateway role</li>
   <li>Handsfree Profile 1.5 in Audio Gateway role</li>
   <ul>
     <li>Three-way calling</li>
     <li>Phonebook over AT commands
     </li>
   </ul>
 </ul>
 <h5>Qualifications for HTC G1 product. Each company reusing this software version has to re-qualify with Bluetooth SIG</h5>
 <ul>
   <li>QDID B014524: Host stack (SDP, L2CAP, GAP, RFCOMM, SPP)</li>
   <li>QDID B014624: EPL for HTC Dream (HSP, HFP)</li>
 </ul>
 <h5>Example products</h5>
 <ul>
   <li>HTC Dream / T-Mobile G1</li>
 </ul>
 <h4>&nbsp;</h4>
 <h4>Android 1.1 release</h4>
 <p>No Bluetooth changes since 1.0</p>
 <h4>&nbsp;</h4>
 <h4>Android 1.5 release (cupcake)</h4>
 <h4>Platform features</h4>
 <ul>
   <li>Based on Bluez 3.36 with Linux Kernel 2.6.27</li>
   <li>Bluetooth 2.0+EDR host stack</li>
   <ul>
     <li>Support for auto-pairing with '0000' devices</li>
   </ul>
   <li>Headset Profile 1.1 in Audio Gateway role</li>
   <li>Handsfree Profile 1.5 in Audio Gateway role</li>
   <ul>
     <li>Three-way calling    </li>
     <li>Phonebook over AT commands    </li>
     <li>Volume synchronization</li>
     <li>eSCO</li>
     <li>Extensive bug fixes and compatibility improvements</li>
   </ul>
   <li>Stereo Bluetooth (A2DP 1.2) in Source role</li>
   <ul>
     <li>AVDTP 1.2 in Acceptor and Initiator roles</li>
     <li>GAVDTP 1.0 in Acceptor and Initiator roles</li>
     <li>44.1 khz, stereo, software SBC codec</li>
   </ul>
   <li>Remote Control (AVRCP 1.0) in Target role</li>
   <ul>
     <li>AVCTP 1.3 in Target role</li>
     <li>play/pause/stop/prev/next</li>
   </ul>
 </ul>
 <h5>Qualifications for HTC Sapphire product. Each company reusing this software version has to re-qualify with Bluetooth SIG</h5>
 <ul>
   <li>QDID B015261: Host stack (SDP, L2CAP, GAP, RFCOMM, SPP, AVCTP, AVRCP, GAVDP, AVDTP, A2DP)</li>
   <li>QDID B015262: EPL for HTC Sapphire (HSP, HFP)</li>
 </ul>
 <h4>Android 2.0/2.1 release (eclair)</h4>
 <h4>Platform features</h4>
 <ul>
   <li>Based on Bluez 4.47 with Linux Kernel 2.6.29</li>
   <li>Bluetooth 2.1+EDR host stack</li>
   <ul>
     <li>Support for auto-pairing with '0000' devices</li>
     <li>Support for Simple Secure Pairing</li>
   </ul>
   <li>Headset Profile 1.1 in Audio Gateway role</li>
   <li>Handsfree Profile 1.5 in Audio Gateway role</li>
   <ul>
     <li>Three-way calling    </li>
     <li>Phonebook over AT commands    </li>
     <li>Volume synchronization</li>
     <li>eSCO</li>
     <li>Extensive bug fixes and compatibility improvements</li>
   </ul>
   <li>Stereo Bluetooth (A2DP 1.2) in Source role</li>
   <ul>
     <li>AVDTP 1.2 in Acceptor and Initiator roles</li>
     <li>GAVDTP 1.0 in Acceptor and Initiator roles</li>
     <li>44.1 khz, stereo, software SBC codec</li>
   </ul>
   <li>Remote Control (AVRCP 1.0) in Target role</li>
   <ul>
     <li>AVCTP 1.3 in Target role</li>
     <li>play/pause/stop/prev/next</li>
   </ul>
   <li> Object Push Profile version 1.1 </li>
   <ul>
      <li>Adds ability to transfer pictures, videos</li>
      <li>Transfer of contacts using vCard is not supported in this release.</li>
   </ul>
   <li>Phone Book Address Profile version 1.0</li>
   <ul>
     <li>Phone Book Server Equipment (PSE) role supported</li>
   </ul>
   <li>Using Java Bluetooth APIs, an Android application can peform the
   following:</li>
   <ul>
    <li>Scan for other Bluetooth devices </li>
    <li>Query the local Bluetooth adapter for paired Bluetooth devices </li>
    <li>Establish RFCOMM channels </li>
    <li>Connect to other devices through service discovery </li>
    <li>Transfer data to and from other devices </li>
    <li>Manage multiple connections </li>
   </ul>
   <li>Support for Bluetooth enabled car and desk docks</li>
   <ul>
    <li>Framework support for routing Phone Call Audio and A2DP streaming using
    car and desk docks. </li>
   </ul>
 </ul>

 <h4>Android 2.2  release (Froyo)</h4>
 <h4>Platform features</h4>
 <ul>
   <li>Based on Bluez 4.47 with Linux Kernel 2.6.32</li>
   <li>No new profiles added.</li>
   <li>Added ability to share contacts using vCard</li>
   <li>Added ability to export all contacts - useful to transfer contacts to car kits </li>
   <li>Improved compatibility with headsets and car kits. </li>
 </ul>

 <h4>Android 2.3  release (Gingerbread)</h4>
 <h4>Platform features</h4>
 <ul>
   <li>Based on Bluez 4.69 with Linux Kernel 2.6.35</li>
   <li>No new profiles added.</li>
   <li>Improved compatibility with headsets and car kits. </li>
 </ul>

 <h4>Android 3.0 release (Honeycomb)</h4>
 <h4>Platform features</h4>
 <ul>
   <li>Based on Bluez 4.69 with Linux Kernel 2.6.36</li>
   <li>HID and PAN (NAP and PANU role) are the new profiles added.
   <li>Improved compatibility with headsets and car kits. </li>
 </ul>

 <h5>&nbsp;</h5>
 <h4>Future releases</h4>
 <p>This section offers a rough guide of which features the team is developing for the next release. This feature list may change without notice. It isn't possible to post scheduling advice to the mailing lists.</p>
 <ul>
   <li>More profiles...</li>
   <li>Improved compatibility with headsets and car kits</li>
   <li>Bluetooth emulator support</li>
   <li>Bluetooth Low Energy </li>
 </ul>
	page.title=Bluetooth
	pdk.version=1.0
	doc.type=porting
	@jd:body

	<div id="qv-wrapper">
	<div id="qv">
	<h2>In this document</h2>
	<a name="toc"/>
	<ul>
	<li><a href="#androidBluetoothPorting">Porting</a></li>
	<li><a href="#androidBluetoothCompiling">Compiling</a></li>
	<li><a href="#androidBluetoothTroubleshooting">Troubleshooting</a></li>
	<li><a href="#androidBluetoothTools">Tools</a></li>
	<li><a href="#androidBluetoothFeatures">Feature Support</a></li>
	</ul>
	</div>
	</div>

	<p>Android's Bluetooth stack uses BlueZ as the host stack.</p>

	<p>Bluez is GPL licensed, so the Android framework interacts with userspace bluez code through D-BUS IPC to avoid proprietary code.</p>

	<p>The qualification notes mentioned below are example qualifications of the particular device in question. Each company has to re-qualify their product with Bluetooth SIG even if no changes are made to the Bluetooth stack.</p>

	<p>Headset and Handsfree (v1.5) profiles are implemented in the Android framework and are both tightly coupled with the Phone App. Profiles like OPP and PBAP are based on java obex. These profiles open a rfcomm socket connection into Bluez kernel bypassing the Bluez userspace stack.</p>

	<p> Profiles like A2DP, AVRCP, HID, PAN and other bluetooth functionality like pairing and scanning use the Bluez userspace stack.</p>

	<p>The diagram below offers a library-oriented view of the Bluetooth stack. Click <a href="bluetooth/bluetooth_process.html">Bluetooth Process Diagram</a> for a process-oriented view.</p>

	<p><img src="images/androidBluetooth.gif"></p>

	Solid elements represent Android blocks and dashed elements represent partner-specific blocks.



	<a name="androidBluetoothPorting"></a><h3>Porting</h3>

	<p>BlueZ is Bluetooth 2.1 compatible and should work with any 2.1 chipset and is backward compatibile with older Bluetooth versions. There are two integration points:</p>
	<p><ul>
	<li>UART driver</li>
	<li>Bluetooth Power On / Off</li>
	</ul>
	</p>


	<a name="androidBluetoothPortingDriver"></a><h4>UART Driver</h4>

	<p>The BlueZ kernel sub-system attaches to your hardware-specific UART driver using the <code>hciattach</code> daemon.</p>
	<p>For example, for MSM7201A, this is <code>drivers/serial/msm_serial.c</code>. You may also need to edit command line options to <code>hciattach</code> via <code>init.rc</code>.</p>


	<a name="androidBluetoothPortingPowerOnOff"></a><h4>Bluetooth Power On / Off</h4>

	<p>The method for powering on and off your bluetooth chip varies from Android V 1.0 to post 1.0.</p>

	<p><ul>
	<li><b>1.0</b>: Android framework writes a 0 or 1 to <code>/sys/modules/board_[PLATFORM]/parameters/bluetooth_power_on</code>.</li>

	<li><b>Post 1.0</b>: Android framework uses the linux <code>rfkill</code> API. See <code>arch/arm/mach-msm/board-trout-rfkill.c</code> for an example.</li>
	</ul>
	</p>

	<a name="androidBluetoothCompiling"></a><h4>Compiling</h4>

	<p>To compile Android with Bluetooth support enabled, add the following line to <code>BoardConfig.mk</code>.
	<pre>
	BOARD_HAVE_BLUETOOTH := true
	</pre>

	<a name="androidBluetoothTroubleshooting"></a><h3>Troubleshooting</h3>
	<p><strong>Debugging</strong></p>
	<p>To debug your bluetooth implementation, start by reading the logs (<code>adb logcat</code>) and look for ERRROR and WARNING messages regarding Bluetooth.
	Andoird uses Bluez, which comes with some useful debugging tools. The snippet below provides examples in a suggested order:</p>
	<pre>
	hciconfig -a # print BT chipset address and features. Useful to check if you can communicate with your BT chipset.
	hcidump -XVt # print live HCI UART traffic.
	hcitool scan # scan for local devices. Useful to check if RX/TX works.
	l2ping ADDRESS # ping another BT device. Useful to check if RX/TX works.
	sdptool records ADDRESS # request the SDP records of another BT device.
	</pre>

	<p><strong>Deamon Logs</strong></p>
	<p>Deamon logs for <code>bluetoothd</code> (<code>STDOUT</code>) and <code>hciattach</code> (<code>STDERR</code>) are sent to <code>/dev/null</code> by default. Edit <code>init.rc</code></span> and <code>init.PLATFORM.rc</code></span> to run these daemons under <code>logwrapper</code>, which redirects output to <code>logcat</code>.</p>
	<p><strong>hciconfig -a and hcitool</strong></p>
	<p>If you compile your own system.img for Android, and <code>hciconfig -a</code> works but <code>hcitool</code> scan doesn't, try installing the firmware for the Bluetooth chipset. This firmware isn't yet available in the open source codebase, but you can <code>adb pull</code> and then <code>adb push</code>it from a stock T-Mobile G1 (located in <code>/etc/firmware/brf6300.bin</code>).<br />
	<a name="androidBluetoothTools"></a></p>
	<h3>Tools</h3>

	<p>BlueZ provides a rich set of command line tools for debugging and interacting with the Bluetooth sub-system, including:</p>
	<p><ul>
	<li><code>hciconfig</code></li>
	<li><code>hcitool</code></li>
	<li><code>hcidump</code></li>
	<li><code>sdptool</code></li>
	<li><code>dbus-send</code></li>
	<li><code>dbus-monitor</code></li>
	</ul>
	</p>

	<a name="androidBluetoothFeatures"></a>
	<h3>Feature Support</h3>
	<p>This section provides a change history of Bluetooth features added in each Android release and provides some rough guidance as to future features. </p>
	<h4>Android 1.0 release</h4>
	<h5>Platform features</h5>
	<ul>
	<li>Based on Bluez 3.36 and Linux Kernel 2.6.25</li>
	<li>Bluetooth 2.0+EDR host stack</li>
	<li>Headset Profile 1.0 in Audio Gateway role</li>
	<li>Handsfree Profile 1.5 in Audio Gateway role</li>
	<ul>
	<li>Three-way calling</li>
	<li>Phonebook over AT commands
	</li>
	</ul>
	</ul>
	<h5>Qualifications for HTC G1 product. Each company reusing this software version has to re-qualify with Bluetooth SIG</h5>
	<ul>
	<li>QDID B014524: Host stack (SDP, L2CAP, GAP, RFCOMM, SPP)</li>
	<li>QDID B014624: EPL for HTC Dream (HSP, HFP)</li>
	</ul>
	<h5>Example products</h5>
	<ul>
	<li>HTC Dream / T-Mobile G1</li>
	</ul>
	<h4> </h4>
	<h4>Android 1.1 release</h4>
	<p>No Bluetooth changes since 1.0</p>
	<h4> </h4>
	<h4>Android 1.5 release (cupcake)</h4>
	<h4>Platform features</h4>
	<ul>
	<li>Based on Bluez 3.36 with Linux Kernel 2.6.27</li>
	<li>Bluetooth 2.0+EDR host stack</li>
	<ul>
	<li>Support for auto-pairing with '0000' devices</li>
	</ul>
	<li>Headset Profile 1.1 in Audio Gateway role</li>
	<li>Handsfree Profile 1.5 in Audio Gateway role</li>
	<ul>
	<li>Three-way calling </li>
	<li>Phonebook over AT commands </li>
	<li>Volume synchronization</li>
	<li>eSCO</li>
	<li>Extensive bug fixes and compatibility improvements</li>
	</ul>
	<li>Stereo Bluetooth (A2DP 1.2) in Source role</li>
	<ul>
	<li>AVDTP 1.2 in Acceptor and Initiator roles</li>
	<li>GAVDTP 1.0 in Acceptor and Initiator roles</li>
	<li>44.1 khz, stereo, software SBC codec</li>
	</ul>
	<li>Remote Control (AVRCP 1.0) in Target role</li>
	<ul>
	<li>AVCTP 1.3 in Target role</li>
	<li>play/pause/stop/prev/next</li>
	</ul>
	</ul>
	<h5>Qualifications for HTC Sapphire product. Each company reusing this software version has to re-qualify with Bluetooth SIG</h5>
	<ul>
	<li>QDID B015261: Host stack (SDP, L2CAP, GAP, RFCOMM, SPP, AVCTP, AVRCP, GAVDP, AVDTP, A2DP)</li>
	<li>QDID B015262: EPL for HTC Sapphire (HSP, HFP)</li>
	</ul>
	<h4>Android 2.0/2.1 release (eclair)</h4>
	<h4>Platform features</h4>
	<ul>
	<li>Based on Bluez 4.47 with Linux Kernel 2.6.29</li>
	<li>Bluetooth 2.1+EDR host stack</li>
	<ul>
	<li>Support for auto-pairing with '0000' devices</li>
	<li>Support for Simple Secure Pairing</li>
	</ul>
	<li>Headset Profile 1.1 in Audio Gateway role</li>
	<li>Handsfree Profile 1.5 in Audio Gateway role</li>
	<ul>
	<li>Three-way calling </li>
	<li>Phonebook over AT commands </li>
	<li>Volume synchronization</li>
	<li>eSCO</li>
	<li>Extensive bug fixes and compatibility improvements</li>
	</ul>
	<li>Stereo Bluetooth (A2DP 1.2) in Source role</li>
	<ul>
	<li>AVDTP 1.2 in Acceptor and Initiator roles</li>
	<li>GAVDTP 1.0 in Acceptor and Initiator roles</li>
	<li>44.1 khz, stereo, software SBC codec</li>
	</ul>
	<li>Remote Control (AVRCP 1.0) in Target role</li>
	<ul>
	<li>AVCTP 1.3 in Target role</li>
	<li>play/pause/stop/prev/next</li>
	</ul>
	<li> Object Push Profile version 1.1 </li>
	<ul>
	<li>Adds ability to transfer pictures, videos</li>
	<li>Transfer of contacts using vCard is not supported in this release.</li>
	</ul>
	<li>Phone Book Address Profile version 1.0</li>
	<ul>
	<li>Phone Book Server Equipment (PSE) role supported</li>
	</ul>
	<li>Using Java Bluetooth APIs, an Android application can peform the
	following:</li>
	<ul>
	<li>Scan for other Bluetooth devices </li>
	<li>Query the local Bluetooth adapter for paired Bluetooth devices </li>
	<li>Establish RFCOMM channels </li>
	<li>Connect to other devices through service discovery </li>
	<li>Transfer data to and from other devices </li>
	<li>Manage multiple connections </li>
	</ul>
	<li>Support for Bluetooth enabled car and desk docks</li>
	<ul>
	<li>Framework support for routing Phone Call Audio and A2DP streaming using
	car and desk docks. </li>
	</ul>
	</ul>

	<h4>Android 2.2 release (Froyo)</h4>
	<h4>Platform features</h4>
	<ul>
	<li>Based on Bluez 4.47 with Linux Kernel 2.6.32</li>
	<li>No new profiles added.</li>
	<li>Added ability to share contacts using vCard</li>
	<li>Added ability to export all contacts - useful to transfer contacts to car kits </li>
	<li>Improved compatibility with headsets and car kits. </li>
	</ul>

	<h4>Android 2.3 release (Gingerbread)</h4>
	<h4>Platform features</h4>
	<ul>
	<li>Based on Bluez 4.69 with Linux Kernel 2.6.35</li>
	<li>No new profiles added.</li>
	<li>Improved compatibility with headsets and car kits. </li>
	</ul>

	<h4>Android 3.0 release (Honeycomb)</h4>
	<h4>Platform features</h4>
	<ul>
	<li>Based on Bluez 4.69 with Linux Kernel 2.6.36</li>
	<li>HID and PAN (NAP and PANU role) are the new profiles added.
	<li>Improved compatibility with headsets and car kits. </li>
	</ul>

	<h5> </h5>
	<h4>Future releases</h4>
	<p>This section offers a rough guide of which features the team is developing for the next release. This feature list may change without notice. It isn't possible to post scheduling advice to the mailing lists.</p>
	<ul>
	<li>More profiles...</li>
	<li>Improved compatibility with headsets and car kits</li>
	<li>Bluetooth emulator support</li>
	<li>Bluetooth Low Energy </li>
	</ul>