tRollNhard Bluetooth Device Manager Skill
What This Skill Does
This skill generates a complete multi-device Bluetooth control system consisting of:
- Wi-Fi Agents — Lightweight services that run on each device (PC, Android, TV) and expose Bluetooth control via a REST API on the local network
- Web Dashboard — A browser-based control panel with buttons to pair/unpair/connect/disconnect any Bluetooth device on any networked device
- Python Desktop GUI — A native desktop app with the same functionality
- Auto-Discovery — Agents automatically find each other on the local network using UDP broadcast (no manual IP entry required)
- Notification System — Real-time status updates and error alerts
- Priority & Fallback — Configurable device priority lists with automatic fallback
System Architecture
┌─────────────────────────────────────────────────────────────────┐
│ YOUR LOCAL WI-FI NETWORK │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ PC Agent │ │ Phone Agent │ │ TV Agent │ ... │
│ │ (Python) │ │ (Python) │ │ (Python) │ │
│ │ │ │ │ │ │ │
│ │ ● BT Radio │ │ ● BT Radio │ │ ● BT Radio │ │
│ │ ● REST API │ │ ● REST API │ │ ● REST API │ │
│ │ ● Port 8377 │ │ ● Port 8377 │ │ ● Port 8377 │ │
│ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │
│ │ │ │ │
│ └──────────────────┼──────────────────┘ │
│ │ │
│ UDP Auto-Discovery │
│ (Broadcast :8378) │
│ │ │
│ ┌───────────┴───────────┐ │
│ │ CONTROLLER DEVICE │ │
│ │ │ │
│ │ ┌──────────────────┐ │ │
│ │ │ Web Dashboard │ │ ← Browser-based UI │
│ │ │ (Port 8380) │ │ with buttons │
│ │ └──────────────────┘ │ │
│ │ OR │ │
│ │ ┌──────────────────┐ │ │
│ │ │ Python GUI App │ │ ← Native desktop app │
│ │ └──────────────────┘ │ │
│ └────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
Component Details
1. Wi-Fi Agent (agent.py)
The agent runs on EVERY device you want to control. It is a lightweight Python Flask/FastAPI server that:
- Exposes Bluetooth controls via REST API on port
8377 - Announces itself via UDP broadcast on port
8378every 10 seconds - Reports status including connected BT devices, available BT devices, signal strength
- Executes commands: pair, unpair, connect, disconnect, scan, trust, remove
API Endpoints
| Method | Endpoint | Description |
|---|---|---|
| GET | /api/status |
Agent status, hostname, OS, BT adapter info |
| GET | /api/devices |
List all known/paired BT devices |
| GET | /api/devices/connected |
List currently connected BT devices |
| GET | /api/scan |
Trigger BT scan, return discovered devices |
| POST | /api/connect |
Connect to a BT device by MAC address |
| POST | /api/disconnect |
Disconnect a BT device by MAC address |
| POST | /api/pair |
Pair with a new BT device |
| POST | /api/unpair |
Remove pairing with a BT device |
| POST | /api/trust |
Trust a BT device (auto-connect) |
| GET | /api/ping |
Health check |
Platform-Specific BT Backends
| Platform | Backend | Library/Tool |
|---|---|---|
| Linux PC | bluetoothctl via subprocess |
Built-in BlueZ |
| Windows PC | WMI + PowerShell BT cmdlets | pybluez2 or bleak |
| Android | Termux + bluetoothctl OR companion app |
Termux API |
| Android TV | ADB shell commands via network | adb over TCP |
| Smart TV (Linux-based) | SSH + bluetoothctl |
SSH access required |
2. Auto-Discovery System
Agents discover each other without manual configuration:
Agent Startup:
1. Bind UDP socket on port 8378
2. Every 10 seconds, broadcast: {"agent": hostname, "ip": local_ip, "port": 8377, "os": platform}
3. Listen for broadcasts from other agents
4. Maintain a live registry of discovered agents (expire after 30s no-broadcast)
Discovery Packet Format (JSON over UDP broadcast):
{
"service": "bt-device-manager",
"version": "1.0",
"hostname": "MyPC",
"ip": "192.168.1.50",
"port": 8377,
"os": "windows",
"bt_adapter": "Intel AX200",
"timestamp": 1708444800
}
3. Web Dashboard (dashboard.html + dashboard_server.py)
A responsive web UI served by the controller device:
- Device Cards — One card per discovered agent showing hostname, OS icon, connection status
- BT Device List — Under each card, paired/connected Bluetooth devices with action buttons
- Action Buttons — Connect, Disconnect, Pair, Unpair, Scan — each triggers the agent API
- Status Bar — Real-time notifications (success/failure/warnings)
- Priority Manager — Drag-and-drop to set device connection priority order
- Quick Actions — "Disconnect All," "Connect Favorites," "Switch Speaker To..."
Tech Stack: HTML5 + Tailwind CSS + Vanilla JS (no build step, runs in any browser)
4. Python Desktop GUI (gui_app.py)
A native desktop application using tkinter (built into Python):
- Same functionality as web dashboard
- System tray icon with quick actions
- Desktop notifications via
plyerlibrary - Runs on Windows, Linux, macOS
5. Notification System
| Event | Notification |
|---|---|
| Device connected | "✅ JBL Speaker connected to PC" |
| Device disconnected | "🔌 AirPods disconnected from Phone" |
| Connection failed | "❌ Failed to connect HP Printer — device out of range" |
| Agent went offline | "⚠️ TV Agent is no longer responding" |
| New device discovered | "🔍 New BT device found: Unknown Device (AA:BB:CC:DD:EE)" |
| Priority fallback triggered | "🔄 Speaker unavailable on PC, connecting to Phone instead" |
Delivery Methods:
- Web dashboard: Toast notifications in-browser
- Python GUI: Desktop OS notifications
- Optional: Push notifications via ntfy.sh (free, self-hosted push service)
6. Priority & Fallback System
Users define priority lists per Bluetooth device:
{
"JBL Flip 6": {
"mac": "AA:BB:CC:DD:EE:FF",
"priority": ["MyPC", "MyPhone", "LivingRoomTV"],
"auto_fallback": true,
"fallback_delay_seconds": 5
}
}
Logic:
- When "Connect JBL Flip 6" is triggered, try priority[0] first
- If fails/unavailable, wait
fallback_delay_seconds, try priority[1] - Continue down the list
- Notify user which device it connected to (and if fallback was used)
File Structure
When this skill generates the BT Device Manager, it creates:
bt-device-manager/
├── README.md # Setup guide & documentation
├── requirements.txt # Python dependencies
├── config.json # User configuration (devices, priorities)
│
├── agent/ # Wi-Fi Agent (runs on each device)
│ ├── agent.py # Main agent server (Flask/FastAPI)
│ ├── bt_backend_linux.py # Linux bluetoothctl backend
│ ├── bt_backend_windows.py # Windows BT backend
│ ├── bt_backend_android.py # Android/Termux BT backend
│ ├── discovery.py # UDP auto-discovery module
│ └── config.py # Agent configuration loader
│
├── controller/ # Controller (runs on your main device)
│ ├── dashboard_server.py # Serves web dashboard + proxies API calls
│ ├── gui_app.py # Python tkinter desktop GUI
│ ├── discovery_client.py # Discovers agents on network
│ ├── priority_manager.py # Priority & fallback logic
│ ├── notification_manager.py # Notification routing
│ └── static/ # Web dashboard files
│ ├── index.html # Main dashboard page
│ ├── style.css # Tailwind-based styling
│ └── app.js # Dashboard JavaScript
│
├── scripts/ # Setup & utility scripts
│ ├── install_agent_linux.sh # One-line Linux agent installer
│ ├── install_agent_windows.bat # One-click Windows agent installer
│ ├── install_agent_android.sh # Termux agent installer
│ ├── start_agent.py # Cross-platform agent launcher
│ └── start_controller.py # Cross-platform controller launcher
│
└── tests/ # Test suite
├── test_discovery.py # Auto-discovery tests
├── test_bt_backends.py # BT backend mock tests
└── test_api.py # Agent API tests
Setup & Deployment Guide
Step 1: Install Agent on Each Device
On a Linux PC:
curl -sSL https://raw.githubusercontent.com/.../install_agent_linux.sh | bash
# OR manually:
pip install flask bleak zeroconf
python agent/agent.py
On a Windows PC:
Double-click install_agent_windows.bat
# OR manually:
pip install flask bleak zeroconf
python agent/agent.py
On Android (via Termux):
pkg install python bluetooth-utils
pip install flask
python agent/agent.py
Step 2: Start Controller on Your Main Device
python scripts/start_controller.py
# Opens web dashboard at http://localhost:8380
# AND/OR launches desktop GUI
Step 3: Devices Auto-Discover Each Other
Within 10 seconds, all agents on your Wi-Fi network appear in the dashboard. No manual IP entry needed.
How Claude Should Use This Skill
When the user asks to create or customize a BT Device Manager:
- Read this SKILL.md first to understand the full architecture
- Read references/api-spec.md for the complete API specification
- Read references/bt-backends.md for platform-specific Bluetooth commands
- Read references/setup-guides.md for detailed installation instructions
- Ask the user which components they want (all, or specific ones)
- Generate the code following the file structure above
- Include setup instructions tailored to the user's devices
- Test connectivity by generating mock discovery packets and API responses
Customization Options to Ask About
- Which devices will run agents? (PC, phone, TV, etc.)
- Which device is the primary controller?
- Do they want the web dashboard, GUI app, or both?
- Any specific BT devices to pre-configure in config.json?
- Do they want autostart on boot?
- Do they want the optional push notification service?
Dependencies
| Package | Purpose | Required On |
|---|---|---|
flask |
REST API server | All agents |
bleak |
Cross-platform BT library | Windows/macOS agents |
pydbus |
D-Bus interface for BlueZ | Linux agents |
zeroconf |
mDNS discovery (backup) | All devices |
plyer |
Desktop notifications | Controller (GUI) |
tkinter |
Desktop GUI | Controller (GUI) |
requests |
HTTP client for API calls | Controller |
netifaces |
Network interface detection | All devices |
Security Considerations
Since this runs on your LOCAL network only:
- No internet exposure — agents only bind to local network interfaces
- API key authentication — simple shared secret in config.json
- Device allowlist — only pre-approved agent hostnames can execute commands
- HTTPS optional — can enable self-signed certs for encrypted local traffic
- No cloud dependency — everything runs locally, your data never leaves your network
Troubleshooting
| Problem | Solution |
|---|---|
| Agent not discovered | Check both devices on same Wi-Fi subnet; check firewall ports 8377-8378 |
| BT command fails on Linux | Ensure user is in bluetooth group: sudo usermod -aG bluetooth $USER |
| BT command fails on Windows | Run agent as Administrator for BT access |
| Android agent won't control BT | Enable Termux Bluetooth permissions in Android settings |
| Connection drops randomly | Check BT device isn't auto-connecting to another device; use Trust feature |
| Dashboard won't load | Check port 8380 isn't blocked; try http://IP:8380 from another device |
Future Enhancements (v2.0 Roadmap)
- macOS/iOS support via CoreBluetooth framework
- Voice control integration (Google Home / Alexa routines)
- Scheduling — auto-switch speaker to bedroom at 10 PM
- Presence detection — auto-connect when phone joins Wi-Fi
- Plugin system — support for custom device types
- Cross-skill integration — connect with skill-vault for config management