Skip to content

BLUETOOTH_SYSTEM_README.md

Latest commit

 

History

History
177 lines (139 loc) · 5.3 KB

BLUETOOTH_SYSTEM_README.md

File metadata and controls

177 lines (139 loc) · 5.3 KB

Automatic Bluetooth Mesh Client Connection System

This system automatically connects new web app users to the Bluetooth mesh network when they register.

Architecture

Web App User Registration → Flask Backend → Client Manager → Bluetooth Mesh (Odin)

Components

1. Client Manager (web_application/client_manager.py)

  • Purpose: Manages multiple Bluetooth client connections
  • Function: Automatically connects new users to Odin (D8:3A:DD:03:1E:77)
  • API Port: 8001
  • Features:
    • Polls backend for new users every 10 seconds
    • Creates individual MeshClient instances per user
    • Handles connection lifecycle and error recovery
    • Provides REST API for manual control

2. Enhanced Flask Backend (blueQ-backend.py)

  • New Endpoints:
    • GET /api/bluetooth/manager/status - Check client manager status
    • POST /api/bluetooth/manager/connect/<user_id> - Manual user connection
    • POST /api/bluetooth/manager/disconnect/<user_id> - Manual user disconnection
    • POST /api/bluetooth/send - Send messages via Bluetooth mesh
  • Auto-Connection: Automatically triggers Bluetooth connection when users register

3. Enhanced User Registration

  • When a user registers in the web app, the system automatically:
    1. Creates user account in Flask backend
    2. Sends connection request to Client Manager
    3. Client Manager creates new MeshClient instance
    4. Connects user to Odin Bluetooth node
    5. Performs initial user scan

Usage

Quick Start

# Start the entire system
./start_bluetooth_system.sh

Manual Start

# Terminal 1: Start Flask Backend
python3 blueQ-backend.py

# Terminal 2: Start Client Manager
cd web_application
python3 client_manager.py D8:3A:DD:03:1E:77 http://localhost:5000 8001

Custom Configuration

# Custom Odin MAC address
python3 client_manager.py YOUR_ODIN_MAC http://localhost:5000 8001

# Custom backend URL and API port
python3 client_manager.py D8:3A:DD:03:1E:77 http://your-backend:5000 8002

API Endpoints

Client Manager API (Port 8001)

  • GET /api/status - Get status of all connections
  • POST /api/connect - Connect a user (JSON: {user_id, user_name})
  • POST /api/disconnect - Disconnect a user (JSON: {user_id})
  • POST /api/send - Send message (JSON: {user_id, destination, message})

Flask Backend API (Port 5000)

  • GET /api/bluetooth/manager/status - Proxy to client manager status
  • POST /api/bluetooth/manager/connect/<user_id> - Connect specific user
  • POST /api/bluetooth/send - Send Bluetooth message

Configuration

Default Settings

  • Odin MAC: D8:3A:DD:03:1E:77
  • Backend URL: http://localhost:5000
  • Client Manager Port: 8001
  • Polling Interval: 10 seconds
  • Connection Timeout: 10 seconds

Environment Variables

You can override defaults via command line arguments:

python3 client_manager.py [ODIN_MAC] [BACKEND_URL] [API_PORT]

Features

Automatic Connection

  • New users are automatically connected to Bluetooth mesh on registration
  • No manual intervention required
  • Immediate Bluetooth scan after connection

Error Handling

  • Automatic reconnection attempts
  • Graceful handling of Bluetooth connection failures
  • Cleanup of disconnected users

Monitoring

  • Real-time status via API endpoints
  • Health checks and connection monitoring
  • Detailed logging for debugging

Manual Control

  • Manual connect/disconnect via API
  • Send messages on behalf of users
  • View connection status and statistics

Troubleshooting

Client Manager Not Starting

  • Check if port 8001 is available
  • Verify Odin MAC address is correct
  • Ensure Flask backend is running

Users Not Auto-Connecting

  • Check client manager logs
  • Verify backend can reach client manager on port 8001
  • Check Bluetooth permissions and availability

Connection Failures

  • Verify Odin node is powered on and discoverable
  • Check Bluetooth adapter status: hciconfig
  • Ensure proper Bluetooth permissions: sudo usermod -a -G bluetooth $USER

API Not Responding

  • Check if services are running: ps aux | grep python
  • Verify ports are not blocked by firewall
  • Check network connectivity between components

Development

Adding New Features

  1. Extend BluetoothClientManager class
  2. Add new API endpoints in setup_api()
  3. Update Flask backend proxy endpoints if needed
  4. Test with manual API calls

Testing

# Check client manager status
curl http://localhost:8001/api/status

# Manually connect a user
curl -X POST http://localhost:8001/api/connect \
  -H "Content-Type: application/json" \
  -d '{"user_id": "test123", "user_name": "TestUser"}'

# Send a test message
curl -X POST http://localhost:8001/api/send \
  -H "Content-Type: application/json" \
  -d '{"user_id": "test123", "destination": "broadcast", "message": "Hello World"}'

Integration Points

Web App Integration

  • User registration automatically triggers connection
  • Contact refresh includes Bluetooth users
  • Status indicators show connection health

Bluetooth Mesh Integration

  • Each user gets individual connection to Odin
  • Messages are properly formatted with user identity
  • Automatic user discovery and synchronization

Backend Integration

  • Seamless API between web and Bluetooth layers
  • Unified user management across platforms
  • Real-time status synchronization