Repository navigation
Add external USB Bluetooth HCI adapter support on Android. - #2227
Merged
davidz25 merged 1 commit intoNov 20, 2026
Merged
Conversation
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
approved these changes
Nov 20, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds Android support for external USB Bluetooth HCI adapters using
multipaz-bthciand wires live adapter discovery, selection persistence, USB permission management, and controller diagnostics intosamples/testapp.What Changed
multipaz-bthci:requiresControllerResetOnClosetoHciPacketIoand updatedBleHciEngine.flushAndDisconnect()to issueHCI_Resetand awaitCommand_Completebefore closing transports like USB HCI where closingUsbDeviceConnectiondoes not reset the controller.UsbHciEventAssembler,UsbHciAclAssembler,extractUsbHciCommandPayload(), andextractUsbHciAclPayload()for Bluetooth Core Spec Vol 4 Part B H4 <-> USB packet framing and reassembly.AndroidUsbHciPacketIo(androidMain) implementingHciPacketIoover Android'sUsbManager/UsbDeviceConnection/UsbRequestAPIs for standard (0xE0/0x01/0x01) and Broadcom-style vendor-specific (0xFF/0x01/0x01) USB Bluetooth HCI Primary Controllers (findBluetoothHciInterface()/isBluetoothHciDevice()).AndroidUsbHciPacketIoTestcovering fragmented/exact-multiple USB HCI events, fragmented/coalesced ACL frames, short-packet resynchronization, outbound framing validation, concurrent read/write/close lifecycle, orderly vs. fallbackHCI_Reset, duplicate open rejection, and USB disconnect handling.samples/testapp::multipaz-bthcion Android and replacedusb_nfc_readers.xmlwithusb_devices.xml+ separate CCID vs. Bluetooth HCI routing inMainActivity.handleIntent().AndroidUsbBluetoothManagerand persistedandroidBleUsbAdapterId/androidBleUsbAdapterNamesettings inTestAppSettingsModel.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).TestAppConfiguration.mdocTransportFactoryon Android (and wiredTestAppMdocNdefServiceandTestAppMdocNfcCceService) to dynamically delegate toBtHciMdocTransportFactorywhen 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=trueFixes #2226