Step 1: Build a BLE beacon scanner

Step 1: Build a BLE beacon scanner

animation
bluetooth
ble
Try In the BLE Scanner Wokwi Simulator, paste the ESP32 scanner sketch into the editor, click Play, and open Serial Monitor with the terminal icon.
Observe In Serial Monitor, look for the 5-second scan summary and, if devices are reported, their names, addresses, RSSI and rough proximity zones.
Explain The sketch assigns proximity zones using RSSI cutoffs of -50, -70 and -90 dBm, then clears the scan results and waits 2000 ms before scanning again.

Technical boundaries. This page assumes an ESP32 running the shown BLE scanner sketch in the embedded Wokwi simulator. The sketch defines scan timing and rough RSSI zones; the page supplies no simulated BLE advertisers or radio environment, and the zones are not measured distances.

Step 1: Build a BLE beacon scanner

Advertising made BLE discoverable in the mental model. The first build step is therefore a scanner: the ESP32 is configured as a BLE Central device, listens for nearby advertisements, parses BLE advertisement data, and extracts the device name, address, RSSI, and a rough proximity zone. This nearby-device scanning is signal-strength proximity analysis in miniature, and it lets you see that BLE is not magic; it is a stream of short radio messages with measurable signal strength.

TipHow to Use the Simulator

Open the ESP32 starter at Wokwi ESP32 starter if the embedded Wokwi simulator is slow to load. In the simulator below, click inside the code editor, replace the default code with the BLE scanner code, click the green Play button to compile and run, and open the Serial Monitor with the terminal icon to see scan results.

Here is the complete scanner. The important path is BLEDevice::init(), then BLEDevice::getScan(), then a callback that runs for each BLEAdvertisedDevice.

#include <BLEDevice.h>
#include <BLEScan.h>
#include <BLEAdvertisedDevice.h>

BLEScan* pBLEScan;

// Callback: runs for each discovered BLE device
class ScanCallbacks : public BLEAdvertisedDeviceCallbacks {
    void onResult(BLEAdvertisedDevice dev) {
      int rssi = dev.getRSSI();
      const char* proximity = rssi >= -50 ? "IMMEDIATE (<1m)"
                            : rssi >= -70 ? "NEAR (1-3m)"
                            : rssi >= -90 ? "FAR (3-10m)"
                            :               "VERY FAR (>10m)";

      Serial.printf("Device: %s | Addr: %s | RSSI: %d dBm | %s\n",
        dev.getName().c_str(),
        dev.getAddress().toString().c_str(),
        rssi, proximity);
    }
};

void setup() {
  Serial.begin(115200);
  BLEDevice::init("ESP32-Scanner");
  pBLEScan = BLEDevice::getScan();
  pBLEScan->setAdvertisedDeviceCallbacks(new ScanCallbacks());
  pBLEScan->setActiveScan(true);  // Request scan response data
  pBLEScan->setInterval(100);
  pBLEScan->setWindow(99);        // Nearly continuous scanning
}

void loop() {
  BLEScanResults found = pBLEScan->start(5, false); // 5-second scan
  Serial.printf("Scan complete: %d device(s)\n\n", found.getCount());
  pBLEScan->clearResults();
  delay(2000);
}

The setup begins by naming the scanner and creating the scan object.

BLEDevice::init("ESP32-Scanner");
pBLEScan = BLEDevice::getScan();

Active scanning asks advertisers for scan response data, while the interval and window decide how often and how long the ESP32 listens.

pBLEScan->setActiveScan(true);   // Request scan response data
pBLEScan->setInterval(100);       // Time between scan windows
pBLEScan->setWindow(99);          // Duration of each listening window

The scanner converts RSSI into coarse zones. Those names are deliberately rough: they are useful for “near enough” logic, not tape-measure distance.

if (rssi >= -50) proximity = "IMMEDIATE (<1m)";
else if (rssi >= -70) proximity = "NEAR (1-3m)";
else if (rssi >= -90) proximity = "FAR (3-10m)";
else proximity = "VERY FAR (>10m)";
WarningRSSI Limitations

RSSI-based distance estimation is approximate. Signal strength is affected by obstacles such as walls, furniture, and people; by device orientation and antenna design; by interference from other 2.4 GHz devices; and by environmental factors such as humidity and reflective surfaces.

Back to the chapter