Debugging BLE on Android: Tools, Packet Sniffers, and Log Analysis

A BLE failure crosses several boundaries: application state, Android's host stack, the phone's controller, the radio link, and peripheral firmware. A disconnect status or failed characteristic operation rarely identifies the responsible boundary by itself.

The fastest path is to capture the same failure at three boundaries: peripheral behavior, Android host-controller traffic, and application state. This guide shows a repeatable workflow using a generic BLE client, HCI snoop logs, Wireshark, Logcat, and privacy-conscious product diagnostics.

1. Establish a controlled comparison with a generic client

A generic client such as Nordic Semiconductor's nRF Connect for Mobile can exercise the advertised profile independently of your application. It does not certify the firmware, but it gives the team a controlled comparison for the same phone, peripheral state, and operation sequence.

Use it to inspect advertising data, connect, discover services and characteristics, read or write values, and subscribe to notifications or indications. Record the exact sequence and firmware version so the comparison is reproducible.

Key debugging workflows with nRF Connect

• Advertisement validation: Check that your peripheral advertises the correct service UUIDs, local name, and manufacturer-specific data. Filter by RSSI to confirm signal strength at your expected operating distance.
• Service discovery verification: After connecting, verify the full GATT table. Confirm that all services, characteristics, and descriptors are present with the correct UUIDs and properties (read, write, notify, indicate).
• Manual characteristic testing: Write values, read responses, and enable notifications or indications. A successful generic-client path narrows the investigation but does not exclude timing, phone-stack, or firmware defects.
• MTU negotiation check: Record the negotiated MTU for that client and connection. It confirms the active result, not every value the peripheral could support in another configuration.
• Bonding and pairing: Test the security flow independently and record bond state, key lifecycle, and whether the attribute requires authentication or encryption.

Use nRF Connect as a controlled comparison, one central at a time unless the peripheral explicitly supports multiple connections. Record the same firmware state and operation sequence. If the utility discovers the expected profile and your app does not, compare your timing, filters, connection state, and service validation before assigning the fault to either side.

2. Enabling and Capturing HCI Snoop Logs

Android HCI snoop logging records traffic at the host-controller boundary. It can show HCI commands and events plus host-visible ACL data, including ATT traffic. It is not an over-the-air capture: it cannot show radio packets the controller never received, and it does not replace a link-layer sniffer when RF timing or retransmission is the question.

Enabling HCI snoop logs

Many Android builds expose Bluetooth HCI snoop logging through Developer Options:

1. Go to Settings, then System, then Developer Options
2. Find "Enable Bluetooth HCI snoop log" and toggle it on
3. Reproduce the BLE issue
4. Toggle the snoop log off

Storage location and direct access vary by manufacturer and build. A bug report is the most portable starting point for a test device:

adb bugreport bugreport.zip

Extract the archive and locate the Bluetooth snoop artifact for that build. HCI captures can contain device identifiers and application payloads, so collect them on consented test devices, minimize sharing, and apply a defined retention policy.

3. Analyzing BLE Packets in Wireshark

Wireshark can read BTSnoop captures and decode the host-visible HCI, L2CAP, and ATT traffic. Advertising packets, link-layer retransmissions, and other over-the-air details require an air sniffer rather than an HCI log.

Essential Wireshark display filters for BLE

# Show only ATT protocol (GATT reads, writes, notifications)
btatt

# Filter by specific ATT opcode (e.g., Write Request = 0x12)
btatt.opcode == 0x12

# Show HCI commands and events
bthci_cmd || bthci_evt

# Show GATT notifications only
btatt.opcode == 0x1b

# Show errors (ATT Error Response)
btatt.opcode == 0x01

The ATT Error Response filter (btatt.opcode == 0x01) is useful when the peripheral returned a protocol-level error such as insufficient authentication, invalid handle, or write not permitted. An empty result does not exclude a disconnect, controller error, application timeout, or packet lost before the host boundary.

Diagnosing connection parameter issues

One of the most common BLE problems on Android is connection parameter mismatches. In Wireshark, filter for bthci_evt.le_meta_subevent == 0x03 to see Connection Update Complete events. Check the resulting connection interval, peripheral latency, and supervision timeout. If the peripheral requests parameters that Android rejects, you will see the negotiation play out in the capture.

A useful trace lets you answer specific questions: which side initiated the parameter update, what values were accepted, which side terminated the connection, and what controller reason was reported. Keep those timestamps aligned with firmware and app logs so the team can work from one timeline.

4. Logcat Filtering for BluetoothGatt

An HCI trace shows the host-controller boundary; Logcat shows application callbacks and some Android stack events. Neither is a complete radio view. Align both with firmware logs and an air trace when the missing evidence is below HCI.

Key Logcat tags for BLE debugging

# Core BLE GATT operations
adb logcat -s BluetoothGatt:V BluetoothAdapter:V

# Broader Bluetooth stack logging
adb logcat -s bt_btif:V bt_btif_gatt:V BtGatt.GattService:V

# Connection management
adb logcat -s BluetoothGatt:V BtGatt.ContextMap:V

# Broad Logcat filter for common Bluetooth tag names
adb logcat | grep -i "bluetooth\|bt_\|BtGatt\|BluetoothGatt"

Decoding BluetoothGatt status codes

The BluetoothGattCallback connection, discovery, and characteristic-operation callbacks include a numeric status. Preserve it in decimal and hexadecimal along with the callback, old and new state, active operation, and elapsed time. Some values reflect ATT or Android GATT status; connection callbacks can also surface controller reason codes.

• 0: success for the relevant callback.
• 0x08: connection timeout at the controller boundary; the trace is needed to distinguish range, RF, scheduling, or peripheral behavior.
• 0x13: remote user terminated the connection. Confirm the reason in firmware state rather than assuming intent from the label alone.
• 0x16: connection terminated by the local host. Correlate it with application disconnect or close calls and Android lifecycle events.
• 0x3E: connection failed to establish. Compare advertising, scan-to-connect timing, and controller events.
• 133: Android's generic GATT error. It does not identify a root cause.

Do not turn these labels into automatic remedies. Adapter resets, bond removal, or repeated reconnect loops can destroy useful state and disrupt other applications. Choose recovery from the connection state machine and reproduced evidence.

5. Common BLE Error Patterns and Their Root Causes

Use recurring symptoms to choose evidence, not to declare a root cause from one status value.

Pattern: Status 133 after reconnection

If status 133 appears after reconnect, first verify connection ownership: the previous BluetoothGatt instance should be closed, late callbacks should be ignored, and only one reconnect attempt should be active. These checks remove common application races without pretending that a generic status identifies one universal cause.

Model one owner for each BluetoothGatt instance, make late callbacks harmless, and schedule reconnect through the connection state machine. Close an instance when it is no longer needed, but do not present an arbitrary fixed delay as a universal fix.

Pattern: Service discovery returns empty or unexpected data

Do not diagnose an empty service list as "the cache" from the callback alone. Capture the immediate return from discoverServices(), callback status, connection state, peripheral firmware version, and an HCI trace. Validate the expected profile before setup continues. If firmware changes the GATT database, support the standard Service Changed behavior and reconnect cleanly. Android's hidden refresh() method is not a stable production API, and an app should not toggle system Bluetooth as an automatic fallback.

Pattern: Notifications stop arriving after a few minutes

If notifications stop after running successfully, a missing initial CCCD write is unlikely to be the whole explanation. Check sequence counters, peripheral buffer state, subscription state after reconnect, app callback latency, connection events, and firmware logs. During setup, Android requires local notification configuration plus the appropriate CCCD write; check the immediate API result and descriptor callback before advancing the setup state.

6. Building a BLE Debug Overlay in Your App

For development and QA, a debug overlay can expose the connection state, MTU, subscription state, and recent operations without requiring a tethered Logcat session.

Implementing a minimal debug overlay

Render a state object already owned by the BLE layer; do not create a second source of connection truth for the overlay. Useful fields include connection generation, lifecycle state, active GATT operation, last callback and status, negotiated MTU, subscription state, sequence progression, queue depth, bytes received, and time since the last packet.

Logging BLE events to a ring buffer

Maintain a bounded event buffer with both monotonic elapsed time and wall time, a connection-generation identifier, event type, operation identifier, numeric status, and redacted detail. Export it only through an explicit diagnostic action. Keep characteristic payloads, stable device identifiers, biosignals, and patient data out of routine transport logs.

7. Remote Debugging BLE Issues in Production

Some BLE failures appear only on a particular phone, OS build, peripheral firmware version, or radio environment. When the team cannot reproduce the issue locally, debugging depends on a comparable timeline from the affected device rather than a larger pile of unstructured logs.

Structured BLE telemetry

Choose production telemetry from the support need, privacy model, consent, and retention policy. Prefer aggregate health metrics for routine monitoring and a user-initiated diagnostic bundle for detailed timelines. Potential fields include:

• Connection attempts with phone model, Android build, app version, and peripheral firmware version
• Connection successes and failures (with GATT status codes)
• Service discovery results (number of services found, duration)
• MTU negotiation results (requested vs. granted)
• Disconnection events (with status code and connection duration)
• Notification throughput (bytes per second, averaged over 10-second windows)
• Bounded RSSI summaries when signal context is necessary

On-device diagnostic mode

Provide a visible, time-limited diagnostic mode that explains what it records and requires an explicit export action. Store the bundle in application-private storage, redact it before sharing, expire it automatically, and use the platform's controlled file-sharing mechanism. A support deep link may navigate to the feature but should not silently enable collection.

8. A production BLE debugging decision tree

When a BLE bug arrives, follow this decision tree to pick the right tool:

1. Can you reproduce with a generic BLE client? If so, your app is less likely to be the only cause, but the phone stack, RF environment, profile, and firmware are all still in scope.
2. Is it a connection or data issue? For connection failures, begin with the application timeline and add HCI evidence when the callback does not identify the boundary. Filter for connection events and controller reason codes.
3. Is it device-specific? Group evidence by exact phone model, Android build, peripheral firmware, and scenario before adding an OEM workaround.
4. Is it timing-related? Use the BLE event ring buffer to check the exact sequence and timing of operations. Many BLE bugs are race conditions between GATT operations that must be serialized.
5. Can you only reproduce in the field? With the user's agreement, enable the time-limited diagnostic mode and export the redacted bundle. Combine it with aggregate health telemetry and firmware evidence while stating which boundaries remain unobserved.

The useful deliverable is one aligned timeline: what the peripheral sent, what the controller reported, what Android delivered, and what state the app believed it was in. Build that evidence path before field failures force you to guess.