From 56deaf7d4753052160db92fa38cc1a76f63d75f2 Mon Sep 17 00:00:00 2001 From: fl4p Date: Tue, 26 May 2026 11:28:25 +0100 Subject: [PATCH] Clarify NimBLEAddress(uint8_t[6], type) byte order in docstring MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The constructor calls std::reverse_copy on its input, expecting bytes in MSB-first order (Bluedroid's esp_bd_addr_t layout). The previous docstring said "compatibility with bluedroid esp library using native ESP representation," which is correct but ambiguous if the reader doesn't already know the conventions of both stacks. Callers reaching for this constructor with LSB-first bytes (e.g. as they'd come out of NimBLE's own ble_addr_t.val) silently end up with a reversed address — the radio uses val[] directly for HCI commands, so GAP connects target a fictional peer and time out as BLE_HS_ETIMEOUT with no diagnostic. Documentation-only change; behaviour is unchanged. Points readers to NimBLEAddress(ble_addr_t) for LSB-first wire bytes and to NimBLEAddress(const uint64_t&, uint8_t) for hex literals. Refs #423 --- src/NimBLEAddress.cpp | 15 +++++++++++++-- 1 file changed, 13 insertions(+), 2 deletions(-) diff --git a/src/NimBLEAddress.cpp b/src/NimBLEAddress.cpp index 2a719375..a631b25d 100644 --- a/src/NimBLEAddress.cpp +++ b/src/NimBLEAddress.cpp @@ -97,8 +97,19 @@ NimBLEAddress::NimBLEAddress(const std::string& addr, uint8_t type) { } // NimBLEAddress /** - * @brief Constructor for compatibility with bluedroid esp library using native ESP representation. - * @param [in] address A uint8_t[6] or esp_bd_addr_t containing the address. + * @brief Constructor accepting a 6-byte MSB-first BLE address (Bluedroid `esp_bd_addr_t` layout). + * @details The input bytes are stored internally in LSB-first wire + * order (NimBLE's `ble_addr_t.val` layout), so this constructor + * **reverses** the input. If you already have LSB-first wire bytes — + * e.g. straight out of a NimBLE callback's `ble_addr_t` — use the + * `NimBLEAddress(ble_addr_t)` constructor instead (it stores them + * as-is). If you have the address as a hex integer (e.g. + * `0xa4c1385def16` for `"a4:c1:38:5d:ef:16"`), use + * `NimBLEAddress(const uint64_t&, uint8_t)`. + * @param [in] address Six bytes in MSB-first order + * (`{0xaa, 0xbb, 0xcc, 0xdd, 0xee, 0xff}` for + * `"aa:bb:cc:dd:ee:ff"`). Compatible with + * Bluedroid's `esp_bd_addr_t`. * @param [in] type The type of the address should be one of: * * BLE_ADDR_PUBLIC (0) * * BLE_ADDR_RANDOM (1)