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

Platform-Specific BT Backends

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": "JasonsPC",
  "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

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": ["JasonsPC", "JasonsPhone", "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

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

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