16 BLE App Development on ESP32

16.3.1 Roles: who talks first

The device that advertises is the peripheral. In our build, the ESP32 becomes a peripheral when it behaves like a temperature sensor or an iBeacon, and in connected GATT examples it is also the server. The device that scans or connects is the central. A phone is usually the central because it has the screen, the app, and the power budget to search for nearby devices, and in connected GATT examples it usually behaves as the client.

The scanner lab reverses the view on purpose. First, the ESP32 acts as a central so you can see the radio world around you. Then, after the scan output makes advertising concrete, the ESP32 becomes the thing your phone can discover.

One source-era Classic Bluetooth remote-control design makes the connected roles concrete without pretending that its socket API is GATT. The remote sends command messages through a BluetoothSocket. The receiver listens with a BluetoothServerSocket, accepts a BluetoothSocket, parses each message, and dispatches the result to a GpioProcessor that owns the hardware action. Keep those boundaries separate in any implementation: transport moves bytes, parsing turns bytes into a command, and the GPIO layer decides how that command reaches a pin. A successful socket connection is therefore not proof that the actuator path is correct.

16.3.2 GATT: folders, files, and values

GATT is BLE’s way to organize connected data. Think of a service as a folder and a characteristic as a file in that folder. A temperature sensor might have an Environmental Sensing service, and inside it a Temperature characteristic. The value in that characteristic is the live reading.

The properties on a characteristic say what a central may do. READ means the phone can ask for the current value. NOTIFY means the ESP32 can push an update after the phone opts in. That opt-in matters: BLE notifications are not automatic just because the characteristic advertises the NOTIFY property.

16.3.3 What this chapter promises

By the end of this chapter you will be able to:

Work through What this chapter promises as a connected sequence. Start with implement BLE scanning and advertising on ESP32 with the Arduino BLE library. Next, configure GATT services and characteristics with the right properties and descriptors. Then, build iBeacon transmitters with correct manufacturer data and calibrated signal power (the trilateration build continues in Indoor Positioning with BLE Beacons). Then, diagnose the classic failures: MTU mismatches, missing CCCD descriptors, and connection-parameter surprises. Finally, estimate BLE range with the path-loss exponent formula.

With the mental model in place, the next section turns it into code. We start by listening before we transmit, because the fastest way to understand BLE advertising is to watch real advertisements arrive.

16.4.1 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.

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)";

Checkpoint: you should now see scan results in the Serial Monitor. Each line should include a device name if one was advertised, an address, an RSSI value in dBm, and a proximity label such as NEAR or FAR.

16.4.2 Step 2: Give the phone something to read

Advertising made the device discoverable; now inspect Figure 16.2 to decide how the phone will find and interpret the actual sensor value. The hierarchy matters because a characteristic only has application meaning inside an agreed service, UUID, encoding, properties, and access policy.

Read Figure 16.2 from the GATT server into its services and then down to characteristics. For this build, the phone discovers Environmental Sensing service 0x181A, then Temperature characteristic 0x2A6E, whose properties and encoding define what the client can read or subscribe to. That ordered discovery connects the scanner exercise to the code below: the ESP32 becomes ESP32-TempSensor, but interoperability comes from the standard service contract rather than the device name.

#include <BLEDevice.h>
#include <BLEServer.h>
#include <BLE2902.h>

#define SERVICE_UUID   "181A"  // Environmental Sensing (standard)
#define TEMP_CHAR_UUID "2A6E"  // Temperature (standard)

BLECharacteristic* pTempChar = NULL;
bool deviceConnected = false;
float temperature = 22.5;

class ServerCB : public BLEServerCallbacks {
  void onConnect(BLEServer* s)    { deviceConnected = true; }
  void onDisconnect(BLEServer* s) {
    deviceConnected = false;
    s->getAdvertising()->start(); // Resume advertising
  }
};

void setup() {
  Serial.begin(115200);
  BLEDevice::init("ESP32-TempSensor");
  BLEServer* pServer = BLEDevice::createServer();
  pServer->setCallbacks(new ServerCB());

  BLEService* pSvc = pServer->createService(SERVICE_UUID);
  pTempChar = pSvc->createCharacteristic(TEMP_CHAR_UUID,
      BLECharacteristic::PROPERTY_READ |
      BLECharacteristic::PROPERTY_NOTIFY);
  pTempChar->addDescriptor(new BLE2902()); // CCCD for notifications
  pSvc->start();

  BLEDevice::getAdvertising()->addServiceUUID(SERVICE_UUID);
  BLEDevice::getAdvertising()->start();
}

void loop() {
  if (deviceConnected) {
    temperature += random(-10, 11) / 100.0;
    int16_t val = (int16_t)(temperature * 100); // 0.01 C resolution
    pTempChar->setValue((uint8_t*)&val, 2);
    pTempChar->notify();
  }
  delay(1000);
}

The service UUID 181A tells generic BLE tools that this is Environmental Sensing data. The characteristic UUID 2A6E says the value is temperature. Standard services improve interoperability with generic tools and gateways, while vendor-specific UUIDs still work for private services when you document them clearly; the Bluetooth SIG database matters for shared meaning, not for whether packets can move. PROPERTY_READ supports polling, while PROPERTY_NOTIFY supports real-time updates after the client enables notifications. The BLE2902 descriptor is the Client Characteristic Configuration Descriptor, or CCCD, that gives the client a place to write that opt-in. The temperature is packed as an int16_t in 0.01 C units, so 22.50 C travels as 2250.

Checkpoint: you should now be able to discover ESP32-TempSensor, find service 0x181A, read characteristic 0x2A6E, and receive changing notifications once the client writes the CCCD.

16.4.3 Step 3: Turn advertisements into beacons

Inspect Figure 16.3 before filling the beacon API so every byte has an explicit identity or calibration purpose. Unlike the connected GATT example, receivers must interpret this advertisement without negotiating a service contract.

Read Figure 16.3 from Apple’s company identifier and the iBeacon type and length bytes into the 16-byte UUID, then Major and Minor, and finally the calibrated TX Power byte. UUID identifies the deployment namespace, Major and Minor subdivide it, and TX Power supports a rough RSSI-based distance estimate. This layout connects the connected sensor build to a connectionless pattern: the phone can classify nearby beacons, but payload meaning, calibration, privacy, and authenticity must be designed in advance.

#include <BLEDevice.h>
#include <BLEBeacon.h>

#define BEACON_UUID  "FDA50693-A4E2-4FB1-AFCF-C6EB07647825"
#define BEACON_MAJOR 1     // Store/building number
#define BEACON_MINOR 101   // Specific beacon ID

void setup() {
  Serial.begin(115200);
  BLEDevice::init("iBeacon");
  BLEDevice::createServer();

  BLEBeacon beacon;
  beacon.setManufacturerId(0x4C00);  // Apple's company ID
  beacon.setProximityUUID(BLEUUID(BEACON_UUID));
  beacon.setMajor(BEACON_MAJOR);
  beacon.setMinor(BEACON_MINOR);
  beacon.setSignalPower(-59);  // Calibrated RSSI at 1 m

  BLEAdvertisementData advData;
  advData.setFlags(0x04);  // BR_EDR_NOT_SUPPORTED
  advData.setManufacturerData(beacon.getData());

  BLEAdvertising* pAdv = BLEDevice::getAdvertising();
  pAdv->setAdvertisementData(advData);
  pAdv->start();
}

void loop() { delay(1000); }

The manufacturer ID 0x4C00 marks Apple’s company ID. The UUID identifies the beacon group, major can represent a store or building, and minor can represent a specific beacon. setSignalPower(-59) stores the calibrated RSSI at 1 meter, which receivers use as the reference point for distance estimation.

The distance estimate comes from the path loss formula:

$d = 10^{\frac{TxPower - RSSI}{10 \times n}}$

TxPower is the RSSI measured at 1 meter, typically around -59 to -65 dBm for iBeacon work. n is the path loss exponent: about 2.0 in free space and often 2.5 to 4.0 indoors. RSSI is the measured signal strength at the receiver.

float calculateDistance(int rssi, int txPower = -59, float n = 2.5) {
  if (rssi == 0) return -1.0;
  float ratio = (txPower - rssi) / (10.0 * n);
  return pow(10, ratio);
}

Curious how those numbers behave in a real room? The worked example below runs two actual measurements through the formula — open it to see why exact distances wobble and why the zone labels are the trustworthy part. It is optional: the build works without it.

Checkpoint: you should now have an ESP32 that broadcasts an iBeacon frame. A scanner should be able to see the UUID, major value, minor value, and calibrated signal power, then estimate distance from RSSI with visible uncertainty.

16.4.4 Step 4: Make the build your own

After the scanner, temperature service, and beacon all work, the next useful move is practice. These challenges keep the same code path but ask you to change one design decision at a time.

if (rssi < -80) return;  // Skip weak signals

String knownDevices[] = {"a4:c1:38:12:34:56", "b8:27:eb:aa:bb:cc"};
// Check if address matches known devices

Checkpoint: you should now be able to point to the exact line you changed, describe the BLE behavior it affects, and predict what should appear differently in the Serial Monitor or phone scanner.

16.4.5 Build Checks

Quick self-tests for what you just built. The multiple-choice questions check the essentials; the matching, sequencing, labeling, and code checks after them push the same ideas further — each one earns XP.

16.6.1 What’s Next

Bluetooth implementation quality depends on the event lifecycle: advertise, connect, discover services, exchange data, handle errors, and recover after disconnects. Treat each state as testable behavior. Before you call the build production-ready, expand the review checks below — they test exactly these lifecycle states.