Implement automatic pairing functionality

- Add new connection management methods that wrap BTstack callbacks
- Implement internal handlers that automatically trigger pairing when enabled
- Remove need for manual pairing requests in connection callbacks
- Update examples to use new callback registration methods
- Add comprehensive documentation with migration guide

This update makes requestPairingOnConnect() work automatically without requiring
manual checks of the flag or explicit pairing requests in user code.

Author: IoT-gamer

README.md

@@ -30,6 +30,7 @@ This library extends the functionality of the arduino-pico core's BTstack implem
   - Receive notifications for all pairing events
   - Display pairing codes
   - Confirm pairing with numeric comparison
+  - Automatic pairing management through connection callbacks
 
 ## Installation
 
@@ -81,6 +82,19 @@ lib_deps =
 #include <BTstackLib.h>
 #include <BLESecure.h>
 
+// Callbacks for BLE events
+void bleDeviceConnected(BLEStatus status, BLEDevice* device) {
+  if (status == BLE_STATUS_OK) {
+    Serial.println("Device connected!");
+    // No need to manually call BLESecure.requestPairing() here
+    // It's automatically handled if requestPairingOnConnect is enabled
+  }
+}
+
+void bleDeviceDisconnected(BLEDevice* device) {
+  Serial.println("Device disconnected!");
+}
+
 void setup() {
   Serial.begin(115200);
 
@@ -96,6 +110,10 @@ void setup() {
   // Request pairing automatically when a device connects
   BLESecure.requestPairingOnConnect(true);
 
+  // Register connection callbacks through BLESecure (not BTstack)
+  BLESecure.setBLEDeviceConnectedCallback(bleDeviceConnected);
+  BLESecure.setBLEDeviceDisconnectedCallback(bleDeviceDisconnected);
+  
   // Start advertising
   BTstack.startAdvertising();
 }
@@ -108,6 +126,18 @@ void loop() {
 }
 ```
 
+### Connection Management
+
+Register connection and disconnection callbacks through BLESecure instead of directly through BTstack:
+
+```cpp
+// Register callbacks through BLESecure for automatic pairing management
+BLESecure.setBLEDeviceConnectedCallback(bleDeviceConnected);
+BLESecure.setBLEDeviceDisconnectedCallback(bleDeviceDisconnected);
+```
+
+This allows the BLESecure library to automatically handle pairing requests based on your `requestPairingOnConnect` setting.
+
 ### Setting Up Security Level
 
 Choose the appropriate security level for your application:
@@ -170,6 +200,46 @@ void setup() {
 }
 ```
 
+## Migration Guide
+
+### Version 1.X to 2.X
+
+The 2.X version introduces a new way to handle connection events and automatic pairing. Here are the key changes:
+
+1. **Connection Callbacks**: Register connection and disconnection callbacks through BLESecure instead of BTstack:
+   ```cpp
+   // Old way:
+   BTstack.setBLEDeviceConnectedCallback(bleDeviceConnected);
+   BTstack.setBLEDeviceDisconnectedCallback(bleDeviceDisconnected);
+   
+   // New way:
+   BLESecure.setBLEDeviceConnectedCallback(bleDeviceConnected);
+   BLESecure.setBLEDeviceDisconnectedCallback(bleDeviceDisconnected);
+   ```
+
+2. **Automatic Pairing**: When `requestPairingOnConnect(true)` is set, pairing is now automatically initiated when a device connects. You no longer need to manually check the flag and call `requestPairing()` in your connection callback:
+   ```cpp
+   // Old way:
+   void bleDeviceConnected(BLEStatus status, BLEDevice* device) {
+     if (status == BLE_STATUS_OK) {
+       // Manually check and request pairing
+       if (BLESecure._requestPairingOnConnect) {
+         BLESecure.requestPairing(device);
+       }
+     }
+   }
+   
+   // New way:
+   void bleDeviceConnected(BLEStatus status, BLEDevice* device) {
+     if (status == BLE_STATUS_OK) {
+       // Pairing is automatically handled if enabled
+       // No manual check needed
+     }
+   }
+   ```
+
+These changes simplify the code required to implement secure BLE connections and ensure consistent behavior across applications.
+
 ## Examples
 
 The library includes several example platformIO projects demonstrating its usage:
@@ -210,12 +280,17 @@ The library includes several example platformIO projects demonstrating its usage
 
 #### Pairing Control
 
-- `void requestPairingOnConnect(bool enable)`: Request pairing when a device connects
+- `void requestPairingOnConnect(bool enable)`: Request pairing automatically when a device connects
 - `bool requestPairing(BLEDevice* device)`: Manually request pairing with a connected device
 - `bool bondWithDevice(BLEDevice* device)`: Bond with a device (store keys for reconnection)
 - `bool removeBonding(BLEDevice* device)`: Remove bonding information for a device
 - `void clearAllBondings()`: Remove all stored bonding information
 
+#### Connection Management
+
+- `void setBLEDeviceConnectedCallback(void (*callback)(BLEStatus status, BLEDevice* device))`: Register callback for device connection events
+- `void setBLEDeviceDisconnectedCallback(void (*callback)(BLEDevice* device))`: Register callback for device disconnection events
+
 #### Callback Registration
 
 - `void setPasskeyDisplayCallback(void (*callback)(uint32_t passkey))`: Callback for handling passkey display
@@ -248,5 +323,4 @@ When using this library, you must comply with the terms of both licenses.
 Contributions to improve the library are welcome! Please submit pull requests or open issues on the repository.
 
 ## Acknowledgements and Credits
-This library is based on the [BTstackLib](https://github.com/earlephilhower/arduino-pico/tree/master/libraries/BTstackLib) library for Arduino-Core and Raspberry Pi Pico. Special thanks to the BTstack developers for their work on BLE stack implementation and arduino-pico core maintainers.
-```
+This library is based on the [BTstackLib](https://github.com/earlephilhower/arduino-pico/tree/master/libraries/BTstackLib) library for Arduino-Core and Raspberry Pi Pico. Special thanks to the BTstack developers for their work on BLE stack implementation and arduino-pico core maintainers.

examples/SecurePairingHigh/src/main.cpp

@@ -25,20 +25,20 @@
 
  // Callbacks for BLE events
  void bleDeviceConnected(BLEStatus status, BLEDevice* device) {
-   if (status == BLE_STATUS_OK) {
-     Serial.println("Device connected!");
-     deviceConnected = true;
-     connectedDevice = device;
-     
-     // Manually request pairing
-     if (BLESecure._requestPairingOnConnect) {
-       BLESecure.requestPairing(device);
-     }
-   } else {
-     Serial.print("Connection failed with status: ");
-     Serial.println(status);
-   }
- }
+  if (status == BLE_STATUS_OK) {
+    Serial.println("Device connected!");
+    deviceConnected = true;
+    connectedDevice = device;
+    
+    // No need to manually check BLESecure._requestPairingOnConnect
+    // or call BLESecure.requestPairing() here
+    // The BLESecure library now handles this automatically
+    
+  } else {
+    Serial.print("Connection failed with status: ");
+    Serial.println(status);
+  }
+} 
 
  void bleDeviceDisconnected(BLEDevice* device) {
    Serial.println("Device disconnected!");
@@ -144,8 +144,9 @@
    BLESecure.setNumericComparisonCallback(onNumericComparison);
 
    // Register callbacks for BLE connection events
-   BTstack.setBLEDeviceConnectedCallback(bleDeviceConnected);
-   BTstack.setBLEDeviceDisconnectedCallback(bleDeviceDisconnected);
+   BLESecure.setBLEDeviceConnectedCallback(bleDeviceConnected);
+   BLESecure.setBLEDeviceDisconnectedCallback(bleDeviceDisconnected);
+
 
    // Register GATT write callback
    BTstack.setGATTCharacteristicWrite(gattWriteCallback);

examples/SecurePairingHighSC/src/main.cpp

@@ -29,24 +29,20 @@
 
  // Callbacks for BLE events
  void bleDeviceConnected(BLEStatus status, BLEDevice* device) {
-   if (status == BLE_STATUS_OK) {
-     Serial.println("Device connected!");
-     deviceConnected = true;
-     connectedDevice = device;
-     
-     // MTU exchange will happen automatically
-     Serial.println("MTU exchange will happen automatically through BTstack");
-     
-     // Manually request pairing
-     if (BLESecure._requestPairingOnConnect) {
-       Serial.println("Requesting secure pairing with Secure Connections...");
-       BLESecure.requestPairing(device);
-     }
-   } else {
-     Serial.print("Connection failed with status: ");
-     Serial.println(status);
-   }
- }
+  if (status == BLE_STATUS_OK) {
+    Serial.println("Device connected!");
+    deviceConnected = true;
+    connectedDevice = device;
+    
+    // No need to manually check BLESecure._requestPairingOnConnect
+    // or call BLESecure.requestPairing() here
+    // The BLESecure library now handles this automatically
+    
+  } else {
+    Serial.print("Connection failed with status: ");
+    Serial.println(status);
+  }
+} 
 
  void bleDeviceDisconnected(BLEDevice* device) {
    Serial.println("Device disconnected!");
@@ -183,8 +179,8 @@
    BLESecure.setNumericComparisonCallback(onNumericComparison);
 
    // Register callbacks for BLE connection events
-   BTstack.setBLEDeviceConnectedCallback(bleDeviceConnected);
-   BTstack.setBLEDeviceDisconnectedCallback(bleDeviceDisconnected);
+   BLESecure.setBLEDeviceConnectedCallback(bleDeviceConnected);
+   BLESecure.setBLEDeviceDisconnectedCallback(bleDeviceDisconnected);
 
    // Register GATT write callback
    BTstack.setGATTCharacteristicWrite(gattWriteCallback);

examples/SecurePairingMedium/src/main.cpp

@@ -25,21 +25,20 @@
 
  // Callbacks for BLE events
  void bleDeviceConnected(BLEStatus status, BLEDevice* device) {
-   if (status == BLE_STATUS_OK) {
-     Serial.println("Device connected!");
-     deviceConnected = true;
-     connectedDevice = device;
-     
-     // Manually request pairing if enabled
-     if (BLESecure._requestPairingOnConnect) {
-       Serial.println("Requesting secure pairing (MEDIUM - Just Works)...");
-       BLESecure.requestPairing(device);
-     }
-   } else {
-     Serial.print("Connection failed with status: ");
-     Serial.println(status);
-   }
- }
+  if (status == BLE_STATUS_OK) {
+    Serial.println("Device connected!");
+    deviceConnected = true;
+    connectedDevice = device;
+    
+    // No need to manually check BLESecure._requestPairingOnConnect
+    // or call BLESecure.requestPairing() here
+    // The BLESecure library now handles this automatically
+    
+  } else {
+    Serial.print("Connection failed with status: ");
+    Serial.println(status);
+  }
+} 
 
  void bleDeviceDisconnected(BLEDevice* device) {
    Serial.println("Device disconnected!");
@@ -129,8 +128,8 @@
    BLESecure.setPairingStatusCallback(onPairingStatus);
 
    // Register callbacks for BLE connection events
-   BTstack.setBLEDeviceConnectedCallback(bleDeviceConnected);
-   BTstack.setBLEDeviceDisconnectedCallback(bleDeviceDisconnected);
+   BLESecure.setBLEDeviceConnectedCallback(bleDeviceConnected);
+   BLESecure.setBLEDeviceDisconnectedCallback(bleDeviceDisconnected);
 
    // Register GATT write callback
    BTstack.setGATTCharacteristicWrite(gattWriteCallback);

include/BLESecure.h

@@ -95,6 +95,12 @@
      // Process security manager events - should be called from the main event handler
      void handleSMEvent(uint8_t packet_type, uint16_t channel, uint8_t* packet, uint16_t size);
 
+     // Method to register connection callback that also handles auto-pairing
+     void setBLEDeviceConnectedCallback(void (*callback)(BLEStatus status, BLEDevice* device));
+     
+     // Method to register disconnection callback
+     void setBLEDeviceDisconnectedCallback(void (*callback)(BLEDevice* device));
+     
      // Flag to indicate if pairing should be automatically requested on connect
      bool _requestPairingOnConnect;
 
@@ -112,11 +118,21 @@
      void (*_pairingStatusCallback)(BLEPairingStatus status, BLEDevice* device);
      void (*_numericComparisonCallback)(uint32_t passkey, BLEDevice* device);
 
+     // Connection and disconnection callbacks
+     void (*_userConnectedCallback)(BLEStatus status, BLEDevice* device);
+     void (*_userDisconnectedCallback)(BLEDevice* device);
+     
      // Store the current device handle for callbacks
      hci_con_handle_t _currentDeviceHandle;
 
      // Register for Security Manager events
      void setupSMEventHandler();
+     
+     // Internal connection callback that handles auto-pairing
+     static void internalConnectionCallback(BLEStatus status, BLEDevice* device);
+     
+     // Internal disconnection callback
+     static void internalDisconnectionCallback(BLEDevice* device);
  };
 
  extern BLESecureClass BLESecure;

library.json

@@ -1,6 +1,6 @@
 {
     "name": "pico-ble-secure",
-    "version": "1.0.1",
+    "version": "2.0.0",
     "description": "A library for implementing secure Bluetooth Low Energy (BLE) pairing and encryption on Raspberry Pi Pico using the arduino-pico core",
     "keywords": "bluetooth, BLE, security, pairing, encryption, Pico, arduino-pico, secure connections, MITM protection",
     "repository": {

src/BLESecure.cpp

@@ -27,6 +27,8 @@
      _passkeyEntryCallback(nullptr),
      _pairingStatusCallback(nullptr),
      _numericComparisonCallback(nullptr),
+     _userConnectedCallback(nullptr),
+     _userDisconnectedCallback(nullptr),
      _currentDeviceHandle(HCI_CON_HANDLE_INVALID),
      _bondingEnabled(true)
  {
@@ -104,9 +106,6 @@
 
  void BLESecureClass::requestPairingOnConnect(bool enable) {
      _requestPairingOnConnect = enable;
-     
-     // Note: We can't directly access BluetoothHCI's protected method setPairOnMeta
-     // The user will need to manually call requestPairing in the connection callback
  }
 
  bool BLESecureClass::requestPairing(BLEDevice* device) {
@@ -243,6 +242,45 @@
      sm_event_callback_registration.callback = SMEVENTCB(BLESecureClass, handleSMEvent);
      sm_add_event_handler(&sm_event_callback_registration);
  }
+
+ // New methods for connection/disconnection handling with auto-pairing
+ void BLESecureClass::setBLEDeviceConnectedCallback(void (*callback)(BLEStatus status, BLEDevice* device)) {
+     _userConnectedCallback = callback;
+     BTstack.setBLEDeviceConnectedCallback(internalConnectionCallback);
+ }
+
+ void BLESecureClass::setBLEDeviceDisconnectedCallback(void (*callback)(BLEDevice* device)) {
+     _userDisconnectedCallback = callback;
+     BTstack.setBLEDeviceDisconnectedCallback(internalDisconnectionCallback);
+ }
+
+ // Internal connection callback that handles auto-pairing
+ void BLESecureClass::internalConnectionCallback(BLEStatus status, BLEDevice* device) {
+     // Auto-request pairing if enabled
+     if (status == BLE_STATUS_OK && BLESecure._requestPairingOnConnect) {
+         Serial.println("Auto-requesting pairing as configured in BLESecure");
+         BLESecure.requestPairing(device);
+     }
+     
+     // Call the user's callback if registered
+     if (BLESecure._userConnectedCallback) {
+         BLESecure._userConnectedCallback(status, device);
+     }
+ }
+
+ // Internal disconnection callback
+ void BLESecureClass::internalDisconnectionCallback(BLEDevice* device) {
+     // Reset pairing status if this was the device we were pairing with
+     if (BLESecure._currentDeviceHandle == device->getHandle()) {
+         BLESecure._pairingStatus = PAIRING_IDLE;
+         BLESecure._currentDeviceHandle = HCI_CON_HANDLE_INVALID;
+     }
+     
+     // Call the user's callback if registered
+     if (BLESecure._userDisconnectedCallback) {
+         BLESecure._userDisconnectedCallback(device);
+     }
+ }
 
  void BLESecureClass::handleSMEvent(uint8_t packet_type, uint16_t channel, uint8_t* packet, uint16_t size) {
      (void)channel;