Bt device manager

Bluetooth Device Manager Skill

What This Skill Does

This skill generates a complete multi-device Bluetooth control system consisting of:

1. 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
2. Web Dashboard — A browser-based control panel with buttons to pair/unpair/connect/disconnect any Bluetooth device on any networked device
3. Python Desktop GUI — A native desktop app with the same functionality
4. Auto-Discovery — Agents automatically find each other on the local network using UDP broadcast (no manual IP entry required)
5. Notification System — Real-time status updates and error alerts
6. 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 8378 every 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 plyer library
• 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:

1. When "Connect JBL Flip 6" is triggered, try priority[0] first
2. If fails/unavailable, wait fallback_delay_seconds, try priority[1]
3. Continue down the list
4. 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:

1. Read this SKILL.md first to understand the full architecture
2. Read references/api-spec.md for the complete API specification
3. Read references/bt-backends.md for platform-specific Bluetooth commands
4. Read references/setup-guides.md for detailed installation instructions
5. Ask the user which components they want (all, or specific ones)
6. Generate the code following the file structure above
7. Include setup instructions tailored to the user's devices
8. 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