docs(ble): update bridge docs and troubleshooting

tools/ble/ble_uart_bridge/README.md

@@ -8,6 +8,7 @@ BLE UART Bridge is a host-side utility for talking to ESP-IDF applications that
 ## Table of contents
 
 - [Quick Start](#quick-start) - install dependencies and run the first commands
+- [Linux troubleshooting](#linux-troubleshooting) - reset the host Bluetooth service when Linux connections fail
 - [CLI overview](#cli-overview) - command list and common Console/Daemon workflows
   - [Typical Console workflow](#typical-console-workflow)
   - [Typical Daemon workflow](#typical-daemon-workflow)
@@ -41,7 +42,7 @@ cd tools/ble/ble_uart_bridge
 python -m pip install -r requirements.txt
 ```
 
-List nearby BLE UART devices:
+List nearby BLE devices:
 
 ```bash
 python main.py list-devices
@@ -79,6 +80,15 @@ python main.py daemon-notify --op set_led --json '{"state": true}'
 
 For Daemon details, the HTTP API, and the JSONL RPC protocol, see [Quick-Start-BLE-UART-Daemon.md](docs/Quick-Start-BLE-UART-Daemon.md).
 
+## Linux troubleshooting
+
+On Linux, the host Bluetooth stack can occasionally get into a stale state. Symptoms may include repeated connection failures, pairing getting stuck, or successful connection without discovering the expected BLE UART service or characteristics. When this happens, reset the system Bluetooth service, then retry `list-devices`, `connection-check`, `console`, or `daemon`:
+
+```bash
+sudo systemctl stop bluetooth
+sudo systemctl start bluetooth
+```
+
 ## CLI overview
 
 Run:
@@ -179,7 +189,7 @@ Use it when you want to write your own Python script or tool on top of BLE UART
 
 Main responsibilities:
 
-- Scan for BLE UART devices.
+- Scan for nearby BLE devices.
 - Check whether a target device can be connected.
 - Connect and disconnect with a BLE UART GATT profile.
 - Subscribe to device-to-host notifications.

tools/ble/ble_uart_bridge/docs/PORTING.md

@@ -242,14 +242,9 @@ async def main() -> None:
 asyncio.run(main())
 ```
 
-For custom service UUID discovery:
-
-```python
-devices = await scan_devices(
-    timeout=5.0,
-    service_uuid="00000000-0000-0000-0000-000000000001",
-)
-```
+`scan_devices()` performs an unfiltered BLE scan. If your script needs to
+restrict results to a specific profile, filter or connect-verify devices in
+your application code.
 
 ## Error handling guidance
 

tools/ble/ble_uart_bridge/docs/Quick-Start-BLE-UART-Console.md

@@ -136,7 +136,7 @@ This affects BLE GATT write behavior only. It does not create an application-lev
 Use the [BLE UART Service example](../../../../examples/bluetooth/ble_uart_service) when you want a ready-made ESP-IDF Echo Server for testing BLE UART Bridge Console. After building, flashing, and pairing with the example, open Console and type any text; the example should echo the same data back as `[RX]` output.
 
 ```bash
-# List nearby BLE UART devices and use the printed device ID as DEVICE_ID
+# List nearby BLE devices and use the printed device ID as DEVICE_ID
 python main.py list-devices
 python main.py console AA:BB:CC:DD:EE:FF
 ```
@@ -190,6 +190,14 @@ aa 55 01 00
 - Make sure no other host is already connected to the BLE device.
 - Restart advertising on the device.
 - Run `connection-check` before opening the console.
+- On Linux, reset the system Bluetooth service if connections keep failing,
+  pairing gets stuck, or service discovery cannot find the BLE UART service or
+  characteristics:
+
+  ```bash
+  sudo systemctl stop bluetooth
+  sudo systemctl start bluetooth
+  ```
 
 ### Text looks broken
 

tools/ble/ble_uart_bridge/docs/Quick-Start-BLE-UART-Daemon.md

@@ -432,6 +432,14 @@ while the daemon waits for a response that never arrives.
 - The BLE device is disconnected or not advertising.
 - The daemon tried to reconnect before sending the request or notification, but
   the reconnect attempt failed.
+- On Linux, reset the system Bluetooth service if reconnects keep failing,
+  pairing gets stuck, or service discovery cannot find the BLE UART service or
+  characteristics:
+
+  ```bash
+  sudo systemctl stop bluetooth
+  sudo systemctl start bluetooth
+  ```
 - Restore the BLE device and retry the same command; the daemon does not replay
   failed requests automatically.
 - After three consecutive BLE transport failures, the daemon exits. Restart it