android-bluetooth

Fix Android Bluetooth connection failures across Classic SPP/RFCOMM and BLE GATT scenarios.

8|1|Updated Mar 30, 2026
One-click install
npx skills add https://github.com/drewid74/ai_skills --skill android-bluetooth-drewid74
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: android-bluetooth
Source: https://github.com/drewid74/ai_skills/tree/main/android-bluetooth
Command: npx skills add https://github.com/drewid74/ai_skills --skill android-bluetooth-drewid74

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

Android Bluetooth connections frequently fail due to incorrect transport choice, missing runtime permissions, unreliable disconnect detection, and stale socket state—causing apps to appear connected when they are not or to get stuck in reconnect loops.

Core Features & Use Cases

  • Permissions & Android version matrix: Fix silent failures by selecting the correct BLUETOOTH_SCAN/CONNECT permissions (and legacy ones) plus the required connected-device foreground service handling.
  • Classic Bluetooth (SPP/RFCOMM) connection workflow: Route discovery vs bonded-device enumeration, create sockets using a prioritized path (reflection, secure, insecure), and connect with retry plus teardown delays to avoid race conditions.
  • Robust disconnect detection & lifecycle-safe state: Detect dead links via I/O read-loop failures and heartbeats (with ACL_DISCONNECTED as backup), using idempotent disconnect handling and a real connection state machine.
  • BLE/GATT guidance: Support BLE use cases such as race trackers and sensors by handling GATT discovery and notification/MTU setup via the referenced BLE documentation.

Use case example: You built an Android app to connect to an OBDLink-style classic SPP adapter and sometimes it connects once but fails on subsequent attempts; apply this skill to fix socket creation order, teardown timing, permissions, and disconnect/reconnect logic.

Quick Start

Use the android-bluetooth skill to troubleshoot your Android app that connects to a Bluetooth device but shows connected incorrectly or gets stuck during reconnect for the device you are pairing.

Frequently Asked Questions about android-bluetooth

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
Why does my Android Bluetooth connection fail on reconnect after pairing successfully once?

Android Bluetooth reconnect failures often stem from incorrect socket creation order, improper teardown timing, or stale state. Fix this by applying a prioritized socket factory path with proper retry and teardown delays to avoid race conditions.

How do I detect when an Android Bluetooth SPP connection has dropped unexpectedly?

Detect dropped Bluetooth connections by monitoring I/O read-loop failures and heartbeat signals, using ACL_DISCONNECTED as a backup trigger. Combine this with an idempotent disconnect handler to safely manage the connection state machine and prevent stuck reconnect loops.

What Android permissions do I need for Bluetooth Classic and BLE scanning?

Bluetooth scanning requires selecting correct runtime permissions based on the Android version matrix, including BLUETOOTH_SCAN and BLUETOOTH_CONNECT for newer APIs alongside legacy permissions. You must also implement a connected-device foreground service to prevent silent connection failures.

What is the best way to route Android Bluetooth discovery versus connecting to bonded devices?

Route discovery versus bonded-device enumeration by checking the paired device list first to skip scanning overhead. If the target device is not bonded, initiate discovery; otherwise, use the existing bond to create the RFCOMM socket directly using the prioritized factory method.

Does this approach work for both Classic SPP adapters and BLE GATT sensors?

Yes, the approach supports both Classic SPP/RFCOMM and BLE/GATT scenarios. Classic connections use socket creation strategies and state machines, while BLE connections handle GATT discovery, notification setup, and MTU configuration via referenced documentation for race trackers and sensors.

When should I use reflection to create a Bluetooth socket on Android?

Use reflection to create a Bluetooth socket when standard secure and insecure socket factory methods fail, particularly across different Android versions. Apply reflection as the first attempt in a prioritized path to maximize compatibility with stubborn SPP devices like OBDLink adapters.