16 KiB
Proxmark5 BWM — Battery, BLE & WiFi
The Battery / Wireless Module (BWM) adds a battery + charger and an ESP32 that bridges the Proxmark5 to BLE and WiFi. Everything below is PM5-only and is compiled in with the BWM platform extra.
Contents
Build
Build the firmware with the BWM extra — this enables WITH_BWM_FORWARD (the
UART4 / app_com driver, battery telemetry, and BLE/WiFi forwarding):
make clean
make PLATFORM=PM5 PLATFORM_EXTRAS=BWM
make client # or your usual client build
Or set it persistently in Makefile.platform:
PLATFORM=PM5
PLATFORM_EXTRAS=BWM
Note
Without
PLATFORM_EXTRAS=BWMthe firmware builds a plain PM5 with none of the battery / BLE / WiFi commands below.
1. Battery / BWM control
These run over any active connection — USB, BLE, or WiFi.
hw status — battery + charger telemetry
[usb] pm3 --> hw status
The Battery / BWM section reports the AW32001 charger (power path, fault, charge state, input limit, charge current/voltage/enable) and the BQ27427 fuel gauge (state-of-charge %, voltage, current, remaining/full capacity, temperature, health).
hw bwm setcap — set fuel-gauge design capacity
Program the BQ27427 Design Capacity for the fitted cell.
| Argument | Description |
|---|---|
--cap <mAh> |
Design capacity in mAh (default 500) |
hw bwm setcap # set design capacity to the default 500 mAh
hw bwm setcap --cap 500 # set design capacity to 500 mAh
Warning
Run this once after fitting or replacing the battery. Running it repeatedly triggers a gauge config-update and disrupts the Impedance Track learning cycle.
hw bwm charge — enable/disable charging (one-shot)
Clears/sets the AW32001E charge-enable bit (CEB, REG01[3]).
| Sub-action | Description |
|---|---|
on |
Enable charging |
off |
Disable charging |
hw bwm charge on # enable charging
hw bwm charge off # disable charging
Note
One-shot: the charger watchdog reverts this after ~160 s unless serviced, so charging may stop on its own. Use it to nudge a top-up.
hw bwm vchg — set charge-voltage limit
Sets the AW32001E charge-voltage regulation target (VBAT_REG, REG04[7:2]).
Lowering it below 4.2 V reduces top-of-charge stress and extends cell life.
| Argument | Description |
|---|---|
--mv <mV> |
Charge voltage in mV (default 4100, clamped 3600..4200) |
hw bwm vchg # set the default 4100 mV target (-> 4.095 V)
hw bwm vchg --mv 4200 # set 4200 mV
The value snaps to the nearest 15 mV hardware step, and the command reports the
voltage actually applied (e.g. 4100 → 4.095 V; 4110 would be the next step).
Note
The firmware applies the
4100mV default (4.095 V) at every boot — the AW32001E's own power-on default is 4.2 V. It is a runtime register write, but because the boot config disables the charger watchdog the value then holds until the next power cycle (which re-applies it), so you don't need to re-run it per charge.
hw bwm autooff — auto power-off on USB unplug
Toggles automatic power-off when the PM5 is unplugged from USB. Default is on:
the board powers down after USB is removed so a BWM-equipped PM5 doesn't silently
drain the battery. Button power-on is unaffected.
| Sub-action | Description |
|---|---|
on |
Enable auto power-off |
off |
Disable auto power-off |
hw bwm autooff off # disable auto power-off
hw bwm autooff on # re-enable auto power-off
Note
Runtime only — resets to
onat each boot. Disable it for an uninterrupted move from USB to standalone / BLE / WiFi use on battery. For regular standalone / BLE / WiFi use on battery, one can just turn it on when needed, no need to touch that setting.
2. BLE
The BWM advertises as:
| Property | Value |
|---|---|
| Name | Proxmark5 |
| Address | 58:2A:BD:34:F1:82 (LE Public, Espressif OUI) |
| Service | 0xAE86 (16-bit) |
| Data char | 0xAE88 (WRITE / WRITE_NO_RSP / NOTIFY) |
| Security | none (plaintext GATT, no bonding) |
Note
58:2A:BD:34:F1:82is just an example — each module has its own address. Find yours withbtmgmt find, or use the bridge's name-scan (-n Proxmark5), which avoids needing the address at all.
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).
hw bwm name — get/set the BLE advertising name
Reads or changes the name the BWM advertises over BLE. With no argument it prints
the current name; --set changes it (1–31 characters).
| Argument | Description |
|---|---|
--set <name> |
New BLE name, 1–31 chars; omit to read current name |
hw bwm name # show the current BLE name
hw bwm name --set MyPM5 # set the BLE name to 'MyPM5'
The name is stored on the BWM in NVS, so it persists across power cycles. The BWM applies the advertised name at BLE start-up, so setting a name reboots the BWM to make it take effect — this briefly drops a BLE or WiFi connection, so reconnect after a few seconds. Over USB the reboot is not noticeable, since the client stays connected to the PM5 while only the BWM's ESP restarts.
Note
If a device is connected over BLE when you change the name, the running advertisement can't change mid-connection; the new name shows up on the next scan after the reboot.
2.1 Native BLE transport — Linux only, no bridge
Uses a raw L2CAP/ATT socket — no bleak, no bluetoothd daemon dependency.
Needs the Bluetooth dev headers at build time:
sudo apt install libbluetooth-dev
make client # rebuild so HAVE_BLUEZ is picked up
Then connect by address:
./pm3 -p ble:58:2A:BD:34:F1:82
On success you'll see e.g. BLE connected, MTU 512, char handle 0x0014.
2.2 BLE bridge — cross-platform (pm5_ble_bridge.py)
Requires Python 3 and bleak (pip install bleak). It bridges the BWM's BLE SPP
to a PTY or a TCP socket that the pm3 client then opens.
Important
Run the bridge on the machine that has the Bluetooth radio.
Common options:
| Option | Description |
|---|---|
-n, --name <name> |
Advertised name to scan for (default Proxmark5) |
-a, --address <mac> |
Connect by address instead of scanning by name |
--dump |
Hexdump traffic both directions (debug) |
-v, --verbose |
Verbose logging |
a) PTY (Linux/macOS) — simplest, one process:
python3 pm5_ble_bridge.py --pty # default link /tmp/pm5-ble
./pm3 -p /tmp/pm5-ble
b) TCP listener — bridge listens, client connects in:
python3 pm5_ble_bridge.py --tcp 18888 # or HOST:PORT
./pm3 -p tcp:127.0.0.1:18888
c) Outbound TCP (--connect) — bridge dials out to a listener. Pairs with
the client's --wait mode (2.3) and crosses
the WSL2 NAT boundary:
python3 pm5_ble_bridge.py --connect 127.0.0.1:18888
d) Relay only (no BLE) — TCP listener ↔ PTY, for chaining:
python3 pm5_ble_bridge.py --relay --listen 18888 --pty
Note
Windows / WSL: run the bridge on Windows (where the radio is) with
py, and let only TCP cross into WSL.
2.3 Client listen mode — pm3 … --wait
With a tcp: port, --wait makes the client bind / listen and wait for an
incoming connection instead of dialing out. Start the client first, then point the
bridge at it with --connect. This removes the relay/PTY hop.
# window 1 — client listens (blocks until something connects)
./pm3 -p tcp:127.0.0.1:18888 --wait
# window 2 — bridge dials in (on the machine with the radio)
python3 pm5_ble_bridge.py --connect 127.0.0.1:18888
Note
For a plain serial port,
--waitkeeps 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, just BLE instead of classic Bluetooth. Tested with the paid BT/USB/TCP Bridge 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).
- Build the client in Termux (see termux_notes.md).
- In the bridge app:
| Setting | Value |
|---|---|
| Device A | Start TCP server, use client default port:18888 |
| Device B | Connect to BLE device → Proxmark5 |
| Characteristic | the last one: service 0000ae86-…, characteristic 0000ae88-…, for RX+TX |
- In Termux, connect over the local port:
./client/proxmark3 tcp:localhost:18888
Or, as we're using the default port, just
./client/proxmark3 tcp:localhost
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): the client then connects straight to the BWM's TCP server, with no app in between.
3. WiFi (STA + TCP server)
hw bwm wifi joins your WiFi network as a station and starts a TCP server on
the BWM. You then connect the client over plain TCP. Run hw bwm wifi over an
existing link (USB, or an existing BLE connection). Use hw bwm wifi status to check an
existing connection without touching the config.
3.1 Bring up WiFi
hw bwm wifi --ssid <ssid> [--pwd <password>] [--port <n>] [--hostname <name>]
| Argument | Description |
|---|---|
--ssid <ssid> |
WiFi network to join (required) |
--pwd <password> |
WiFi password (omit for an open network) |
--port <dec> |
TCP server listen port (default 18888) |
--hostname <name> |
DHCP hostname (default Proxmark5) |
Two sub-actions take no other arguments and are positional (no dashes):
hw bwm wifi status and hw bwm wifi stop (see 3.3 and 3.4).
hw bwm wifi --ssid Home --pwd secret
hw bwm wifi --ssid Home --pwd secret --port 9000 --hostname pm5-lab
hw bwm wifi --ssid OpenGuestWiFi # open network
The join can take ~15 s. On success it prints the assigned IP and the connect strings:
[+] BWM on WiFi at 192.168.1.77
[?] Connect with: pm3 -p tcp:192.168.1.77:18888
[?] Or by name (router-dependent): pm3 -p tcp:pm5-lab:18888
3.2 Connect over WiFi
./pm3 -p tcp:192.168.1.77:18888
Or, as we're using the default port, just
./pm3 -p tcp:192.168.1.77
Note
Connecting by hostname works only if your router registers DHCP client names in its local DNS (some need a suffix like
<name>.lanor<name>.home; some don't do it at all). BWM firmware with mDNS also answers<name>.local, e.g../pm3 -p tcp:pm5-lab.local:18888; this needs an mDNS-capable resolver on the host (Avahi/nss-mdns or systemd-resolved on Linux; built in on macOS and Windows 10+).
3.3 Check WiFi status — hw bwm wifi status
Queries the BWM's current connection state and IP without reconnecting or changing the WiFi config. Handy to confirm a join actually completed — the bring-up occasionally reports failure if the DHCP lease lands late, even though the STA connected a moment later.
hw bwm wifi status
[+] BWM WiFi connected, IP 192.168.1.77
[?] Connect with: pm3 -p tcp:192.168.1.77:<port>
Note
"Connected" here means the STA has a DHCP lease (a usable IP). If it reports not connected right after a bring-up, wait a few seconds and re-check — the lease may still be in flight.
3.4 Stop WiFi — hw bwm wifi stop
Tears down the WiFi station and TCP server and returns the BWM to BLE-only. Run it over an existing link (USB or BLE); it does not need any other arguments.
hw bwm wifi stop
Note
If you issue
hw bwm wifi stopover the WiFi connection itself, that connection drops as the TCP server goes away — reconnect over USB or BLE afterwards.
4. Update BWM firmware — hw bwm upgrade
Reflashes the BWM (ESP32-C2) firmware over the existing BWM link — no 5-pin
header, no soldering, no esptool. Run it over whatever link you already have
(USB or BLE). It updates a BWM that still responds; it cannot recover a fully
bricked one — that still needs the production 5-pin header + esptool.
hw bwm upgrade -f <bwm_esp32.bin> [--delay <ms>]
| Argument | Description |
|---|---|
-f, --file |
ESP32-C2 firmware image .bin (required) |
--delay <ms> |
Per-chunk delay pacing the slow AT32-ESP UART (default 20) |
The client refuses to flash anything that is not an ESP32-C2 app image (it checks
the ESP image magic 0xE9 and chip_id 0x000C), so a wrong-chip image can't
brick the module.
It prints the running version first, uploads the image, then reboots the ESP into the new image and confirms by reading the version back:
[=] Current BWM firmware..... v1.2.3
[=] Uploading 812345 bytes of ESP firmware over the BWM link...
[=] BWM rebooting into the new image (link drops briefly)...
[+] BWM firmware updated: v1.2.3 -> v1.3.0
Note
There is no resume: a chunk dropped mid-transfer restarts the whole upload, and the client retries automatically (up to 6 attempts). If uploads keep failing on the slow link, raise the pacing, e.g.
--delay 40.
Note
The link drops briefly while the ESP reboots into the new image. Over BLE the post-reboot version read sometimes can't complete even though the flash succeeded — reconnect and run
hw statusto confirm the running version.
Notes
- Bulk transfers over BLE/WiFi (
lf read,mem dump, trace download) are paced by the BWM flow control so they don't drop — expect them to be slower than USB. - COTAG / large realtime LF reads use a separate streaming path and are not covered by this flow control.
- All BWM commands are PM5-only and require the firmware built with
PLATFORM_EXTRAS=BWM.