From 39bbf20cce3119bf26d6abaff7453a4222f0d363 Mon Sep 17 00:00:00 2001 From: Msprg <18015488+Msprg@users.noreply.github.com> Date: Fri, 18 Sep 2026 12:42:36 +0200 Subject: [PATCH] pm5: hw bwm ble, the module's BLE settings incl. on/off and pairing The module ships with BLE open: anyone in range can connect and run commands, and there was no way to turn the radio off or to require pairing from the PM5, although the module already implements bonding with a static passkey (LE Secure Connections + MITM, SPP characteristic encrypted) behind commands nothing exposed. New CMD_PM5_BWM_BLE (0x0183): one action byte, then a full status snapshot back (bwm_ble_status_t: switch, state, bonding, passkey, TX power, address, name, bonded devices). Client menu `hw bwm ble`: status everything above, with a warning while open on | off persisted radio switch (needs the companion Proxmark5_BWM_esp32 PR; off = nothing can connect, USB/WiFi only) pairing on|off [-k] require the 6-digit passkey, set the passkey; a change of on/off restarts the stack (drops a connected client), the factory key 123456 is flagged forget -i N | --all remove bonded devices txpower -a/-c dBm advertising / connection power, -24..18 and 20 The firmware replies before restarting the stack so the reply survives when the command itself arrived over BLE. Fields a module without the switch cannot answer read 0xFF and print as unknown. A module that does not answer at all ends the status snapshot after its first query instead of running into the client's timeout. Co-Authored-By: Claude Fable 5.1 --- CHANGELOG.md | 1 + armsrc/appmain.c | 61 +++++++++ armsrc/bwm_wifi.c | 77 +++++++++++ armsrc/bwm_wifi.h | 26 ++++ client/src/cmdbwm.c | 303 ++++++++++++++++++++++++++++++++++++++++++++ doc/commands.json | 86 ++++++++++++- doc/commands.md | 15 +++ include/pm3_cmd.h | 22 ++++ 8 files changed, 589 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 253e69430..4700683d0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,6 +3,7 @@ All notable changes to this project will be documented in this file. This project uses the changelog in accordance with [keepchangelog](http://keepachangelog.com/). Please use this to write notable changes, which is not the same as git commit log... ## [unreleased][unreleased] +- Added `hw bwm ble` - the BWM's BLE settings: `on`/`off` (persisted radio switch), `pairing` (require a 6-digit passkey, LE Secure Connections; the module ships open), `forget` bonded devices, `txpower`, `status` (@Msprg) - Changed `hw bwm autooff` - `--idle ` adds an opt-in power-off after that long idle on battery (no command, button press or BLE/WiFi client), off by default; `--unplug off` makes an unplug only restart that idle clock instead of powering off at once; all stored on the BWM, `hw status` shows it (@Msprg) - Added `hw bwm wifipower` - turn the BWM WiFi fully off, or set its modem power-save type (none/min/max), persisted on the module (@Msprg) - Added `hw bwm powersave` - show/set the BWM (ESP32) power-save switch: DFS, light sleep and slow advertising after 30 s, or the stock always-on behaviour, persisted on the module (@Msprg) diff --git a/armsrc/appmain.c b/armsrc/appmain.c index 43cf97cf1..5cc53c3cb 100644 --- a/armsrc/appmain.c +++ b/armsrc/appmain.c @@ -4466,6 +4466,67 @@ static void PacketReceived(PacketCommandNG *packet) { reply_ng(CMD_PM5_BWM_POWERSAVE, res, &state, (res == PM3_SUCCESS) ? 1 : 0); #else reply_ng(CMD_PM5_BWM_POWERSAVE, PM3_ENOTIMPL, NULL, 0); +#endif + break; + } + case CMD_PM5_BWM_BLE: { +#ifdef WITH_BWM_FORWARD + // BLE settings on the module: one action, then a full status snapshot back. + if (packet->length < 1) { + reply_ng(CMD_PM5_BWM_BLE, PM3_EINVARG, NULL, 0); + break; + } + uint8_t action = packet->data.asBytes[0]; + const uint8_t *arg = &packet->data.asBytes[1]; + uint16_t alen = packet->length - 1; + int res = PM3_SUCCESS; + bool restart = false; // a bonding change applies at the next stack start + switch (action) { + case BWM_BLE_ACTION_STATUS: + break; + case BWM_BLE_ACTION_ENABLE: { + uint8_t stored = 0; + res = (alen >= 1) ? bwm_esp_set_ble_enable(arg[0] != 0, &stored) : PM3_EINVARG; + break; + } + case BWM_BLE_ACTION_PAIRING: + res = (alen >= 1) ? bwm_esp_set_ble_bonding(arg[0] != 0) : PM3_EINVARG; + restart = (res == PM3_SUCCESS); + break; + case BWM_BLE_ACTION_KEY: + res = (alen >= 6) ? bwm_esp_set_ble_key(arg) : PM3_EINVARG; + break; + case BWM_BLE_ACTION_FORGET: + res = (alen >= 1) ? bwm_esp_ble_forget(arg[0]) : PM3_EINVARG; + break; + case BWM_BLE_ACTION_TXPOWER: + res = (alen >= 2) ? bwm_esp_set_ble_txpower(arg[0], arg[1]) : PM3_EINVARG; + break; + default: + res = PM3_EINVARG; + break; + } + if (res != PM3_SUCCESS) { + reply_ng(CMD_PM5_BWM_BLE, res, NULL, 0); + break; + } + bwm_ble_status_t st; + res = bwm_esp_ble_status(&st); + if (res != PM3_SUCCESS) { + reply_ng(CMD_PM5_BWM_BLE, res, NULL, 0); + if (restart) { + (void)bwm_esp_ble_restart(); + } + break; + } + reply_ng(CMD_PM5_BWM_BLE, PM3_SUCCESS, (uint8_t *)&st, sizeof(st)); + if (restart) { + // Reply first: over BLE the restart drops the client's own link. + SpinDelay(500); + (void)bwm_esp_ble_restart(); + } +#else + reply_ng(CMD_PM5_BWM_BLE, PM3_ENOTIMPL, NULL, 0); #endif break; } diff --git a/armsrc/bwm_wifi.c b/armsrc/bwm_wifi.c index 8b5b405d2..ffff5921b 100644 --- a/armsrc/bwm_wifi.c +++ b/armsrc/bwm_wifi.c @@ -360,6 +360,83 @@ int bwm_esp_host_value_get(uint8_t id, uint32_t *value, uint32_t timeout_ms) { return PM3_SUCCESS; } +int bwm_esp_set_ble_enable(bool on, uint8_t *stored) { + uint8_t v = on ? 1 : 0; + return bwm_esp_u8_cmd(BWM_CMD_SET_BLE_ENABLE, &v, 1, stored, 3000); +} + +int bwm_esp_set_ble_bonding(bool on) { + uint8_t v = on ? 1 : 0; + return bwm_cmd(BWM_CMD_SET_BLE_BONDING_ENABLE, &v, 1, NULL, NULL, 3000); +} + +int bwm_esp_set_ble_key(const uint8_t key[6]) { + return bwm_cmd(BWM_CMD_SET_BLE_BONDING_KEY, key, 6, NULL, NULL, 3000); +} + +int bwm_esp_ble_forget(uint8_t idx) { + if (idx == 0xFF) { + return bwm_cmd(BWM_CMD_CLEAR_BLE_BONDED, NULL, 0, NULL, NULL, 3000); + } + return bwm_cmd(BWM_CMD_DEL_BLE_BONDED, &idx, 1, NULL, NULL, 3000); +} + +int bwm_esp_set_ble_txpower(uint8_t type, uint8_t level) { + uint8_t req[2] = { type, level }; + return bwm_cmd(BWM_CMD_SET_BLE_TX_POWER, req, sizeof(req), NULL, NULL, 3000); +} + +int bwm_esp_ble_restart(void) { + uint8_t state = 0; + int res = bwm_esp_get_ble_state(&state, 3000); + if (res != PM3_SUCCESS || state == 0) { + return res; // stopped (or switched off): nothing to restart + } + res = bwm_cmd(BWM_CMD_STOP_BLE_SPP, NULL, 0, NULL, NULL, 3000); + if (res != PM3_SUCCESS) { + return res; + } + return bwm_cmd(BWM_CMD_START_BLE_SPP, NULL, 0, NULL, NULL, 3000); +} + +int bwm_esp_ble_status(bwm_ble_status_t *st) { + memset(st, 0xFF, sizeof(*st)); + // The first query wakes a light-sleeping module; the rest land while it is up. + // Its timeout is also the only one we pay when no module answers at all. + int res = bwm_esp_get_ble_state(&st->state, 1500); + if (res == PM3_ETIMEOUT) { + return res; + } + (void)bwm_esp_u8_cmd(BWM_CMD_GET_BLE_ENABLE, NULL, 0, &st->enabled, 800); // older fw: CMD_ERROR or silence + (void)bwm_esp_u8_cmd(BWM_CMD_GET_BLE_BONDING_ENABLE, NULL, 0, &st->bonding, 1500); + uint16_t len = sizeof(st->passkey); + (void)bwm_cmd(BWM_CMD_GET_BLE_BONDING_KEY, NULL, 0, (uint8_t *)st->passkey, &len, 1500); + uint8_t type = 0; + (void)bwm_esp_u8_cmd(BWM_CMD_GET_BLE_TX_POWER, &type, 1, &st->txp_adv, 1500); + type = 1; + (void)bwm_esp_u8_cmd(BWM_CMD_GET_BLE_TX_POWER, &type, 1, &st->txp_conn, 1500); + len = sizeof(st->addr); + (void)bwm_cmd(BWM_CMD_GET_BLE_DEVICE_ADDR, NULL, 0, st->addr, &len, 1500); + memset(st->name, 0, sizeof(st->name)); + len = sizeof(st->name) - 1; + if (bwm_esp_get_ble_name((uint8_t *)st->name, &len) != PM3_SUCCESS) { + st->name[0] = 0; + } + st->bonded_count = 0; + uint8_t n = 0; + if (bwm_esp_u8_cmd(BWM_CMD_GET_BLE_BONDED_NUMS, NULL, 0, &n, 1500) == PM3_SUCCESS) { + for (uint8_t i = 0; i < n && i < BWM_BLE_BONDED_MAX; i++) { + len = 7; + if (bwm_cmd(BWM_CMD_GET_BLE_BONDED_ADDR, &i, 1, st->bonded[i], &len, 1500) == PM3_SUCCESS && len == 7) { + st->bonded_count++; + } else { + break; + } + } + } + return PM3_SUCCESS; +} + int bwm_esp_set_power_save(bool on, uint8_t *state) { // Applied at once on the ESP (no reboot) and saved to its NVS; the reply // carries the state the ESP ended up in. diff --git a/armsrc/bwm_wifi.h b/armsrc/bwm_wifi.h index eb5ea9202..3a58b605c 100644 --- a/armsrc/bwm_wifi.h +++ b/armsrc/bwm_wifi.h @@ -10,6 +10,7 @@ #define BWM_WIFI_H #include "common.h" +#include "pm3_cmd.h" // bwm_ble_status_t // app_com command codes (authoritative, from BWM main/app_com_defs.h) #define BWM_CMD_SET_TO_WIFI_DISABLE_MODE 2000 // no payload: tear down WiFi, back to BLE-only @@ -105,6 +106,31 @@ int bwm_esp_host_value_get(uint8_t id, uint32_t *value, uint32_t timeout_ms); #define BWM_CMD_GET_BLE_SPP_STATUS 4020 // resp: u8 0=stopped 1=advertising 2=client connected #define BWM_BLE_STATE_CONNECTED 2 int bwm_esp_get_ble_state(uint8_t *state, uint32_t timeout_ms); + +// BLE settings behind `hw bwm ble` (app_com_defs.h, BLE block @4000). +#define BWM_CMD_GET_BLE_DEVICE_ADDR 4007 // resp: 6 bytes +#define BWM_CMD_SET_BLE_BONDING_ENABLE 4008 // req: u8; takes effect at the next stack start +#define BWM_CMD_GET_BLE_BONDING_ENABLE 4009 // resp: u8 +#define BWM_CMD_SET_BLE_BONDING_KEY 4010 // req: 6 ASCII digits +#define BWM_CMD_GET_BLE_BONDING_KEY 4011 // resp: 6 ASCII digits +#define BWM_CMD_GET_BLE_BONDED_NUMS 4012 // resp: u8 count +#define BWM_CMD_GET_BLE_BONDED_ADDR 4013 // req: u8 index; resp: addr[6] + type +#define BWM_CMD_DEL_BLE_BONDED 4014 // req: u8 index +#define BWM_CMD_CLEAR_BLE_BONDED 4015 // no payload +#define BWM_CMD_SET_BLE_TX_POWER 4018 // req: [type][level] +#define BWM_CMD_GET_BLE_TX_POWER 4019 // req: u8 type; resp: u8 level +#define BWM_CMD_SET_BLE_ENABLE 4023 // req: u8 (persisted, applied at once); resp: u8 stored. Newer ESP fw only +#define BWM_CMD_GET_BLE_ENABLE 4024 // resp: u8 +int bwm_esp_set_ble_enable(bool on, uint8_t *stored); +int bwm_esp_set_ble_bonding(bool on); +int bwm_esp_set_ble_key(const uint8_t key[6]); +int bwm_esp_ble_forget(uint8_t idx); // 0xFF = all +int bwm_esp_set_ble_txpower(uint8_t type, uint8_t level); +// Stop + start the stack so a bonding change applies; no-op while it is stopped. +int bwm_esp_ble_restart(void); +// Best-effort snapshot for `hw bwm ble`; fields the module cannot answer read 0xFF. +// PM3_ETIMEOUT (nothing filled in) when the module does not answer the first query. +int bwm_esp_ble_status(bwm_ble_status_t *st); // ESP WiFi modem power-save type (0 none, 1 min, 2 max), persisted on the ESP. #define BWM_CMD_SET_WIFI_CFG_PS_MODE 2052 // req: u8 mode; resp: u8 applied mode #define BWM_CMD_GET_WIFI_CFG_PS_MODE 2053 // resp: u8 mode diff --git a/client/src/cmdbwm.c b/client/src/cmdbwm.c index 922b607d7..9057bc223 100644 --- a/client/src/cmdbwm.c +++ b/client/src/cmdbwm.c @@ -904,9 +904,312 @@ static int CmdBwmWifiPower(const char *Cmd) { return PM3_SUCCESS; } + +// --------------------------------------------------------------------------- +// hw bwm ble: the module's BLE settings (CMD_PM5_BWM_BLE) +// --------------------------------------------------------------------------- + +static const char *ble_state_str(uint8_t state) { + switch (state) { + case 0: return "off"; + case 1: return "advertising, no client"; + case 2: return "client connected"; + default: return "unknown"; + } +} + +// esp_power_level_t index <-> dBm: -24 dBm + 3 dB per step, index 15 = +20 dBm +static int ble_level_to_dbm(uint8_t level) { + if (level == 15) return 20; + return -24 + 3 * (int)level; +} + +static int ble_dbm_to_level(int dbm) { + if (dbm == 20) return 15; + if (dbm < -24 || dbm > 18 || ((dbm + 24) % 3) != 0) return -1; + return (dbm + 24) / 3; +} + +static void ble_print_status(const bwm_ble_status_t *st) { + PrintAndLogEx(INFO, "--- " _CYAN_("BWM BLE") " ---------------------------"); + if (st->enabled == 0xFF) { + PrintAndLogEx(INFO, "BLE................ %s " _YELLOW_("(module firmware without the on/off switch)"), ble_state_str(st->state)); + } else if (st->enabled == 0) { + PrintAndLogEx(INFO, "BLE................ " _YELLOW_("off") " (persisted; radio silent, USB/WiFi only)"); + } else { + PrintAndLogEx(INFO, "BLE................ " _GREEN_("on") ", %s", ble_state_str(st->state)); + } + if (st->name[0]) { + PrintAndLogEx(INFO, "Name............... " _YELLOW_("%s"), st->name); + } + if (st->addr[0] != 0xFF || st->addr[5] != 0xFF) { + PrintAndLogEx(INFO, "Address............ %02X:%02X:%02X:%02X:%02X:%02X", + st->addr[0], st->addr[1], st->addr[2], st->addr[3], st->addr[4], st->addr[5]); + } + if (st->bonding == 1) { + PrintAndLogEx(INFO, "Pairing............ " _GREEN_("required") " (LE Secure Connections, passkey " _YELLOW_("%.6s") ")", st->passkey); + if (memcmp(st->passkey, "123456", 6) == 0) { + PrintAndLogEx(WARNING, "the passkey is the factory default, change it: " _YELLOW_("hw bwm ble pairing -k <6 digits>")); + } + } else if (st->bonding == 0) { + PrintAndLogEx(INFO, "Pairing............ " _RED_("not required") " - anyone in range can connect and use the device"); + PrintAndLogEx(HINT, "enable it with " _YELLOW_("hw bwm ble pairing on")); + } + if (st->bonded_count != 0xFF) { + PrintAndLogEx(INFO, "Bonded devices..... %u%s", st->bonded_count, (st->bonded_count == BWM_BLE_BONDED_MAX) ? " (or more)" : ""); + for (uint8_t i = 0; i < st->bonded_count; i++) { + const uint8_t *a = st->bonded[i]; + PrintAndLogEx(INFO, " [%u] %02X:%02X:%02X:%02X:%02X:%02X (%s)", i, + a[0], a[1], a[2], a[3], a[4], a[5], (a[6] == 0) ? "public" : "random"); + } + } + if (st->txp_adv != 0xFF && st->txp_conn != 0xFF) { + PrintAndLogEx(INFO, "TX power........... advertising %d dBm, connection %d dBm", + ble_level_to_dbm(st->txp_adv), ble_level_to_dbm(st->txp_conn)); + } +} + +// One CMD_PM5_BWM_BLE round trip. Prints the status on success unless quiet. +static int ble_action(uint8_t action, const uint8_t *arg, size_t alen, bool quiet) { + uint8_t payload[1 + 8] = { action }; + if (alen > sizeof(payload) - 1) { + return PM3_EINVARG; + } + if (alen) { + memcpy(&payload[1], arg, alen); + } + clearCommandBuffer(); + SendCommandNG(CMD_PM5_BWM_BLE, payload, 1 + alen); + PacketResponseNG resp; + // Up to a dozen module round trips behind one reply, plus a light-sleep wake. + if (WaitForResponseTimeout(CMD_PM5_BWM_BLE, &resp, 8000) == false) { + PrintAndLogEx(WARNING, "command timeout (is this a PM5? over BLE, a pairing or on/off change drops your own link)"); + return PM3_ETIMEOUT; + } + if (resp.status == PM3_ENOTIMPL) { + PrintAndLogEx(WARNING, "firmware built without the BWM link"); + return resp.status; + } + if (resp.status != PM3_SUCCESS) { + PrintAndLogEx(FAILED, "module refused or did not answer (%s)", (resp.status == PM3_ETIMEOUT) ? "timeout" : "error"); + return resp.status; + } + if (resp.length < sizeof(bwm_ble_status_t)) { + PrintAndLogEx(FAILED, "short reply (%u bytes)", resp.length); + return PM3_EFAILED; + } + if (quiet == false) { + ble_print_status((const bwm_ble_status_t *)resp.data.asBytes); + } + return PM3_SUCCESS; +} + +static int CmdBwmBleStatus(const char *Cmd) { + CLIParserContext *ctx; + CLIParserInit(&ctx, "hw bwm ble status", + "Show the module's BLE settings: on/off, name, address, pairing and passkey,\n" + "bonded devices, TX power.", + "hw bwm ble status"); + void *argtable[] = { + arg_param_begin, + arg_param_end + }; + CLIExecWithReturn(ctx, Cmd, argtable, true); + CLIParserFree(ctx); + return ble_action(BWM_BLE_ACTION_STATUS, NULL, 0, false); +} + +static int ble_set_enable(const char *Cmd, bool on) { + CLIParserContext *ctx; + CLIParserInit(&ctx, on ? "hw bwm ble on" : "hw bwm ble off", + "Switch the module's BLE radio on or off. Persisted on the module, applied at\n" + "once. Off means nothing can connect over BLE at all; the PM5 stays reachable\n" + "over USB (and WiFi if configured). Needs a BWM firmware with the BLE switch.\n" + _YELLOW_("Over BLE, `off` cuts your own connection."), + on ? "hw bwm ble on" : "hw bwm ble off"); + void *argtable[] = { + arg_param_begin, + arg_param_end + }; + CLIExecWithReturn(ctx, Cmd, argtable, true); + CLIParserFree(ctx); + uint8_t v = on ? 1 : 0; + return ble_action(BWM_BLE_ACTION_ENABLE, &v, 1, false); +} + +static int CmdBwmBleOn(const char *Cmd) { + return ble_set_enable(Cmd, true); +} + +static int CmdBwmBleOff(const char *Cmd) { + return ble_set_enable(Cmd, false); +} + +static int CmdBwmBlePairing(const char *Cmd) { + // Positional sub-action (no dashes): hw bwm ble pairing [on|off] [-k ] + char verb[16] = {0}; + int consumed = 0; + sscanf(Cmd, "%15s%n", verb, &consumed); + bool on = (strcmp(verb, "on") == 0); + bool off = (strcmp(verb, "off") == 0); + const char *rest = (on || off) ? Cmd + consumed : Cmd; + + CLIParserContext *ctx; + CLIParserInit(&ctx, "hw bwm ble pairing", + "Require pairing before a BLE client can use the device. The module ships with\n" + "pairing " _RED_("off") ": anyone in range can connect and run commands. With it on, a\n" + "client must pair once with the 6-digit passkey (LE Secure Connections, MITM)\n" + "and the data characteristic only works over the encrypted link; paired\n" + "(bonded) devices reconnect without the key until you forget them.\n" + "Both settings persist on the module. A change of on/off restarts the BLE\n" + "stack, which " _YELLOW_("drops a connected client - reconnect (and pair) afterwards.") "\n" + "The factory passkey is 123456; set your own.", + "hw bwm ble pairing on --> require pairing\n" + "hw bwm ble pairing on -k 482913 --> require pairing with this passkey\n" + "hw bwm ble pairing -k 482913 --> change the passkey only\n" + "hw bwm ble pairing off --> open access again"); + void *argtable[] = { + arg_param_begin, + arg_str0("k", "key", "<6 digits>", "passkey a client must enter"), + arg_param_end + }; + CLIExecWithReturn(ctx, rest, argtable, true); + uint8_t key[8] = {0}; + int keylen = 0; + int kres = CLIParamStrToBuf(arg_get_str(ctx, 1), key, sizeof(key) - 1, &keylen); + CLIParserFree(ctx); + if (kres) { + PrintAndLogEx(WARNING, "the passkey must be exactly 6 digits"); + return PM3_EINVARG; + } + + if (keylen) { + bool ok = (keylen == 6); + for (int i = 0; ok && i < 6; i++) { + ok = isdigit(key[i]); + } + if (ok == false) { + PrintAndLogEx(WARNING, "the passkey must be exactly 6 digits"); + return PM3_EINVARG; + } + int res = ble_action(BWM_BLE_ACTION_KEY, key, 6, (on || off)); + if (res != PM3_SUCCESS) { + return res; + } + if (!on && !off) { + PrintAndLogEx(SUCCESS, "passkey set"); + return PM3_SUCCESS; + } + } else if (!on && !off) { + PrintAndLogEx(WARNING, "specify " _YELLOW_("on") ", " _YELLOW_("off") " and/or " _YELLOW_("-k <6 digits>")); + return PM3_EINVARG; + } + uint8_t v = on ? 1 : 0; + int res = ble_action(BWM_BLE_ACTION_PAIRING, &v, 1, false); + if (res == PM3_SUCCESS) { + PrintAndLogEx(SUCCESS, "pairing %s; the BLE stack is restarting, a connected client is dropped", on ? _GREEN_("required") : _YELLOW_("not required")); + } + return res; +} + +static int CmdBwmBleForget(const char *Cmd) { + CLIParserContext *ctx; + CLIParserInit(&ctx, "hw bwm ble forget", + "Remove bonded (paired) devices from the module, so they must pair again with\n" + "the passkey. Indexes are the ones `hw bwm ble status` lists.", + "hw bwm ble forget --all\n" + "hw bwm ble forget -i 0"); + void *argtable[] = { + arg_param_begin, + arg_int0("i", "idx", "", "index of the bonded device to remove"), + arg_lit0(NULL, "all", "remove all bonded devices"), + arg_param_end + }; + CLIExecWithReturn(ctx, Cmd, argtable, true); + int idx = arg_get_int_def(ctx, 1, -1); + bool all = arg_get_lit(ctx, 2); + CLIParserFree(ctx); + if ((all && idx >= 0) || (!all && idx < 0)) { + PrintAndLogEx(WARNING, "specify either " _YELLOW_("-i ") " or " _YELLOW_("--all")); + return PM3_EINVARG; + } + if (idx > 254) { + PrintAndLogEx(WARNING, "index out of range"); + return PM3_EINVARG; + } + uint8_t v = all ? 0xFF : (uint8_t)idx; + return ble_action(BWM_BLE_ACTION_FORGET, &v, 1, false); +} + +static int CmdBwmBleTxPower(const char *Cmd) { + CLIParserContext *ctx; + CLIParserInit(&ctx, "hw bwm ble txpower", + "Set the module's BLE transmit power for advertising and/or connections.\n" + "Steps of 3 dB from -24 to 18 dBm, plus 20. Lower saves a little battery and\n" + "shrinks the range at which the device can be found. Persisted on the module.", + "hw bwm ble txpower -a 0 -c 0 --> 0 dBm for both\n" + "hw bwm ble txpower -a -6 --> quieter advertising only"); + void *argtable[] = { + arg_param_begin, + arg_int0("a", "adv", "", "advertising power"), + arg_int0("c", "conn", "", "connection power"), + arg_param_end + }; + CLIExecWithReturn(ctx, Cmd, argtable, true); + bool has_adv = (arg_get_int_count(ctx, 1) > 0); + bool has_conn = (arg_get_int_count(ctx, 2) > 0); + int adv = arg_get_int_def(ctx, 1, 0); + int conn = arg_get_int_def(ctx, 2, 0); + CLIParserFree(ctx); + if ((has_adv == false) && (has_conn == false)) { + PrintAndLogEx(WARNING, "specify " _YELLOW_("-a ") " and/or " _YELLOW_("-c ")); + return PM3_EINVARG; + } + int la = has_adv ? ble_dbm_to_level(adv) : 0; + int lc = has_conn ? ble_dbm_to_level(conn) : 0; + if (la < 0 || lc < 0) { + PrintAndLogEx(WARNING, "valid values: -24, -21, ... 15, 18, 20 dBm"); + return PM3_EINVARG; + } + int res = PM3_SUCCESS; + if (has_adv) { + uint8_t v[2] = { 0, (uint8_t)la }; + res = ble_action(BWM_BLE_ACTION_TXPOWER, v, 2, has_conn); + } + if (res == PM3_SUCCESS && has_conn) { + uint8_t v[2] = { 1, (uint8_t)lc }; + res = ble_action(BWM_BLE_ACTION_TXPOWER, v, 2, false); + } + return res; +} + +static int CmdHelpBwmBle(const char *Cmd); +static command_t BwmBleCommandTable[] = { + {"help", CmdHelpBwmBle, AlwaysAvailable, "This help"}, + {"status", CmdBwmBleStatus, IfBwm, "Show BLE settings: on/off, pairing, bonded devices, TX power"}, + {"on", CmdBwmBleOn, IfBwm, "Switch BLE on (persisted)"}, + {"off", CmdBwmBleOff, IfBwm, "Switch BLE off (persisted) - nothing can connect"}, + {"pairing", CmdBwmBlePairing, IfBwm, "Require pairing with a passkey, set the passkey"}, + {"forget", CmdBwmBleForget, IfBwm, "Remove bonded devices"}, + {"txpower", CmdBwmBleTxPower, IfBwm, "Set advertising / connection TX power"}, + {NULL, NULL, NULL, NULL} +}; + +static int CmdHelpBwmBle(const char *Cmd) { + (void)Cmd; + CmdsHelp(BwmBleCommandTable); + return PM3_SUCCESS; +} + +static int CmdBwmBle(const char *Cmd) { + clearCommandBuffer(); + return CmdsParse(BwmBleCommandTable, Cmd); +} + static command_t BwmCommandTable[] = { {"help", CmdHelpBwm, AlwaysAvailable, "This help"}, {"autooff", CmdBwmAutoOff, IfBwm, "Show/set auto power-off (USB unplug, idle on battery)"}, + {"ble", CmdBwmBle, IfBwm, "{ BLE: on/off, pairing, bonded devices, TX power... }"}, {"charge", CmdBwmCharge, IfBwm, "Enable/disable battery charging (one-shot)"}, {"name", CmdBwmName, IfBwm, "Get/set the BWM BLE advertising name"}, {"powersave", CmdBwmPowerSave, IfBwm, "Show/set the BWM power-save switch (DFS, light sleep, slow adv)"}, diff --git a/doc/commands.json b/doc/commands.json index 6c96bcfe3..104290840 100644 --- a/doc/commands.json +++ b/doc/commands.json @@ -11030,6 +11030,88 @@ ], "usage": "hw break [-h]" }, + "hw bwm ble forget": { + "command": "hw bwm ble forget", + "description": "Remove bonded (paired) devices from the module, so they must pair again with the passkey. Indexes are the ones `hw bwm ble status` lists.", + "notes": [ + "hw bwm ble forget --all", + "hw bwm ble forget -i 0" + ], + "offline": false, + "options": [ + "-h, --help This help", + "-i, --idx index of the bonded device to remove", + "--all remove all bonded devices" + ], + "usage": "hw bwm ble forget [-h] [-i ] [--all]" + }, + "hw bwm ble help": { + "command": "hw bwm ble help", + "description": "help This help --------------------------------------------------------------------------------------- hw bwm ble status available offline: no Show the module's BLE settings: on/off, name, address, pairing and passkey, bonded devices, TX power.", + "notes": [ + "hw bwm ble status" + ], + "offline": true, + "options": [ + "-h, --help This help" + ], + "usage": "hw bwm ble status [-h]" + }, + "hw bwm ble off": { + "command": "hw bwm ble off", + "description": "Switch the module's BLE radio on or off. Persisted on the module, applied at once. Off means nothing can connect over BLE at all; the PM5 stays reachable over USB (and WiFi if configured). Needs a BWM firmware with the BLE switch. Over BLE, `off` cuts your own connection.", + "notes": [ + "hw bwm ble off" + ], + "offline": false, + "options": [ + "-h, --help This help" + ], + "usage": "hw bwm ble off [-h]" + }, + "hw bwm ble on": { + "command": "hw bwm ble on", + "description": "Switch the module's BLE radio on or off. Persisted on the module, applied at once. Off means nothing can connect over BLE at all; the PM5 stays reachable over USB (and WiFi if configured). Needs a BWM firmware with the BLE switch. Over BLE, `off` cuts your own connection.", + "notes": [ + "hw bwm ble on" + ], + "offline": false, + "options": [ + "-h, --help This help" + ], + "usage": "hw bwm ble on [-h]" + }, + "hw bwm ble pairing": { + "command": "hw bwm ble pairing", + "description": "Require pairing before a BLE client can use the device. The module ships with pairing off: anyone in range can connect and run commands. With it on, a client must pair once with the 6-digit passkey (LE Secure Connections, MITM) and the data characteristic only works over the encrypted link; paired (bonded) devices reconnect without the key until you forget them. Both settings persist on the module. A change of on/off restarts the BLE stack, which drops a connected client - reconnect (and pair) afterwards. The factory passkey is 123456; set your own.", + "notes": [ + "hw bwm ble pairing on -> require pairing", + "hw bwm ble pairing on -k 482913 -> require pairing with this passkey", + "hw bwm ble pairing -k 482913 -> change the passkey only", + "hw bwm ble pairing off -> open access again" + ], + "offline": false, + "options": [ + "-h, --help This help", + "-k, --key <6 digits> passkey a client must enter" + ], + "usage": "hw bwm ble pairing [-h] [-k <6 digits>]" + }, + "hw bwm ble txpower": { + "command": "hw bwm ble txpower", + "description": "Set the module's BLE transmit power for advertising and/or connections. Steps of 3 dB from -24 to 18 dBm, plus 20. Lower saves a little battery and shrinks the range at which the device can be found. Persisted on the module.", + "notes": [ + "hw bwm ble txpower -a 0 -c 0 -> 0 dBm for both", + "hw bwm ble txpower -a -6 -> quieter advertising only" + ], + "offline": false, + "options": [ + "-h, --help This help", + "-a, --adv advertising power", + "-c, --conn connection power" + ], + "usage": "hw bwm ble txpower [-h] [-a ] [-c ]" + }, "hw bwm charge": { "command": "hw bwm charge", "description": "Enable or disable BWM battery charging by clearing/setting the AW32001E charge-enable bit (CEB, REG01[3]). PM5 only. One-shot: the charger watchdog reverts this after ~160 s unless serviced, so charging may stop on its own. Use to nudge a top-up.", @@ -16700,8 +16782,8 @@ } }, "metadata": { - "commands_extracted": 929, + "commands_extracted": 935, "extracted_by": "PM3Help2JSON v1.00", - "extracted_on": "2026-09-24T08:31:45+00:00" + "extracted_on": "2026-09-24T08:32:19+00:00" } } diff --git a/doc/commands.md b/doc/commands.md index adba1355d..5fb6c6f9d 100644 --- a/doc/commands.md +++ b/doc/commands.md @@ -1059,6 +1059,21 @@ Check column "offline" for their availability. |`hw bwm wifipower `|N |`WiFi fully off, or the modem power-save type (none/min/max)` +### hw bwm ble + + { BLE: on/off, pairing, bonded devices, TX power... } + +|command |offline |description +|------- |------- |----------- +|`hw bwm ble help `|Y |`This help` +|`hw bwm ble status `|N |`Show BLE settings: on/off, pairing, bonded devices, TX power` +|`hw bwm ble on `|N |`Switch BLE on (persisted)` +|`hw bwm ble off `|N |`Switch BLE off (persisted) - nothing can connect` +|`hw bwm ble pairing `|N |`Require pairing with a passkey, set the passkey` +|`hw bwm ble forget `|N |`Remove bonded devices` +|`hw bwm ble txpower `|N |`Set advertising / connection TX power` + + ### lf { Low frequency commands... } diff --git a/include/pm3_cmd.h b/include/pm3_cmd.h index 9361a0540..dee23a9ff 100644 --- a/include/pm3_cmd.h +++ b/include/pm3_cmd.h @@ -961,6 +961,28 @@ typedef struct { #define BWM_WIFI_PS_MIN 1 // sleeps between DTIM beacons (ESP-IDF default) #define BWM_WIFI_PS_MAX 2 // sleeps for the listen interval #define BWM_WIFI_STATE_OFF 0xFF // wifi_state byte: WiFi stack down (BLE-only) +// PM5, BWM BLE settings (`hw bwm ble`). req: [action:u8][args]; resp: bwm_ble_status_t +// on success. Unknown fields (module firmware without the command) read 0xFF. +#define CMD_PM5_BWM_BLE 0x0183 +#define BWM_BLE_ACTION_STATUS 0x00 +#define BWM_BLE_ACTION_ENABLE 0x01 // [on:u8], persisted on the module +#define BWM_BLE_ACTION_PAIRING 0x02 // [on:u8], persisted; restarts the stack (drops a BLE client) +#define BWM_BLE_ACTION_KEY 0x03 // [6 ASCII digits], persisted +#define BWM_BLE_ACTION_FORGET 0x04 // [idx:u8, 0xFF = all bonded devices] +#define BWM_BLE_ACTION_TXPOWER 0x05 // [type:u8 0 adv 1 conn][level:u8 esp_power_level_t 0..15, -24 dBm + 3/step, 15 = 20 dBm] +#define BWM_BLE_BONDED_MAX 8 +typedef struct { + uint8_t enabled; // persisted switch + uint8_t state; // 0 off, 1 advertising, 2 client connected + uint8_t bonding; // 1 = pairing with passkey required, SPP characteristic encrypted + char passkey[6]; // ASCII digits, not NUL-terminated + uint8_t txp_adv; // esp_power_level_t index + uint8_t txp_conn; + uint8_t addr[6]; // as the module reports it (big-endian display order) + char name[16]; // NUL-padded + uint8_t bonded_count; + uint8_t bonded[BWM_BLE_BONDED_MAX][7]; // addr[6] + type, first bonded_count valid +} PACKED bwm_ble_status_t; #define BWM_OTA_ACTION_BEGIN 0x00 #define BWM_OTA_ACTION_WRITE 0x01 #define BWM_OTA_ACTION_END 0x02