btdiag — universal Bluetooth audio diagnostics + battery alerts

🎧 Why this exists — a note from the person who had the problem

I had a problem: my earbuds kept dying mid-song and nothing — not Windows, not the buds, not any app — would just tell me the battery level before it hit zero. Cheap earbuds, no companion app, no warning. So I built the thing I wished existed.

I had a problem. I built a solution. (Well — of course Claude built the solution. I brought the problem, the stubbornness, and the "no, make it work for any earbud, not just the expensive ones" energy.)

And honestly? That's the part I'm proud of. GitHub has millions of repos — most built once and never opened again, by people who never actually use the thing they made. This one I use every single day. Every "🔋 earbuds at 20%" buzz on my phone is my own little tool, quietly doing its job, solving my problem on my terms. That small daily "huh — it actually works" is the whole payoff. That's why this exists.

If it spares you one dead-battery moment too — even better. 🔋

A small, open tool that surfaces everything your OS and your earbuds expose — battery (with the timestamp of when it was reported), every supported profile in plain English, device class, vendor, connection history, the adapter in use, and the vendor control channels — for any Bluetooth audio device, regardless of brand. Then it alerts you before the battery dies at thresholds you choose.

No vendor app. No account. No cloud. Works on devices that never shipped an app at all (budget TWS like Noise, boAt, Baseus, TOZO, Wings…).

⚡ AI-native: control your earbuds with MCP

btdiag ships an MCP server. Point Claude, Claude Code, or an on-device/edge model at btdiag_mcp.py and just say what you want:

"is my left bud dying?" → bt_battery · "disconnect my earbuds" → bt_disconnect "find my earbuds" → bt_findmy · "what is my headset sending?" → bt_snoop_decode

// Register in any MCP client (e.g. Claude Desktop config):
"btdiag": { "command": "python", "args": ["C:/path/to/btdiag_mcp.py"] }

9 tools: bt_scan · bt_info · bt_battery · bt_monitor_status · bt_connect · bt_disconnect · bt_unpair · bt_findmy · bt_snoop_decode.

How this differs from other Bluetooth MCP servers. A few BLE MCP servers exist (e.g. bluetooth-mcp-server, ble-mcp-server) — they expose raw BLE plumbing: scan, connect, read/write GATT characteristics. btdiag is different: it exposes high-level device management — battery %, low-battery alerts, connect/disconnect/unpair on Classic BT (not just BLE), plain-English diagnostics, find-my proximity, and an HCI-snoop packet explainer — and MCP is just one face of a complete product (GUI + CLI + Android app + background monitor) sharing one core. The aim isn't "expose BLE to an LLM"; it's a universal, brand-agnostic Bluetooth tool that humans and AI can drive.

See docs/RESEARCH_AI_FINDMY_TRANSPORT.md for the edge-AI architecture (on-device function-calling models → MCP → Bluetooth).

Related MCP server: macos-computer-use-mcp

Why this exists

Most budget earbuds — the majority of units sold — have no PC app, no Linux app, and often no/dropped mobile app. Windows itself still has no built-in low-battery alert for Bluetooth headsets. Existing open tools each target a single premium brand:

btdiag is brand-agnostic by design. Layer 1 (this release) uses standard OS interfaces, so it works on every headset today. Layer 2 (in progress) adds vendor-protocol modules (BES TOTA, JieLi RCSP) for deeper data — per-bud + case battery, ANC, EQ, find-my — across whole families of cheap earbuds at once.

Layout

btdiag.py            CLI entry point
btdiag/              Python package (Windows + Android backends, decoders)
android-app/         standalone Android app (Kotlin) — battery alerts on phone
dist/                build outputs (Android APK; Windows .exe via PyInstaller)
scripts/             install/uninstall the silent Windows background monitor
docs/                research report
research/            every approach we tried, worked or not (research/README.md)
apk_work/            decompiler + tooling (not part of source)

Windows (PC)

Requires Python 3.10+ . No third-party packages for the core (standard library only).

python btdiag.py scan            # list all paired BT devices, one line each
python btdiag.py info [name]     # full decoded report for connected device(s)
python btdiag.py raw  [name]     # dump every hidden PnP property (the full unfurl)
python btdiag.py monitor [name]  # low-battery alert loop (80/60/40/20/10%)
python btdiag.py status | stop   # check / stop the background monitor

[name] is an optional case-insensitive filter, e.g. python btdiag.py info noise.

Run silently at every login (no console, no admin)

powershell -ExecutionPolicy Bypass -File scripts\install_autostart.ps1

This drops a hidden launcher in your Startup folder and starts the monitor now. Remove it any time with scripts\uninstall_autostart.ps1.

Android (phone)

1. Standalone app (recommended) — install dist/btbattery-debug.apk. It runs as a background service, listens for the headset's IPHONEACCEV battery report, shows a live status notification, and alerts at each threshold. After install it needs no PC and no debugging — it is a normal app, auto-starts on boot.

2. From the PC over ADB (development/diagnostics) — python btdiag.py battery (one-shot) or python btdiag.py android (continuous). Needs the phone on USB or wireless debugging; port discovery is automatic via mDNS.

Example

============================================================
  Airdopes 148 Gen 2
============================================================
  Status        : CONNECTED
  Address       : BB:D1:7A:A6:BA:BF
  Address note  : randomized / locally-administered address (no IEEE vendor)
  Via adapter   : 40:1A:58:4B:82:5F
  Device class  : Audio / Video > Wearable Headset
  Capabilities  : Rendering, Audio
  Battery       : [####################] 100%
  Profiles / services (what the device can do):
    - Advanced Audio Distribution (A2DP)
        -> streams stereo music to the device
    - Hands-Free (HFP)
        -> call audio + microphone + battery reporting
    - Serial Port (SPP)
        -> raw data channel - often the vendor control/config link
  First paired  : 05/26/2026 16:49:07
  Last connected: 06/14/2026 18:07:17
============================================================

That report was produced unmodified against a boAt device, though the tool was developed against a Noise device — the same code handles both.

Architecture

btdiag/
  bt_constants.py   Class-of-Device decoder, profile names + plain-English meanings,
                    MAC/OUI vendor analysis, vendor UUIDs
  win_query.ps1     fast batched PnP property query (Windows backend)
  windows.py        assembles physical devices, decodes, reads SDP cache
  android.py        ADB backend: battery via IPHONEACCEV from dumpsys
  report.py         human-readable rendering
  monitor.py        multi-threshold, charging-aware battery alerts
  tota.py           BES TOTA Layer-2 module (read-only; reverse-engineered)
btdiag.py           CLI entry point

The backends are isolated, so macOS/Linux backends and Layer-2 protocol modules plug in without touching the CLI or rendering.

Optional: full vendor names

The MAC/OUI vendor table is a small curated hint list. For complete vendor coverage, drop the IEEE/Wireshark oui.txt into btdiag/oui.txt — it is loaded automatically if present.

What's readable from Bluetooth (honest scope)

1. OS-exposed, any device: name, MAC, vendor, device class, profiles, battery %, connection state, pairing history. info decodes all of it.

2. Vendor control, device-specific: per-bud battery, ANC, EQ, gestures — needs the vendor protocol (BES TOTA module).

3. Raw live packets: require Android HCI snoop log or a hardware sniffer — a research activity, not a runtime feature. See research/README.md.

Roadmap

• Layer 1: universal OS-level diagnostics + battery alerts (Windows)

• Android battery alerts (standalone APK + ADB backend)

• BES TOTA protocol module → per-bud + case battery, ANC, EQ, find-my

• JieLi RCSP protocol module

• Linux (BlueZ) and macOS backends

• System-tray UI

History

This began as a focused reverse-engineering effort on the Noise earbuds; see docs/RESEARCH_REPORT.md for the full protocol findings (GATT map, BES TOTA auth handshake, command IDs) and research/README.md for every approach tried. research/superseded/battery_monitor.py is the original single-file monitor that btdiag replaced.

License

MIT — see LICENSE. Safe by design: read-only against the OS; vendor modules use only documented, non-destructive commands (never firmware/OTA).