Bluetooth HCI Snoop Log and btsnooz Debugging Guide for Android
When Bluetooth device find results are inconsistent, guessing at app logic is expensive. Android's official stack-debug guidance points to a better sequence: gather dumpsys state, collect a bugreport, extract Bluetooth traces with btsnooz.py, and then classify where failure occurs. This guide converts that into a practical workflow.
TL;DR: Use evidence before edits. Collect adb shell dumpsys bluetooth_manager, bugreport output, and HCI-level traces. Diagnose discovery, pairing, or reconnect failures from logs first, then patch.
Fast answer block for search intent
The quickest reliable Bluetooth debugging path on Android is: status snapshot, reproducible test run, bugreport capture, snoop extraction, and timeline review. This method works for "Bluetooth discovery not finding devices" and "pairing fails randomly" because it separates stack behavior from app assumptions.
Practical troubleshooting steps
- Capture adapter and service state. Run
adb shell dumpsys bluetooth_managerbefore and after reproduction. - Run one controlled reproduction. Keep distance, accessory firmware, and phone model constant for the first run.
- Generate bugreport immediately. Avoid long delay between failure and capture so timing remains useful.
- Extract Bluetooth snoop timeline. Use
btsnooz.py BUG_REPORT.txt > BTSNOOP.logand inspect in Wireshark-capable tooling. - Classify failure stage. Tag each run as discovery, pairing, encryption/bonding, reconnect, or background-resume failure.
- Compare with permissions and policy. Confirm scan permissions and background constraints match the observed stage.
- Clean test device state. Remove stale debug builds and outdated paired entries to keep repeated tests deterministic.
- Patch one variable at a time. Re-run with identical logging sequence so diffs are meaningful.
What evidence usually ends debates fastest?
- Service state snapshot: proves adapter/service conditions during failure windows.
- Snoop timeline: reveals whether packets were exchanged and where sequence breaks.
- Single-change rerun: confirms if the fix altered stack behavior or only symptoms.
Packet-level reading cheat sheet for faster triage
When reviewing BTSNOOP.log, keep a compact decode map next to the timeline. This avoids broad assumptions and speeds up handoff notes for firmware and app teams.
- Discovery signal: look for LE advertising events such as
ADV_IND,ADV_EXT_IND, and matching scan-response activity. - Connection handoff: verify
LE Create Connectioncompletion and monitor subsequent supervision timeout behavior. - Security stage: track pairing feature exchange, key distribution, and encryption start sequence boundaries.
- GATT health: inspect MTU exchange, service discovery bursts, and repeated ATT error responses.
- Recovery pattern: watch for rapid disconnect-reconnect loops that indicate policy, power, or interval mismatch.
Tag each trace with handset model, build fingerprint, peripheral firmware, and RF context. That metadata is often the difference between a fix and another inconclusive repro.
Bluetooth trace glossary for engineering handoff quality
Use exact protocol terms in tickets so firmware, mobile, and QA teams can align quickly. Ambiguous wording increases back-and-forth and slows root-cause isolation.
- LE Meta Event: umbrella event carrying subevents like connection complete, advertising report, and PHY update.
- ADV_IND / ADV_EXT_IND: advertising packet forms that change visibility behavior across scanner implementations.
- SCAN_REQ / SCAN_RSP: active scan exchange proving scanner-peripheral interaction beyond passive listening.
- CONNECT_IND: link-initiation intent; useful when \"device seen but never connected\" reports appear.
- LL_FEATURE_REQ / LL_FEATURE_RSP: confirms negotiated controller capabilities early in link setup.
- LL_LENGTH_REQ / LL_LENGTH_RSP: data-length extension negotiation often tied to throughput regressions.
- LL_PHY_REQ / LL_PHY_RSP: PHY negotiation sequence that can expose range or stability asymmetry.
- SMP Pairing Request / Response: security-manager phase where IO capability and auth method diverge.
- LTK distribution: long-term key exchange details relevant to post-bond reconnect failures.
- ATT Error Response: attribute protocol error framing that points to service/permission mismatches.
- GATT MTU Exchange: payload sizing step that can mask app-layer timeout assumptions.
- Supervision Timeout: disconnect trigger indicating missed link-layer keepalive expectations.
- Connection Parameter Update: interval/latency negotiation that affects power and responsiveness.
- RSSI trendline: signal-strength progression for movement, attenuation, and enclosure diagnostics.
Command notebook template for reproducible runs
Store the exact command sequence with every incident. A minimal notebook makes repeated triage auditable and comparable across teams.
adb shell dumpsys bluetooth_manageradb shell dumpsys activity services bluetooth_manageradb bugreport ./bugreports/session-01.zippython btsnooz.py BUG_REPORT.txt > BTSNOOP.logadb logcat -b all -v threadtimeadb shell settings get global bluetooth_onadb shell getprop ro.build.fingerprintadb shell dumpsys package your.app.idadb shell cmd bluetooth_manager enableadb shell cmd bluetooth_manager disable
FAQ
What is btsnooz used for in Bluetooth debugging?
It extracts Bluetooth snoop logs from bugreport text so packet timelines can be analyzed.
Can this workflow help with discovery problems, not just pairing?
Yes. Stage tagging covers discovery, pairing, and reconnect paths with one consistent evidence model.
Why mention cleanup in a debugging guide?
Cleaning old pairings and stale debug apps reduces noise and improves test reproducibility.