You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Is the ESP32-S3 cannot support adding random IP addresses from Android phones to the whitelist? #1108
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?
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.
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.
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.
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.
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?
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());
}
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...
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.
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.
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.
Activity
h2zero commentedon Mar 12, 2026
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.
onConnectcallback works the same here as on android, it doesn't know the state of bonding/authentication at this time. I suggest callingNimBLEDevice::startSecurityhere and waiting for theonAuthenticationCompletecallback.onIdentitycallback will be called which will provide the resolved ID address inNimBLEConnInfo::getIdAddressand this is what you need to use in the whitelist.LusterWong commentedon Mar 13, 2026
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.
LusterWong commentedon Mar 17, 2026
The following is the initialization code.
and the callback function,
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.
h2zero commentedon Mar 17, 2026
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":
Otherwise, if you want to use "just works" leave that line alone and change the last params in
setSecurityAuthto false:LusterWong commentedon Mar 19, 2026
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.
LusterWong commentedon Mar 19, 2026
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:
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...
h2zero commentedon Mar 19, 2026
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.
LusterWong commentedon Mar 20, 2026
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.
h2zero commentedon Mar 20, 2026
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.
h2zero commentedon Mar 20, 2026
I tested this with espidf v5.5.3 today and it works, just need to wait for the next arduino core relase.