| Supported Targets | ESP32 | ESP32-C2 | ESP32-C3 | ESP32-C5 | ESP32-C6 | ESP32-C61 | ESP32-H2 | ESP32-S3 |
|---|
Bluedroid GATT Server Example
Overview
This example is extended from Bluedroid Connection Example, and further introduces
- How to implement a GATT server
- How to handle characteristic access requests
- Write access demonstrated by LED control
- Read and indicate access demonstrated by heart rate measurement(mocked)
It uses ESP32's Bluetooth controller and Bluedroid host stack.
To test this demo, any BLE scanner application can be used.
Try It Yourself
Set Target
Before project configuration and build, be sure to set the correct chip target using:
idf.py set-target <chip_name>
For example, if you're using ESP32, then input
idf.py set-target esp32
Build and Flash
Run the following command to build, flash and monitor the project.
idf.py -p <PORT> flash monitor
For example, if the corresponding serial port is /dev/ttyACM0, then it goes
idf.py -p /dev/ttyACM0 flash monitor
(To exit the serial monitor, type Ctrl-].)
See the Getting Started Guide for full steps to configure and use ESP-IDF to build projects.
Code Explained
Overview
- Initialization
- Initialize LED, NVS flash, Bluedroid Host stack, GAP service
- Initialize GATT service and register primary services and characteristics
- Start heart rate update task thread
- Wait for Bluedroid host stack to start advertising; wait for connection event to come
- After connection established, wait for GATT characteristics access events to come
- On write LED event, turn on or off the LED accordingly
- On read heart rate event, send out current heart rate measurement value
- On indicate heart rate event, enable heart rate indication
Entry Point
In this example, we have two GATT service profiles, the heart rate profile and the LED control profile. The heart rate profile is used to mock a heart rate measurement, and the LED control profile is used to control the LED on the ESP32 board. Thus, we need to register two application IDs in total for two GATT service profiles.
void app_main(void)
{
...
ret = esp_ble_gatts_app_register(HEART_PROFILE_APP_ID);
if (ret) {
ESP_LOGE(GATTS_TAG, "app register error, error code = %x", ret);
return;
}
ret = esp_ble_gatts_app_register(AUTO_IO_PROFILE_APP_ID);
if (ret) {
ESP_LOGE(GATTS_TAG, "app register error, error code = %x", ret);
return;
}
...
}
Then, after Bluedroid host task has been initialized, we'll create another task defined in heart_rate_task to update heart rate measurement mock value and send indication if enabled.
GATT Services
In this example, there are two GATT primary services defined
- Heart rate service with a UUID of
0x180D - Automation IO service with a UUID of
0x1815
The characteristics and characteristic descriptors are added sequentially triggered by GATT events.
After the heart rate service has been successfully initialized, we will start a task to mock a heart rate measurement in one second interval. This measurement will be updated to the heart rate measurement characteristic value.
static void heart_gatts_profile_event_handler(esp_gatts_cb_event_t event, esp_gatt_if_t gatts_if, esp_ble_gatts_cb_param_t *param)
{
...
case ESP_GATTS_REG_EVT:
ESP_LOGI(GATTS_TAG, "GATT server register, status %d, app_id %d", param->reg.status, param->reg.app_id);
gl_profile_tab[HEART_PROFILE_APP_ID].service_id.is_primary = true;
gl_profile_tab[HEART_PROFILE_APP_ID].service_id.id.inst_id = 0x00;
gl_profile_tab[HEART_PROFILE_APP_ID].service_id.id.uuid.len = ESP_UUID_LEN_16;
gl_profile_tab[HEART_PROFILE_APP_ID].service_id.id.uuid.uuid.uuid16 = HEART_RATE_SVC_UUID;
//config adv data
esp_err_t ret = esp_ble_gap_config_adv_data(&adv_data);
if(ret){
ESP_LOGE(GATTS_TAG, "config adv data failed, error code = %x", ret);
break;
}
esp_ble_gatts_create_service(gatts_if, &gl_profile_tab[HEART_PROFILE_APP_ID].service_id, HEART_NUM_HANDLE);
break;
case ESP_GATTS_CREATE_EVT:
//service has been created, now add characteristic declaration
ESP_LOGI(GATTS_TAG, "Service create, status %d, service_handle %d", param->create.status, param->create.service_handle);
gl_profile_tab[HEART_PROFILE_APP_ID].service_handle = param->create.service_handle;
gl_profile_tab[HEART_PROFILE_APP_ID].char_uuid.len = ESP_UUID_LEN_16;
gl_profile_tab[HEART_PROFILE_APP_ID].char_uuid.uuid.uuid16 = HEART_RATE_CHAR_UUID;
esp_ble_gatts_start_service(gl_profile_tab[HEART_PROFILE_APP_ID].service_handle);
heart_property = ESP_GATT_CHAR_PROP_BIT_READ | ESP_GATT_CHAR_PROP_BIT_INDICATE;
ret = esp_ble_gatts_add_char(gl_profile_tab[HEART_PROFILE_APP_ID].service_handle, &gl_profile_tab[HEART_PROFILE_APP_ID].char_uuid,
ESP_GATT_PERM_READ,
heart_property,
&heart_rate_attr, NULL);
if (ret) {
ESP_LOGE(GATTS_TAG, "add char failed, error code = %x", ret);
}
break;
case ESP_GATTS_ADD_CHAR_EVT:
ESP_LOGI(GATTS_TAG, "Characteristic add, status %d, attr_handle %d, char_uuid %x",
param->add_char.status, param->add_char.attr_handle, param->add_char.char_uuid.uuid.uuid16);
gl_profile_tab[HEART_PROFILE_APP_ID].char_handle = param->add_char.attr_handle;
gl_profile_tab[HEART_PROFILE_APP_ID].descr_uuid.len = ESP_UUID_LEN_16;
gl_profile_tab[HEART_PROFILE_APP_ID].descr_uuid.uuid.uuid16 = ESP_GATT_UUID_CHAR_CLIENT_CONFIG;
ESP_LOGI(GATTS_TAG, "heart rate char handle %d", param->add_char.attr_handle);
ret = esp_ble_gatts_add_char_descr(gl_profile_tab[HEART_PROFILE_APP_ID].service_handle, &gl_profile_tab[HEART_PROFILE_APP_ID].descr_uuid,
ESP_GATT_PERM_READ | ESP_GATT_PERM_WRITE, NULL, NULL);
break;
case ESP_GATTS_ADD_CHAR_DESCR_EVT:
ESP_LOGI(GATTS_TAG, "Descriptor add, status %d, attr_handle %u",
param->add_char_descr.status, param->add_char_descr.attr_handle);
gl_profile_tab[HEART_PROFILE_APP_ID].descr_handle = param->add_char_descr.attr_handle;
xTaskCreate(heart_rate_task, "Heart Rate", 2 * 1024, NULL, 5, NULL);
break;
...
}
static void auto_io_gatts_profile_event_handler(esp_gatts_cb_event_t event, esp_gatt_if_t gatts_if, esp_ble_gatts_cb_param_t *param)
{
...
case ESP_GATTS_REG_EVT:
ESP_LOGI(GATTS_TAG, "GATT server register, status %d, app_id %d", param->reg.status, param->reg.app_id);
gl_profile_tab[AUTO_IO_PROFILE_APP_ID].service_id.is_primary = true;
gl_profile_tab[AUTO_IO_PROFILE_APP_ID].service_id.id.inst_id = 0x00;
gl_profile_tab[AUTO_IO_PROFILE_APP_ID].service_id.id.uuid.len = ESP_UUID_LEN_16;
gl_profile_tab[AUTO_IO_PROFILE_APP_ID].service_id.id.uuid.uuid.uuid16 = AUTO_IO_SVC_UUID;
esp_ble_gatts_create_service(gatts_if, &gl_profile_tab[AUTO_IO_PROFILE_APP_ID].service_id, AUTO_IO_NUM_HANDLE);
break;
case ESP_GATTS_CREATE_EVT:
//service has been created, now add characteristic declaration
ESP_LOGI(GATTS_TAG, "Service create, status %d, service_handle %d", param->create.status, param->create.service_handle);
gl_profile_tab[AUTO_IO_PROFILE_APP_ID].service_handle = param->create.service_handle;
gl_profile_tab[AUTO_IO_PROFILE_APP_ID].char_uuid.len = ESP_UUID_LEN_128;
memcpy(gl_profile_tab[AUTO_IO_PROFILE_APP_ID].char_uuid.uuid.uuid128, led_chr_uuid, ESP_UUID_LEN_128);
esp_ble_gatts_start_service(gl_profile_tab[AUTO_IO_PROFILE_APP_ID].service_handle);
auto_io_property = ESP_GATT_CHAR_PROP_BIT_WRITE ;
esp_err_t ret = esp_ble_gatts_add_char(gl_profile_tab[AUTO_IO_PROFILE_APP_ID].service_handle, &gl_profile_tab[AUTO_IO_PROFILE_APP_ID].char_uuid,
ESP_GATT_PERM_READ | ESP_GATT_PERM_WRITE ,
auto_io_property,
&led_status_attr, NULL);
if (ret) {
ESP_LOGE(GATTS_TAG, "add char failed, error code = %x", ret);
}
break;
case ESP_GATTS_ADD_CHAR_EVT:
ESP_LOGI(GATTS_TAG, "Characteristic add, status %d, attr_handle %d, char_uuid %x",
param->add_char.status, param->add_char.attr_handle, param->add_char.char_uuid.uuid.uuid16);
gl_profile_tab[AUTO_IO_PROFILE_APP_ID].char_handle = param->add_char.attr_handle;
break;
case ESP_GATTS_ADD_CHAR_DESCR_EVT:
ESP_LOGI(GATTS_TAG, "Descriptor add, status %d", param->add_char_descr.status);
gl_profile_tab[AUTO_IO_PROFILE_APP_ID].descr_handle = param->add_char_descr.attr_handle;
break;
...
}
Automation IO Service
Under automation IO service, there's a LED characteristic, with a vendor-specific 128-bit UUID led_chr_uuid and read/write permission.
When a value is written to the characteristic, Bluedroid Host will trigger an ESP_GATTS_WRITE_EVT. If the written value is 1, the LED will be turned on. Otherwise, the LED will be turned off.
static void auto_io_gatts_profile_event_handler(esp_gatts_cb_event_t event, esp_gatt_if_t gatts_if, esp_ble_gatts_cb_param_t *param)
{
...
case ESP_GATTS_WRITE_EVT:
ESP_LOGI(GATTS_TAG, "Characteristic write, value len %u, value ", param->write.len);
ESP_LOG_BUFFER_HEX(GATTS_TAG, param->write.value, param->write.len);
if (param->write.value[0]) {
ESP_LOGI(GATTS_TAG, "LED ON!");
led_on();
} else {
ESP_LOGI(GATTS_TAG, "LED OFF!");
led_off();
}
example_write_event_env(gatts_if, param);
break;
...
}
void example_write_event_env(esp_gatt_if_t gatts_if, esp_ble_gatts_cb_param_t *param)
{
esp_gatt_status_t status = ESP_GATT_OK;
if (param->write.need_rsp) {
esp_ble_gatts_send_response(gatts_if, param->write.conn_id, param->write.trans_id, status, NULL);
}
}
Heart Rate Service
Under heart rate service, there's a heart rate measurement characteristic, with a standard UUID 0x2A37 and read/indicate permission. Under the heart rate characteristic, there is also a characteristic client config descriptor with UUID 0x2902 with read/write permissions. This descriptor is used to control whether the characteristic should be notified/indicated or not.
All read and write requests to the heart rate service will be handled by calling heart_gatts_profile_event_handler.
1. When an ESP_GATTS_READ_EVT occurs, we will send a response to the client identified by the connection id with the latest heart rate measurement mock value.
2. When an ESP_GATTS_WRITE_EVT occurs, we will first determine if the write target is the characteristic client config descriptor. If it is, we will update the notify/indicate flag of the heart rate characteristic.
3. If the indicate flag is set, whenever there's an update on the charatertistic value, we will send an indication containing the heart rate measurement data to the client identified by the connection id.
static void heart_gatts_profile_event_handler(esp_gatts_cb_event_t event, esp_gatt_if_t gatts_if, esp_ble_gatts_cb_param_t *param)
{
...
case ESP_GATTS_READ_EVT:
ESP_LOGI(GATTS_TAG, "Characteristic read");
esp_gatt_rsp_t rsp;
memset(&rsp, 0, sizeof(esp_gatt_rsp_t));
rsp.attr_value.handle = param->read.handle;
rsp.attr_value.len = 2;
memcpy(rsp.attr_value.value, heart_rate_val, sizeof(heart_rate_val));
esp_ble_gatts_send_response(gatts_if, param->read.conn_id, param->read.trans_id, ESP_GATT_OK, &rsp);
break;
case ESP_GATTS_WRITE_EVT:
ESP_LOGI(GATTS_TAG, "Characteristic write, value len %u, value ", param->write.len);
ESP_LOG_BUFFER_HEX(GATTS_TAG, param->write.value, param->write.len);
if (gl_profile_tab[HEART_PROFILE_APP_ID].descr_handle == param->write.handle && param->write.len == 2){
uint16_t descr_value = param->write.value[1]<<8 | param->write.value[0];
if (descr_value == 0x0001){
if (heart_property & ESP_GATT_CHAR_PROP_BIT_NOTIFY){
ESP_LOGI(GATTS_TAG, "Notification enable");
uint8_t notify_data[15];
for (int i = 0; i < sizeof(notify_data); ++i)
{
notify_data[i] = i%0xff;
}
//the size of notify_data[] need less than MTU size
esp_ble_gatts_send_indicate(gatts_if, param->write.conn_id, gl_profile_tab[HEART_PROFILE_APP_ID].char_handle,
sizeof(notify_data), notify_data, false);
}
}else if (descr_value == 0x0002){
if (heart_property & ESP_GATT_CHAR_PROP_BIT_INDICATE){
ESP_LOGI(GATTS_TAG, "Indication enable");
indicate_enabled = true;
uint8_t indicate_data[15];
for (int i = 0; i < sizeof(indicate_data); ++i)
{
indicate_data[i] = i%0xff;
}
//the size of indicate_data[] need less than MTU size
esp_ble_gatts_send_indicate(gatts_if, param->write.conn_id, gl_profile_tab[HEART_PROFILE_APP_ID].char_handle,
sizeof(indicate_data), indicate_data, true);
}
}
else if (descr_value == 0x0000) {
indicate_enabled = false;
ESP_LOGI(GATTS_TAG, "Notification/Indication disable");
} else {
ESP_LOGE(GATTS_TAG, "Unknown descriptor value");
ESP_LOG_BUFFER_HEX(GATTS_TAG, param->write.value, param->write.len);
}
}
example_write_event_env(gatts_if, param);
break;
case ESP_GATTS_SET_ATTR_VAL_EVT:
ESP_LOGI(GATTS_TAG, "Attribute value set, status %d", param->set_attr_val.status);
if(indicate_enabled){
uint8_t indicate_data[2] = {0};
memcpy(indicate_data, heart_rate_val, sizeof(heart_rate_val));
esp_ble_gatts_send_indicate(gatts_if, gl_profile_tab[HEART_PROFILE_APP_ID].conn_id, gl_profile_tab[HEART_PROFILE_APP_ID].char_handle, sizeof(indicate_data), indicate_data, true);
}
break;
...
}
Observation
If everything goes well, you should be able to see 4 services when connected to ESP32, including
- Generic Access Service
- Generic Attribute Service
- Heart Rate Service
- Automation IO Service
Click on Automation IO Service, you should be able to see LED characteristic. Click on upload button, you should be able to write ON or OFF value. Send it to the device, LED will be turned on or off following your instruction.
Click on Heart Rate Service, you should be able to see Heart Rate Measurement characteristic. Click on download button, you should be able to see the latest heart rate measurement mock value, and it should be consistent with what is shown on serial output. Click on subscribe button, you should be able to see the heart rate measurement mock value updated every second.
Troubleshooting
For any technical queries, please file an issue on GitHub. We will get back to you soon.