android/README

   1 BlueZ for Android
   2 *****************
   3
   4 Since Android 4.2 there exists a well standardized HAL interface that the
   5 Bluetooth stack is expected to provide and which enables the easy replacement
   6 of the stack of choice on Android. Android BlueZ is intended as a drop-in
   7 replacement to Android provided Bluetooth stack.
   8
   9 More details about BlueZ for Android architecture and components can be found
  10 in android/hal-ipc-api.txt file.
  11
  12 Supported Android version: 4.4 KitKat and 5.0, 5.1 Lollipop
  13
  14
  15 Building and running on Android
  16 ===============================
  17
  18 Steps needed to build and run Android Open Source Project with integrated BlueZ.
  19
  20
  21 Build requirements
  22 ------------------
  23
  24 - GLib - Android 4.2 or later don't provide GLib and one must provide it in
  25 'external/bluetooth/glib' folder of Android tree. Sample Android GLib port
  26 is available at https://github.com/bluez-android/glib
  27
  28 - SBC - A2DP code requires SBC library (version 1.2 or higher) present in
  29 'external/bluetooth/sbc' directory. Library is build from Android.mk provided
  30 by BlueZ. SBC code is available at git://git.kernel.org/pub/scm/bluetooth/sbc
  31
  32 - Bionic support - Android 5.0 provides all required functionality. Running
  33 BlueZ on Android 4.4 requires backporting missing features (epoll_create1 and
  34 ppoll calls). Sample Bionic for Android 4.4 with all required features
  35 backported is available at
  36 https://github.com/bluez-android/aosp_platform_bionic
  37
  38 Runtime requirements
  39 --------------------
  40
  41 BlueZ HAL library requires 'bluetoothd' and 'bluetoothd-snoop' services to be
  42 available on Android system. Some permissions settings are also required.
  43
  44 This can be done by importing init.bluetooth.rc file in init.rc file of targeted
  45 board:
  46 import init.bluetooth.rc
  47
  48 For convenience examples are provided at:
  49 https://github.com/bluez-android/aosp_device_lge_mako           (Nexus 4)
  50 https://github.com/bluez-android/aosp_device_lge_hammerhead     (Nexus 5)
  51 https://github.com/bluez-android/aosp_device_asus_flo           (Nexus 7 2013)
  52
  53 Security-Enhanced Linux in Android
  54 ----------------------------------
  55
  56 Since 5.0 release Android moved to full enforcement of SELinux. This requires
  57 proper policy to be provided for all BlueZ for Android services (and services
  58 interacting with BlueZ). Policies should be placed in external/selinux/ path.
  59
  60 Required policy files are provided at:
  61 bluetoothd.te
  62 bluetoothd_snoop.te
  63
  64 For convenience sepolicy.git with all required policies is available at:
  65 https://github.com/bluez-android/aosp_platform_external_sepolicy
  66
  67 Downloading and building
  68 ------------------------
  69
  70 Building for Android requires full Android AOSP source tree. Sample Android tree
  71 with all required components present is available at
  72 https://github.com/bluez-android
  73
  74 This tree provides support for Nexus4 (mako), Nexus 5 (hammerhead) and
  75 Nexus 7 2013 (flo, deb). Tree does not provide binary blobs needed to run
  76 Android on supported devices. Those can be obtained from
  77 https://developers.google.com/android/nexus/drivers. Binary blobs needs to be
  78 unpacked (EULA acceptance required) into 'vendor' directory of Android tree.
  79
  80 Downloading:
  81 Android 5.0 - 'lollipop' branch
  82 Android 4.4 - 'kitkat' branch
  83
  84 repo init -u https://github.com/bluez-android/aosp_platform_manifest \
  85         -b lollipop
  86 repo sync
  87
  88 Building:
  89 source build/envsetup.sh
  90 lunch aosp_<target>-userdebug
  91 make -j8
  92
  93 Flashing:
  94 adb reboot bootloader
  95 fastboot flashall -w
  96
  97 After full build is done it is possible to rebuild only BlueZ:
  98 'cd external/bluetooth/bluez/android/'
  99 'mm' (or 'mm -B' to force rebuilding of all files)
 100 'adb sync' to update target device.
 101
 102 Downloading and building for Intel devices
 103 ------------------------------------------
 104
 105 Sample Android tree with all required components for Intel devices based on
 106 Intel reference image (https://01.org/android-ia) can be reconstructed following
 107 instructions below.
 108
 109 This tree provides support for Dell XPS12, Minnowboard MAX, Intel NUC,
 110 Acer Iconia W700 and other devices mentioned in:
 111 https://01.org/android-ia/guides/devices
 112
 113 Downloading:
 114 repo init -u https://github.com/01org/android-bluez-manifest.git -b android-ia \
 115         -m topic/bluez
 116 repo sync
 117
 118 Building:
 119 source build/envsetup.sh
 120 lunch haswell_generic-eng
 121 make -j8
 122
 123 Installing:
 124 Live and Install image is $OUT/live.img
 125 Flash live.img to USB flash and boot from it. More instructions here:
 126 https://01.org/android-ia/guides/developers/build-and-install
 127
 128 Linux Kernel requirements
 129 -------------------------
 130
 131 BlueZ for Android uses Linux Bluetooth subsystem and it must be enabled in
 132 kernel. Minimal required version of management interface is 1.3. This
 133 corresponds to Linux 3.9 but latest available version is recommended. Other
 134 requirements include UHID and network bridge support.
 135
 136 Following kernel options should be enabled:
 137 CONFIG_BT
 138 CONFIG_BT_RFCOMM
 139 CONFIG_BT_RFCOMM_TTY
 140 CONFIG_BT_BNEP
 141 CONFIG_BT_BNEP_MC_FILTER
 142 CONFIG_BT_BNEP_PROTO_FILTER
 143 CONFIG_BRIDGE
 144 CONFIG_UHID
 145 CONFIG_CRYPTO_CMAC
 146 CONFIG_CRYPTO_USER_API
 147 CONFIG_CRYPTO_USER_API_HASH
 148 CONFIG_CRYPTO_USER_API_SKCIPHER
 149
 150 Also BT chip driver needs to be enabled e.g:
 151 CONFIG_BT_HCIBTUSB
 152
 153 If it is not possible to use new enough Linux kernel one can use updated
 154 bluetooth subsystem from Backports project. More information about Backports can
 155 be found at https://backports.wiki.kernel.org. Sample kernels using backports
 156 for running BlueZ on Android are available at https://github.com/bluez-android.
 157
 158
 159 Running with Valgrind
 160 ---------------------
 161
 162 BlueZ for Android is preconfigured to be easily run under Valgrind memcheck.
 163 Appropriate configuration and required modules are automatically included when
 164 building either userdebug or eng variant of Android platform.
 165
 166 Valgrind can be enabled in runtime by setting "persist.sys.bluetooth.valgrind"
 167 property to either literal "true" or any numeric value >0. For example:
 168 adb root
 169 adb shell setprop persist.sys.bluetooth.valgrind true
 170
 171 After changing property value Bluetooth need to be restarted to apply changes
 172 (this can be done using UI, just disable and enable it again). Property is
 173 persistent, i.e. there's no need to enable Valgrind again after reboot.
 174
 175 It's recommended to have unstripped libglib.so installed which will enable
 176 complete backtraces in Valgrind output. Otherwise, in many cases backtrace
 177 will break at e.g. g_free() function without prior callers. It's possible to
 178 have proper library installed automatically by appropriate entry in Android.mk,
 179 see https://github.com/bluez-android/glib for an example.
 180
 181 When running with valgrind SElinux needs to be set into permissive mode. This
 182 can be done by executing 'setenforce 0' from root shell.
 183
 184
 185 Enabling BlueZ debugs
 186 ---------------------
 187
 188 BlueZ debug logs can be enabled in runtime by setting
 189 "persist.sys.bluetooth.debug" property to either literal "true" or any
 190 numeric value >0. For example:
 191 adb root
 192 adb shell setprop persist.sys.bluetooth.debug 1
 193
 194 After changing property value Bluetooth needs to be restarted to apply changes.
 195
 196 There is also a possibility to enable mgmt debug logs which also enables debugs
 197 as above. To enable it proceed in the same way as described above but use
 198 system properties called: persist.sys.bluetooth.mgmtdbg
 199
 200 Note: Debugs are only available on NON USER build variants
 201
 202
 203 Customization
 204 -------------
 205
 206 It is possible to customize BlueZ for Android through Android system properties.
 207 This may include enabling extra profiles or features inside HALs implementation
 208 These properties are read on Bluetooth stack startup only and require stack
 209 restart if changed. All customization properties names start with
 210 "persist.sys.bluetooth." or "ro.bluetooth." followed by specific HAL name e.g.
 211 "persist.sys.bluetooth.handsfree". If both are present "persist.sys.bluetooth."
 212 takes precedence. This allows for read only properties to be set during build
 213 leaving enough flexibility for developing or debugging purposes.
 214 This section list available customization options.
 215
 216 Property        Value           Description
 217 -------------------------------------------
 218 mode            bredr           Enable BlueZ in BR/EDR mode
 219                 le              Enable BlueZ in LE mode
 220                 <none>          Enable BlueZ in default mode - enable BR/EDR/LE
 221                                 if available.
 222 handsfree       hfp             Enable Handsfree Profile (HFP) with narrowband
 223                                 speech only
 224                 hfp_wbs         Enable Handsfree Profile (HFP) with narrowband
 225                                 and wideband speech support
 226                 <none>          Don't enable Handsfree Profile (HFP)
 227 vendor          <any>           Set vendor name in DIS. If not set fallback to
 228                                 "ro.product.manufacturer".
 229 model           <any>           Set model name used as default adapter name.
 230                                 If not set fallback to "ro.product.model".
 231 name            <any>           Set model number in DIS. If not set fallback to
 232                                 "ro.product.name".
 233 serialno        <any>           Set serial number in DIS. If not set fallback to
 234                                 "ro.serialno".
 235 systemid        <uint64>        Set system ID in DIS. Hex string encoded uint64.
 236 pnpid           <any>           PnP information used in DIS and DID profiles.
 237                                 Required format: "Source:VID:PID:Version".
 238                                 Source must be either "bluetooth" or "usb".
 239                                 VID, PID and Version are uint16. Version is
 240                                 optional.
 241 fwrev           <any>           Firmware revision in DIS. If not set fallback to
 242                                 "ro.build.version.release".
 243 hwrew           <any>           Hardware revision in DIS. If not set fallback to
 244                                 "ro.board.platform".
 245
 246
 247 Building and running on Linux
 248 -----------------------------
 249
 250 It is possible to build and test BlueZ for Android daemon on Linux (eg. PC).
 251 Simply follow instructions available at README file in BlueZ top directory.
 252 Android daemon binary is located at android/bluetoothd. See next section on
 253 how to test Android daemon on Linux.
 254
 255
 256 Testing tool
 257 ------------
 258
 259 BT HAL test tools located in android/haltest is provided for HAL level testing
 260 of both Android daemon and HAL library. Start it with '-n' parameter and type
 261 'bluetooth init' in prompt to initialize HAL library. Running without parameter
 262 will make haltest try to initialize all services after start. On Android
 263 required bluetoothd service will be started automatically. On Linux it is
 264 required to start android/bluetoothd manually before init command timeout or
 265 use provided android/system-emulator, which takes care of launching daemon
 266 automatically on HAL library initialization. To deinitialize HAL library and
 267 stop daemon type 'bluetooth cleanup'. Type 'help' for more information. Tab
 268 completion is also supported.
 269
 270
 271 Implementation status
 272 =====================
 273
 274 Summary of HALs implementation status.
 275
 276 complete    - implementation is feature complete and Android Framework is able
 277               to use it normally
 278 partial     - implementation is in progress and not all required features are
 279               present, Android Framework is able to use some of features
 280 initial     - only initial implementations is present, Android Framework is
 281               able to initialize but most likely not able to use it
 282 not started - no implementation, Android Framework is not able to initialize it
 283
 284 Profile ID        HAL header         4.4 Status    5.0 status
 285 -------------------------------------------------------------
 286 core              bluetooth.h        complete      partial
 287 a2dp              bt_av.h            complete      complete
 288 gatt              bt_gatt.h          complete      partial
 289                   bt_gatt_client.h   complete      partial
 290                   bt_gatt_server.h   complete      partial
 291 handsfree         bt_hf.h            complete      complete
 292 hidhost           bt_hh.h            complete      complete
 293 health            bt_hl.h            complete      complete
 294 pan               bt_pan.h           complete      complete
 295 avrcp             bt_rc.h            complete      complete
 296 socket            bt_sock.h          complete      partial
 297 handsfree_client  bt_hf_client.h     N/A           complete
 298 map_client        bt_mce.h           N/A           complete
 299 a2dp_sink         bt_av.h            N/A           partial
 300 avrcp_ctrl        bt_rc.h            N/A           partial
 301
 302
 303 Implementation shortcomings
 304 ===========================
 305
 306 It is possible that some of HAL functionality (although being marked as
 307 complete) is missing implementation due to reasons like feature feasibility or
 308 necessity for latest Android Framework. This sections provides list of such
 309 deficiencies. Note that HAL library is always expected to fully implement HAL
 310 API so missing implementation might happen only in daemon.
 311
 312
 313 HAL Bluetooth
 314 -------------
 315
 316 methods:
 317 dut_mode_send                      never called from Android Framework
 318 le_test_mode                       never called from Android Framework
 319
 320 callbacks:
 321 dut_mode_recv_cb                   empty JNI implementation
 322 le_test_mode_cb                    empty JNI implementation
 323
 324 properties:
 325 BT_PROPERTY_SERVICE_RECORD         not supported for adapter, for device this
 326                                    property is returned as a response to
 327                                    get_remote_service_record call
 328
 329 BT_PROPERTY_REMOTE_VERSION_INFO    information required by this property (LMP
 330                                    information) are not accessible from mgmt
 331                                    interface, also marking this property as
 332                                    settable is probably a typo in HAL header
 333
 334 HAL Socket
 335 ----------
 336
 337 Support only for BTSOCK_RFCOMM socket type.
 338
 339
 340 HAL AVRCP
 341 ---------
 342
 343 methods:
 344 list_player_app_attr_rsp           never called from Android Framework
 345 list_player_app_value_rsp          never called from Android Framework
 346 get_player_app_value_rsp           never called from Android Framework
 347 get_player_app_attr_text_rsp       never called from Android Framework
 348 get_player_app_value_text_rsp      never called from Android Framework
 349 set_player_app_value_rsp           never called from Android Framework
 350
 351 callbacks:
 352 list_player_app_attr_cb            NULL JNI implementation
 353 list_player_app_values_cb          NULL JNI implementation
 354 get_player_app_value_cb            NULL JNI implementation
 355 get_player_app_attrs_text_cb       NULL JNI implementation
 356 get_player_app_values_text_cb      NULL JNI implementation
 357 set_player_app_value_cb            NULL JNI implementation
 358
 359
 360 HAL GATT
 361 --------
 362
 363 methods:
 364 client->set_adv_data               missing kernel support for vendor data
 365 client->connect                    is_direct parameter is ignored
 366
 367
 368 Audio SCO HAL
 369 =============
 370
 371 When Bluetooth chip's audio is not wired directly to device audio, Audio SCO
 372 HAL is used to enable SCO support. It needs to be loaded by AudioFlinger
 373 following audio_policy.conf configuration. Example of configuration is shown
 374 below:
 375
 376 ...
 377   sco {
 378     outputs {
 379       sco {
 380         sampling_rates 8000|44100
 381         channel_masks AUDIO_CHANNEL_OUT_STEREO
 382         formats AUDIO_FORMAT_PCM_16_BIT
 383         devices AUDIO_DEVICE_OUT_ALL_SCO
 384       }
 385     }
 386     inputs {
 387       sco {
 388         sampling_rates 8000|44100
 389         channel_masks AUDIO_CHANNEL_IN_MONO
 390         formats AUDIO_FORMAT_PCM_16_BIT
 391         devices AUDIO_DEVICE_IN_BLUETOOTH_SCO_HEADSET
 392       }
 393     }
 394   }
 395 ...
 396
 397 Known Android issues
 398 ====================
 399
 400 It is possible that BlueZ is triggering bugs on Android Framework that could
 401 affect qualification or user experience. This section provides list of
 402 recommended Android fixes that are not part of latest AOSP release supported by
 403 BlueZ.
 404
 405 For Android 5.1 Lollipop:
 406 https://android-review.googlesource.com/177314
 407
 408 For Android 5.0 Lollipop:
 409 https://android-review.googlesource.com/99761
 410 https://android-review.googlesource.com/100297
 411 https://android-review.googlesource.com/102882
 412 https://android-review.googlesource.com/132733
 413 https://android-review.googlesource.com/132763
 414 https://android-review.googlesource.com/177314
 415
 416 For Android 4.4 KitKat:
 417 https://android-review.googlesource.com/82757
 418 https://android-review.googlesource.com/87670
 419 https://android-review.googlesource.com/88384
 420 https://android-review.googlesource.com/99761
 421 https://android-review.googlesource.com/99850
 422 https://android-review.googlesource.com/100297
 423 https://android-review.googlesource.com/102882
 424 https://android-review.googlesource.com/177314
 425
 426 Unimplemented Bluetooth features
 427 ================================
 428
 429 Some Bluetooth functionality require support from outside of BT stack
 430 eg. telephony stack. This sections describes profiles optional features not
 431 implemented due to lack of support in other Android subsystems or missing API
 432 in respective BT HALs.
 433
 434 Profile         Feature                         Comments
 435 --------------------------------------------------------
 436 HFP             Attach a phone number to        AT+BINP=1
 437                 a voice tag
 438 HFP             Enhanced Call Control           AT+CHLD={1x,2x}
 439 HFP             Explicit Call Transfer          AT+CHLD=4
 440 HFP             Response and Hold               AT+BTRH, +BTRH
 441 HFP             In-band Ring Tone               +BSIR
 442 AVRCP           Player Settings                 HAL API present but not used
 443 AVRCP           Browsing                        No HAL API
 444 GATT            Read multiple characteristics   No HAL API
 445
 446
 447 Reporting Bugs
 448 ==============
 449
 450 Bugs should be reported at https://01.org/jira/browse/BA. When reporting
 451 a bug please attach logs from logcat (logcat -v time) and HCI trace. Daemon
 452 debug logs should be enabled. When reporting daemon crash please run it under
 453 valgrind if possible. For details on how to enabled debug logs and valgrind see
 454 "Enabling BlueZ debugs" section.