跪拜 Guibai
← All articles
Android

What startDiscovery() Actually Returns: Tracing Android Bluetooth Discovery to the Controller

By 阿杰m ·
Read original on juejin.cn ↗ Google Translate ↗ Alt translation

Misreading startDiscovery()'s boolean reply as proof of discovery leads to empty lists and wasted debugging. This walkthrough of the full stack explains where asynchronous acceptance happens, why a discovery can be shared across apps, and how to correlate app logs with HCI-level evidence, so developer don't chase the wrong layer when devices don't appear.

Summary

The Chinese Android source-code series takes a single call to startDiscovery() and walks it through the entire Bluetooth stack. The key lesson is that the boolean return is just an admission of the request into the system: devices arrive later asynchronously via ACTION_FOUND broadcasts, and the same discovery can be shared among multiple packages. The trace shows where the App's observation window ends and where the system's own state machine takes over.

The article also nails down the architecture many developers gloss over: the App talks to a service in the Bluetooth process, not directly to the controller. A JNI callback bridge hands work to native BTIF, then BTA, then BTM, which builds an HCI Inquiry command. That command is queued in the HciLayer, sent through the default AIDL HAL (implemented partly in Rust), and finally written to a Linux HCI user channel socket or a virtual controller. Every layer has its own acceptance point, and confusion between them causes false debugging conclusions.

A complete, copy-paste demo runs on Android 13+ and logs REQUEST, STARTED, FOUND, FINISHED, and LOCAL_END events on the main thread. The article also explains how to pair this with HCI snoop logs to correlate app-visible results with controller-level commands, and it flags common traps like deep-copied properties and the fact that cancelDiscovery's return doesn't guarantee the controller stopped.

Takeaways
— startDiscovery() returning true only means the Android service accepted the call; no device has been found yet.
— Device results arrive asynchronously via ACTION_FOUND broadcasts, and the App must register a BroadcastReceiver before calling startDiscovery().
— A single discovery can be shared among multiple packages: a new caller may receive STARTED and cached results without a new HCI Inquiry being issued.
— The App's observation window is separate from the system's discovery lifecycle; FINISHED broadcast and LOCAL_END are different endpoints.
— The HCI Inquiry command's duration unit is 1.28 seconds per count, not milliseconds.
— In Android 13+ with the default AIDL HAL, HCI commands flow through a Rust-based HciProxy and module chain to a C++ BluetoothHci implementation.
— The default HAL tries to open a Linux HCI user channel socket (HCI_CHANNEL_USER), not raw L2CAP; Android consumes HCI events in userspace.
— Device properties are deep-copied before crossing the JNI thread; the original bt_property_t.val may point to local data that becomes invalid.
— cancelDiscovery() returning true does not guarantee the controller has stopped; other packages may keep the discovery alive, and the HCI cancel response can arrive later.
— A FINISHED broadcast with zero FOUND results is not necessarily a failure; it can happen on an AVD with no discoverable peer.
Conclusions

The layered acceptance points—Java boolean, native command status, and controller command complete—explain why simple true/false checks are insufficient for debugging Bluetooth discovery.

The modern Android Bluetooth stack mixes Java, C++, Rust, and a Linux kernel path; tracing one call requires following function pointers and Binder connections, not just looking at class names.

The distinction between user channel and raw channel is subtle but important: Android deliberately bypasses Linux's normal Bluetooth protocol handling, so kernel hooks like L2CAP are not used on this path.

The article's insistence on linking fixed source commits to observations is a practical reminder that Android Bluetooth behavior changes between versions; a developer must verify against their exact build.

The shared-discovery model, where multiple apps piggyback on one system scan, is a design that reduces radio activity but complicates app-side lifecycle management.

Concepts & terms
HCI (Host Controller Interface)
The interface between the Bluetooth host stack and the controller hardware, defining commands, events, and data packets. In this context, it's the layer where Inquiry commands are packaged and sent to the controller.
Inquiry
The classic Bluetooth BR/EDR procedure for discovering devices in discoverable mode. The host sends an Inquiry command with a LAP and duration; results come back as Inquiry Result events and completion as Inquiry Complete.
HCI user channel
A Linux socket channel (HCI_CHANNEL_USER) that gives a userspace process exclusive access to HCI commands and events for a device, bypassing the kernel's normal Bluetooth protocol handling. Android uses this to consume HCI data directly.
BTIF/BTA/BTM
Layers in Android's native Bluetooth stack: BTIF (Bluetooth Interface) bridges Java and C++, BTA (Bluetooth Application) provides high-level services, and BTM (Bluetooth Manager) handles core management like inquiry and pairing.
AIDL HAL
The hardware abstraction layer for Bluetooth defined with Android Interface Definition Language. In this version, the default implementation uses a Rust-based service and a C++ BluetoothHci object to send HCI bytes to the transport.
From the discussion
Featured comments
booboosui

Let me add a time constant that matches your section 13.1: the official comment for startDiscovery says the inquiry scan lasts about 12 seconds, and only then does it do a page scan for each newly discovered device to fetch the name. So FOUND arriving first and the name arriving later are two separate actions, not a single callback. If the name stays empty, it's usually not that the device is broken; it's that that particular page scan didn't succeed. Identify the device by address and RSSI for now. The same comment also has a line that's rarely mentioned: discovery is a heavyweight operation; don't create new connections during discovery, and existing connections will lose bandwidth and gain latency. It explicitly requires that even if this round of discovery wasn't initiated by you, you should still call cancelDiscovery, because discovery runs as a system service and isn't under your Activity's control. Another counterexample: the list stays empty. The comment states that only devices that are in a discoverable state and have inquiry scan enabled will be found. Many devices are not visible by default; you have to long-press to enter pairing mode. For such an empty list, the fault isn't in the code. I didn't follow the branch about package-name-based sharing determination in section 13.8; the above points are only based on the comments and real-device behavior.

See top comments, translated →
Source: juejin.cn ↗ Google Translate ↗ Backup ↗