{"id":34663378,"url":"https://github.com/yeraze/meshtastic-ble-bridge","last_synced_at":"2026-01-23T14:11:31.061Z","repository":{"id":320098980,"uuid":"1080790777","full_name":"Yeraze/meshtastic-ble-bridge","owner":"Yeraze","description":"Provide a TCP interface to BLE-connected Meshtastic nodes","archived":false,"fork":false,"pushed_at":"2025-10-29T02:19:39.000Z","size":157,"stargazers_count":13,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-12T17:13:33.046Z","etag":null,"topics":["ble","meshtastic"],"latest_commit_sha":null,"homepage":"https://meshmonitor.org/configuration/ble-bridge.html","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Yeraze.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":null,"patreon":null,"open_collective":null,"ko_fi":"yeraze","tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"lfx_crowdfunding":null,"polar":null,"buy_me_a_coffee":null,"thanks_dev":null,"custom":null}},"created_at":"2025-10-21T21:49:23.000Z","updated_at":"2025-12-29T02:20:40.000Z","dependencies_parsed_at":"2025-10-22T00:22:06.439Z","dependency_job_id":"4e48868c-7cf0-4332-b332-cf536e76ce3b","html_url":"https://github.com/Yeraze/meshtastic-ble-bridge","commit_stats":null,"previous_names":["yeraze/meshtastic-ble-bridge"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/Yeraze/meshtastic-ble-bridge","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Yeraze%2Fmeshtastic-ble-bridge","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Yeraze%2Fmeshtastic-ble-bridge/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Yeraze%2Fmeshtastic-ble-bridge/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Yeraze%2Fmeshtastic-ble-bridge/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Yeraze","download_url":"https://codeload.github.com/Yeraze/meshtastic-ble-bridge/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Yeraze%2Fmeshtastic-ble-bridge/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28693670,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-23T11:01:27.039Z","status":"ssl_error","status_checked_at":"2026-01-23T11:00:26.909Z","response_time":59,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ble","meshtastic"],"created_at":"2025-12-24T18:55:47.582Z","updated_at":"2026-01-23T14:11:31.055Z","avatar_url":"https://github.com/Yeraze.png","language":"Python","funding_links":["https://ko-fi.com/yeraze"],"categories":[],"sub_categories":[],"readme":"# MeshMonitor BLE Bridge\n\n[![Docker Image](https://ghcr-badge.egpl.dev/yeraze/meshtastic-ble-bridge/latest_tag?color=%235b4566\u0026ignore=latest,main\u0026label=version\u0026trim=)](https://github.com/Yeraze/meshmonitor/pkgs/container/meshtastic-ble-bridge)\n[![Docker Pulls](https://ghcr-badge.egpl.dev/yeraze/meshtastic-ble-bridge/size?color=%235b4566\u0026tag=latest\u0026label=image%20size\u0026trim=)](https://github.com/Yeraze/meshmonitor/pkgs/container/meshtastic-ble-bridge)\n\nA Docker-based bridge that exposes a TCP api to Bluetooth Low Energy (BLE) Meshtastic devices. Designed for use with MeshMonitor, but works with any tool that supports the Meshtastic TCP interface.\n\n**Features:**\n- BLE-to-TCP protocol translation\n- Automatic reconnection on node reboots or disconnects (v1.3+)\n- Optional config caching for faster reconnections (v1.4.0+)\n- Configurable cache size limits for memory management (v1.4.0+)\n- mDNS/Avahi autodiscovery for zero-configuration networking\n- Automatic service registration and cleanup\n- Graceful shutdown with proper resource cleanup\n- Comprehensive test suite with CI/CD\n\n## What's Included\n\n```\nmeshmonitor-ble-bridge/\n├── README.md                           # This file\n├── QUICK_START.md                      # Get up and running fast\n├── docker-compose.ble.yml              # Docker Compose configuration\n├── src/\n│   ├── ble_tcp_bridge.py              # Main bridge application\n│   ├── Dockerfile                      # Container build instructions\n│   └── .dockerignore                   # Docker build exclusions\n└── docs/\n    ├── CLAUDE_BLE_BRIDGE.md           # Claude Code context \u0026 technical details\n    ├── BLE_TCP_BRIDGE_ANALYSIS.md     # Comprehensive technical analysis\n    ├── README_BLE_BRIDGE.md           # User documentation\n    └── DEPLOY_BLE_BRIDGE.md           # Deployment guide\n```\n\n## Quick Start\n\n### Prerequisites\n- Docker installed\n- Bluetooth adapter (built-in or USB)\n- Meshtastic device with BLE enabled\n\n### 1. Pull the Container\n```bash\ndocker pull ghcr.io/yeraze/meshtastic-ble-bridge:latest\n```\n\n### 2. Find Your Device\n```bash\ndocker run --rm --privileged \\\n  -v /var/run/dbus:/var/run/dbus \\\n  ghcr.io/yeraze/meshtastic-ble-bridge:latest --scan\n```\n\n### 3. Pair Your Device (if required)\n```bash\nbluetoothctl\npair AA:BB:CC:DD:EE:FF  # Replace with your device MAC\ntrust AA:BB:CC:DD:EE:FF\nexit\n```\n\n### 4. Start the Bridge\n```bash\ndocker run -d --name ble-bridge \\\n  --privileged \\\n  -p 4403:4403 \\\n  --restart unless-stopped \\\n  -v /var/run/dbus:/var/run/dbus \\\n  -v /var/lib/bluetooth:/var/lib/bluetooth:ro \\\n  -v /etc/avahi/services:/etc/avahi/services \\\n  ghcr.io/yeraze/meshtastic-ble-bridge:latest AA:BB:CC:DD:EE:FF\n```\n\nThe bridge will automatically register an mDNS service for network autodiscovery.\n\n### 5. Connect MeshMonitor\nPoint MeshMonitor to:\n- **IP:** `\u003cbridge-host-ip\u003e`\n- **Port:** `4403`\n\nOr use mDNS autodiscovery to find the bridge automatically on your network:\n```bash\n# Test mDNS discovery\navahi-browse -rt _meshtastic._tcp\n```\n\nThe bridge advertises itself as `_meshtastic._tcp.local.` with TXT records containing:\n- `bridge=ble`\n- `port=4403`\n- `ble_address=\u003cdevice-mac\u003e`\n- `version=1.4.0`\n\n## Documentation\n\n- **Quick Start:** See `QUICK_START.md` for step-by-step setup\n- **Deployment:** See `docs/DEPLOY_BLE_BRIDGE.md` for production deployment\n- **User Guide:** See `docs/README_BLE_BRIDGE.md` for usage and troubleshooting\n- **Technical Details:** See `docs/CLAUDE_BLE_BRIDGE.md` for architecture and development\n- **Analysis:** See `docs/BLE_TCP_BRIDGE_ANALYSIS.md` for comprehensive protocol analysis\n\n## Using with Claude Code\n\nThis package includes `docs/CLAUDE_BLE_BRIDGE.md` which provides complete context for working on the BLE bridge with Claude Code. Simply:\n\n1. Extract this tarball on your target machine\n2. Open the directory in Claude Code\n3. Reference `docs/CLAUDE_BLE_BRIDGE.md` for full technical context\n\n## Architecture\n\n```\n┌──────────────┐  TCP 4403         ┌───────────────┐\n│ MeshMonitor  │ ←────────────────→│  BLE Bridge   │\n└──────────────┘                    └───────┬───────┘\n      ↑                                     │ BLE\n      │ mDNS autodiscovery          ┌───────▼───────┐\n      └─────────────────────────────│  Meshtastic   │\n                                    └───────────────┘\n```\n\nThe bridge translates between:\n- **BLE:** Raw protobuf bytes on Meshtastic GATT characteristics\n- **TCP:** Framed protocol `[0x94][0xC3][LEN][PROTOBUF]`\n\nAnd provides:\n- **mDNS:** Automatic service discovery via Avahi (`_meshtastic._tcp.local.`)\n\n## Docker Compose Integration\n\nFor MeshMonitor users, use the included `docker-compose.ble.yml` as an overlay:\n\n```bash\n# Copy to MeshMonitor directory\ncp docker-compose.ble.yml /path/to/meshmonitor/\n\n# Create .env file\necho \"BLE_ADDRESS=AA:BB:CC:DD:EE:FF\" \u003e /path/to/meshmonitor/.env\n\n# Start both services\ncd /path/to/meshmonitor\ndocker compose -f docker-compose.yml -f docker-compose.ble.yml up -d\n```\n\n## Common Issues\n\n### \"No BLE adapter found\"\n```bash\nsudo systemctl start bluetooth\n```\n\n### \"Permission denied\"\nContainer needs `--privileged` flag for BLE access\n\n### \"Device not found\"\n- Ensure device BLE is enabled\n- Move closer (BLE range ~10-30m)\n- Check device not connected to another app\n\n### \"Connection refused\" from MeshMonitor\n- Verify bridge listening on `0.0.0.0:4403`\n- Check firewall allows port 4403\n- Test with: `telnet \u003cbridge-ip\u003e 4403`\n\n## Reconnection Behavior (v1.3+)\n\nThe bridge now automatically handles node reboots and BLE disconnections:\n\n**Internal Reconnection:**\n- Detects disconnections immediately via callback and polling\n- Attempts up to 5 reconnections with exponential backoff (2s, 4s, 8s, 16s, 32s)\n- Continues operation if reconnection succeeds\n\n**Container Restart:**\n- If all reconnection attempts fail, the container exits with error code 1\n- Docker's `restart: unless-stopped` policy automatically restarts the container\n- Fresh container attempts clean connection to the device\n\n**Recommended Docker Configuration:**\n```yaml\nservices:\n  ble-bridge:\n    restart: unless-stopped  # Auto-restart on failure\n    healthcheck:\n      test: [\"CMD-SHELL\", \"netstat -tln | grep -q :4403 || exit 1\"]\n      interval: 30s\n      timeout: 10s\n      retries: 3\n```\n\n**Monitoring:**\nCheck logs to see reconnection activity:\n```bash\ndocker logs -f ble-bridge\n```\n\nLook for:\n- `⚠️  BLE device disconnected` - Initial disconnect detected\n- `🔄 Reconnection attempt X/5` - Retry in progress\n- `✅ Reconnected successfully` - Success\n- `💀 Failed to reconnect` - Container will exit and restart\n\n## Support \u0026 Development\n\nFor issues, questions, or contributions:\n- MeshMonitor: https://github.com/Yeraze/meshmonitor\n- Meshtastic: https://meshtastic.org\n\n## Star History\n\n[![Star History Chart](https://api.star-history.com/svg?repos=yeraze/meshtastic-ble-bridge\u0026type=date\u0026legend=top-left)](https://www.star-history.com/#yeraze/meshtastic-ble-bridge\u0026type=date\u0026legend=top-left)\n\n## License\n\nBSD-3-Clause (same as MeshMonitor)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyeraze%2Fmeshtastic-ble-bridge","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyeraze%2Fmeshtastic-ble-bridge","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyeraze%2Fmeshtastic-ble-bridge/lists"}