Meshtastic MCP Server

# Bluetooth Connection Guide This guide covers connecting to Meshtastic devices via Bluetooth Low Energy (BLE). ## Why Use Bluetooth? - **No cables needed** - Wireless connection to your device - **Mobile friendly** - Connect from laptops or tablets without USB - **Multiple devices** - Switch between devices easily - **Range** - Works within ~10-30 meters depending on environment ## Prerequisites ### Software Requirements Make sure you have the Bluetooth library installed: ```bash pip install bleak ``` ### Hardware Requirements - A Meshtastic device with Bluetooth enabled (most devices support this) - Bluetooth adapter on your computer (built-in on most modern laptops) - Bluetooth must be enabled in your OS settings ## Finding Your Device ### Step 1: Scan for Devices Use the test script to discover nearby Meshtastic devices: ```bash python test_connection.py --type scan ``` Output example: ``` Scanning for Bluetooth devices (timeout: 10s)... ✓ Found 2 Meshtastic device(s): - Meshtastic_a1b2 (AA:BB:CC:DD:EE:FF) RSSI: -65 dBm - Meshtastic_c3d4 (11:22:33:44:55:66) RSSI: -78 dBm ``` The MAC address (e.g., `AA:BB:CC:DD:EE:FF`) is what you'll use to connect. ### Step 2: Test Connection Test connecting to your device: ```bash python test_connection.py --type bluetooth --device AA:BB:CC:DD:EE:FF ``` ## Using Bluetooth with the MCP Server ### Via Claude Desktop Once you've found your device's MAC address, you can tell Claude to connect: ``` "Connect to my Meshtastic device via Bluetooth at AA:BB:CC:DD:EE:FF" ``` Or just: ``` "Scan for nearby Meshtastic devices via Bluetooth" ``` Claude will discover available devices and can then connect to the one you choose. ### Example Conversation ``` You: Scan for Meshtastic devices via Bluetooth Claude: I'll scan for nearby Meshtastic devices... Found 1 Meshtastic device: - Meshtastic_a1b2 (AA:BB:CC:DD:EE:FF) RSSI: -65 dBm You: Connect to that device Claude: Connecting via Bluetooth to AA:BB:CC:DD:EE:FF... ✓ Successfully connected to Meshtastic device via bluetooth ``` ## Platform-Specific Notes ### macOS - Bluetooth should work out of the box - Grant Bluetooth permissions if prompted - May need to "pair" device first in System Settings → Bluetooth ### Linux - May require `bluez` package: ```bash sudo apt-get install bluez ``` - Check Bluetooth service is running: ```bash sudo systemctl status bluetooth ``` - If permission issues: ```bash sudo usermod -a -G bluetooth $USER # Log out and back in ``` ### Windows - Bluetooth drivers should be installed - Windows 10/11 usually work out of the box - Older Windows versions may have limited BLE support ## Troubleshooting ### "No Meshtastic devices found" 1. **Check device Bluetooth is enabled** - In Meshtastic app, verify BLE is on - Some devices need Bluetooth explicitly enabled in config 2. **Check computer Bluetooth** - Ensure Bluetooth is turned on in your OS - Try scanning with your phone's Bluetooth settings to verify the device is visible 3. **Increase scan timeout** ```bash python test_connection.py --type scan --timeout 30 ``` 4. **Distance and interference** - Move closer to the device (within 10 meters) - Reduce interference from other Bluetooth devices ### "Connection timeout" or "Failed to connect" 1. **Device already connected** - Disconnect from Meshtastic app on your phone - Only one device can connect via BLE at a time 2. **Pair the device first** (macOS/Windows) - Open system Bluetooth settings - Pair with the Meshtastic device - Then try connecting 3. **Restart Bluetooth** - Toggle Bluetooth off and on - Restart Bluetooth service (Linux) 4. **Power cycle device** - Turn off and on your Meshtastic device - Wait a few seconds before scanning ### "bleak not installed" ```bash pip install bleak ``` ### Permission denied (Linux) ```bash # Add user to bluetooth group sudo usermod -a -G bluetooth $USER # May also need sudo setcap 'cap_net_raw,cap_net_admin+eip' $(which python) ``` ## MAC Address Formats Different platforms may show MAC addresses differently: - **Linux**: `AA:BB:CC:DD:EE:FF` - **macOS**: `AA:BB:CC:DD-EE-FF` or UUID format - **Windows**: `AA:BB:CC:DD:EE:FF` The MCP server accepts any format. ## Bluetooth vs Serial vs TCP | Feature | Bluetooth | Serial | TCP | |---------|-----------|--------|-----| | Setup | Easy | Easy | Medium | | Cables | None | USB | Ethernet | | Range | ~10-30m | Cable length | Network range | | Speed | Medium | Fast | Fast | | Power | Low | Powers device | Device needs power | | Multi-device | One at a time | One at a time | Multiple | ## Best Practices 1. **Start with scan** - Always scan first to find your device 2. **Note MAC address** - Save it for future connections 3. **Close other apps** - Disconnect from Meshtastic app when using MCP 4. **Stay in range** - Keep within 10 meters for stable connection 5. **Check battery** - BLE connection drains battery faster than sleep mode ## Security Notes - Bluetooth connections can be less secure than wired - Use Meshtastic's built-in encryption for sensitive data - Be aware of Bluetooth range - anyone nearby can potentially connect - Consider disabling Bluetooth when not in use ## Advanced: Automatic Connection You can configure the MCP server to automatically connect to a specific device: Create a config file `ble_config.json`: ```json { "auto_connect": true, "device_address": "AA:BB:CC:DD:EE:FF" } ``` (Note: This feature is not yet implemented but can be added) ## Next Steps - Test your connection with the test script - Start using Claude to interact with your mesh - Check out EXAMPLES.md for usage ideas