ESP32 BLE server

I wanted to try out the BLE capabilities of the ESP32. I will not go into deep explanations how BLE works. Adafruit has a nice tutorial that explains details. To learn about BLE, check out the Introduction to Bluetooth Low Energy. As I have temperature and humidity sensors attached the logical step would be to set it up as an environment sensor. I checked the Bluetooth GATT services to find out if there is something matching defined. And there is already a matching service, the Environmental Sensing. There are many characteristics defined for this service, to keep it simple I chose to implement only the following:

Just for fun I added to the list

Date Time – gives the current date and time and is used as well as notification for the client that updated data is available
Digital Output – to simulate a virtual keypad on the BLE client and trigger functions in the ESP32
Device Name – the name of the BLE server device
Two String – to transmit the comfort ratio and the perception

Now using BLE on the ESP32 has been made quite easy by nkolban who put together the ESP32 BLE for Arduino library. The library is already included in the ESP32 Arduino framework, so there is no need to install it separate.

To use the library, we first need to include the header files

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

#include <BLEDevice.h>

#include <BLEUtils.h>

#include <BLEServer.h>

#include <BLE2902.h>

#include <BLEAdvertising.h>

Then we define the UUIDs for the service and the characteristics

// List of Service and Characteristic UUIDs
#define SERVICE_UUID        0x181A
#define NOTIFICATION_UUID   0x2A08
#define TEMP_UUID           0x2A6E
#define HUMID_UUID          0x2A6F
#define HEAT_UUID           0x2A7A
#define DEW_UUID            0x2A7B
#define COMFORT_UUID        "00002A3D-ead2-11e7-80c1-9a214cf093ae" // same as String characteristic 0x2A3D
#define PERCEPTION_UUID     "10002A3D-ead2-11e7-80c1-9a214cf093ae" //	same as String characteristic 0x2A3D
#define OUTPUT_UUID         0x2A57
#define DEVICENAME_UUID     0x2A00

// List of Service and Characteristic UUIDs

#define SERVICE_UUID 0x181A

#define NOTIFICATION_UUID 0x2A08

#define TEMP_UUID 0x2A6E

#define HUMID_UUID 0x2A6F

#define HEAT_UUID 0x2A7A

#define DEW_UUID 0x2A7B

#define COMFORT_UUID "00002A3D-ead2-11e7-80c1-9a214cf093ae" // same as String characteristic 0x2A3D

#define PERCEPTION_UUID "10002A3D-ead2-11e7-80c1-9a214cf093ae" // same as String characteristic 0x2A3D

#define OUTPUT_UUID 0x2A57

#define DEVICENAME_UUID 0x2A00

Next is the pointers to the service class, the characteristic classes and the advertising class. In addition some flags and a global variable was defined for handling the BLE communications

/** Characteristic for client notification */
BLECharacteristic *pCharacteristicNotify;
/** Characteristic for temperature in celsius */
BLECharacteristic *pCharacteristicTemp;
/** Characteristic for humidity in percent */
BLECharacteristic *pCharacteristicHumid;
/** Characteristic for heat index in celsius */
BLECharacteristic *pCharacteristicHeatIndex;
/** Characteristic for dew point in celsius */
BLECharacteristic *pCharacteristicDewPoint;
/** Characteristic for environment comfort status */
BLECharacteristic *pCharacteristicComfort;
/** Characteristic for environment perception status */
BLECharacteristic *pCharacteristicPerception;
/** Characteristic for digital output */
BLECharacteristic *pCharacteristicOutput;
/** Characteristic for device name */
BLECharacteristic *pCharacteristicDeviceName;

/** BLE Advertiser */
BLEAdvertising* pAdvertising;
/** BLE Service */
BLEService *pService;
/** BLE Server */
BLEServer *pServer;

/** Digital output value received from the client */
uint8_t digitalOut = 0;
/** Flag for change in digital output value */
bool digOutChanged = false;

/** Characteristic for client notification */

BLECharacteristic *pCharacteristicNotify;

/** Characteristic for temperature in celsius */

BLECharacteristic *pCharacteristicTemp;

/** Characteristic for humidity in percent */

BLECharacteristic *pCharacteristicHumid;

/** Characteristic for heat index in celsius */

BLECharacteristic *pCharacteristicHeatIndex;

/** Characteristic for dew point in celsius */

BLECharacteristic *pCharacteristicDewPoint;

/** Characteristic for environment comfort status */

BLECharacteristic *pCharacteristicComfort;

/** Characteristic for environment perception status */

BLECharacteristic *pCharacteristicPerception;

/** Characteristic for digital output */

BLECharacteristic *pCharacteristicOutput;

/** Characteristic for device name */

BLECharacteristic *pCharacteristicDeviceName;

/** BLE Advertiser */

BLEAdvertising* pAdvertising;

/** BLE Service */

BLEService *pService;

/** BLE Server */

BLEServer *pServer;

/** Digital output value received from the client */

uint8_t digitalOut = 0;

/** Flag for change in digital output value */

bool digOutChanged = false;

The BLE library works with callbacks for BLE events. The first callback needed is for client connection and disconnection. Here we set as well a flag to see if any BLE client is connected.

/**
 * MyServerCallbacks
 * Callbacks for client connection and disconnection
 */
class MyServerCallbacks: public BLEServerCallbacks {
  void onConnect(BLEServer* pServer) {
    bleConnected = true;
  };
  void onDisconnect(BLEServer* pServer) {
    if (pServer->getConnectedCount() == 0) {
      bleConnected = false;
    }
  }
};

/**

* MyServerCallbacks

* Callbacks for client connection and disconnection

class MyServerCallbacks: public BLEServerCallbacks {

void onConnect(BLEServer* pServer) {

bleConnected = true;

};

void onDisconnect(BLEServer* pServer) {

if (pServer->getConnectedCount() == 0) {

bleConnected = false;

}

};

Next callback is for client write requests. As we have defined a characteristic Digital Output, the client might write values to this characteristic. If this happens, this callback is called.

/**
 * MyCallbackHandler
 * Callbacks for client write requests
 */
class MyCallbackHandler: public BLECharacteristicCallbacks {
  void onWrite(BLECharacteristic *pCharacteristic) {
    std::string value = pCharacteristic->getValue();
    if (value.length() > 0) {
      // save the value for later use
      digitalOut = (uint8_t) value[0];
      // set the flag that the value has changed
      digOutChanged = true;
    }
  }
};

/**

* MyCallbackHandler

* Callbacks for client write requests

class MyCallbackHandler: public BLECharacteristicCallbacks {

void onWrite(BLECharacteristic *pCharacteristic) {

std::string value = pCharacteristic->getValue();

if (value.length() > 0) {

// save the value for later use

digitalOut = (uint8_t) value[0];

// set the flag that the value has changed

digOutChanged = true;

}

};

Now we can initialize the BLE server, create a server and attach the callbacks.

/**
 * initBLEserver
 * Setup BLE server
 * Setup callbacks for server and pCharacteristicStatus
 * Start advertising the BLE service
 */
void initBLEserver() {

  // Initialize BLE
  BLEDevice::init(apName);

  // Create BLE Server
  pServer = BLEDevice::createServer();

  // Set server callbacks
  pServer->setCallbacks(new MyServerCallbacks());

  // Create BLE Service
  pService = pServer->createService(BLEUUID((uint16_t)SERVICE_UUID),20);

/**

* initBLEserver

* Setup BLE server

* Setup callbacks for server and pCharacteristicStatus

* Start advertising the BLE service

void initBLEserver() {

// Initialize BLE

BLEDevice::init(apName);

// Create BLE Server

pServer = BLEDevice::createServer();

// Set server callbacks

pServer->setCallbacks(new MyServerCallbacks());

// Create BLE Service

pService = pServer->createService(BLEUUID((uint16_t)SERVICE_UUID),20);

Next we create the characteristic for Date time. This characteristic is different from the other ones, because it has an additional descriptor which required if the client should be notified if data has been updated.

  // Create BLE Characteristic for Alert
  pCharacteristicNotify = pService->createCharacteristic(
    BLEUUID((uint16_t)NOTIFICATION_UUID),
    BLECharacteristic::PROPERTY_READ	 |
    BLECharacteristic::PROPERTY_NOTIFY
  );

  // Create a BLE Descriptor for Alert
  pCharacteristicNotify->addDescriptor(new BLE2902());

// Create BLE Characteristic for Alert

pCharacteristicNotify = pService->createCharacteristic(

BLEUUID((uint16_t)NOTIFICATION_UUID),

BLECharacteristic::PROPERTY_READ |

BLECharacteristic::PROPERTY_NOTIFY

);

// Create a BLE Descriptor for Alert

pCharacteristicNotify->addDescriptor(new BLE2902());

The other characteristics are created similar, but the do not have PROPERTY_NOTIFY set and no descriptor attached. All these characteristics are read only. That is indicated by PROPERTY_READ

  // Create BLE Characteristic for Temperature
  pCharacteristicTemp = pService->createCharacteristic(
    BLEUUID((uint16_t)TEMP_UUID),
    BLECharacteristic::PROPERTY_READ
  );

  // Create BLE Characteristic for Humidity
  pCharacteristicHumid = pService->createCharacteristic(
    BLEUUID((uint16_t)HUMID_UUID),
    BLECharacteristic::PROPERTY_READ
  );

  // Create BLE Characteristic for Dew Point
  pCharacteristicDewPoint = pService->createCharacteristic(
    BLEUUID((uint16_t)DEW_UUID),
    BLECharacteristic::PROPERTY_READ
  );

  // Create BLE Characteristic for Perception
  pCharacteristicPerception = pService->createCharacteristic(
    PERCEPTION_UUID,
    BLECharacteristic::PROPERTY_READ
  );

  // Create BLE Characteristic for Comfort
  pCharacteristicComfort = pService->createCharacteristic(
    COMFORT_UUID,
    BLECharacteristic::PROPERTY_READ
  );

  // Create BLE Characteristic for Heat Index
  pCharacteristicHeatIndex = pService->createCharacteristic(
    BLEUUID((uint16_t)HEAT_UUID),
    BLECharacteristic::PROPERTY_READ
  );

  // Create BLE Characteristic for Device Name
  pCharacteristicDeviceName = pService->createCharacteristic(
    BLEUUID((uint16_t)DEVICENAME_UUID),
    BLECharacteristic::PROPERTY_READ
  );
  pCharacteristicDeviceName->setValue((uint8_t*)apName,16);

// Create BLE Characteristic for Temperature

pCharacteristicTemp = pService->createCharacteristic(

BLEUUID((uint16_t)TEMP_UUID),