From 1fdc2eda93b43f451f247ca656ceb9efe7291901 Mon Sep 17 00:00:00 2001
From: MarekWo <mwojtaszek@gmail.com>
Date: Sun, 29 Mar 2026 14:07:21 +0200
Subject: [PATCH] docs(ble): add troubleshooting section to pairing guide
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

bluetoothctl info auto-connects to trusted devices, stealing the
connection from Docker — document hcitool as safe alternative and
add connection loop recovery steps.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 docs/meshcore_bluetooth_pairing.md | 44 ++++++++++++++++++++++++++++++
 1 file changed, 44 insertions(+)

diff --git a/docs/meshcore_bluetooth_pairing.md b/docs/meshcore_bluetooth_pairing.md
index 2f2ff10..cca61dc 100644
--- a/docs/meshcore_bluetooth_pairing.md
+++ b/docs/meshcore_bluetooth_pairing.md
@@ -81,3 +81,47 @@ This is the most crucial step. You must "trust" the device so that `mc-webui` ca
    ```
 
 Your MeshCore device is now permanently paired, trusted, and ready to communicate with the `mc-webui` server!
+
+---
+
+## Troubleshooting
+
+### Checking BLE Connection Status
+
+**Do NOT use `bluetoothctl info <MAC>` to check connection state** — it auto-connects to trusted devices, which steals the connection from the `mc-webui` container.
+
+Instead, use `hcitool` which only reads status without triggering a connection:
+```bash
+hcitool con
+```
+Expected output when connected:
+```
+Connections:
+	< LE AC:A7:04:08:66:A1 handle 65 state 1 lm CENTRAL AUTH ENCRYPT
+```
+
+### Container Can't Connect (connection loop)
+
+If `mc-webui` is stuck in a "Failed to connect to device / Retrying..." loop:
+
+1. Check if something else holds the connection:
+   ```bash
+   hcitool con
+   ```
+2. If a connection exists, disconnect it:
+   ```bash
+   bluetoothctl disconnect AC:A7:04:08:66:A1
+   ```
+3. Restart the container:
+   ```bash
+   cd ~/mc-webui && docker compose restart mc-webui
+   ```
+4. Verify (wait ~15s for retry):
+   ```bash
+   hcitool con
+   curl -s http://localhost:5000/api/status | python3 -m json.tool
+   ```
+
+### Only One BLE Client at a Time
+
+A BLE peripheral can only be connected to one central at a time. If `bluetoothctl`, another app, or a mobile phone is connected, the container will fail. Always disconnect other clients before starting `mc-webui`.