How to Use BLE with ESP32: Simple Guide and Example

To use BLE with ESP32, initialize the BLE device, create a server, define services and characteristics, then start advertising. Use the ESP32 BLE Arduino library to handle BLE functions easily in your code.

Syntax

Using BLE on ESP32 involves these main steps:

• Initialize BLE device: Set device name and start BLE.
• Create BLE server: This handles connections.
• Create BLE service: Group related characteristics.
• Create BLE characteristic: Data points to read/write.
• Start advertising: Make device discoverable.

cpp

BLEDevice::init("ESP32_BLE_Device");
BLEServer *pServer = BLEDevice::createServer();
BLEService *pService = pServer->createService(SERVICE_UUID);
BLECharacteristic *pCharacteristic = pService->createCharacteristic(
    CHARACTERISTIC_UUID,
    BLECharacteristic::PROPERTY_READ | BLECharacteristic::PROPERTY_WRITE
);
pService->start();
BLEAdvertising *pAdvertising = BLEDevice::getAdvertising();
pAdvertising->addServiceUUID(SERVICE_UUID);
pAdvertising->start();

Example

This example shows a simple BLE server on ESP32 that advertises a service with one characteristic. The characteristic can be read and written by a BLE client.

cpp

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

#define SERVICE_UUID        "12345678-1234-1234-1234-123456789abc"
#define CHARACTERISTIC_UUID "abcd1234-5678-90ab-cdef-1234567890ab"

BLECharacteristic *pCharacteristic;

void setup() {
  Serial.begin(115200);
  BLEDevice::init("ESP32_BLE_Device");
  BLEServer *pServer = BLEDevice::createServer();
  BLEService *pService = pServer->createService(SERVICE_UUID);

  pCharacteristic = pService->createCharacteristic(
                      CHARACTERISTIC_UUID,
                      BLECharacteristic::PROPERTY_READ |
                      BLECharacteristic::PROPERTY_WRITE
                    );

  pCharacteristic->setValue("Hello BLE");
  pService->start();

  BLEAdvertising *pAdvertising = BLEDevice::getAdvertising();
  pAdvertising->addServiceUUID(SERVICE_UUID);
  pAdvertising->start();

  Serial.println("BLE server started and advertising");
}

void loop() {
  // put your main code here, to run repeatedly:
  delay(2000);
  std::string value = pCharacteristic->getValue();
  Serial.print("Characteristic value: ");
  Serial.println(value.c_str());
}

Output

BLE server started and advertising
Characteristic value: Hello BLE
Characteristic value: Hello BLE
...

Common Pitfalls

Common mistakes when using BLE with ESP32 include:

• Not initializing BLEDevice before creating server.
• Forgetting to start the service or advertising.
• Using incorrect UUID formats (must be 128-bit strings).
• Not setting characteristic properties properly (read/write).
• Not handling BLE events or callbacks for connection management.

Always check serial output for errors and ensure BLE client supports the service UUID.

cpp

/* Wrong: Missing BLEDevice::init() */
BLEServer *pServer = BLEDevice::createServer(); // This will fail

/* Right: Initialize first */
BLEDevice::init("ESP32_BLE_Device");
BLEServer *pServer = BLEDevice::createServer();

Quick Reference

BLE with ESP32 quick tips:

• Use BLEDevice::init() once at start.
• Define unique 128-bit UUIDs for services and characteristics.
• Set characteristic properties to control read/write permissions.
• Start service and advertising to make device visible.
• Use serial prints to debug BLE state and values.

Key Takeaways

Always initialize BLEDevice before creating servers or services.

Use unique 128-bit UUIDs for BLE services and characteristics.

Start both the BLE service and advertising to enable discovery.

Set characteristic properties correctly for intended read/write access.

Check serial output to debug BLE connection and data issues.