From 443b2d8fc84d97396284cc07ebfbfab84250cf77 Mon Sep 17 00:00:00 2001 From: Niel Nielsen Date: Sat, 12 Sep 2026 13:45:14 +0200 Subject: [PATCH] Document 'hw bwm name' command for BLE name management Added documentation for the 'hw bwm name' command, detailing how to get and set the BLE advertising name, including usage examples and notes on behavior during name changes. Signed-off-by: Niel Nielsen --- doc/md/PM5_Start_Here/PM5-BWM-USAGE.md | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/doc/md/PM5_Start_Here/PM5-BWM-USAGE.md b/doc/md/PM5_Start_Here/PM5-BWM-USAGE.md index b16fe983c..793b7952a 100644 --- a/doc/md/PM5_Start_Here/PM5-BWM-USAGE.md +++ b/doc/md/PM5_Start_Here/PM5-BWM-USAGE.md @@ -158,6 +158,31 @@ There are three ways to connect: a **native transport** (Linux), a **cross-platf Python bridge** (Linux / macOS / Windows / WSL / iOS), and a **bridge app** on Android ([2.4](#24-android--termux--ble-bridge-app)). +### `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 ` | 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.