Bump docs version

* Add missing definition for default device callbacks (which prevents calling the `setDeviceCallbacks` method)
* Ensure `m_pDeviceCallbacks` inital value is set to `&defaultDeviceCallbacks` to prevent crash when pairing table is full

After #295 any time the pairing table fills up, the device will crash on the next pairing attempt.

CHANGELOG.md

@@ -1,6 +1,21 @@
 # Changelog
 All notable changes to this project will be documented in this file.
 
+## [2.2.1] 2025-02-28
+
+## Fixed
+- Added back `NimBLEClient::connect` overload with `NimBLEAdvertisedDevice` parameter to resolve connection error due to NULL address.
+- Crash caused by returning invalid vector entry when retrieving remote descriptors.
+
+## [2.2.0] 2025-02-24
+
+## Fixed
+- Crash when calling `NimBLEClient::DiscoverAttributes`.
+
+## Added
+- Conditional macros for logging.
+- `NimBLEDeviceCallbacks` class with a callback for handling bond storage.
+
 ## [2.1.1] 2025-01-26
 
 ## Fixed

NOTICE

@@ -1,6 +1,6 @@
 esp-nimble-cpp
 NimBLE-Arduino
-Copyright 2020-2024 Ryan Powell <ryan@nable-embedded.io> and
+Copyright 2020-2025 Ryan Powell <ryan@nable-embedded.io> and
 esp-nimble-cpp, NimBLE-Arduino contributors.
 
 The Initial Developer of some parts of this library, which are copied from, 

docs/Doxyfile

@@ -48,7 +48,7 @@ PROJECT_NAME           = esp-nimble-cpp
 # could be handy for archiving the generated documentation or if some version
 # control system is used.
 
-PROJECT_NUMBER         = 2.1.1
+PROJECT_NUMBER         = 2.2.1
 
 # Using the PROJECT_BRIEF tag one can provide an optional one line description
 # for a project that appears at the top of each page and should give viewer a

idf_component.yml

@@ -1,5 +1,5 @@
 ## IDF Component Manager Manifest File
-version: "2.1.1"
+version: "2.2.1"
 license: "Apache-2.0"
 description: "C++ wrapper for the NimBLE BLE stack"
 url: "https://github.com/h2zero/esp-nimble-cpp"

library.json

@@ -1,6 +1,6 @@
 {
   "name": "esp-nimble-cpp",
-  "version": "2.1.1",
+  "version": "2.2.1",
   "description": "C++ wrapper for the NimBLE BLE stack",
   "keywords": [
     "BLE",

src/NimBLE2904.cpp

@@ -1,5 +1,5 @@
 /*
- * Copyright 2020-2024 Ryan Powell <ryan@nable-embedded.io> and
+ * Copyright 2020-2025 Ryan Powell <ryan@nable-embedded.io> and
  * esp-nimble-cpp, NimBLE-Arduino contributors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");

src/NimBLE2904.h

@@ -1,5 +1,5 @@
 /*
- * Copyright 2020-2024 Ryan Powell <ryan@nable-embedded.io> and
+ * Copyright 2020-2025 Ryan Powell <ryan@nable-embedded.io> and
  * esp-nimble-cpp, NimBLE-Arduino contributors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
@@ -68,7 +68,7 @@ class NimBLE2904 : public NimBLEDescriptor {
     static const uint8_t FORMAT_OPAQUE    = 27;
     static const uint8_t FORMAT_MEDASN1   = 28;
 
-    void setDescription(uint16_t);
+    void setDescription(uint16_t description);
     void setExponent(int8_t exponent);
     void setFormat(uint8_t format);
     void setNamespace(uint8_t namespace_value);

src/NimBLEAddress.cpp

@@ -1,5 +1,5 @@
 /*
- * Copyright 2020-2024 Ryan Powell <ryan@nable-embedded.io> and
+ * Copyright 2020-2025 Ryan Powell <ryan@nable-embedded.io> and
  * esp-nimble-cpp, NimBLE-Arduino contributors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");

src/NimBLEAddress.h

@@ -1,5 +1,5 @@
 /*
- * Copyright 2020-2024 Ryan Powell <ryan@nable-embedded.io> and
+ * Copyright 2020-2025 Ryan Powell <ryan@nable-embedded.io> and
  * esp-nimble-cpp, NimBLE-Arduino contributors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");

src/NimBLEAdvertisedDevice.cpp

@@ -1,5 +1,5 @@
 /*
- * Copyright 2020-2024 Ryan Powell <ryan@nable-embedded.io> and
+ * Copyright 2020-2025 Ryan Powell <ryan@nable-embedded.io> and
  * esp-nimble-cpp, NimBLE-Arduino contributors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
@@ -780,6 +780,16 @@ bool NimBLEAdvertisedDevice::isLegacyAdvertisement() const {
 # endif
 } // isLegacyAdvertisement
 
+/**
+ * @brief Convenience operator to convert this NimBLEAdvertisedDevice to NimBLEAddress representation.
+ * @details This allows passing NimBLEAdvertisedDevice to functions
+ * that accept NimBLEAddress and/or or it's methods as a parameter.
+ */
+NimBLEAdvertisedDevice::operator NimBLEAddress() const {
+    NimBLEAddress address(getAddress());
+    return address;
+} // operator NimBLEAddress
+
 /**
  * @brief Get the payload advertised by the device.
  * @return The advertisement payload.

src/NimBLEAdvertisedDevice.h

@@ -1,5 +1,5 @@
 /*
- * Copyright 2020-2024 Ryan Powell <ryan@nable-embedded.io> and
+ * Copyright 2020-2025 Ryan Powell <ryan@nable-embedded.io> and
  * esp-nimble-cpp, NimBLE-Arduino contributors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
@@ -93,6 +93,7 @@ class NimBLEAdvertisedDevice {
     uint8_t  getSecondaryPhy() const;
     uint16_t getPeriodicInterval() const;
 # endif
+    operator NimBLEAddress() const;
 
     const std::vector<uint8_t>&                getPayload() const;
     const std::vector<uint8_t>::const_iterator begin() const;

src/NimBLEAdvertisementData.cpp

@@ -1,5 +1,5 @@
 /*
- * Copyright 2020-2024 Ryan Powell <ryan@nable-embedded.io> and
+ * Copyright 2020-2025 Ryan Powell <ryan@nable-embedded.io> and
  * esp-nimble-cpp, NimBLE-Arduino contributors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");

src/NimBLEAdvertisementData.h

@@ -1,5 +1,5 @@
 /*
- * Copyright 2020-2024 Ryan Powell <ryan@nable-embedded.io> and
+ * Copyright 2020-2025 Ryan Powell <ryan@nable-embedded.io> and
  * esp-nimble-cpp, NimBLE-Arduino contributors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
@@ -38,7 +38,7 @@ class NimBLEAdvertisementData {
     bool addData(const uint8_t* data, size_t length);
     bool addData(const std::vector<uint8_t>& data);
     bool setAppearance(uint16_t appearance);
-    bool setFlags(uint8_t);
+    bool setFlags(uint8_t flag);
     bool addTxPower();
     bool setPreferredParams(uint16_t minInterval, uint16_t maxInterval);
     bool addServiceUUID(const NimBLEUUID& serviceUUID);

src/NimBLEAdvertising.cpp

@@ -1,5 +1,5 @@
 /*
- * Copyright 2020-2024 Ryan Powell <ryan@nable-embedded.io> and
+ * Copyright 2020-2025 Ryan Powell <ryan@nable-embedded.io> and
  * esp-nimble-cpp, NimBLE-Arduino contributors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");

src/NimBLEAdvertising.h

@@ -1,5 +1,5 @@
 /*
- * Copyright 2020-2024 Ryan Powell <ryan@nable-embedded.io> and
+ * Copyright 2020-2025 Ryan Powell <ryan@nable-embedded.io> and
  * esp-nimble-cpp, NimBLE-Arduino contributors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");

src/NimBLEAttValue.cpp

@@ -1,5 +1,5 @@
 /*
- * Copyright 2020-2024 Ryan Powell <ryan@nable-embedded.io> and
+ * Copyright 2020-2025 Ryan Powell <ryan@nable-embedded.io> and
  * esp-nimble-cpp, NimBLE-Arduino contributors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");

src/NimBLEAttValue.h

@@ -1,5 +1,5 @@
 /*
- * Copyright 2020-2024 Ryan Powell <ryan@nable-embedded.io> and
+ * Copyright 2020-2025 Ryan Powell <ryan@nable-embedded.io> and
  * esp-nimble-cpp, NimBLE-Arduino contributors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");

src/NimBLEAttribute.h

@@ -1,5 +1,5 @@
 /*
- * Copyright 2020-2024 Ryan Powell <ryan@nable-embedded.io> and
+ * Copyright 2020-2025 Ryan Powell <ryan@nable-embedded.io> and
  * esp-nimble-cpp, NimBLE-Arduino contributors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");

src/NimBLEBeacon.cpp

@@ -1,5 +1,5 @@
 /*
- * Copyright 2020-2024 Ryan Powell <ryan@nable-embedded.io> and
+ * Copyright 2020-2025 Ryan Powell <ryan@nable-embedded.io> and
  * esp-nimble-cpp, NimBLE-Arduino contributors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");

src/NimBLEBeacon.h

@@ -1,5 +1,5 @@
 /*
- * Copyright 2020-2024 Ryan Powell <ryan@nable-embedded.io> and
+ * Copyright 2020-2025 Ryan Powell <ryan@nable-embedded.io> and
  * esp-nimble-cpp, NimBLE-Arduino contributors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");

src/NimBLECharacteristic.cpp

@@ -1,5 +1,5 @@
 /*
- * Copyright 2020-2024 Ryan Powell <ryan@nable-embedded.io> and
+ * Copyright 2020-2025 Ryan Powell <ryan@nable-embedded.io> and
  * esp-nimble-cpp, NimBLE-Arduino contributors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");

src/NimBLECharacteristic.h

@@ -1,5 +1,5 @@
 /*
- * Copyright 2020-2024 Ryan Powell <ryan@nable-embedded.io> and
+ * Copyright 2020-2025 Ryan Powell <ryan@nable-embedded.io> and
  * esp-nimble-cpp, NimBLE-Arduino contributors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");

src/NimBLEClient.cpp

@@ -1,5 +1,5 @@
 /*
- * Copyright 2020-2024 Ryan Powell <ryan@nable-embedded.io> and
+ * Copyright 2020-2025 Ryan Powell <ryan@nable-embedded.io> and
  * esp-nimble-cpp, NimBLE-Arduino contributors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
@@ -126,6 +126,22 @@ size_t NimBLEClient::deleteService(const NimBLEUUID& uuid) {
     return m_svcVec.size();
 } // deleteService
 
+/**
+ * @brief Connect to an advertising device.
+ * @param [in] pDevice A pointer to the advertised device instance to connect to.
+ * @param [in] deleteAttributes If true this will delete any attribute objects this client may already\n
+ * have created when last connected.
+ * @param [in] asyncConnect If true, the connection will be made asynchronously and this function will return immediately.\n
+ * If false, this function will block until the connection is established or the connection attempt times out.
+ * @param [in] exchangeMTU If true, the client will attempt to exchange MTU with the server after connection.\n
+ * If false, the client will use the default MTU size and the application will need to call exchangeMTU() later.
+ * @return true on success.
+ */
+bool NimBLEClient::connect(const NimBLEAdvertisedDevice* pDevice, bool deleteAttributes, bool asyncConnect, bool exchangeMTU) {
+    NimBLEAddress address(pDevice->getAddress());
+    return connect(address, deleteAttributes, asyncConnect, exchangeMTU);
+} // connect
+
 /**
  * @brief Connect to the BLE Server using the address of the last connected device, or the address\n
  * passed to the constructor.
@@ -141,22 +157,6 @@ bool NimBLEClient::connect(bool deleteAttributes, bool asyncConnect, bool exchan
     return connect(m_peerAddress, deleteAttributes, asyncConnect, exchangeMTU);
 } // connect
 
-/**
- * @brief Connect to an advertising device.
- * @param [in] device The device to connect to.
- * @param [in] deleteAttributes If true this will delete any attribute objects this client may already\n
- * have created when last connected.
- * @param [in] asyncConnect If true, the connection will be made asynchronously and this function will return immediately.\n
- * If false, this function will block until the connection is established or the connection attempt times out.
- * @param [in] exchangeMTU If true, the client will attempt to exchange MTU with the server after connection.\n
- * If false, the client will use the default MTU size and the application will need to call exchangeMTU() later.
- * @return true on success.
- */
-bool NimBLEClient::connect(const NimBLEAdvertisedDevice* device, bool deleteAttributes, bool asyncConnect, bool exchangeMTU) {
-    NimBLEAddress address(device->getAddress());
-    return connect(address, deleteAttributes, asyncConnect, exchangeMTU);
-} // connect
-
 /**
  * @brief Connect to a BLE Server by address.
  * @param [in] address The address of the server.

src/NimBLEClient.h

@@ -1,5 +1,5 @@
 /*
- * Copyright 2020-2024 Ryan Powell <ryan@nable-embedded.io> and
+ * Copyright 2020-2025 Ryan Powell <ryan@nable-embedded.io> and
  * esp-nimble-cpp, NimBLE-Arduino contributors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");

src/NimBLEConnInfo.h

@@ -1,5 +1,5 @@
 /*
- * Copyright 2020-2024 Ryan Powell <ryan@nable-embedded.io> and
+ * Copyright 2020-2025 Ryan Powell <ryan@nable-embedded.io> and
  * esp-nimble-cpp, NimBLE-Arduino contributors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");

src/NimBLEDescriptor.cpp

@@ -1,5 +1,5 @@
 /*
- * Copyright 2020-2024 Ryan Powell <ryan@nable-embedded.io> and
+ * Copyright 2020-2025 Ryan Powell <ryan@nable-embedded.io> and
  * esp-nimble-cpp, NimBLE-Arduino contributors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");

src/NimBLEDescriptor.h

@@ -1,5 +1,5 @@
 /*
- * Copyright 2020-2024 Ryan Powell <ryan@nable-embedded.io> and
+ * Copyright 2020-2025 Ryan Powell <ryan@nable-embedded.io> and
  * esp-nimble-cpp, NimBLE-Arduino contributors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");

src/NimBLEDevice.cpp

@@ -1,5 +1,5 @@
 /*
- * Copyright 2020-2024 Ryan Powell <ryan@nable-embedded.io> and
+ * Copyright 2020-2025 Ryan Powell <ryan@nable-embedded.io> and
  * esp-nimble-cpp, NimBLE-Arduino contributors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
@@ -76,6 +76,9 @@ extern "C" void ble_store_config_init(void);
 /**
  * Singletons for the NimBLEDevice.
  */
+NimBLEDeviceCallbacks NimBLEDevice::defaultDeviceCallbacks{};
+NimBLEDeviceCallbacks* NimBLEDevice::m_pDeviceCallbacks = &defaultDeviceCallbacks;
+
 # if defined(CONFIG_BT_NIMBLE_ROLE_OBSERVER)
 NimBLEScan* NimBLEDevice::m_pScan = nullptr;
 # endif
@@ -900,7 +903,9 @@ bool NimBLEDevice::init(const std::string& deviceName) {
         // Setup callbacks for host events
         ble_hs_cfg.reset_cb        = NimBLEDevice::onReset;
         ble_hs_cfg.sync_cb         = NimBLEDevice::onSync;
-        ble_hs_cfg.store_status_cb = ble_store_util_status_rr; /*TODO: Implement handler for this*/
+        ble_hs_cfg.store_status_cb = [](struct ble_store_status_event* event, void* arg) {
+            return m_pDeviceCallbacks->onStoreStatus(event, arg);
+        };
 
         // Set initial security capabilities
         ble_hs_cfg.sm_io_cap         = BLE_HS_IO_NO_INPUT_OUTPUT;
@@ -1262,4 +1267,13 @@ void nimble_cpp_assert(const char* file, unsigned line) {
 }
 # endif // CONFIG_NIMBLE_CPP_DEBUG_ASSERT_ENABLED
 
+void NimBLEDevice::setDeviceCallbacks(NimBLEDeviceCallbacks* cb) {
+    m_pDeviceCallbacks = cb ? cb : &defaultDeviceCallbacks;
+}
+
+int NimBLEDeviceCallbacks::onStoreStatus(struct ble_store_status_event* event, void* arg) {
+    NIMBLE_LOGD("NimBLEDeviceCallbacks", "onStoreStatus: default");
+    return ble_store_util_status_rr(event, arg);
+}
+
 #endif // CONFIG_BT_ENABLED

src/NimBLEDevice.h

@@ -1,5 +1,5 @@
 /*
- * Copyright 2020-2024 Ryan Powell <ryan@nable-embedded.io> and
+ * Copyright 2020-2025 Ryan Powell <ryan@nable-embedded.io> and
  * esp-nimble-cpp, NimBLE-Arduino contributors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
@@ -66,6 +66,7 @@ class NimBLEConnInfo;
 # endif
 
 class NimBLEAddress;
+class NimBLEDeviceCallbacks;
 
 # define BLEDevice                    NimBLEDevice
 # define BLEClient                    NimBLEClient
@@ -129,6 +130,7 @@ class NimBLEDevice {
     static bool          setOwnAddrType(uint8_t type);
     static bool          setOwnAddr(const NimBLEAddress& addr);
     static bool          setOwnAddr(const uint8_t* addr);
+    static void          setDeviceCallbacks(NimBLEDeviceCallbacks* cb);
     static void          setScanDuplicateCacheSize(uint16_t cacheSize);
     static void          setScanFilterMode(uint8_t type);
     static bool          setCustomGapHandler(gap_event_handler handler);
@@ -213,6 +215,8 @@ class NimBLEDevice {
     static ble_gap_event_listener     m_listener;
     static uint8_t                    m_ownAddrType;
     static std::vector<NimBLEAddress> m_whiteList;
+    static NimBLEDeviceCallbacks*     m_pDeviceCallbacks;
+    static NimBLEDeviceCallbacks      defaultDeviceCallbacks;
 
 # if defined(CONFIG_BT_NIMBLE_ROLE_OBSERVER)
     static NimBLEScan* m_pScan;
@@ -295,5 +299,27 @@ class NimBLEDevice {
 
 # include "NimBLEUtils.h"
 
+/**
+ * @brief Callbacks associated with a BLE device.
+ */
+class NimBLEDeviceCallbacks {
+  public:
+    virtual ~NimBLEDeviceCallbacks() {};
+
+    /**
+     * @brief Indicates an inability to perform a store operation.
+     * This callback should do one of two things:
+     *     -Address the problem and return 0, indicating that the store operation
+     *      should proceed.
+     *     -Return nonzero to indicate that the store operation should be aborted.
+     * @param event     Describes the store event being reported.
+     *                      BLE_STORE_EVENT_FULL; or
+     *                      BLE_STORE_EVENT_OVERFLOW
+     * @return          0 if the store operation should proceed;
+     *                  nonzero if the store operation should be aborted.
+     */
+    virtual int onStoreStatus(struct ble_store_status_event* event, void* arg);
+};
+
 #endif // CONFIG_BT_ENABLED
 #endif // NIMBLE_CPP_DEVICE_H_

src/NimBLEEddystoneTLM.cpp

@@ -1,5 +1,5 @@
 /*
- * Copyright 2020-2024 Ryan Powell <ryan@nable-embedded.io> and
+ * Copyright 2020-2025 Ryan Powell <ryan@nable-embedded.io> and
  * esp-nimble-cpp, NimBLE-Arduino contributors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");

src/NimBLEEddystoneTLM.h

@@ -1,5 +1,5 @@
 /*
- * Copyright 2020-2024 Ryan Powell <ryan@nable-embedded.io> and
+ * Copyright 2020-2025 Ryan Powell <ryan@nable-embedded.io> and
  * esp-nimble-cpp, NimBLE-Arduino contributors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");

src/NimBLEExtAdvertising.cpp

@@ -1,5 +1,5 @@
 /*
- * Copyright 2020-2024 Ryan Powell <ryan@nable-embedded.io> and
+ * Copyright 2020-2025 Ryan Powell <ryan@nable-embedded.io> and
  * esp-nimble-cpp, NimBLE-Arduino contributors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");

src/NimBLEExtAdvertising.h

@@ -1,5 +1,5 @@
 /*
- * Copyright 2020-2024 Ryan Powell <ryan@nable-embedded.io> and
+ * Copyright 2020-2025 Ryan Powell <ryan@nable-embedded.io> and
  * esp-nimble-cpp, NimBLE-Arduino contributors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");

src/NimBLEHIDDevice.cpp

@@ -1,5 +1,5 @@
 /*
- * Copyright 2020-2024 Ryan Powell <ryan@nable-embedded.io> and
+ * Copyright 2020-2025 Ryan Powell <ryan@nable-embedded.io> and
  * esp-nimble-cpp, NimBLE-Arduino contributors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");

src/NimBLEHIDDevice.h

@@ -1,5 +1,5 @@
 /*
- * Copyright 2020-2024 Ryan Powell <ryan@nable-embedded.io> and
+ * Copyright 2020-2025 Ryan Powell <ryan@nable-embedded.io> and
  * esp-nimble-cpp, NimBLE-Arduino contributors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");

src/NimBLELocalAttribute.h

@@ -1,5 +1,5 @@
 /*
- * Copyright 2020-2024 Ryan Powell <ryan@nable-embedded.io> and
+ * Copyright 2020-2025 Ryan Powell <ryan@nable-embedded.io> and
  * esp-nimble-cpp, NimBLE-Arduino contributors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");

src/NimBLELocalValueAttribute.h

@@ -1,5 +1,5 @@
 /*
- * Copyright 2020-2024 Ryan Powell <ryan@nable-embedded.io> and
+ * Copyright 2020-2025 Ryan Powell <ryan@nable-embedded.io> and
  * esp-nimble-cpp, NimBLE-Arduino contributors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");

src/NimBLELog.h

@@ -1,5 +1,5 @@
 /*
- * Copyright 2020-2024 Ryan Powell <ryan@nable-embedded.io> and
+ * Copyright 2020-2025 Ryan Powell <ryan@nable-embedded.io> and
  * esp-nimble-cpp, NimBLE-Arduino contributors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
@@ -110,16 +110,16 @@
 
 #   define NIMBLE_CPP_LOG_FORMAT(letter, format) NIMBLE_CPP_LOG_COLOR_##letter #letter " (%lu) %s: " format LOG_RESET_COLOR "\n"
 
-#   define NIMBLE_CPP_LOG_LEVEL_LOCAL(level, tag, format, ...)                                                                                                  		\
-      do {                                                                                                                                                          	\
-        if (level==ESP_LOG_ERROR)       { esp_log_write(ESP_LOG_ERROR, tag, NIMBLE_CPP_LOG_FORMAT(E, format), esp_log_timestamp(), tag __VA_OPT__(,) __VA_ARGS__); }	\
+#   define NIMBLE_CPP_LOG_LEVEL_LOCAL(level, tag, format, ...)                                                                                                          \
+      do {                                                                                                                                                              \
+        if (level==ESP_LOG_ERROR)       { esp_log_write(ESP_LOG_ERROR, tag, NIMBLE_CPP_LOG_FORMAT(E, format), esp_log_timestamp(), tag __VA_OPT__(,) __VA_ARGS__); }    \
         else if (level==ESP_LOG_WARN)   { esp_log_write(ESP_LOG_WARN, tag, NIMBLE_CPP_LOG_FORMAT(W, format), esp_log_timestamp(), tag __VA_OPT__(,) __VA_ARGS__); }     \
         else if (level==ESP_LOG_INFO)   { esp_log_write(ESP_LOG_INFO, tag, NIMBLE_CPP_LOG_FORMAT(I, format), esp_log_timestamp(), tag __VA_OPT__(,) __VA_ARGS__); }     \
         else                            { esp_log_write(ESP_LOG_DEBUG, tag, NIMBLE_CPP_LOG_FORMAT(D, format), esp_log_timestamp(), tag __VA_OPT__(,) __VA_ARGS__); }    \
       } while(0)
 
-#   define NIMBLE_CPP_LOG_PRINT(level, tag, format, ...)                                               				\
-      do {                                                                                                      	\
+#   define NIMBLE_CPP_LOG_PRINT(level, tag, format, ...)                                                            \
+      do {                                                                                                          \
         if (CONFIG_NIMBLE_CPP_LOG_LEVEL >= level) NIMBLE_CPP_LOG_LEVEL_LOCAL(level, tag, format, ##__VA_ARGS__);    \
       } while (0)
 
@@ -172,5 +172,12 @@
 #  endif
 
 # endif  /* CONFIG_NIMBLE_CPP_IDF */
+
+#  define NIMBLE_LOGD_IF(cond, tag, format, ...) { if (cond) { NIMBLE_LOGD(tag, format, ##__VA_ARGS__); }}
+#  define NIMBLE_LOGI_IF(cond, tag, format, ...) { if (cond) { NIMBLE_LOGI(tag, format, ##__VA_ARGS__); }}
+#  define NIMBLE_LOGW_IF(cond, tag, format, ...) { if (cond) { NIMBLE_LOGW(tag, format, ##__VA_ARGS__); }}
+#  define NIMBLE_LOGE_IF(cond, tag, format, ...) { if (cond) { NIMBLE_LOGE(tag, format, ##__VA_ARGS__); }}
+#  define NIMBLE_LOGE_RC(rc, tag, format, ...) { if (rc) { NIMBLE_LOGE(tag, format "; rc=%d %s", ##__VA_ARGS__, rc, NimBLEUtils::returnCodeToString(rc)); }}
+
 #endif   /* CONFIG_BT_ENABLED */
 #endif   /* NIMBLE_CPP_LOG_H_ */

src/NimBLERemoteCharacteristic.cpp

@@ -1,5 +1,5 @@
 /*
- * Copyright 2020-2024 Ryan Powell <ryan@nable-embedded.io> and
+ * Copyright 2020-2025 Ryan Powell <ryan@nable-embedded.io> and
  * esp-nimble-cpp, NimBLE-Arduino contributors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
@@ -63,11 +63,8 @@ NimBLERemoteCharacteristic::~NimBLERemoteCharacteristic() {
 /**
  * @brief Callback used by the API when a descriptor is discovered or search complete.
  */
-int NimBLERemoteCharacteristic::descriptorDiscCB(uint16_t connHandle,
-                                                 const ble_gatt_error* error,
-                                                 uint16_t chrHandle,
-                                                 const ble_gatt_dsc* dsc,
-                                                 void* arg) {
+int NimBLERemoteCharacteristic::descriptorDiscCB(
+    uint16_t connHandle, const ble_gatt_error* error, uint16_t chrHandle, const ble_gatt_dsc* dsc, void* arg) {
     int        rc        = error->status;
     auto       filter    = (NimBLEDescriptorFilter*)arg;
     auto       pTaskData = (NimBLETaskData*)filter->taskData;
@@ -77,8 +74,7 @@ int NimBLERemoteCharacteristic::descriptorDiscCB(uint16_t connHandle,
 
     // Results for chrHandle added until rc != 0
     // Must find specified UUID if filter is used
-    if (rc == 0 && pChr->getHandle() == chrHandle
-      && (!uuid || 0 == ble_uuid_cmp(uuid->getBase(), &dsc->uuid.u))) {
+    if (rc == 0 && pChr->getHandle() == chrHandle && (!uuid || 0 == ble_uuid_cmp(uuid->getBase(), &dsc->uuid.u))) {
         // Return BLE_HS_EDONE if the descriptor was found, stop the search
         pChr->m_vDescriptors.push_back(new NimBLERemoteDescriptor(pChr, dsc));
         rc = !!uuid * BLE_HS_EDONE;
@@ -93,10 +89,10 @@ int NimBLERemoteCharacteristic::descriptorDiscCB(uint16_t connHandle,
 
 /**
  * @brief Populate the descriptors (if any) for this characteristic.
- * @param [in] filter Structure containing pointers to descriptor, UUID, and task data.
+ * @param [in] pFilter Pointer to a filter containing pointers to descriptor, UUID, and task data.
  * @return True if successfully retrieved, success = BLE_HS_EDONE.
  */
-bool NimBLERemoteCharacteristic::retrieveDescriptors(NimBLEDescriptorFilter* filter) const {
+bool NimBLERemoteCharacteristic::retrieveDescriptors(NimBLEDescriptorFilter* pFilter) const {
     NIMBLE_LOGD(LOG_TAG, ">> retrieveDescriptors() for characteristic: %s", getUUID().toString().c_str());
 
     // If this is the last handle then there are no descriptors
@@ -105,25 +101,35 @@ bool NimBLERemoteCharacteristic::retrieveDescriptors(NimBLEDescriptorFilter* fil
         return true;
     }
 
+    NimBLETaskData         taskData(const_cast<NimBLERemoteCharacteristic*>(this));
+    NimBLEDescriptorFilter defaultFilter{nullptr, nullptr, &taskData};
+    if (pFilter == nullptr) {
+        pFilter = &defaultFilter;
+    }
+
     int rc = ble_gattc_disc_all_dscs(getClient()->getConnHandle(),
                                      getHandle(),
                                      getRemoteService()->getEndHandle(),
                                      NimBLERemoteCharacteristic::descriptorDiscCB,
-                                     filter);
+                                     pFilter);
     if (rc != 0) {
         NIMBLE_LOGE(LOG_TAG, "ble_gattc_disc_all_dscs: rc=%d %s", rc, NimBLEUtils::returnCodeToString(rc));
         return false;
     }
 
-    NimBLEUtils::taskWait(filter->taskData, BLE_NPL_TIME_FOREVER);
-    rc = ((NimBLETaskData*)filter->taskData)->m_flags;
+    auto prevDscCount = m_vDescriptors.size();
+    NimBLEUtils::taskWait(pFilter->taskData, BLE_NPL_TIME_FOREVER);
+    rc = ((NimBLETaskData*)pFilter->taskData)->m_flags;
     if (rc != BLE_HS_EDONE) {
         NIMBLE_LOGE(LOG_TAG, "<< retrieveDescriptors(): failed: rc=%d %s", rc, NimBLEUtils::returnCodeToString(rc));
         return false;
     }
 
-    filter->dsc = m_vDescriptors.back();
-    NIMBLE_LOGD(LOG_TAG, "<< retrieveDescriptors(): found %d descriptors.", m_vDescriptors.size());
+    if (m_vDescriptors.size() > prevDscCount) {
+        pFilter->dsc = m_vDescriptors.back();
+    }
+
+    NIMBLE_LOGD(LOG_TAG, "<< retrieveDescriptors(): found %d descriptors.", m_vDescriptors.size() - prevDscCount);
     return true;
 } // retrieveDescriptors
 
@@ -134,9 +140,9 @@ bool NimBLERemoteCharacteristic::retrieveDescriptors(NimBLEDescriptorFilter* fil
  */
 NimBLERemoteDescriptor* NimBLERemoteCharacteristic::getDescriptor(const NimBLEUUID& uuid) const {
     NIMBLE_LOGD(LOG_TAG, ">> getDescriptor: uuid: %s", uuid.toString().c_str());
+    NimBLEUUID             uuidTmp{uuid};
     NimBLETaskData         taskData(const_cast<NimBLERemoteCharacteristic*>(this));
-    NimBLEDescriptorFilter filter = {nullptr, &uuid, &taskData};
-    NimBLEUUID             uuidTmp;
+    NimBLEDescriptorFilter filter{nullptr, &uuidTmp, &taskData};
 
     for (const auto& dsc : m_vDescriptors) {
         if (dsc->getUUID() == uuid) {
@@ -148,16 +154,18 @@ NimBLERemoteDescriptor* NimBLERemoteCharacteristic::getDescriptor(const NimBLEUU
     if (!retrieveDescriptors(&filter) || filter.dsc) {
         goto Done;
     }
-    // Try again with 128 bit uuid if request succeeded with no uuid found.
-    if (uuid.bitSize() == BLE_UUID_TYPE_16 || uuid.bitSize() == BLE_UUID_TYPE_32) {
-        uuidTmp = NimBLEUUID(uuid).to128();
+
+    // Try again with 128 bit uuid if request succeeded but no descriptor found.
+    if (uuid.bitSize() != BLE_UUID_TYPE_128) {
+        uuidTmp.to128();
         retrieveDescriptors(&filter);
         goto Done;
     }
-    // Try again with 16 bit uuid if request succeeded with no uuid found.
-    // If the uuid was 128 bit but not of the BLE base type this check will fail.
-    uuidTmp = NimBLEUUID(uuid).to16();
+
+    // If the uuid was 128 bit, try again with 16 bit uuid.
+    uuidTmp.to16();
     if (uuidTmp.bitSize() == BLE_UUID_TYPE_16) {
+        filter.uuid = &uuidTmp;
         retrieveDescriptors(&filter);
     }
 

src/NimBLERemoteCharacteristic.h

@@ -1,5 +1,5 @@
 /*
- * Copyright 2020-2024 Ryan Powell <ryan@nable-embedded.io> and
+ * Copyright 2020-2025 Ryan Powell <ryan@nable-embedded.io> and
  * esp-nimble-cpp, NimBLE-Arduino contributors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
@@ -67,7 +67,7 @@ class NimBLERemoteCharacteristic : public NimBLERemoteValueAttribute {
     ~NimBLERemoteCharacteristic();
 
     bool setNotify(uint16_t val, notify_callback notifyCallback = nullptr, bool response = true) const;
-    bool retrieveDescriptors(NimBLEDescriptorFilter* filter = nullptr) const;
+    bool retrieveDescriptors(NimBLEDescriptorFilter* pFilter = nullptr) const;
 
     static int descriptorDiscCB(
         uint16_t connHandle, const ble_gatt_error* error, uint16_t chrHandle, const ble_gatt_dsc* dsc, void* arg);

src/NimBLERemoteDescriptor.cpp

@@ -1,5 +1,5 @@
 /*
- * Copyright 2020-2024 Ryan Powell <ryan@nable-embedded.io> and
+ * Copyright 2020-2025 Ryan Powell <ryan@nable-embedded.io> and
  * esp-nimble-cpp, NimBLE-Arduino contributors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");

src/NimBLERemoteDescriptor.h

@@ -1,5 +1,5 @@
 /*
- * Copyright 2020-2024 Ryan Powell <ryan@nable-embedded.io> and
+ * Copyright 2020-2025 Ryan Powell <ryan@nable-embedded.io> and
  * esp-nimble-cpp, NimBLE-Arduino contributors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");

src/NimBLERemoteService.cpp

@@ -1,5 +1,5 @@
 /*
- * Copyright 2020-2024 Ryan Powell <ryan@nable-embedded.io> and
+ * Copyright 2020-2025 Ryan Powell <ryan@nable-embedded.io> and
  * esp-nimble-cpp, NimBLE-Arduino contributors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");

src/NimBLERemoteService.h

@@ -1,5 +1,5 @@
 /*
- * Copyright 2020-2024 Ryan Powell <ryan@nable-embedded.io> and
+ * Copyright 2020-2025 Ryan Powell <ryan@nable-embedded.io> and
  * esp-nimble-cpp, NimBLE-Arduino contributors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");

src/NimBLERemoteValueAttribute.cpp

@@ -1,5 +1,5 @@
 /*
- * Copyright 2020-2024 Ryan Powell <ryan@nable-embedded.io> and
+ * Copyright 2020-2025 Ryan Powell <ryan@nable-embedded.io> and
  * esp-nimble-cpp, NimBLE-Arduino contributors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");

src/NimBLERemoteValueAttribute.h

@@ -1,5 +1,5 @@
 /*
- * Copyright 2020-2024 Ryan Powell <ryan@nable-embedded.io> and
+ * Copyright 2020-2025 Ryan Powell <ryan@nable-embedded.io> and
  * esp-nimble-cpp, NimBLE-Arduino contributors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");

src/NimBLEScan.cpp

@@ -1,5 +1,5 @@
 /*
- * Copyright 2020-2024 Ryan Powell <ryan@nable-embedded.io> and
+ * Copyright 2020-2025 Ryan Powell <ryan@nable-embedded.io> and
  * esp-nimble-cpp, NimBLE-Arduino contributors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");

src/NimBLEScan.h

@@ -1,5 +1,5 @@
 /*
- * Copyright 2020-2024 Ryan Powell <ryan@nable-embedded.io> and
+ * Copyright 2020-2025 Ryan Powell <ryan@nable-embedded.io> and
  * esp-nimble-cpp, NimBLE-Arduino contributors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");

src/NimBLEServer.cpp

@@ -1,5 +1,5 @@
 /*
- * Copyright 2020-2024 Ryan Powell <ryan@nable-embedded.io> and
+ * Copyright 2020-2025 Ryan Powell <ryan@nable-embedded.io> and
  * esp-nimble-cpp, NimBLE-Arduino contributors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");

src/NimBLEServer.h

@@ -1,5 +1,5 @@
 /*
- * Copyright 2020-2024 Ryan Powell <ryan@nable-embedded.io> and
+ * Copyright 2020-2025 Ryan Powell <ryan@nable-embedded.io> and
  * esp-nimble-cpp, NimBLE-Arduino contributors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");

src/NimBLEService.cpp

@@ -1,5 +1,5 @@
 /*
- * Copyright 2020-2024 Ryan Powell <ryan@nable-embedded.io> and
+ * Copyright 2020-2025 Ryan Powell <ryan@nable-embedded.io> and
  * esp-nimble-cpp, NimBLE-Arduino contributors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");

src/NimBLEService.h

@@ -1,5 +1,5 @@
 /*
- * Copyright 2020-2024 Ryan Powell <ryan@nable-embedded.io> and
+ * Copyright 2020-2025 Ryan Powell <ryan@nable-embedded.io> and
  * esp-nimble-cpp, NimBLE-Arduino contributors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");

src/NimBLEUUID.cpp

@@ -1,5 +1,5 @@
 /*
- * Copyright 2020-2024 Ryan Powell <ryan@nable-embedded.io> and
+ * Copyright 2020-2025 Ryan Powell <ryan@nable-embedded.io> and
  * esp-nimble-cpp, NimBLE-Arduino contributors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");

src/NimBLEUUID.h

@@ -1,5 +1,5 @@
 /*
- * Copyright 2020-2024 Ryan Powell <ryan@nable-embedded.io> and
+ * Copyright 2020-2025 Ryan Powell <ryan@nable-embedded.io> and
  * esp-nimble-cpp, NimBLE-Arduino contributors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");

src/NimBLEUtils.cpp

@@ -1,5 +1,5 @@
 /*
- * Copyright 2020-2024 Ryan Powell <ryan@nable-embedded.io> and
+ * Copyright 2020-2025 Ryan Powell <ryan@nable-embedded.io> and
  * esp-nimble-cpp, NimBLE-Arduino contributors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");

src/NimBLEUtils.h

@@ -1,5 +1,5 @@
 /*
- * Copyright 2020-2024 Ryan Powell <ryan@nable-embedded.io> and
+ * Copyright 2020-2025 Ryan Powell <ryan@nable-embedded.io> and
  * esp-nimble-cpp, NimBLE-Arduino contributors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");