Skip to content

Is the ESP32-S3 cannot support adding random IP addresses from Android phones to the whitelist? #1108

Open

Description

@LusterWong

Thank you for providing such a powerful library.

I am currently using the ESP32-S3 as a GATT server. I need to limit the connection to a maximum of two specific clients to prevent unauthorized access. My current approach is as follows:

In the onAuthenticationComplete callback, I use NimBLEDevice::whiteListAdd(connInfo.getAddress()) to add the Android phone's address to the whitelist.

Once two phones have been bonded, I enable whitelist filtering for advertising.

The Problem:
After an Android phone disconnects and attempts to reconnect, it fails to establish a connection indefinitely. Does NimBLE support the resolution of Random Addresses?

I am using the latest library version v2.3.9. How can I properly restrict clients when they use Random Resolvable Addresses?

NimBLEDevice::whiteListAdd(connInfo.getAddress());
NimBLEDevice::whiteListAdd(connInfo.getIdAddress());
bool bonded = connInfo.isBonded();
int bonds = NimBLEDevice::getNumBonds();

if(bonds >= MAX_BONDS) {
      NimBLEAdvertising* pAdvertising = NimBLEDevice::getAdvertising();
      pAdvertising->stop();
      pAdvertising->setScanFilter(true, true);
      pAdvertising->start();
      return;
      }

Furthermore, if the whitelist function fails to work, I think it is also possible to determine in the onConnect callback function whether the device making this connection has been bound. Unfortunately, in the onConnect function, for Android phones, connInfo.isBonded() is always equal to false. Only in the onAuthenticationComplete callback function does connInfo.isBonded() have an effect, but the timing for the judgment has been missed.

Thanks.

Activity

  1. h2zero commented on Mar 12, 2026

    @h2zero
    Owner

    Hi @LusterWong, the S3 certainly can do this. I must apologize for the lack of documentation regarding the process as this is quite a common requirement without a simple solution.

    • The onConnect callback works the same here as on android, it doesn't know the state of bonding/authentication at this time. I suggest calling NimBLEDevice::startSecurity here and waiting for the onAuthenticationComplete callback.
    • Then check the bonded status there and handle it accordingly.
    • Next the onIdentity callback will be called which will provide the resolved ID address in NimBLEConnInfo::getIdAddress and this is what you need to use in the whitelist.
  2. LusterWong commented on Mar 13, 2026

    @LusterWong
    Author

    Hi @LusterWong, the S3 certainly can do this. I must apologize for the lack of documentation regarding the process as this is quite a common requirement without a simple solution.

    • The onConnect callback works the same here as on android, it doesn't know the state of bonding/authentication at this time. I suggest calling NimBLEDevice::startSecurity here and waiting for the onAuthenticationComplete callback.
    • Then check the bonded status there and handle it accordingly.
    • Next the onIdentity callback will be called which will provide the resolved ID address in NimBLEConnInfo::getIdAddress and this is what you need to use in the whitelist.

    Thanks for the reply. I previously tried using NimBLEDevice::whiteListAdd(connInfo.getAddress()); within the onAuthenticationComplete or onIdentity callbacks to whitelist the address. However, the Android phone would fail to reconnect after being disconnected for a while.

    I’ll try using NimBLEConnInfo::getIdAddress() as you suggested to see if that achieves the goal.

  3. LusterWong commented on Mar 17, 2026

    @LusterWong
    Author

    Hi @LusterWong, the S3 certainly can do this. I must apologize for the lack of documentation regarding the process as this is quite a common requirement without a simple solution.

    • The onConnect callback works the same here as on android, it doesn't know the state of bonding/authentication at this time. I suggest calling NimBLEDevice::startSecurity here and waiting for the onAuthenticationComplete callback.
    • Then check the bonded status there and handle it accordingly.
    • Next the onIdentity callback will be called which will provide the resolved ID address in NimBLEConnInfo::getIdAddress and this is what you need to use in the whitelist.

    The following is the initialization code.

    NimBLEDevice::init("Dev123");
    NimBLEDevice::setSecurityIOCap(BLE_HS_IO_NO_INPUT_OUTPUT); //use numeric comparison
    NimBLEDevice::setSecurityAuth(true, true, true);
    NimBLEDevice::setMTU(512);
    

    and the callback function,

    class ServerCallbacks : public NimBLEServerCallbacks {
        void onConnect(NimBLEServer* pServer, NimBLEConnInfo& connInfo) override {
            Serial.printf("Client address: %s\n", connInfo.getAddress().toString().c_str());
            NimBLEDevice::startSecurity(connInfo.getConnHandle());
            pServer->updateConnParams(connInfo.getConnHandle(), 24, 48, 0, 180);
        }
    
        void onDisconnect(NimBLEServer* pServer, NimBLEConnInfo& connInfo, int reason) override {
            Serial.printf("Client disconnected - start advertising\n");
            NimBLEDevice::startAdvertising();
        }
    
        void onMTUChange(uint16_t MTU, NimBLEConnInfo& connInfo) override {
            Serial.printf("MTU updated: %u for connection ID: %u\n", MTU, connInfo.getConnHandle());
        }
    
        /********************* Security handled here *********************/
        uint32_t onPassKeyDisplay() override {
            Serial.printf("Server Passkey Display\n");
            /**
             * This should return a random 6 digit number for security
             *  or make your own static passkey as done here.
             */
            return 123456;
        }
    
        void onConfirmPassKey(NimBLEConnInfo& connInfo, uint32_t pass_key) override {
            Serial.printf("The passkey YES/NO number: %" PRIu32 "\n", pass_key);
            /** Inject false if passkeys don't match. */
            NimBLEDevice::injectConfirmPasskey(connInfo, true);
        }
    
        void onAuthenticationComplete(NimBLEConnInfo& connInfo) override {
            /** Check that encryption was successful, if not we disconnect the client */
            if (!connInfo.isEncrypted()) {
                NimBLEDevice::getServer()->disconnect(connInfo.getConnHandle());
                Serial.printf("Encrypt connection failed - disconnecting client\n");
                // return;
            }
            NimBLEDevice::startAdvertising();
        }
    
        void onIdentity(NimBLEConnInfo& connInfo) override {
            int bonds = NimBLEDevice::getNumBonds();
            bool bonded = connInfo.isBonded();
    
            NimBLEAdvertising* pAdvertising = NimBLEDevice::getAdvertising();
            NimBLEDevice::whiteListAdd(connInfo.getIdAddress());
            pAdvertising->stop();
            pAdvertising->setScanFilter(true, true);
            pAdvertising->start();
            Serial.printf("onIdentity whiteListAdd\n");
        }
    } serverCallbacks;
    

    Modify the code according to the method you provided and conduct the test. I am using a SONY Android phone. After connecting the ESP32-S3 to the phone, it will prompt for pairing. After it prints "onIdentity whiteListAdd". The whitelist has been recorded. When attempting to connect the ESP32-S3 using another phone or PC after this, it prompts failure. However, when the SONY phone loses connection and reconnects, it will never succeed, as if it is being blocked by the whitelist. This problem has been bothering me for two weeks. Is there anything that was not done correctly?

    Thanks.

  4. h2zero commented on Mar 17, 2026

    @h2zero
    Owner

    Might be that android isn't sharing it's IRK, does bond show in the phone?

    Try changing the security setting, looks like you want to use numeric comparison but you have the IO set to "just works":

    NimBLEDevice::setSecurityIOCap(BLE_HS_IO_DISPLAY_YESNO); //use numeric comparison
    

    Otherwise, if you want to use "just works" leave that line alone and change the last params in setSecurityAuth to false:

    NimBLEDevice::setSecurityAuth(true, false, false);
    
  5. LusterWong commented on Mar 19, 2026

    @LusterWong
    Author

    Might be that android isn't sharing it's IRK, does bond show in the phone?

    Try changing the security setting, looks like you want to use numeric comparison but you have the IO set to "just works":

    NimBLEDevice::setSecurityIOCap(BLE_HS_IO_DISPLAY_YESNO); //use numeric comparison
    

    Otherwise, if you want to use "just works" leave that line alone and change the last params in setSecurityAuth to false:

    NimBLEDevice::setSecurityAuth(true, false, false);
    

    HI,

    I'll put the entire code here. I do need a simple "just works" type of pairing. setSecurityAuth(true, false, false); or setSecurityAuth(true, true, true); on SONY Android phone, there will be a pairing prompt. However, use setSecurityAuth(true, false, false); After adding the whitelist, there is a certain chance that the phone will reconnect and regain connectivity. However, it is not 100% guaranteed to succeed. Once it fails, it will never be able to reconnect. It worked fine during the continuous test for half an hour. But suddenly, when attempting a reconnection, it failed and I couldn't connect anymore.

    #include <arduino.h>
    #include"esp_mac.h"
    #include <NimBLEDevice.h>
    #include "common.h"
    
    
    static NimBLEServer* pServer;
    
    
    /**  None of these are required as they will be handled by the library with defaults. **
     **                       Remove as you see fit for your needs                        */
    class ServerCallbacks : public NimBLEServerCallbacks {
        void onConnect(NimBLEServer* pServer, NimBLEConnInfo& connInfo) override {
            Serial.printf("Client address: %s\n", connInfo.getAddress().toString().c_str());
            NimBLEDevice::startSecurity(connInfo.getConnHandle());
            pServer->updateConnParams(connInfo.getConnHandle(), 24, 48, 0, 180);
        }
    
        void onDisconnect(NimBLEServer* pServer, NimBLEConnInfo& connInfo, int reason) override {
            Serial.printf("Client disconnected - start advertising\n");
            NimBLEDevice::startAdvertising();
        }
    
        void onMTUChange(uint16_t MTU, NimBLEConnInfo& connInfo) override {
            Serial.printf("MTU updated: %u for connection ID: %u\n", MTU, connInfo.getConnHandle());
        }
    
        /********************* Security handled here *********************/
        uint32_t onPassKeyDisplay() override {
            Serial.printf("Server Passkey Display\n");
            /**
             * This should return a random 6 digit number for security
             *  or make your own static passkey as done here.
             */
            return 123456;
        }
    
        void onConfirmPassKey(NimBLEConnInfo& connInfo, uint32_t pass_key) override {
            Serial.printf("The passkey YES/NO number: %" PRIu32 "\n", pass_key);
            /** Inject false if passkeys don't match. */
            NimBLEDevice::injectConfirmPasskey(connInfo, true);
        }
    
        void onAuthenticationComplete(NimBLEConnInfo& connInfo) override {
            /** Check that encryption was successful, if not we disconnect the client */
            if (!connInfo.isEncrypted()) {
                NimBLEDevice::getServer()->disconnect(connInfo.getConnHandle());
                Serial.printf("Encrypt connection failed - disconnecting client\n");
                return;
            }
    		
    		Serial.printf("Secured connection to: %s\n", connInfo.getAddress().toString().c_str());
        }
    
        void onIdentity(NimBLEConnInfo& connInfo) override {
            int bonds = NimBLEDevice::getNumBonds();
            bool bonded = connInfo.isBonded();
    
            NimBLEAdvertising* pAdvertising = NimBLEDevice::getAdvertising();
            NimBLEDevice::whiteListAdd(connInfo.getIdAddress());
            pAdvertising->stop();
            pAdvertising->setScanFilter(true, true);
            pAdvertising->start();
            Serial.printf("onIdentity whiteListAdd\n");
        }
    } serverCallbacks;
    
    /** Handler class for characteristic actions */
    class CharacteristicCallbacks : public NimBLECharacteristicCallbacks {
        void onRead(NimBLECharacteristic* pCharacteristic, NimBLEConnInfo& connInfo) override {
            Serial.printf("%s : onRead(), value: %s\n",
                          pCharacteristic->getUUID().toString().c_str(),
                          pCharacteristic->getValue().c_str());
        }
    
        void onWrite(NimBLECharacteristic* pCharacteristic, NimBLEConnInfo& connInfo) override {
            Serial.printf("%s : onWrite(), value: %s\n",
                          pCharacteristic->getUUID().toString().c_str(),
                          pCharacteristic->getValue().c_str());
        }
    
        /**
         *  The value returned in code is the NimBLE host return code.
         */
        void onStatus(NimBLECharacteristic* pCharacteristic, int code) override {
            Serial.printf("Notification/Indication return code: %d, %s\n", code, NimBLEUtils::returnCodeToString(code));
        }
    
        /** Peer subscribed to notifications/indications */
        void onSubscribe(NimBLECharacteristic* pCharacteristic, NimBLEConnInfo& connInfo, uint16_t subValue) override {
            std::string str  = "Client ID: ";
            str             += connInfo.getConnHandle();
            str             += " Address: ";
            str             += connInfo.getAddress().toString();
            if (subValue == 0) {
                str += " Unsubscribed to ";
            } else if (subValue == 1) {
                str += " Subscribed to notifications for ";
            } else if (subValue == 2) {
                str += " Subscribed to indications for ";
            } else if (subValue == 3) {
                str += " Subscribed to notifications and indications for ";
            }
            str += std::string(pCharacteristic->getUUID());
    
            Serial.printf("%s\n", str.c_str());
        }
    } chrCallbacks;
    
    /** Handler class for descriptor actions */
    class DescriptorCallbacks : public NimBLEDescriptorCallbacks {
        void onWrite(NimBLEDescriptor* pDescriptor, NimBLEConnInfo& connInfo) override {
            std::string dscVal = pDescriptor->getValue();
            Serial.printf("Descriptor written value: %s\n", dscVal.c_str());
        }
    
        void onRead(NimBLEDescriptor* pDescriptor, NimBLEConnInfo& connInfo) override {
            Serial.printf("%s Descriptor read\n", pDescriptor->getUUID().toString().c_str());
        }
    } dscCallbacks;
    
    void BSPBLEGetMac(uint8_t* MAC)
    {
        esp_read_mac(MAC, ESP_MAC_BT);
    }
    
    void BSBLEInit(char* DevName)
    {
        /** Initialize NimBLE and set the device name */
        NimBLEDevice::init(DevName);
        NimBLEDevice::setSecurityIOCap(BLE_HS_IO_NO_INPUT_OUTPUT); //use numeric comparison
        NimBLEDevice::setSecurityAuth(true, false, false);
        NimBLEDevice::setMTU(512);
        //NimBLEDevice::deleteAllBonds();
    
        pServer = NimBLEDevice::createServer();
        pServer->setCallbacks(&serverCallbacks);
    
        NimBLEService*        pDeadService = pServer->createService("4a2d0001-7b1f-49b0-9c2d-9486770f1900");
        NimBLECharacteristic* pBeefCharacteristic =
            pDeadService->createCharacteristic("4a2d0002-7b1f-49b0-9c2d-9486770f1910",
                                               NIMBLE_PROPERTY::READ | NIMBLE_PROPERTY::WRITE | NIMBLE_PROPERTY::NOTIFY |
                                                   /** Require a secure connection for read and write access */
                                                   NIMBLE_PROPERTY::READ_ENC | // only allow reading if paired / encrypted
                                                   NIMBLE_PROPERTY::WRITE_ENC  // only allow writing if paired / encrypted
            );
    
        // pBeefCharacteristic->setValue("Burger");
        pBeefCharacteristic->setCallbacks(&chrCallbacks);
    
        /**
         *  2902 and 2904 descriptors are a special case, when createDescriptor is called with
         *  either of those uuid's it will create the associated class with the correct properties
         *  and sizes. However we must cast the returned reference to the correct type as the method
         *  only returns a pointer to the base NimBLEDescriptor class.
         */
        NimBLE2904* pBeef2904 = pBeefCharacteristic->create2904();
        pBeef2904->setFormat(NimBLE2904::FORMAT_UTF8);
        pBeef2904->setCallbacks(&dscCallbacks);
    
        pDeadService->start();
        // pBaadService->start();
    
        /** Create an advertising instance and add the services to the advertised data */
        NimBLEAdvertising* pAdvertising = NimBLEDevice::getAdvertising();
        pAdvertising->setName(DevName);
        pAdvertising->addServiceUUID(pDeadService->getUUID());
    
        pAdvertising->enableScanResponse(true);
        pAdvertising->start();
    
        Serial.printf("Bonded: %d\n", NimBLEDevice::getNumBonds());
    }
    
    
    
    
  6. LusterWong commented on Mar 19, 2026

    @LusterWong
    Author

    When the reconnection is successful, you can see the address change. It seems that the Android phone is using a dynamic address, and the log output would look something like this:

    Client ID: ␁ Address: 69:21:a5:21:91:03 Subscribed to notifications for 4a2d0002-7b1f-49b0-9c2d-9486770f1910␊
    Client address: 69:21:a5:21:91:03␊
    Client ID: ␁ Address: 69:21:a5:21:91:03 Unsubscribed to 4a2d0002-7b1f-49b0-9c2d-9486770f1910␊
    Client disconnected - start advertising␊
    Client ID: ␁ Address: 69:21:a5:21:91:03 Subscribed to notifications for 4a2d0002-7b1f-49b0-9c2d-9486770f1910␊
    Client address: 69:21:a5:21:91:03␊
    Client ID: ␁ Address: 69:21:a5:21:91:03 Unsubscribed to 4a2d0002-7b1f-49b0-9c2d-9486770f1910␊
    Client disconnected - start advertising␊
    Client ID: ␁ Address: 7c:fd:27:f2:36:d1 Subscribed to notifications for 4a2d0002-7b1f-49b0-9c2d-9486770f1910␊
    Client address: 7c:fd:27:f2:36:d1␊
    Client ID: ␁ Address: 7c:fd:27:f2:36:d1 Unsubscribed to 4a2d0002-7b1f-49b0-9c2d-9486770f1910␊
    Client disconnected - start advertising␊
    Client ID: ␁ Address: 7c:fd:27:f2:36:d1 Subscribed to notifications for 4a2d0002-7b1f-49b0-9c2d-9486770f1910␊
    Client address: 7c:fd:27:f2:36:d1␊
    

    It seems that the dynamic address resolution was successful. I don't understand why it fails to connect after just one reconnection attempt. I'm feeling confused...

  7. h2zero commented on Mar 19, 2026

    @h2zero
    Owner

    Thanks @LusterWong, the good news is I can reproduce this with your code, the bad news is it's a controller problem.
    The esp32 controller doesn't seem to be handling the whitelist correctly, whereas I tested the same code on and nRF52840 and it works as expected.

    There isn't anything we can do about this as the esp32 controller is closed source, so you will need to wait for the fix to come from the arduino core/esp-idf.

  8. LusterWong commented on Mar 20, 2026

    @LusterWong
    Author

    Thanks @LusterWong, the good news is I can reproduce this with your code, the bad news is it's a controller problem. The esp32 controller doesn't seem to be handling the whitelist correctly, whereas I tested the same code on and nRF52840 and it works as expected.

    There isn't anything we can do about this as the esp32 controller is closed source, so you will need to wait for the fix to come from the arduino core/esp-idf.

    I'm using ESP32-S3 not ESP32. After researching, it seems that ESP32-S3 supports whitelisting?
    Identifying the problem is a good start, but at the same time it's a hassle for me because the product is in the process of trial production and the hardware cannot be changed. Currently, we are using the Arduino 3.3.0 framework, and it's likely that IDF won't be updated either. Currently, there is no way to restrict the phone from connecting to BLE.

    Thank you.

  9. h2zero commented on Mar 20, 2026

    @h2zero
    Owner

    By esp32 I was short handing for your chip, I performed my testing on an esp32s3. Yes it does support whitelisting and handles the address resolution in the controller, unlike the original esp32, which is what you need. However their controller code is bugged, try arduino core 3.3.7?

    A workaround is to just disconnect anything that isn't in the whitelist, not ideal but works.

  10. h2zero commented on Mar 20, 2026

    @h2zero
    Owner

    I tested this with espidf v5.5.3 today and it works, just need to wait for the next arduino core relase.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions