From d3bf03f3e3b2e845d0abe154658ce1bde28fc44d Mon Sep 17 00:00:00 2001
From: Msprg <18015488+Msprg@users.noreply.github.com>
Date: Thu, 3 Sep 2026 01:39:17 +0200
Subject: [PATCH] Docs: Add PM5 BWM BLE connection instructions

---
 doc/md/PM5_Start_Here/PM5-BWM-USAGE.md | 38 ++++++++++++++++++++++++--
 doc/termux_notes.md                    | 14 ++++++++++
 2 files changed, 50 insertions(+), 2 deletions(-)

diff --git a/doc/md/PM5_Start_Here/PM5-BWM-USAGE.md b/doc/md/PM5_Start_Here/PM5-BWM-USAGE.md
index d88e0afdd..c3a75b358 100644
--- a/doc/md/PM5_Start_Here/PM5-BWM-USAGE.md
+++ b/doc/md/PM5_Start_Here/PM5-BWM-USAGE.md
@@ -152,8 +152,9 @@ The BWM advertises as:
 > yours with `btmgmt find`, or use the bridge's name-scan (`-n Proxmark5`), which
 > avoids needing the address at all.
 
-There are two ways to connect: a **native transport** (Linux) and a **cross-platform
-Python bridge** (Linux / macOS / Windows / WSL / iOS).
+There are three ways to connect: a **native transport** (Linux), a **cross-platform
+Python bridge** (Linux / macOS / Windows / WSL / iOS), and a **bridge app** on Android
+([2.4](#24-android--termux--ble-bridge-app)).
 
 ### 2.1 Native BLE transport — Linux only, no bridge
 
@@ -240,6 +241,39 @@ python3 pm5_ble_bridge.py --connect 127.0.0.1:7777
 > For a plain **serial** port, `--wait` keeps its original meaning: wait ~20 s for
 > the device node to appear.
 
+### 2.4 Android — Termux + BLE bridge app
+
+Termux has no Bluetooth access, so a bridge app exposes the BWM's BLE characteristic
+as a local TCP port that the client then opens — same idea as
+[termux_notes.md](../../termux_notes.md), just BLE instead of classic Bluetooth.
+Tested with the paid
+[BT/USB/TCP Bridge](https://play.google.com/store/apps/details?id=masar.bluetoothbridge.pro)
+app, which lets you pick the GATT characteristic; the free version works too but is
+limited to 10 minutes per session (the limit resets after quitting the app).
+
+1. Build the client in Termux (see [termux_notes.md](../../termux_notes.md)).
+2. In the bridge app:
+
+| Setting          | Value                                                             |
+| ---------------- | ----------------------------------------------------------------- |
+| Device A         | Start TCP server (default port `54321`)                           |
+| Device B         | Connect to BLE device → `Proxmark5`                               |
+| Characteristic   | the last one: service `0000ae86-…`, characteristic `0000ae88-…`, for RX+TX |
+
+3. In Termux, connect over the local port:
+
+```
+./client/proxmark3 tcp:localhost:54321
+```
+
+No pairing is needed (the BWM has no BLE security). The same app also does classic
+Bluetooth, so one setup covers a Blueshark-equipped Proxmark3 too.
+
+> [!NOTE]
+> If you would rather not use a bridge app, put the phone in hotspot mode and use
+> WiFi instead ([3](#3-wifi-sta--tcp-server)): the client then connects straight to
+> the BWM's TCP server, with no app in between.
+
 ---
 
 ## 3. WiFi (STA + TCP server)
diff --git a/doc/termux_notes.md b/doc/termux_notes.md
index 798218d92..1c3851320 100644
--- a/doc/termux_notes.md
+++ b/doc/termux_notes.md
@@ -24,6 +24,7 @@
       - [USB-UART Bridge Application for UDP to USB bridging](#usb-uart-bridge-application-for-udp-to-usb-bridging)
     - [Bluetooth connection](#bluetooth-connection)
       - [BT-UART Bridge Application for TCP to BT bridging](#bt-uart-bridge-application-for-tcp-to-bt-bridging)
+      - [BLE bridging for the Proxmark5 BWM](#ble-bridging-for-the-proxmark5-bwm)
     - [TCP connection](#tcp-connection)
     - [UDP connection](#udp-connection)
     - [Troubleshooting](#troubleshooting-1)
@@ -184,6 +185,19 @@ Choose your registered PM3 device as 'Device B' -> 'Connect to classic Bluetooth
 Ensure 'Retransmission' is set to 'both ways'.
 It is possible to record the config as autostart, cf 'Settings' -> 'Autostart setting'.
 
+#### BLE bridging for the Proxmark5 BWM
+^[Top](#top)
+
+The Proxmark5 Battery Wireless Module (BWM) uses BLE, not classic Bluetooth.
+The [paid version of the BT/USB/TCP Bridge app](https://play.google.com/store/apps/details?id=masar.bluetoothbridge.pro) handles it (the free version works with 10 minute time limit, can be reset by restarting the app):
+
+In the app, select TCP server as 'Device A' (default port 54321).
+Choose 'Device B' -> 'Connect to BLE device' -> `Proxmark5`.
+When asked for the characteristic, choose: service UUID starting with `0000ae86`, characteristic starting with `0000ae88`, for RX+TX.
+No pairing is needed. Then connect from Termux as in [TCP connection](#tcp-connection) using port 54321.
+
+See [PM5-BWM-USAGE.md](md/PM5_Start_Here/PM5-BWM-USAGE.md) for the BWM firmware build flag and the WiFi alternative, which needs no bridge app at all.
+
 ### TCP connection
 ^[Top](#top)