ESP32

Bluetooth Architecture

Version 1.2
Espressif Systems
Copyright © 2024
 About This Guide
This document introduces the ESP32 Bluetooth® architecture, namely Bluetooth, Classic
Bluetooth, and Bluetooth Low Energy. Note that this user guide is only applicable to ESP-
IDF v5.0 and later.

Release Notes

Date Version Release notes

2018.01 v1.0 First release.

• Updated document cover;

2019.11 v1.1
• Updated an example in Section 3.24.

2024.04 v1.2 Updated some outdated information

Documentation Change Noti cation

Espressif provides email noti cations to keep customers updated on changes to
technical documentation. Please subscribe at https://www.espressif.com/en/subscribe.

Certi cation
Download certi cates for Espressif products from https://www.espressif.com/en/
certi cates.
fi
fi
fi
fi
fi
 Table of Contents
1. Bluetooth ................................................................................................................................1
1.1. Overview ....................................................................................................................................1
1.1.1. Bluetooth Application Structure ...................................................................................1
1.1.2. Bluetooth Operating Environment ................................................................................2
1.2. Architecture ................................................................................................................................2
1.2.1. Controller ......................................................................................................................2
1.2.2. BLUEDROID .................................................................................................................3
1.2.2.1. Overall Architecture ...............................................................................................3
1.2.2.2. OS-Related Adaptation .........................................................................................5
1.2.3. Bluedroid Directory Introduction...................................................................................5
2. Classic Bluetooth ...................................................................................................................7
2.1. Overview ....................................................................................................................................7
2.2. Pro les and Protocols ................................................................................................................8
2.2.1. L2CAP ...........................................................................................................................8
2.2.2. SDP ...............................................................................................................................8
2.2.3. GAP...............................................................................................................................8
2.2.4. A2DP and AVRCP .........................................................................................................9
3. Bluetooth Low Energy .........................................................................................................12
3.1. GAP ..........................................................................................................................................12
3.1.1. Overview .....................................................................................................................12
3.1.2. Status Transitions Among GAP Roles ........................................................................12
3.1.3. BLE Broadcast Procedure ..........................................................................................13
3.1.3.1. Broadcast Using a Public Address ....................................................................13
3.1.3.2. Broadcast Using a Resolvable Address .............................................................13
3.1.3.3. Broadcast Using a Static Random Address ......................................................14
3.1.4. BLE Modes .................................................................................................................16
3.1.4.1. Connectable Scannable Undirected Mode ........................................................16
3.1.4.2. High Duty Cycle Directed Mode and Connectable Low Duty Cycle Directed
Mode .........................................................................................................................................16
3.1.4.3. Scannable Undirected Mode .............................................................................16
3.1.4.4. Non-Connectable Undirected Mode ..................................................................17
3.1.5. BLE Broadcast Filtering Policy ...................................................................................17
3.1.6. BLE Scanning Procedure............................................................................................17
fi
 3.1.7. BLE GAP Implementation Mechanism .......................................................................18
3.2. GATT ........................................................................................................................................18
3.2.1. ATT ..............................................................................................................................18
3.2.2. GATT Pro le ................................................................................................................20
3.2.3. Add Gatt Services in ESP32 IDF Environment ...........................................................22
3.2.4. Discover a Peer Device’s Services in ESP32 IDF (GATT Client) .................................23
3.3. SMP .........................................................................................................................................24
3.3.1. Overview .....................................................................................................................24
3.3.2. Safety Management Controller ...................................................................................25
3.3.2.1.BLE Encryption ....................................................................................................25
3.3.2.2.BLE Bonding ........................................................................................................26
3.3.3. The Implementation of SMP .......................................................................................27
fi
 1. Bluetooth

1. Bluetooth
This chapter describes the basic Bluetooth architecture of ESP32.

1.1. Overview
1.1.1. Bluetooth Application Structure
Bluetooth is a wireless technology standard for exchanging data over short distances, with
advantages including robustness, low power consumption, and low cost. The Bluetooth
system can be divided into two different categories: Classic Bluetooth and Bluetooth Low
Energy (BLE). ESP32 supports dual-mode Bluetooth, meaning that both Classic Bluetooth
and Bluetooth LE are supported by ESP32.
The Bluetooth protocol stack can be split into two parts: a “controller stack” and a “host
stack”. The controller stack contains the PHY, Baseband, Link Controller, Link Manager,
Device Manager, HCI, and other modules, and is used for the hardware interface
management and link management. The host stack contains L2CAP, SMP, SDP, ATT, GATT,
GAP, and various pro les, and functions as an interface to the application layer, thus
facilitating the application layer to access the Bluetooth system. The Bluetooth Host can be
implemented on the same device as the Controller, or on different devices. Both
approaches are supported by ESP32. Figure 1-1 describes some typical application
structures:

ESP32
PC

Bluedroid Linux/Android

IO
SD
RT/
UA
VHCI

PC

Bluetooth
Test Tool(BQB)
Controller UART

Figure 1-1.The Architecture of Bluetooth Host and Controller in ESP-IDP

• Scenario 1 (Default ESP-IDF setting): BLUEDROID is selected as the Bluetooth Host,

and VHCI (software-implemented virtual HCI interface) is used for the communication
between Bluetooth Host and Controller. In this scenario, both the BLUEDROID and

1/28
Espressif Systems Submit Documentation Feedback 2024.04
fi
 1. Bluetooth

the Controller are implemented on the same device (i.e., the ESP32 chip), eliminating
the need for an extra PC or other host devices running the Bluetooth Host.
• Scenario 2: The ESP32 system is used only as a Bluetooth Controller, and an extra
device running the Bluetooth Host is required (such as a Linux PC running BlueZ or
an Android device running BLUEDROID, etc). In this scenario, Controller and Host are
implemented on different devices, which is quite similar to the case of mobile phones,
PADs or PCs.
• Scenario 3: This scenario is similar to Scenario 2. The difference lies in that, in the
BQB controller test (or other certi cations), ESP32 can be tested by connecting it to
the test tools, with the UART being enabled as the IO interface.

1.1.2. Bluetooth Operating Environment

The default operating environment of ESP-IDF is dual-core FreeRTOS. ESP32 Bluetooth
can assign function-based tasks with different priorities. The tasks with the highest priority
are the ones running the Controller. The Controller tasks, which have higher requirements of
real time, have the highest priority in the FreeRTOS system except for the IPC tasks, which
are mainly for the interprocess communication between the dual-core CPUs. BLUEDROID
(the default ESP-IDF Bluetooth Host) contains four tasks in total, which run the BTC, BTU,
HCI UPWARD, and HCI DOWNWARD.

1.2. Architecture
1.2.1. Controller
The Bluetooth Controller of ESP32 supports both the Classic BT and Bluetooth LE (V4.2).
The Controller has integrated a variety of functions, including H4 protocol, HCI, Link
Manager, Link Controller, Device Manager, and HW Interface. These functions are provided
to the developers in the form of libraries, while some APIs that can access the Controller
are also provided. For details, see API Reference.

2/28
Espressif Systems Submit Documentation Feedback 2024.04
fi
 1. Bluetooth

Figure 1-2. The Architecture of Classic BT & Bluetooth LE Controller (from the SIG BT CORE 4.2)

1.2.2. BLUEDROID

1.2.2.1. Overall Architecture

In ESP-IDF, the signi cantly modi ed BLUEDROID is used as the Bluetooth Host (Classic
BT + BLE). The BLUEDROID, which has a complete set of functions and supports most of
the commonly used standards and architectural designs, is relatively complicated.
However, the modi ed BLUEDROID retains most of the codes below the BTA layer and
almost completely deletes the BTIF layer code, using a leaner BTC layer as the built-in
speci cation and Misc control layer. The architecture of the modi ed BLUEDROID and its
relationship with the Controller is shown in the gure below:

3/28
Espressif Systems Submit Documentation Feedback 2024.04
fi
fi
fi
fi
fi
fi
 1. Bluetooth

Espressif Bluedroid
Coarse Architecture
V1.1
USER
TASK
USER APP
PROCEDURE

GAP SDP BLE BT

ESP_API GATT
PROFILES PROFILES

BTC
TASK

BLE PROFILE BLE PROFILE BT PROFILE

L2C
BAT SPP 6
BLE BLU … AP … A2D …
TER LIK Low D-
SPP
HID FI … … P …
Y E Pan Chan

BTA_API BLE BT
GAP GAP SDP
PROFILES PROFILES

BTU
TASK

BLE & BT BLE LOW-LAYER BT LOW-LAYER

PROFILE PROFILE
STACK
L2CAP
6LowPan Dynamic …… A2DP RFCOMM ……
CHANNEL

GATT/ATT L2ACAP SDP SMP GAP

H4 HCI TRANSPORT LAYER (Include HCI Task)

VHCI_API VHCI

Contr
oller
TASK

Controller

H4
HCI
LM/LC
HW Interface

Figure 1-3.ESP32 BLUEDROID Diagram

📖 Note:

This diagram mainly describes the hierarchy of the BLUEDROID, rather than details, such as the HCI
TASK. The detailed information about each layer can be seen below.

4/28
Espressif Systems Submit Documentation Feedback 2024.04
 1. Bluetooth

As shown in the gure above, the BLUEDROID can be divided into two layers mainly, which
are the BTU layer and the BTC layer (except for HCI). Each layer is responsible for its
corresponding tasks. More speci cally, the BTU layer is mainly responsible for processing
the bottom layer protocol stacks of the Bluetooth Host, including L2CAP, GATT/ATT, SMP,
GAP, and other pro les. The BTU layer provides an interface pre xed with "bta". The BTC
layer is mainly responsible for providing a supported interface, pre xed with “esp”, to the
application layer, processing GATT-based pro les and handling miscellaneous tasks. All the
APIs are located in the ESP_API layer. Developers should use the Bluetooth APIs pre xed
with “esp".
The gure above does not describe the HCI layer in detail. In fact, the HCI layer has one
task that processes the downward and upward data.
The design logic behind this architecture is to minimize the load on the User Tasks and
streamline the Bluetooth structure by handing over the Bluetooth-related tasks to the BTC
layer.
Due to legacy reasons and actual demand, some of the Classic Bluetooth pro les, such as
RFCOMM and A2DP, as well as other lower layer protocols are implemented in the BTU
layer, while some of the protocols that are related to procedural controls, or require the
ESP-API, are implemented in the BTC layer.
Some of the pro les and lower layer functions of the Bluetooth Low Energy, such as the
6LowPan or Dynamic L2CAP Channel, will be implemented in the BTU layer, thus providing
the application layer with the ESP-API through the BTC.
1.2.2.2. OS-Related Adaptation
Some interfaces that are related to the system in BLUEDROID require OSI adaptation. The
functions involved include Timer (Alarm), Task (Thread), Future Await/Ready
(Semphore), and Allocator(malloc/free).
The FreeRTOS Timer in BLUEDROID has been packaged as an Alarm, and is used to start
the timer which triggers certain tasks.
In BLUEDROID, the POSIX Thread has been replaced with the FreeRTOS tasks, and uses
the FreeRTOS Queue to trigger tasks (i.e., wake up).
In BLUEDROID, the Future Await/Ready function is used to achieve Blocking. Future Lock
packages the xSemphoreTake of FreeRTOS as the future_await function, and packages
the xSemphoreGive as the future_ready function. It is worth noting that the future_await
and future_ready functions cannot be called in the same task context.
In BLUEDROID, malloc/free in the standard library is packaged as the Allocator function
that reserves (mallocs) or frees memory.

1.2.3. Bluedroid Directory Introduction

In the component/bt/host/bluedroid screen of the ESP-IDF, you can see the following
sub-folders:

5/28
Espressif Systems Submit Documentation Feedback 2024.04
fi
fi
fi
fi
fi
fi
fi
fi
fi
fi
 1. Bluetooth

Figure 1-4. component/bt/host/bluedroid in ESP-IDF

The detailed description of each sub-folder can be found in the table below:

Table 1-1. Description of component/bt/host/bluedroid in ESP-IDF

Sub-folder Description

The API directory, which includes all the APIs (except for those that are
api
related to the Controller)

The Bluetooth adaptation layer, which is suitable for the interface of some
bta
bottom layer protocols in the host.

The Bluetooth control layer, which controls the upper-layer protocols

btc
(including pro les) and miscellaneous items in the host.

common Common header le for the protocol stack.

config Con gure some parameters for the protocol stack.

Related to the device control of the Controller, e.g., the basic set of HCI
device
CMD controller processes.

Codes that are not directly related to the Bluetooth, but are still usable, e.g.,
external
the SBC codec software programs.

hci HCI layer protocols.

Kconfig.in Menucon g les.

main Main program (mainly to start or halt the process).

The bottom layer protocol stacks in the Host (GAP/ATT/GATT/SDP/SMP,

stack
etc.)

6/28
Espressif Systems Submit Documentation Feedback 2024.04
fi
fi
fi
fi
fi
 2. Classic Bluetooth

2. Classic Bluetooth
This chapter introduces the Classic Bluetooth in ESP-IDF.

2.1. Overview
The Bluetooth Host Stack in ESP-IDF originates from BLUEDROID and has been adapted
to embedded applications. At the lower layer, the Bluetooth Host Stack communicates with
the Bluetooth dual-mode Controller via the virtual HCI interface. At the upper layer, the
Bluetooth Host stack provides the pro les and APIs for stack management to the user
applications.
Protocols de ne the message formats and the procedures aimed to accomplish speci c
functions, e.g., data transportation, link control, security service, and service information
exchange. Bluetooth pro les, on the other hand, de ne the functions and features required
of each layer in the Bluetooth system, from PHY to L2CAP, and any other protocols outside
the core speci cation.
Below are the Classic BT pro les and protocols currently supported in the Host Stack.
• Pro les: GAP, A2DP, AVRCP, SPP, HFP
• Protocols: L2CAP, SDP, AVDTP, AVCTP, RFCOMM
The protocol model is depicted in Figure 2-1.

Figure 2-1. Pro le Dependencies

7/28
Espressif Systems Submit Documentation Feedback 2024.04
fi
fi
fi
fi
fi
fi
fi
fi
fi
 2. Classic Bluetooth

In Figure 2-1, L2CAP and SDP are necessary in a minimal Host Stack for Classic Bluetooth.
AVDTP, AV/C, and AVCTP are outside the core speci cation and are used by speci c
pro les.

2.2. Pro les and Protocols

2.2.1. L2CAP
As an OSI layer 2 Bluetooth protocol, the Bluetooth Logical Link Control and Adaptation
Protocol (L2CAP) supports higher-level protocol multiplexing, packet segmentation, and
reassembly, as well as the delivery of service information quality. L2CAP makes it possible
for different applications to share an ACL-U logical link. Applications and service protocols
interface with L2CAP, using a channel-oriented interface, to create connections to
equivalent entities on other devices.
L2CAP channels may operate in one of the six modes selected through the L2CAP channel
con guration procedure. The operation modes are distinguished from the QoS that they
can provide, and are utilized in different application conditions. These modes are:
• Basic L2CAP Mode

• Flow Control Mode

• Retransmission Mode

• Enhanced Retransmission Mode

• Streaming Mode

• LE Credit-Based Flow Control Mode

For ACL-U logical links, the supported operation modes are the Basic L2CAP Mode,
Enhanced Retransmission Mode and Streaming Mode. For other features, the L2CAP
Signaling channel is the supported xed channel, while the Frame Check Sequence (FCS)
is also a supported option.

2.2.2. SDP
The Service Discovery Protocol (SDP) provides a means for applications to discover
services offered by a peer Bluetooth device, as well as to determine the characteristics of
the available services. The SDP involves communication between an SDP server and an
SDP client. A server maintains a list of service records that describe the characteristics of
services associated with the server. A client can retrieve this information by issuing an SDP
request.

2.2.3. GAP
The Generic Access Pro le (GAP) provides a description of the modes and procedures in
device discoverability, connection and security.

8/28
Espressif Systems Submit Documentation Feedback 2024.04
fi
fi
fi
fi
fi
fi
fi
 2. Classic Bluetooth

For the time being, only a limited number of GAP APIs are provided to the Classic
Bluetooth Host Stack. An application can make use of these APIs, as if they were a
"passive device" which could be discovered by and connected to peer Bluetooth devices.
More GAP APIs for Classic Bluetooth are coming up next. API for link policy settings will be
provided at a later stage.

2.2.4. A2DP and AVRCP

The Advanced Audio Distribution Pro le (A2DP) de nes the protocols and procedures that
realize the distribution of high-quality audio content in mono or stereo on ACL channels.
A2DP handles audio streaming and is often used together with the Audio/Video Remote
Control Pro le (AVRCP), which includes the audio/video control functions. Figure 2-2
depicts the structure and dependencies of the pro les[1]:

📖 Note：

[1]: Advanced Audio Distribution Pro le Speci cation, Revision 1.4.

Figure 2-2. Pro le Dependencies

As indicated in Figure 2-2, the A2DP is dependent upon the GAP, as well as the Generic
Audio/Video Distribution Pro le (GAVDP), which de nes procedures required to set up an
audio/video streaming.
Two roles are de ned in A2DP: Source (SRC) and Sink (SNK). SRC functions as a source of
a digital audio stream and SNK functions as a sink of a digital audio stream delivered from
the SRC.
Two roles de ned in AVRCP are Controller (CT) and Target (TG). CT is a device that initiates
a transaction by sending a command frame to a target. Examples of CT include personal

9/28
Espressif Systems Submit Documentation Feedback 2024.04
fi
fi
fi
fi
fi
fi
fi
fi
fi
fi
fi
 2. Classic Bluetooth

computers, PDAs, and mobile phones. TG is a device that receives a command frame and
accordingly generates a response frame. Audio players or headphones are examples of
TG.
In the current A2DP solution, the only audio codec supported is SBC, which is mandated in
the A2DP speci cation. A2DP Version 1.4 and AVDTP Version 1.3 are implemented.
Audio/Video Distribution Transport Protocol (AVDTP) de nes the binary transactions
between Bluetooth devices for a streaming set-up, and media streaming for audio and
video using L2CAP. As the basic transport protocol for A2DP, AVDTP is built upon the
L2CAP layer and consists of a signaling entity for negotiating streaming parameters and a
transport entity that handles the streaming itself.
The basic service of AVDTP transport capabilities is mandated by the A2DP speci cation.
According to the con guration of current service capabilities, Media Transport and Media
Codec in the basic service capability are provided.
AVRCP de nes the requirements necessary for the support of the Audio/Video remote
control use case.
The commands used in AVRCP fall into three main categories. The rst one is the AV/C
Digital Interface Command Set, which is applied only on certain occasions and is
transported with the Audio/Video Control Transport Protocol (AVCTP). Browsing
commands are included in the second category, which provides browsing functionality over
another transport channel called the AVCTP browsing channel. The third category, Cover
Art Commands, is used to transmit images associated with media items, and is provided
through the protocol de ned in the Bluetooth Basic Imaging Pro le (BIP) with the OBEX
protocol.
Two sets of AV/C commands are used in AVRCP. The rst one includes the PASS
THROUGH command, UNIT INFO command, and SUBUNIT INFO command, which are
de ned in the AV/C speci cation. The second set includes AVRCP-speci c AV/C
commands which are de ned as a Bluetooth SIG Vendor-Dependent extension. AV/C
commands are sent over the AVCTP control channel. A PASS THROUGH command is
used to transfer a user operation via a button from the Controller to the panel subunit,
which provides a simple and common mechanism to control the target. For example, the
operation IDs in PASS THROUGH include common instructions such as Play, Pause, Stop,
Volume Up, and Volume down.
AVRCP arranges the A/V functions in four categories to ensure interoperability:
• Player/Recorder

• Monitor/Ampli er

• Tuner

• Menu

In the current implementation, AVRCP Version 1.5 and AVCTP Version 1.4 are provided.
The default con guration for AVRCP-supported features is Category 2: Monitor/Ampli er.
Also, APIs for sending PASS THROUGH commands are provided.

10/28
Espressif Systems Submit Documentation Feedback 2024.04
fi
fi
fi
fi
fi
fi
fi
fi
fi
fi
fi
fi
fi
fi
fi
fi
 2. Classic Bluetooth

A2DP and AVRCP are often used together. In the current solution, the lower Host stack
implements AVDTP and the AVCTP logic, while providing interfaces for A2DP and AVRCP
independently. In the upper layer of the stack, however, the two pro les combined make up
the "AV" module. The BTA layer, for example, provides a uni ed "AV" interface, and in BTC
layer there is a state machine that handles the events for both pro les. The APIs, however,
are provided separately for A2DP and AVRCP.

11/28
Espressif Systems Submit Documentation Feedback 2024.04
fi
fi
fi
 3. Bluetooth Low Energy

3. Bluetooth Low Energy

This chapter describes the architecture of the Bluetooth Low Energy in ESP32.

3.1. GAP
3.1.1. Overview
This section mainly introduces the implementation and use of the Bluetooth LE GAP APIs in
ESP32. The GAP (the Generic Access Pro le) de nes the discovery process, device
management and the establishment of device connection between Bluetooth LE devices.
The Bluetooth LE GAP is implemented in the form of API calls and Event returns. The
processing result of API calls in the protocol stack is returned by Events. When a peer
device initiates a request, the status of that peer device is also returned by an Event.
There are four GAP roles de ned for a Bluetooth LE device:
• Broadcaster: A broadcaster is a device that sends advertising packets, so it can be
discovered by the observers. This device can only advertise, but cannot be
connected.
• Observer: An observer is a device that scans for broadcasters and reports this
information to an application. This device can only send scan requests, but cannot be
connected.
• Peripheral: A peripheral is a device that advertises by using connectable advertising
packets and becomes a slave once it gets connected.
• Central: A central is a device that initiates connections to peripherals and becomes a
master once a physical link is established.

3.1.2. Status Transitions Among GAP Roles

Scanning

Advertising Standby Initiating

Connection

Figure 3-1. Status Transitions Among GAP Roles

12/28
Espressif Systems Submit Documentation Feedback 2024.04
fi
fi
fi
 3. Bluetooth Low Energy

3.1.3. BLE Broadcast Procedure

3.1.3.1. Broadcast Using a Public Address

When a public address is used for broadcasting, the own_addr_type of
esp_ble_adv_params_t must be set to BLE_ADDR_TYPE_PUBLIC. The broadcast owchart is
as follows:
Advertiser Scanner

API LLM
API LLM
API API

calls
esp_ble_gap_set_device_name

calls
esp_ble_gap_set_device_name

calls
esp_ble_gap_config_adv_data
sends config adv data HCI
command to LL layer

returns set adv data event

returns
esp_gap_ble_adv_data_set_co
mplete_evt

calls
esp_ble_gap_start_advertising
to start broadcast;
sets the own_addr_type
parameter to
ble_addr_type_public
sends start adv HCI command
to LL layer

returns start adv event

advertising event

returns
esp_gap_ble_adv_start_comple advertising event
te_evt

esp_gap_ble_scan_result_evt

Figure 3-2.Broadcast Using a Public Address

3.1.3.2. Broadcast Using a Resolvable Address

When utilizing a resolvable address for broadcasting, the underlying protocol stack updates
the broadcast address upon reaching the timeout for the resolvable private address, with a
default timeout set to 15 minutes. The timeout for the resolvable private address can be
con gured via the BT_BLE_RPA_TIMEOUT option in menucon g. The own_addr_type of
esp_ble_adv_params_t must be set to BLE_ADDR_TYPE_RPA_PUBLIC or
BLE_ADDR_TYPE_RPA_RANDOM. The broadcast owchart is as follows:

13/28
Espressif Systems Submit Documentation Feedback 2024.04
fi
fl
fi
fl
 3. Bluetooth Low Energy

Figure 3-3.Broadcast Using a Resolvable Address

⚠ Note:

When a resolvable address is used for broadcasting, the broadcast only starts after the
esp_ble_gap_config_local_privacy event is returned, and the own_addr_type type, a broadcast
parameter, must be set to BLE_ADDR_TYPE_RPA_PUBLIC or BLE_ADDR_TYPE_RPA_RANDOM.

To use the BLE_ADDR_TYPE_RPA_RANDOM address type, it is necessary to rst set a Static Random Address
through the API esp_ble_gap_set_rand_addr. If BLE_ADDR_TYPE_RPA_PUBLIC is used, setting the address
is not required.

BLE_ADDR_TYPE_RPA_PUBLIC operates as follows: The controller generates a Resolvable Private Address

(RPA) based on the local Identity Resolving Key (IRK) from the resolving list. If the resolving list lacks a
matching entry, the public address is used.

For BLE_ADDR_TYPE_RPA_RANDOM, if there is no matching entry in the resolving list, Static Random Address
is used instead.

3.1.3.3. Broadcast Using a Static Random Address

When a static random address is used for broadcasting, the own_addr_type of the
esp_ble_adv_params_t must be set to BLE_ADDR_TYPE_RANDOM, which is similar to the case

14/28
Espressif Systems Submit Documentation Feedback 2024.04
fi
 3. Bluetooth Low Energy

of broadcasting using a resolvable address. The broadcast owchart is as follows:

Advertiser Scanner

API LLM
API LLM
API API

calls
esp_ble_gap_set_device_name

calls
esp_ble_gap_set_rand_addr sends set rand address HCI
command to LL layer

returns returns set rand address event

esp_gap_ble_set_static_rand_a
ddr_evt

sends config adv data HCI

command to LL layer
calls
esp_ble_gap_config_adv_data

calls returns set adv data event

esp_gap_ble_adv_data_set_co
mplete_evt

calls
esp_ble_gap_start_advertising
to start broadcast;
sets the own_addr_type
parameter to
ble_addr_type_random
sends start adv HCI command
to LL layer
advertising event

returns returns start adv event advertising event

esp_gap_ble_adv_start_comple
te_evt
esp_gap_ble_scan_result_evt

Figure 3-4. Broadcast Using a Static Random Address

15/28
Espressif Systems Submit Documentation Feedback 2024.04
fl
 3. Bluetooth Low Energy

3.1.4. BLE Modes

Five modes are de ned for the Bluetooth LE broadcasts: Connectable Scannable
Undirected mode, High Duty Cycle Directed mode, Scannable Undirected mode, Non-
connectable Undirected mode, and Connectable Low Duty Cycle Directed mode.
3.1.4.1. Connectable Scannable Undirected Mode

Table 3-1.Packet Structure

Payload

AdvA (6 octets) AdvData (0~31 octets)

A device in the Connectable Scannable Undirected mode can be discovered by and

connected to any device. Scannability indicates that the local device needs to reply with a
scan response, when a peer device sends a scan request.
As shown in the table above, a Connectable Scannable Undirected broadcast packet
includes 6 bytes of the broadcast address and 0 ~ 31 bytes of the broadcast packet data.
When a static random address is used for broadcasting, the broadcast address is speci ed
by calling esp_ble_gap_set_rand_addr. When a public address or a resolvable address is
used for broadcasting, the broadcast address is generated automatically by the protocol
stack.
3.1.4.2. High Duty Cycle Directed Mode and Connectable Low Duty Cycle Directed Mode

Table 3-2.Packet Structure

Payload

AdvA (6 octets) InitA (6 octets)

The IP directed broadcasts can only be discovered by and connected to the designated
devices.
As shown in the table above, the High Duty Cycle Directed Broadcast packet includes 6
bytes of the broadcasting device’s address and 6 bytes of the receiving device’s address. In
this mode, the broadcast parameters adv_int_min and adv_int_max are ignored.
In the Connectable Low Duty Cycle Directed mode, the broadcast parameters adv_int_min
and adv_int_max must be greater than 100 ms (0xA0).

📖 Note:

IP directed broadcasts do not carry Adv Data.

3.1.4.3. Scannable Undirected Mode

In the Scannable Undirected mode, a device can be discovered by any other device, but it
cannot get connected to it.

16/28
Espressif Systems Submit Documentation Feedback 2024.04
fi
fi
 3. Bluetooth Low Energy

Table 3-3.Packet Structure

Payload

AdvA (6 octets) AdvData (0~31 octets)

As shown in the table above, a Scannable Undirected packet includes 6 bytes of a

broadcast address and 0~31 bytes of the broadcast packet data, which is the same
structure as in the Connectable Scannable Undirected packet. A device in this mode can
only be scanned by any device, but it cannot be connected to it.
3.1.4.4. Non-Connectable Undirected Mode
In the Non-connectable Undirected mode, a device can be discovered by any device, but it
can neither be scanned by, nor connected to any other devices. An unscannable device is
one that will not reply with a scan response, when a peer device sends a scan request. A
disconnectable device is one that cannot be connected to any device.

Table 3-4.Packet Structure

Payload

AdvA (6 octets) AdvData (0~31 octets)

As shown in the table above, a Non-connectable Undirected broadcast packet also

includes 6 bytes of broadcast address and 0~31 bytes of broadcast packet data. In this
mode, a device can be discovered but cannot be scanned nor be connected by other
devices.

3.1.5. BLE Broadcast Filtering Policy

In ESP32's Bluetooth LE architecture, the broadcast ltering policy is implemented by
setting the adv_filter_policy enumeration type, which has the following four values:
• ADV_FILTER_ALLOW_SCAN_ANY_CON_ANY
• ADV_FILTER_ALLOW_SCAN_WLST_CON_ANY
• ADV_FILTER_ALLOW_SCAN_ANY_CON_WLST
• ADV_FILTER_ALLOW_SCAN_WLST_CON_WLST
The four values correspond to 4 cases, respectively:
• Can be scanned and connected to any device (no white list)
• Handles all of the connection requests, and only the scan requests in the whitelist
• Handles all of the scan requests, and only the connection requests in the whitelist
• Handles the connection requests and scan requests in the whitelist

3.1.6. BLE Scanning Procedure

In ESP32, the scanning device sets the parameters of the scan mainly by calling
esp_ble_gap_set_scan_params, and then starts the scan by calling

17/28
Espressif Systems Submit Documentation Feedback 2024.04
​​
fi
 3. Bluetooth Low Energy

esp_ble_gap_start_scanning. The information of the scanned device will be returned by

the ESP_GAP_BLE_SCAN_RESULT_EVT event, or by the ESP_GAP_SEARCH_INQ_CMPL_EVT event
when the duration times out.

⚠ Notice:

When the value of the duration is 0, the device will be scanned permanently without timeout.

3.1.7. BLE GAP Implementation Mechanism

ESP32 calls the Bluetooth LE GAP APIs, registers Bluetooth LE GAP Callback, and obtains
the status of the current device by the returned value of the Event.

3.2. GATT
3.2.1. ATT
The data inside the Bluetooth LE architecture exists in the form of Attributes that consist of
four basic elements:
• Attribute Handle: an Attribute Handle can help us locate any Attribute, which is similar
to using an address to locate data in the memory. For example, the Handle of the rst
attribute is 0x0001 and the second one is 0x0002, and so on, up to 0xFFFF.
• Attribute Type: Each data set exposes a certain type of information, such as
temperature, transmit power, battery level and so on. The type of the data that is
exposed is called attribute type. Given the different possible types of data that can be
exposed, a 16-bit or 128-bit number, also known as UUID, is used to identify the type
of the attribute. For example, UUID 0x2A09 is for Battery Level and UUID 0x2A6E is
for Temperature.
• Attribute value: the attribute value is the key information of each attribute, while the
other three elements (handle, type and permission) are added so the attribute value
can be better understood. The length of the attribute value for different attribute types
can be xed or variable. For example, the length of the attribute value in Battery Level
is only 1 byte, which is enough to cover all the possible values of a Battery Level
attribute, i.e. 0-100, while the attribute length of a BLE-enabled pass-through module
is variable.
• Attribute Permission: Each attribute contains information that can only be read or
written. To facilitate these restrictions upon access, every attribute has its attribute
permissions. The party that owns the data can control the read/write access of its
local data through attribute permissions.

Table 3-5. Attribute Structure Table

Attribute Handle Attribute Type Attribute Value Attribute Permission

0x0001 - - -

0x0002 - - -

18/28
Espressif Systems Submit Documentation Feedback 2024.04
fi
fi
 3. Bluetooth Low Energy

Attribute Handle Attribute Type Attribute Value Attribute Permission

……… - - -

0xFFFE - - -

0xFFFF - - -

The device that holds the data (i.e. the attributes) is de ned as a server, and the device that
obtains the data from the server is de ned as a client. The common operations between a
server and a client are listed below:
• A client sends data to a server by writing data into the server. Both the Write
Request and Write Command can be used to write an attribute value. However, a
Write Response is only prompted when a Write Request is used.
• A server sends data to a client by sending an Indication or Noti cation to the
client. The only difference between an Indication and a Noti cation is that a
Con rmation is prompted only when an Indication is used. This is similar to the
difference between a Write Request and a Write Command.
• A client can also obtain data from the server by initiating a Read Request.

Figure 3-5. Common Operations Between a Server and a Client

⚠ Notice:

For detailed information regarding the common operations between a server and a client, please refer to
Core_V4.2, Vol3. Part F, Chapter 3.4 “Attribute Protocol PDUs”.

The common operations between a server and a client are achieved by using ATT PDU.
Each device can specify its supported MTU, which is the maximum length of an ATT
message. In ESP32 IDF, the MTU can be 23 - 517 bytes, and the total length of an attribute
value is not limited.

19/28
Espressif Systems Submit Documentation Feedback 2024.04
fi
fi
fi
fi
fi
 3. Bluetooth Low Energy

If the length of the user’s packet is greater than (MTU-3), a Prepare Write Request is
required to write data. Similarly, if the length of the packet is greater than (MTU-1), a Read
Blob Request is required to read the remaining data.

⚠ *Notice:

The difference between the MTU and the LE Packet Length of a single physical packet should be
highlighted here. The MTU, which is about the Host ATT layer in this case, determines whether all the
“data to be sent” can t into a single ATT Request and also whether a Prepare Write Request is required
to send the data. Meanwhile, the LE Packet Length, which is about the PHY layer, determines whether
the packet needs to be divided and transmitted in several packages. For example, if (MTU + 4) is greater
than the LE Packet Length, this ATT packet needs to be divided and transmitted in more than one
physical packets. On the contrary, if (MTU+4) is shorter than the LE Packet Length, only one physical
packet is required to send the whole ATT packet. The reason we add 4 bytes to the MTU is because a 4-
byte L2CAP header will be added during the transmission.

3.2.2. GATT Pro le

The ATT speci es the minimum data storage unit in the Bluetooth LE architecture, while the
GATT de nes how to represent a data set using attribute values and descriptors, how to
aggregate similar data into a service, and how to nd out what services and data a peer
device owns.
The GATT introduces the concept of Characteristics, which are about information that is
not purely numerical, as in the cases outlined below:
• The unit of a given value, for example, weight measured in kilograms (kg),
temperature measured in Celsius (℃), and so on.
• The name of a given value. For example, for characteristics with the same UUID, e.g.
temperature attribute, the name of the value informs the peer device that this value
indicates “the temperature in the master bedroom”, while the other one indicates “the
temperature in the living room”.
• The exponent of excessive data numbers, such as 230,000 and 460,000. Given that
the exponent is already speci ed as 10^4, transmitting only “23” and “46” is enough
to represent 230,000 and 460,000.
These are just a few examples of the many existing requirements for describing data
accurately in actual applications. In order to provide more nuanced information, a large
piece of data space should be reserved to store this additional information in each
characteristic. However, in many cases, most of the extra space reserved will not be used.
Such a design, then, will not comply with BLE's prerequisite to have as concise as possible
protocols. In cases like this, the GATT speci cation introduces the concept of descriptors
to outline this additional information. It must be noted that each piece of data and
descriptor do not have a one-to-one correspondence, that is, complex data can have
multiple descriptors, while simple data can have no descriptors at all.
A characteristic is composed of three basic elements:
• Characteristic Declaration: a declaration is the start of a characteristic, informing a
peer device that the content following the declaration is the characteristic value. All

20/28
Espressif Systems Submit Documentation Feedback 2024.04
fi
fi
fi
fi
fi
fi
fi
​​
 3. Bluetooth Low Energy

the handles between two declarations compose a complete characteristic. The write
and read properties are also included in a declaration.
• Characteristic Value: a characteristic value is the main part of a characteristic, which
carries the most important information of a characteristic.
• Descriptor: Descriptors can further describe characteristics (e.g. providing
con guration information) and a characteristic can have multiple or no descriptors.
In BLE, the GAP groups similar functions together in the form of Services. For example, all
of the characteristics and behaviors related to the battery can be de ned as a Battery
Service; all of the characteristics and behaviors related to the heart rate can be de ned as a
Heart Rate Service; and all of the characteristics and behaviors related to the weight scale
can be de ned as a Weight Scale Service.
A Service typically includes one or more characteristics and each characteristic includes
zero or many descriptors. Users can select the required services based on their own
application requirements, and form the nal application.
A completed service de nition table is shown below:

Table 3-6. The De nition Table of Services

Attribute Handle Attribute Type

0x0001 Service 1

0x0002 Characteristic Declaration 1

0x0003 Characteristic Value 1

0x0004 Descriptor 1

0x0005 Characteristic Declaration 2

0x0006 Characteristic Value 2

0x0007 Descriptor 2

0x0008 Descriptor 3

0x0009 Service 2

……… ………

21/28
Espressif Systems Submit Documentation Feedback 2024.04
fi
fi
fi
fi
fi
fi
fi
 3. Bluetooth Low Energy

⚠ *Notices:

For other de nitions of services, characteristics and descriptors, please refer to:
• Core_V4.2, Vol3., Part G, Chapter 3 “Service Interoperability Requirements”
• https://www.bluetooth.com/zh-cn/speci cations/gatt

3.2.3. Add Gatt Services in ESP32 IDF Environment

Users can add services and characteristics manually, through events, one by one in ESP32
IDF Release 1.0. All of the read-write operations will reach the application layer through
events and users can respond to them with packages. This approach is prone to errors by
users who are not familiar with the Bluetooth LE protocol, especially when adding services
in a large GATT database. So adding services manually one by one is not recommended.

⚠ *Notice:

The interface and examples of adding services and characteristics manually are still reserved in ESP IDF.
For more information, please refer to the gatt_service example.

In this context, adding services and characteristics with an attribute table is introduced in
ESP32 IDF Release 2.0. Users can add new services and characteristics by simply entering
them in an attribute table and, then, calling esp_ble_gatts_create_attr_tab. Additionally,
a lower layer response is also supported in this case, meaning the lower layer is able to
respond to some requests and identify errors automatically, so the users can focus on
receiving and sending data.
In this way, users can port pro les to the ESP32 platform from other platforms easily,
without the need to implement the Bluetooth LE speci cations all over again.

⚠ *Notice:

We recommend that users add services and characteristics through the attribute table, which is much
easier, less error-prone, and supports low-layer responses. For details, please refer to the
gatt_server_service_table examples.

The structure of an attribute table de nes all of the parameters that require initialization to
describe an attribute through esp_gatts_attr_db_t:

Table 3-7. The Structure Parameters of ESP32 IDF

Parameter Description

De nes some responses, such as the write_response, which are given

by the lower layer automatically or passed to the application layer, so that
uint8_t attr_control
users can respond manually. The ESP_GATT_AUTO_RSP automatic
response mode is recommended.

Indicates that the length of UUID is 16 bits, 32 bits or 128 bits. Since the
uint16_t uuid_length attribute UUID is transmitted by pointers, the length of the UUID has to
be speci ed.

22/28
Espressif Systems Submit Documentation Feedback 2024.04
fi
fi
fi
fi
fi
fi
fi
 3. Bluetooth Low Energy

Parameter Description

Indicates the pointer of the UUID of the current attribute. Users can read
uint8_t *uuid_p a certain length of the UUID value, based on the length information
speci ed in the uuid_lenght parameter.

Indicates the write and read permissions of the current attribute. This
parameter is bitwise-operated. Each bit represents a speci c write and
uint16_t perm read permission. Operating a certain bit can change the write and read
permission of the corresponding attribute. For example, PERM_READ |
PERM_WRITE means an attribute that can be read and written.

Indicates the maximum length of the current attribute value. The protocol
stack allocates memory to the attribute, based on this parameter. If the
length of the attribute value that a peer device has written exceeds the
uint16_t max_length
maximum length de ned in this parameter, a write error is returned,
indicating that the error is due to the length of the write operation
exceeding the maximum length of the data.

Indicates the actual length of the current attribute. For example, in case
the maximum length of the attribute is 512 bits and a peer device wants
to write “0x1122” into this attribute, we will set the current length of the
uint16_t length
attribute to 2. When a peer device, then, reads this attribute, we can
obtain the actual length of this attribute from the memory, sending only
the part with the actual values, instead of the whole 512 bits.

Indicates the initialized values of the current attribute value. Since the
format of this parameter is a pointer, the actual length of this parameter
uint8_t *value
should be obtained rst by the length parameter, in order to get the
correct value from the pointer.

3.2.4. Discover a Peer Device’s Services in ESP32 IDF (GATT Client)

The Discovering Service can help a GATT Client discover a peer device’s services and
characteristics. The discovery procedure can be different for different devices. The
discovery procedure of ESP32 IDF is introduced here, along with an example of how to
discover a peer device’s GATT service.
• Firstly, discover all of the peer devices’ services information, including the service
UUID and the range of the attribute handle.
- GATT Service, UUID 0x1801, Handles 0x0001~0x0005
- GAP Service, UUID 0x1800, Handles 0x0014~0x001C
• Then, discover all of the peer devices’ characteristics within the handle range of a
GATT service (0x0001~0x0005).
- Find “Service Change Characteristic”, Handles 0x0002~0x0003
- 0x0002 represents the characteristic declaration
- 0x0003 represents the characteristic value
- So each characteristic has the attributes of at least two handles.

23/28
Espressif Systems Submit Documentation Feedback 2024.04
fi
fi
fi
fi
 3. Bluetooth Low Energy

• Given that the handles of a GATT Service lie in the range of 0x0001~0x0005,
0x0003, for example, should be followed by the corresponding descriptor. All
descriptors, then, should be sought from 0x0004 onwards.
- 0x0004 represents the descriptor of the Client Characteristic Con guration
- 0x0005 does not have any information at the moment, and could be a handle
reserved for this service.
• At this point, the discovery procedure of GATT Service is complete.

3.3. SMP
This chapter mainly introduces the implementation and use of the ESP32 Bluetooth LE
SMP (Security Management Protocol).

3.3.1. Overview
The SMP-related APIs have been packaged in ESP32 BLE’s GAP module.
The SMP generates encryption keys and identity keys, de nes a convenient protocol for
pairing and key distribution, and allows the other layers in the protocol stack to connect
and exchange data with other devices safely. A connection in the data link layer and certain
security standards are required in this process. The GAP SMP allows two devices
encrypting their connection in the data link layer by setting such security levels as those in
the SMP chapter of the Bluetooth Core Speci cation version. Before introducing the
implementation of the GAP SMP, we should clarify the following concepts:
• Pairing indicates that two devices have agreed to establish a connection with certain
security levels.
• Bonding indicates that at least one device has sent some kind of indication or
security information, which could be an LTK, CSRK, or IRK, to another device for
future connections. If these two devices can bond with each other, the key
distribution occurs after the pairing, otherwise, no bonding information will be
exchanged. Bonding is not a prerequisite for pairing. However, during pairing the two
devices exchange their characteristics to determine whether the peer device is open
for bonding. If neither of these two devices is open for bonding, no security
information of the peer devices should be stored.
• Authentication is de ned as a method to verify that the device you are connecting
with is indeed the device it claims to be, ensuring it is not a third-party attacker.
However, a de-authentication link does not necessarily mean this link is not secure at
all. When the key for the link encryption has the security attributes that have been
con rmed by both devices, these two devices are considered authenticated. When
STK is used for the authentication, a keyword is generated during the pairing. For
devices with input/output and OOB functions, all the keys generated and exchanged
have the MITM attributes (PIN/larger OOB keys are used, which enforces security). If
Just Works is used, all the keys generated and exchanged have the No MITM
attributes.

24/28
Espressif Systems Submit Documentation Feedback 2024.04
fi
fi
fi
fi
fi
 3. Bluetooth Low Energy

• Authorization is de ned as the assignment of permission to perform an operation

from the application layer. Some applications may require authorization, in which case
the application must be granted permission before being used. If no permission is
given, the whole process will fail.

3.3.2. Safety Management Controller

3.3.2.1.BLE Encryption
The encryption of a Bluetooth LE device can be achieved with two basic methods:
• When no bonding is established between two Bluetooth LE devices, these devices
are encrypted through the pairing procedure, while bonding (or not bonding) is
determined according to the speci c pairing information of these Bluetooth LE
devices.
• Two bonded devices: initiate the encryption through the bonding procedure. When
two devices have already bonded, encryption is initiated with one device resorting to
the original bonding process.
How a master initiates an encryption request in Just Works mode can be seen in the ow
chart below:

Master Slave

API SMP SMP API

esp_ble_set_encryption

smp_pair_req

esp_gap_ble_sec_req_evt

esp_ble_gap_security_rsp

smp_pair_rsp

Encrypt

esp_gap_ble_auth_cmpl_evt
esp_gap_ble_auth_cmpl_evt

Figure 3-6. The Flow Chart of Encryption in Just Works Mode

25/28
Espressif Systems Submit Documentation Feedback 2024.04
fi
fi
fl
 3. Bluetooth Low Energy

How a master initiates an encryption request in Passkey Notify mode can be seen in the
ow chart below:

Master Slave

API SMP SMP API

esp_ble_set_encryption

smp_pair_req

esp_gap_ble_sec_req_evt

esp_ble_gap_security_rsp

esp_gap_ble_passkey_notify_evt
displays the passkey to the user,
smp_pair_rsp esp_ble_passkey_reply
the peer device should enter this
sends the passkey to the
key and sent it to the SMP stack
SMP stack which is
displayed in the peer device

Encrypt

esp_gap_ble_auth_cmpl_evt esp_gap_ble_auth_cmpl_evt

Figure 3-7. The Flow Chart of Encryption in Passkey Notify Mode

3.3.2.2.BLE Bonding
The bonding between two Bluetooth LE devices is achieved by calling a GAP API.
According to the description in the Bluetooth Core Speci cation, the purpose of bonding is
that two Bluetooth LE devices, which have been encrypted by SMP, are able to use the
same keys to encrypt a link when they reconnect with each other, thus simplifying the
reconnection process. These two Bluetooth LE devices exchange encryption keys during
their pairing, and store them for long-term use. The bonding process can be seen in the
ow chart below:

26/28
Espressif Systems Submit Documentation Feedback 2024.04
fl
fl
fi
 3. Bluetooth Low Energy

Master Slave

API SMP LLC LLC SMP API

esp_ble_set_encryption continues if bonding
is completed with the
peer device

llc_start_enc_cmd

llc_ltk_req_evt

llc_ltk_req_reply_cmd

Encrypt

llc_enc_change_evt
llc_enc_change_evt

esp_gap_ble_auth_cmpl_evt

esp_gap_ble_auth_cmpl_evt

Figure 3-8. The Flow Chart of Buletooth LE Bonding Process

⚠ Notice:

The bonding process must be initiated by a master device during the connection.

3.3.3. The Implementation of SMP

The Bluetooth LE SMP calls encryption APIs in Bluetooth LE GAP, registers the Bluetooth
LE GAP callbacks, and obtains the current encryption status through the return values of
events.

27/28
Espressif Systems Submit Documentation Feedback 2024.04
 Disclaimer and Copyright Notice
Information in this document, including URL references, is subject to change without
notice.
THIS DOCUMENT IS PROVIDED AS IS WITH NO WARRANTIES WHATSOEVER,
INCLUDING ANY WARRANTY OF MERCHANTABILITY, NON-INFRINGEMENT, FITNESS
FOR ANY PARTICULAR PURPOSE, OR ANY WARRANTY OTHERWISE ARISING OUT
OF ANY PROPOSAL, SPECIFICATION OR SAMPLE.
All liability, including liability for infringement of any proprietary rights, relating to use of
information in this document is disclaimed. No licenses express or implied, by estoppel or
otherwise, to any intellectual property rights are granted herein.
The Wi-Fi Alliance Member logo is a trademark of the Wi-Fi Alliance. The Bluetooth logo is
a registered trademark of Bluetooth SIG.
All trade names, trademarks and registered trademarks mentioned in this document are
Espressif IoT Team
property of their respective owners, and are hereby acknowledged.
www.espressif.com Copyright © 2024 Espressif Inc. All rights reserved.