Release/2.2

CHANGELOG.md

@@ -1,13 +1,28 @@
 # Changelog
 All notable changes to this project will be documented in this file.
 
+## [2.2.2] 2025-02-24
+
+## Fixed
+- Crash when calling `NimBLEClient::DiscoverAttributes`.
+
+## Added
+- `NimBLEDeviceCallbacks` class with a callback for handling bond storage.
+
+## [2.2.1] 2025-01-26
+
+## Fixed
+- remote descriptor discovery error when no descriptors exist.
+- scan filter settings not enabled for esp32s3/c3.
+- remote descriptor discovery returning more than the desired descriptor.
+
 ## [2.2.0] 2025-01-12
 
 ## Fixed
 - Crash when retrieving descriptors if more than one exists.
 - Incorrect TX power value being advertised.
 - New user guide code for 2.x
-- Potential race condition if `NimBLEScan::clearResults1 is called from multiple tasks.
+- Potential race condition if `NimBLEScan::clearResults` is called from multiple tasks.
 
 ## Changed
 - If privacy is not enabled identity keys will not be shared.

NOTICE

@@ -1,9 +1,9 @@
 esp-nimble-cpp
 NimBLE-Arduino
-Copyright 2020-2024 Ryan Powell <[email protected]> and
+Copyright 2020-2025 Ryan Powell <[email protected]> and
 esp-nimble-cpp, NimBLE-Arduino contributors.
 
-The Initial Developer of some parts of this library, which are copied from, 
+The Initial Developer of some parts of this library, which are copied from,
 derived from, or inspired by is, esp32-snippets, Copyright 2017 Neil Kolban.
 
 If this library is used for commercial purposes, it is requested that the user consider

docs/Doxyfile

@@ -48,7 +48,7 @@ PROJECT_NAME           = NimBLE-Arduino
 # could be handy for archiving the generated documentation or if some version
 # control system is used.
 
-PROJECT_NUMBER         = 2.2.0
+PROJECT_NUMBER         = 2.2.2
 # 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
 # quick idea about the purpose of the project. Keep the description short.

library.properties

@@ -1,5 +1,5 @@
 name=NimBLE-Arduino
-version=2.2.0
+version=2.2.2
 author=h2zero
 maintainer=Ryan Powell <[email protected]>
 sentence=Bluetooth low energy (BLE) library for Arduino based on NimBLE.

src/NimBLE2904.cpp

@@ -1,5 +1,5 @@
 /*
- * Copyright 2020-2024 Ryan Powell <[email protected]> and
+ * Copyright 2020-2025 Ryan Powell <[email protected]> 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 <[email protected]> and
+ * Copyright 2020-2025 Ryan Powell <[email protected]> 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 <[email protected]> and
+ * Copyright 2020-2025 Ryan Powell <[email protected]> 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 <[email protected]> and
+ * Copyright 2020-2025 Ryan Powell <[email protected]> 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 <[email protected]> and
+ * Copyright 2020-2025 Ryan Powell <[email protected]> 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 <[email protected]> and
+ * Copyright 2020-2025 Ryan Powell <[email protected]> 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 <[email protected]> and
+ * Copyright 2020-2025 Ryan Powell <[email protected]> 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 <[email protected]> and
+ * Copyright 2020-2025 Ryan Powell <[email protected]> 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 <[email protected]> and
+ * Copyright 2020-2025 Ryan Powell <[email protected]> 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 <[email protected]> and
+ * Copyright 2020-2025 Ryan Powell <[email protected]> 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 <[email protected]> and
+ * Copyright 2020-2025 Ryan Powell <[email protected]> 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 <[email protected]> and
+ * Copyright 2020-2025 Ryan Powell <[email protected]> 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 <[email protected]> and
+ * Copyright 2020-2025 Ryan Powell <[email protected]> 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 <[email protected]> and
+ * Copyright 2020-2025 Ryan Powell <[email protected]> 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 <[email protected]> and
+ * Copyright 2020-2025 Ryan Powell <[email protected]> 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 <[email protected]> and
+ * Copyright 2020-2025 Ryan Powell <[email protected]> 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 <[email protected]> and
+ * Copyright 2020-2025 Ryan Powell <[email protected]> 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 <[email protected]> and
+ * Copyright 2020-2025 Ryan Powell <[email protected]> and
  * esp-nimble-cpp, NimBLE-Arduino contributors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
@@ -141,22 +141,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 <[email protected]> and
+ * Copyright 2020-2025 Ryan Powell <[email protected]> and
  * esp-nimble-cpp, NimBLE-Arduino contributors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
@@ -48,10 +48,6 @@ struct NimBLETaskData;
  */
 class NimBLEClient {
   public:
-    bool connect(const NimBLEAdvertisedDevice* device,
-                 bool                          deleteAttributes = true,
-                 bool                          asyncConnect     = false,
-                 bool                          exchangeMTU      = true);
     bool connect(const NimBLEAddress& address, bool deleteAttributes = true, bool asyncConnect = false, bool exchangeMTU = true);
     bool           connect(bool deleteAttributes = true, bool asyncConnect = false, bool exchangeMTU = true);
     bool           disconnect(uint8_t reason = BLE_ERR_REM_USER_CONN_TERM);

src/NimBLEConnInfo.h

@@ -1,5 +1,5 @@
 /*
- * Copyright 2020-2024 Ryan Powell <[email protected]> and
+ * Copyright 2020-2025 Ryan Powell <[email protected]> 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 <[email protected]> and
+ * Copyright 2020-2025 Ryan Powell <[email protected]> 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 <[email protected]> and
+ * Copyright 2020-2025 Ryan Powell <[email protected]> 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 <[email protected]> and
+ * Copyright 2020-2025 Ryan Powell <[email protected]> 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 <[email protected]> and
+ * Copyright 2020-2025 Ryan Powell <[email protected]> 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 <[email protected]> and
+ * Copyright 2020-2025 Ryan Powell <[email protected]> and
  * esp-nimble-cpp, NimBLE-Arduino contributors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");