ESP32 BLE Server and Client (Bluetooth Low Energy)

Learn how to make a BLE (Bluetooth Low Energy) connection between two ESP32 boards. One ESP32 is going to be the server, and the other ESP32 will be the client. The BLE server advertises characteristics that contain sensor readings that the client can read. The ESP32 BLE client reads the values of those characteristics (temperature and humidity) and displays them on an OLED display.
Recommended Reading:
Getting Started with ESP32 Bluetooth Low Energy (BLE)
What is Bluetooth Low Energy?
Before going straight to the project, it is important to take a quick look at some essential BLE concepts so that you’re able to better understand the project later on. If you’re already familiar with BLE, you can skip to the
Project Overview
section.
Bluetooth Low Energy, BLE for short, is a power-conserving variant of Bluetooth. BLE’s primary application is short-distance transmission of small amounts of data (low bandwidth). Unlike Bluetooth that is always on, BLE remains in sleep mode constantly except for when a connection is initiated.
This makes it consume very low power. BLE consumes approximately 100x less power than Bluetooth (depending on the use case). You can
check the main differences between Bluetooth and Bluetooth Low Energy here
BLE Server and Client
With Bluetooth Low Energy, there are two types of devices: the server and the client. The ESP32 can act either as a client or as a server.
The server advertises its existence, so it can be found by other devices and contains data that the client can read. The client scans the nearby devices, and when it finds the server it is looking for, it establishes a connection and listens for incoming data. This is called point-to-point communication.
There are other possible communication modes like broadcast mode and mesh network (not covered in this tutorial).
GATT
GATT stands for Generic Attributes and it defines a hierarchical data structure that is exposed to connected BLE devices. This means that GATT defines the way that two BLE devices send and receive standard messages. Understanding this hierarchy is important because it will make it easier to understand how to use BLE with the ESP32.
Profile
: standard collection of services for a specific use case;
Service
: collection of related information, like sensor readings, battery level, heart rate, etc. ;
Characteristic
: it is where the actual data is saved on the hierarchy (
value
);
Descriptor
: metadata about the data;
Properties
: describe how the characteristic value can be interacted with. For example: read, write, notify, broadcast, indicate, etc.
In our example, we’ll create a service with two
characteristics
. One for the temperature and another for the humidity. The actual temperature and humidity readings are saved on the
value
under their
characteristics
. Each characteristic has the
notify
property, so that it notifies the client whenever the values change.
UUID
Each service, characteristic, and descriptor have a UUID (Universally Unique Identifier). A UUID is a unique 128-bit (16 bytes) number. For example:
55072829-bc9e-4c53-938a-74a6d4c78776
There are shortened UUIDs for all types, services, and profiles specified in the
SIG (Bluetooth Special Interest Group)
But if your application needs its own UUID, you can generate it using this
UUID generator website
In summary, the UUID is used for uniquely identifying information. For example, it can identify a particular service provided by a Bluetooth device.
For a more detailed introduction about BLE, read our getting started guide:
Getting Started with ESP32 Bluetooth Low Energy (BLE) on Arduino IDE
Project Overview
In this tutorial, you’re going to learn how to make a BLE connection between two ESP32 boards. One ESP32 is going to be the BLE server, and the other ESP32 will be the BLE client.
The ESP32 BLE server is connected to a
BME280 sensor
and it updates its temperature and humidity characteristic values every 30 seconds.
The ESP32 client connects to the BLE server and it is notified of its temperature and humidity characteristic values. This ESP32 is connected to an OLED display and it prints the latest readings.
This project is divided into two parts:
Part 1
– ESP32 BLE server
Part 2
– ESP32 BLE client
Parts Required
Here’s a list of the parts required to follow this project:
ESP32 BLE Server:
ESP32 DOIT DEVKIT V1 Board
(read
Best ESP32 development boards
)
BME280 Sensor
Jumper wires
Breadboard
Smartphone with Bluetooth (optional)
ESP32 BLE Client:
ESP32 DOIT DEVKIT V1 Board
(read
Best ESP32 development boards
)
OLED display
Jumper wires
Breadboard
You can use the preceding links or go directly to
MakerAdvisor.com/tools
to find all the parts for your projects at the best price!
1) ESP32 BLE Server
In this part, we’ll set up the BLE Server that advertises a service that contains two characteristics: one for temperature and another for humidity. Those characteristics have the
Notify
property to notify new values to the client.
Schematic Diagram
The ESP32 BLE server will advertise characteristics with temperature and humidity from a BME280 sensor. You can use any other sensor as long as you add the required lines in the code.
We’re going to use I2C communication with the BME280 sensor module. For that, wire the sensor to the default ESP32 SCL (
GPIO 22
) and SDA (
GPIO 21
) pins, as shown in the following schematic diagram.
Recommended reading:
ESP32 Pinout Reference: Which GPIO pins should you use?
Installing BME280 Libraries
As mentioned previously, we’ll advertise sensor readings from a BME280 sensor. So, you need to install the libraries to interface with the BME280 sensor.
Adafruit_BME280 library
Adafruit_Sensor library
You can install the libraries using the Arduino Library Manager. Go to
Sketch
>
Include Library
>
Manage Libraries
and search for the library name.
Installing Libraries (VS Code + PlatformIO)
If you’re using VS Code with the PlatformIO extension, copy the following to the
platformio.ini
file to include the libraries.
lib_deps = adafruit/Adafruit Unified Sensor @ ^1.1.4
adafruit/Adafruit BME280 Library @ ^2.1.2
ESP32 BLE Server – Code
With the circuit ready and the required libraries installed, copy the following code to the Arduino IDE, or to the
main.cpp
file if you’re using VS Code.
/*********
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files.
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
*********/

#include `BLEDevice.h`
#include `BLEServer.h`
#include `BLEUtils.h`
#include `BLE2902.h`
#include `Wire.h`
#include `Adafruit_Sensor.h`
#include `Adafruit_BME280.h`

//Default Temperature is in Celsius
//Comment the next line for Temperature in Fahrenheit
#define temperatureCelsius

//BLE server name
#define bleServerName \"BME280_ESP32\"

Adafruit_BME280 bme; // I2C

float temp;
float tempF;
float hum;

// Timer variables
unsigned long lastTime = 0;
unsigned long timerDelay = 30000;

bool deviceConnected = false;

// See the following for generating UUIDs:
// https://www.uuidgenerator.net/
#define SERVICE_UUID \"91bad492-b950-4226-aa2b-4ede9fa42f59\"

// Temperature Characteristic and Descriptor
#ifdef temperatureCelsius
BLECharacteristic bmeTemperatureCelsiusCharacteristics(\"cba1d466-344c-4be3-ab3f-189f80dd7518\", BLECharacteristic::PROPERTY_NOTIFY);
BLEDescriptor bmeTemperatureCelsiusDescriptor(BLEUUID((uint16_t)0x2902));
#else
BLECharacteristic bmeTemperatureFahrenheitCharacteristics(\"f78ebbff-c8b7-4107-93de-889a6a06d408\", BLECharacteristic::PROPERTY_NOTIFY);
BLEDescriptor bmeTemperatureFahrenheitDescriptor(BLEUUID((uint16_t)0x2902));
#endif

// Humidity Characteristic and Descriptor
BLECharacterist