Skip to content

Add external USB Bluetooth HCI adapter support on Android. - #2227

Merged
davidz25 merged 1 commit into
openwallet-foundation:mainfrom
davidz25-agent:bot1/android-usb-bthci
Nov 20, 2026
Merged

davidz25 merged 1 commit into
openwallet-foundation:mainfrom
davidz25-agent:bot1/android-usb-bthci

Conversation

@davidz25-agent

Copy link
Copy Markdown
Contributor

Summary

Adds Android support for external USB Bluetooth HCI adapters using multipaz-bthci and wires live adapter discovery, selection persistence, USB permission management, and controller diagnostics into samples/testapp.

What Changed

  • multipaz-bthci:
    • Added requiresControllerResetOnClose to HciPacketIo and updated BleHciEngine.flushAndDisconnect() to issue HCI_Reset and await Command_Complete before closing transports like USB HCI where closing UsbDeviceConnection does not reset the controller.
    • Added UsbHciEventAssembler, UsbHciAclAssembler, extractUsbHciCommandPayload(), and extractUsbHciAclPayload() for Bluetooth Core Spec Vol 4 Part B H4 <-> USB packet framing and reassembly.
    • Added AndroidUsbHciPacketIo (androidMain) implementing HciPacketIo over Android's UsbManager / UsbDeviceConnection / UsbRequest APIs for standard (0xE0/0x01/0x01) and Broadcom-style vendor-specific (0xFF/0x01/0x01) USB Bluetooth HCI Primary Controllers (findBluetoothHciInterface() / isBluetoothHciDevice()).
    • Added host unit tests in AndroidUsbHciPacketIoTest covering fragmented/exact-multiple USB HCI events, fragmented/coalesced ACL frames, short-packet resynchronization, outbound framing validation, concurrent read/write/close lifecycle, orderly vs. fallback HCI_Reset, duplicate open rejection, and USB disconnect handling.
  • samples/testapp:
    • Linked :multipaz-bthci on Android and replaced usb_nfc_readers.xml with usb_devices.xml + separate CCID vs. Bluetooth HCI routing in MainActivity.handleIntent().
    • Added AndroidUsbBluetoothManager and persisted androidBleUsbAdapterId / androidBleUsbAdapterName settings in TestAppSettingsModel.
    • Added an Android-only Bluetooth Adapter section in SettingsScreen (PlatformBluetoothAdapterSettingsSection) with live radio selection between Built-in Android Bluetooth (Default) and attached USB HCI adapters, connection/permission status, Grant USB Permission, and Test Adapter (HCI_Reset, HCI_Read_Local_Version_Information, HCI_Read_BD_ADDR).
    • Updated TestAppConfiguration.mdocTransportFactory on Android (and wired TestAppMdocNdefService and TestAppMdocNfcCceService) to dynamically delegate to BtHciMdocTransportFactory when an external USB adapter is selected, failing loudly if disconnected or lacking permission, and bypassing built-in Android Bluetooth permission/enabled UI gates on proximity and multi-device test screens.

Verification

  • ./gradlew :multipaz-bthci:testDebugUnitTest :multipaz-bthci:jvmTest -Pdisable.web.targets=true
  • ./gradlew :samples:testapp:assembleDebug :samples:testapp:testBlueDebugUnitTest -Pdisable.web.targets=true
  • ./gradlew :samples:testapp:compileKotlinJvm :samples:testapp:compileKotlinIosSimulatorArm64 -Pdisable.web.targets=true
  • ./gradlew detektMetadataCommonMain -Pdisable.web.targets=true
  • Manual verification on Android hardware with an external USB Bluetooth HCI adapter

Fixes #2226

Implement Bluetooth HCI over USB on Android in `multipaz-bthci` and wire
adapter selection, USB permission management, and controller diagnostics
into `samples/testapp`:

- Add `requiresControllerResetOnClose` to `HciPacketIo` and update
  `flushAndDisconnect()` in `BleHciEngine` so USB HCI controllers execute
  `HCI_Reset` while the reader loop is active prior to closing.
- Add `UsbHciEventAssembler`, `UsbHciAclAssembler`,
  `extractUsbHciCommandPayload()`, and `extractUsbHciAclPayload()` to
  frame and reassemble H4 HCI packets over USB transfers.
- Add `AndroidUsbHciPacketIo` in `multipaz-bthci` implementing
  `HciPacketIo` over Android USB host APIs for standard (`0xE0/0x01/0x01`)
  and vendor-specific (`0xFF/0x01/0x01`) USB Bluetooth HCI controllers,
  with `findBluetoothHciInterface()` and `isBluetoothHciDevice()`.
- Add host unit tests in `AndroidUsbHciPacketIoTest` covering event/ACL
  reassembly, short-packet resynchronization, outbound framing validation,
  concurrent read/write/close lifecycle, fallback reset, and disconnect
  handling.
- Update `samples/testapp` Android manifest USB device filter and
  `MainActivity` `handleIntent()` to route CCID NFC readers and USB
  Bluetooth HCI adapters separately.
- Add `AndroidUsbBluetoothManager`, persisted settings in
  `TestAppSettingsModel`, dynamic `mdocTransportFactory` delegation in
  `TestAppConfiguration` (including `TestAppMdocNdefService` and
  `TestAppMdocNfcCceService`), and an Android Bluetooth Adapter section in
  `SettingsScreen` with live hotplug status, USB permission prompting, and
  an HCI probe test action.
- Bypass built-in Android Bluetooth permission and adapter-enabled UI
  gates on proximity and multi-device test screens when an external USB
  Bluetooth adapter is selected.

Test:
- `./gradlew :multipaz-bthci:testDebugUnitTest -Pdisable.web.targets=true`
- `./gradlew :multipaz-bthci:jvmTest -Pdisable.web.targets=true`
- `./gradlew :samples:testapp:assembleDebug -Pdisable.web.targets=true`
- `./gradlew :samples:testapp:testBlueDebugUnitTest -Pdisable.web.targets=true`
- `./gradlew :samples:testapp:compileKotlinJvm -Pdisable.web.targets=true`
- `./gradlew :samples:testapp:compileKotlinIosSimulatorArm64`
  `-Pdisable.web.targets=true`
- `./gradlew detektMetadataCommonMain -Pdisable.web.targets=true`
- Manual verification on Android hardware with an external USB Bluetooth
  HCI adapter.

Signed-off-by: David Zeuthen <zeuthen@gmail.com>
@davidz25
davidz25 merged commit 4860f1d into openwallet-foundation:main Nov 20, 2026
4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Support external USB Bluetooth HCI adapters on Android in multipaz-bthci and samples/testapp

2 participants