Bluetooth LE AT Examples
This document provides an introduction and detailed command examples to illustrate how to utilize Bluetooth® Low Energy AT Commands on ESP32.
Introduction
ESP-AT currently only supports Bluetooth LE 4.2 protocol specification, and the description in this document is only for Bluetooth LE 4.2 protocol specification. Please refer to Core Specification 4.2 for more details.
Bluetooth LE protocol architecture
Bluetooth LE protocol stack is divided into several layers from bottom to top: Physical Layer (PHY)
, Link Layer (LL)
, Host Controller Interface (HCI)
, Logical Link Control and Adaptation Protocol Layer (L2CAP)
, Attribute Protocol (ATT)
, Security Manager Protocol (SMP)
, Generic Attribute Profile (GATT)
, Generic Access Profile (GAP)
.
PHY
: the PHY layer is responsible for transmitting and receiving packets of information on the physical channel. Bluetooth LE uses40
RF channels. Frequency Range: 2402 MHz to 2480 MHz.LL
: the LL layer is responsible for the creation, modification and release of logical links (and, if required, their associated logical transports), as well as the update of parameters related to physical links between devices. It controls the Link Layer state machine in one of the five states ofstandby
,advertising
,scanning
,initiating
andconnected
.HCI
: the HCI layer provides a standardized interface to host and controller. This layer can be implemented by softwareAPI
or controlled by hardware interfacesUART
,SPI
andUSB
.L2CAP
: the L2CAP layer is responsible for protocol multiplexing capability, segmentation, and reassembly operation for data exchanged between the host and the protocol stack.ATT
: the ATT layer implements the peer-to-peer protocol between an attribute server and an attribute client. The ATT client sends commands, requests, and confirmations to the ATT server. The ATT server sends responses, notifications and indications to the client.SMP
: the SMP layer is the peer-to-peer protocol used to generate encryption keys and identity keys. The SMP also manages storage of the encryption keys and identity keys and is responsible for generating random addresses and resolving random addresses to known device identities.GATT
: the GATT layer represents the functionality of the attribute server and, optionally, the attribute client. The profile describes the hierarchy of services, characteristics and attributes used in the attribute server. The layer provides interfaces for discovering, reading, writing and indicating of service characteristics and attributes.GAP
: the GAP represents the base functionality common to all Bluetooth devices such as modes and access procedures used by the transports, protocols and application profiles. GAP services include device discovery, connection modes, security, authentication, association models and service discovery.
Bluetooth LE role division
There are different roles in different levels of the Bluetooth LE protocol architecture. These divisions are not affected by each other.
LL
: devices can be divided intomaster
andslave
, the slave advertises, and the master initiates a connection.GAP
: GAP defines four specific roles:broadcaster
,observer
,peripheral
, andcentral
.GATT
: devices can be divided intoserver
andclient
.
Important
The
Bluetooth LE server
andBluetooth LE client
described in this document are bothGATT
layer roles.At present, ESP-AT supports the existence of
Bluetooth LE server
andBluetooth LE client
at the same time.No matter ESP-AT is initialized as Bluetooth LE server or Bluetooth LE client, the maximum number of devices connected at the same time is
3
.
GATT is actually an attribute transmission protocol, which can be regarded as an application layer protocol for attribute transmission. The structure of this attribute is very simple. It is composed of services
, each service
is composed of different numbers of characteristics
, and each characteristic
is composed of many other elements.
GATT server
and GATT client
roles exist after the Bluetooth LE connection is established. The GATT server stores the data transported over the Attribute Protocol and accepts Attribute Protocol requests, commands and confirmations from the GATT client. In short, the end that provides data is called GATT server
, and the end that accesses data is called GATT client
.
Important
The ESP32 Bluetooth LE server needs to download a
ble_data.bin
into flash to provide Bluetooth LE services.To learn how to generate a
ble_data.bin
, please refer to Customize Bluetooth LE Services Tools.The download address of the
ble_data.bin
is the address ofble_data
inat_customize.csv
, or described inbuild/download.config
.
Bluetooth LE client reads and write services
Below is an example of using two ESP32 development boards, one as a Bluetooth LE server (only as Bluetooth LE server role), the other one as a Bluetooth LE client (only as Bluetooth LE client role). The example shows how to use Bluetooth LE functions with AT commands.
Important
In the following steps, the operations starting with ESP32 Bluetooth LE server
only need to be executed at ESP32 Bluetooth LE server, and the operations starting with ESP32 Bluetooth LE client
only need to be executed at ESP32 Bluetooth LE client.
Bluetooth LE initialization.
ESP32 Bluetooth LE server:
Command:
AT+BLEINIT=2
Response:
OK
ESP32 Bluetooth LE client:
Command:
AT+BLEINIT=1
Response:
OK
ESP32 Bluetooth LE server gets Bluetooth LE address.
Command:
AT+BLEADDR?
Response:
+BLEADDR:"24:0a:c4:d6:e4:46" OK
Note:
The address you obtain may be different from that in the above response. Keep yours handy as you will need it in one of the following steps.
ESP32 Bluetooth LE server creates services.
Command:
AT+BLEGATTSSRVCRE
Response:
OK
ESP32 Bluetooth LE server starts services.
Command:
AT+BLEGATTSSRVSTART
Response:
OK
ESP32 Bluetooth LE server discovers characteristics.
Command:
AT+BLEGATTSCHAR?
Response:
+BLEGATTSCHAR:"char",1,1,0xC300,0x02 +BLEGATTSCHAR:"desc",1,1,1,0x2901 +BLEGATTSCHAR:"char",1,2,0xC301,0x02 +BLEGATTSCHAR:"desc",1,2,1,0x2901 +BLEGATTSCHAR:"char",1,3,0xC302,0x08 +BLEGATTSCHAR:"desc",1,3,1,0x2901 +BLEGATTSCHAR:"char",1,4,0xC303,0x04 +BLEGATTSCHAR:"desc",1,4,1,0x2901 +BLEGATTSCHAR:"char",1,5,0xC304,0x08 +BLEGATTSCHAR:"char",1,6,0xC305,0x10 +BLEGATTSCHAR:"desc",1,6,1,0x2902 +BLEGATTSCHAR:"char",1,7,0xC306,0x20 +BLEGATTSCHAR:"desc",1,7,1,0x2902 +BLEGATTSCHAR:"char",1,8,0xC307,0x02 +BLEGATTSCHAR:"desc",1,8,1,0x2901 +BLEGATTSCHAR:"char",2,1,0xC400,0x02 +BLEGATTSCHAR:"desc",2,1,1,0x2901 +BLEGATTSCHAR:"char",2,2,0xC401,0x02 +BLEGATTSCHAR:"desc",2,2,1,0x2901 OK
ESP32 Bluetooth LE server starts advertising, then the ESP32 Bluetooth LE client starts scanning and lasts for 3 s.
ESP32 Bluetooth LE server:
Command:
AT+BLEADVSTART
Response:
OK
ESP32 Bluetooth LE client:
Command:
AT+BLESCAN=1,3
Response:
OK +BLESCAN:"5b:3b:6c:51:90:49",-87,02011a020a0c0aff4c001005071c3024dc,,1 +BLESCAN:"c4:5b:be:93:ec:66",-84,0201060303111809095647543147572d58020a03,,0 +BLESCAN:"24:0a:c4:d6:e4:46",-29,,,0
Note:
The scan results you obtain may be different from those in the above response.
Establish the Bluetooth LE connection.
ESP32 Bluetooth LE client:
Command:
AT+BLECONN=0,"24:0a:c4:d6:e4:46"
Response:
+BLECONN:0,"24:0a:c4:d6:e4:46" OK
Note:
When entering the above command, replace the address with your ESP32 Bluetooth LE server address.
If the Bluetooth LE connection is established successfully, message
+BLECONN:0,"24:0a:c4:d6:e4:46
will be prompted.If the Bluetooth LE connection is broken, message
+BLECONN:0,-1
will be prompted.
ESP32 Bluetooth LE client discovers services.
Command:
AT+BLEGATTCPRIMSRV=0
Response:
+BLEGATTCPRIMSRV:0,1,0x1801,1 +BLEGATTCPRIMSRV:0,2,0x1800,1 +BLEGATTCPRIMSRV:0,3,0xA002,1 +BLEGATTCPRIMSRV:0,4,0xA003,1 OK
Note:
When discovering services, the ESP32 Bluetooth LE client will get two more default services (UUID: 0x1800 and 0x1801) than what the ESP32 Bluetooth LE server will get. So, for the same service, the <srv_index> received by the ESP32 Bluetooth LE client equals the <srv_index> received by the ESP32 Bluetooth LE server + 2. For example, for service 0xA002, the <srv_index> queried on the ESP32 Bluetooth LE client is 3, if the ESP32 Bluetooth LE server is queried through the command AT+BLEGATTSSRV?, then <srv_index> is 1.
ESP32 Bluetooth LE client discovers characteristics.
Command:
AT+BLEGATTCCHAR=0,3
Response:
+BLEGATTCCHAR:"char",0,3,1,0xC300,0x02 +BLEGATTCCHAR:"desc",0,3,1,1,0x2901 +BLEGATTCCHAR:"char",0,3,2,0xC301,0x02 +BLEGATTCCHAR:"desc",0,3,2,1,0x2901 +BLEGATTCCHAR:"char",0,3,3,0xC302,0x08 +BLEGATTCCHAR:"desc",0,3,3,1,0x2901 +BLEGATTCCHAR:"char",0,3,4,0xC303,0x04 +BLEGATTCCHAR:"desc",0,3,4,1,0x2901 +BLEGATTCCHAR:"char",0,3,5,0xC304,0x08 +BLEGATTCCHAR:"char",0,3,6,0xC305,0x10 +BLEGATTCCHAR:"desc",0,3,6,1,0x2902 +BLEGATTCCHAR:"char",0,3,7,0xC306,0x20 +BLEGATTCCHAR:"desc",0,3,7,1,0x2902 +BLEGATTCCHAR:"char",0,3,8,0xC307,0x02 +BLEGATTCCHAR:"desc",0,3,8,1,0x2901 OK
ESP32 Bluetooth LE client reads a characteristic.
Command:
AT+BLEGATTCRD=0,3,1
Response:
+BLEGATTCRD:0,1,0 OK
Note:
Please note that the target characteristic’s property has to support the read operation.
If the ESP32 Bluetooth LE client reads the characteristic successfully, message
+READ:0,"7c:df:a1:b3:8d:de"
will be prompted on the ESP32 Bluetooth LE Server side.
ESP32 Bluetooth LE client writes a characteristic.
Command:
AT+BLEGATTCWR=0,3,3,,2
Response:
>
The symbol
>
indicates that AT is ready for receiving serial data and you can enter data now. When the requirement of data length determined by the parameter<length>
is met, the writing starts.OK
Note:
If the ESP32 Bluetooth LE client writes the characteristic successfully, message
+WRITE:<conn_index>,<srv_index>,<char_index>,[<desc_index>],<len>,<value>
will be prompted on the ESP32 Bluetooth LE server side.
Indicate a characteristic.
ESP32 Bluetooth LE client:
Command:
AT+BLEGATTCWR=0,3,7,1,2
Response:
>
The symbol
>
indicates that AT is ready for receiving serial data and you can enter data now. When the requirement of data length determined by the parameter<length>
is met, the writing starts.To receive data from ESP32 Bluetooth LE server (through the
notify
or theindicate
method), the ESP32 Bluetooth LE client needs to register with the server in advance. Write the value0x0001
to use thenotify
method, and0x0002
to use theindicate
method. This example writes the0x0002
to use theindicate
method.OK
Note:
If the ESP32 Bluetooth LE client writes the descriptor successfully, message
+WRITE:<conn_index>,<srv_index>,<char_index>,<desc_index>,<len>,<value>
will be prompted on the ESP32 Bluetooth LE server side.
ESP32 Bluetooth LE server:
Command:
AT+BLEGATTSIND=0,1,7,3
Response:
>
The symbol
>
indicates that AT is ready for receiving serial data and you can enter data now. When the requirement of data length determined by the parameter<length>
is met, the indication starts.OK
Note:
If the ESP32 Bluetooth LE client receives the indication, message
+INDICATE:<conn_index>,<srv_index>,<char_index>,<len>,<value>
will be prompted.For the same service, the <srv_index> on the ESP32 Bluetooth LE client side equals the <srv_index> on the ESP32 Bluetooth LE server side + 2.
For the permissions of the characteristics in the services, please refer to How to Customize Bluetooth® LE Services.
Bluetooth LE server read and write services
Below is an example of using two ESP32 development boards, one as a Bluetooth LE server (only as Bluetooth LE server role), the other one as a Bluetooth LE client (only as Bluetooth LE client role). The example shows how to establish a Bluetooth LE connection, as well as the read and write characteristics of the server and client settings, and notification characteristics.
Important
In the step, the operations starting with ESP32 Bluetooth LE server
only need to be executed at ESP32 Bluetooth LE server, and the operations starting with ESP32 Bluetooth LE client
only need to be executed at ESP32 Bluetooth LE client.
Bluetooth LE initialization.
ESP32 Bluetooth LE server:
Command:
AT+BLEINIT=2
Response:
OK
ESP32 Bluetooth LE client:
Command:
AT+BLEINIT=1
Response:
OK
ESP32 Bluetooth LE server creates services.
Command:
AT+BLEGATTSSRVCRE
Response:
OK
ESP32 Bluetooth LE server starts services.
Command:
AT+BLEGATTSSRVSTART
Response:
OK
ESP32 Bluetooth LE server gets its MAC address.
Command:
AT+BLEADDR?
Response:
+BLEADDR:"24:0a:c4:d6:e4:46" OK
Note:
The address you obtain may be different from that in the above response. Keep yours handy as you will need it in one of the following steps.
Set Bluetooth LE advertising data.
Command:
AT+BLEADVDATA="0201060A09457370726573736966030302A0"
Response:
OK
ESP32 Bluetooth LE server starts advertising.
Command:
AT+BLEADVSTART
Response:
OK
ESP32 Bluetooth LE client creates services.
Command:
AT+BLEGATTSSRVCRE
Response:
OK
ESP32 Bluetooth LE client starts services.
Command:
AT+BLEGATTSSRVSTART
Response:
OK
ESP32 Bluetooth LE client gets Bluetooth LE address.
Command:
AT+BLEADDR?
Response:
+BLEADDR:"24:0a:c4:03:a7:4e" OK
Note:
The address you obtain may be different from that in the above response. Keep yours handy as you will need it in one of the following steps.
ESP32 Bluetooth LE client enables a scanning for three seconds.
Command:
AT+BLESCAN=1,3
Response:
OK +BLESCAN:"5b:3b:6c:51:90:49",-87,02011a020a0c0aff4c001005071c3024dc,,1 +BLESCAN:"c4:5b:be:93:ec:66",-84,0201060303111809095647543147572d58020a03,,0 +BLESCAN:"24:0a:c4:d6:e4:46",-29,,,0
Note:
The scan results you obtain may be different from those in the above response.
Establish the Bluetooth LE connection.
ESP32 Bluetooth LE client:
Command:
AT+BLECONN=0,"24:0a:c4:d6:e4:46"
Response:
+BLECONN:0,"24:0a:c4:d6:e4:46" OK
Note:
When entering the above command, replace the address with your ESP32 Bluetooth LE server address.
If the Bluetooth LE connection is established successfully, message
+BLECONN:0,"24:0a:c4:d6:e4:46
will be prompted.If the Bluetooth LE connection is broken, message
+BLECONN:0,-1
will be prompted.
ESP32 Bluetooth LE server:
Command:
AT+BLECONN=0,"24:0a:c4:03:a7:4e"
Response:
+BLECONN:0,"24:0a:c4:03:a7:4e" OK
Note:
When entering the above command, replace the address with your ESP32 Bluetooth LE server address.
If the Bluetooth LE connection is established successfully, the message
OK
will be prompted and the message+BLECONN:0,"24:0a:c4:03:a7:4e
will not be prompted.If the Bluetooth LE connection is broken, the message
ERROR
will be prompted and the message+BLECONN:0,-1
will not be prompted.
ESP32 Bluetooth LE client discovers local services.
Command:
AT+BLEGATTSSRV?
Response:
+BLEGATTSSRV:1,1,0xA002,1 +BLEGATTSSRV:2,1,0xA003,1 OK
ESP32 Bluetooth LE client discovers local characteristics.
Command:
AT+BLEGATTSCHAR?
Response:
+BLEGATTSCHAR:"char",1,1,0xC300,0x02 +BLEGATTSCHAR:"desc",1,1,1,0x2901 +BLEGATTSCHAR:"char",1,2,0xC301,0x02 +BLEGATTSCHAR:"desc",1,2,1,0x2901 +BLEGATTSCHAR:"char",1,3,0xC302,0x08 +BLEGATTSCHAR:"desc",1,3,1,0x2901 +BLEGATTSCHAR:"char",1,4,0xC303,0x04 +BLEGATTSCHAR:"desc",1,4,1,0x2901 +BLEGATTSCHAR:"char",1,5,0xC304,0x08 +BLEGATTSCHAR:"char",1,6,0xC305,0x10 +BLEGATTSCHAR:"desc",1,6,1,0x2902 +BLEGATTSCHAR:"char",1,7,0xC306,0x20 +BLEGATTSCHAR:"desc",1,7,1,0x2902 +BLEGATTSCHAR:"char",1,8,0xC307,0x02 +BLEGATTSCHAR:"desc",1,8,1,0x2901 +BLEGATTSCHAR:"char",2,1,0xC400,0x02 +BLEGATTSCHAR:"desc",2,1,1,0x2901 +BLEGATTSCHAR:"char",2,2,0xC401,0x02 +BLEGATTSCHAR:"desc",2,2,1,0x2901 OK
ESP32 Bluetooth LE server discovers primary services.
Command:
AT+BLEGATTCPRIMSRV=0
Response:
+BLEGATTCPRIMSRV:0,1,0x1801,1 +BLEGATTCPRIMSRV:0,2,0x1800,1 +BLEGATTCPRIMSRV:0,3,0xA002,1 +BLEGATTCPRIMSRV:0,4,0xA003,1 OK
Note:
When discovering services, the ESP32 Bluetooth LE server will get two more default services (UUID: 0x1800 and 0x1801) than what the ESP32 Bluetooth LE client will get. So, for the same service, the <srv_index> received by the ESP32 Bluetooth LE server equals the <srv_index> received by the ESP32 Bluetooth LE client + 2. For example, for service 0xA002, the <srv_index> queried on the ESP32 Bluetooth LE client is 3, if the ESP32 Bluetooth LE server is queried through the command AT+BLEGATTSSRV?, then <srv_index> is 1.
ESP32 Bluetooth LE server discovers primary characteristics.
Command:
AT+BLEGATTCCHAR=0,3
Response:
+BLEGATTCCHAR:"char",0,3,1,0xC300,0x02 +BLEGATTCCHAR:"desc",0,3,1,1,0x2901 +BLEGATTCCHAR:"char",0,3,2,0xC301,0x02 +BLEGATTCCHAR:"desc",0,3,2,1,0x2901 +BLEGATTCCHAR:"char",0,3,3,0xC302,0x08 +BLEGATTCCHAR:"desc",0,3,3,1,0x2901 +BLEGATTCCHAR:"char",0,3,4,0xC303,0x04 +BLEGATTCCHAR:"desc",0,3,4,1,0x2901 +BLEGATTCCHAR:"char",0,3,5,0xC304,0x08 +BLEGATTCCHAR:"char",0,3,6,0xC305,0x10 +BLEGATTCCHAR:"desc",0,3,6,1,0x2902 +BLEGATTCCHAR:"char",0,3,7,0xC306,0x20 +BLEGATTCCHAR:"desc",0,3,7,1,0x2902 +BLEGATTCCHAR:"char",0,3,8,0xC307,0x02 +BLEGATTCCHAR:"desc",0,3,8,1,0x2901 OK
ESP32 Bluetooth LE client sets characteristics.
Select the service characteristic that supports the write operation (characteristic) to set the characteristic.
Command:
AT+BLEGATTSSETATTR=1,8,,1
Response:
>
Command:
Write 1 byte ``9``
Response:
OK
ESP32 Bluetooth LE server reads characteristics.
Command:
AT+BLEGATTCRD=0,3,8,
Response:
+BLEGATTCRD:0,1,9 OK
ESP32 Bluetooth LE client write characteristics.
Select the service characteristic that supports the write operation to write the characteristics.
Command:
AT+BLEGATTCWR=0,3,6,1,2
Response:
>
Command:
Write 2 bytes ``12``
Response:
OK
Note:
If the Bluetooth LE server successfully writes the service characteristic value, the Bluetooth LE client will prompt
+WRITE:0,1,6,1,2,12
.
ESP32 Bluetooth LE client notify characteristics.
Command:
AT+BLEGATTSNTFY=0,1,6,10
Response:
>
Command:
Write 10 bytes ``1234567890``
Response:
OK
Note:
If the ESP32 Bluetooth LE client’s notify characteristic is successfully sent to the server, the Bluetooth LE server
+NOTIFY:0,3,6,10,1234567890
will be prompt.
Encrypt Bluetooth LE connection
Below is an example of using two ESP32 development boards, one as a Bluetooth LE server (only as Bluetooth LE server role), the other one as a Bluetooth LE client (only as Bluetooth LE client role). The example shows how to encrypt Bluetooth LE connection.
Important
In the following steps, the operations starting with
ESP32 Bluetooth LE server
only need to be executed at ESP32 Bluetooth LE server, and the operations starting withESP32 Bluetooth LE client
only need to be executed at ESP32 Bluetooth LE client.Encryption
andbonding
are two different concepts.bonding
is just a long-term key stored locally after successful encryption.ESP-AT allows a maximum of
10
devices to be bonded.
Bluetooth LE initialization.
ESP32 Bluetooth LE server:
Command:
AT+BLEINIT=2
Response:
OK
ESP32 Bluetooth LE client:
Command:
AT+BLEINIT=1
Response:
OK
ESP32 Bluetooth LE server gets Bluetooth LE address.
Command:
AT+BLEADDR?
Response:
+BLEADDR:"24:0a:c4:d6:e4:46" OK
Note:
The address you obtain may be different from that in the above response. Keep yours handy as you will need it in one of the following steps.
ESP32 Bluetooth LE server creates services.
Command:
AT+BLEGATTSSRVCRE
Response:
OK
ESP32 Bluetooth LE server starts services.
Command:
AT+BLEGATTSSRVSTART
Response:
OK
ESP32 Bluetooth LE server discovers characteristics.
Command:
AT+BLEGATTSCHAR?
Response:
+BLEGATTSCHAR:"char",1,1,0xC300,0x02 +BLEGATTSCHAR:"desc",1,1,1,0x2901 +BLEGATTSCHAR:"char",1,2,0xC301,0x02 +BLEGATTSCHAR:"desc",1,2,1,0x2901 +BLEGATTSCHAR:"char",1,3,0xC302,0x08 +BLEGATTSCHAR:"desc",1,3,1,0x2901 +BLEGATTSCHAR:"char",1,4,0xC303,0x04 +BLEGATTSCHAR:"desc",1,4,1,0x2901 +BLEGATTSCHAR:"char",1,5,0xC304,0x08 +BLEGATTSCHAR:"char",1,6,0xC305,0x10 +BLEGATTSCHAR:"desc",1,6,1,0x2902 +BLEGATTSCHAR:"char",1,7,0xC306,0x20 +BLEGATTSCHAR:"desc",1,7,1,0x2902 +BLEGATTSCHAR:"char",1,8,0xC307,0x02 +BLEGATTSCHAR:"desc",1,8,1,0x2901 +BLEGATTSCHAR:"char",2,1,0xC400,0x02 +BLEGATTSCHAR:"desc",2,1,1,0x2901 +BLEGATTSCHAR:"char",2,2,0xC401,0x02 +BLEGATTSCHAR:"desc",2,2,1,0x2901 OK
ESP32 Bluetooth LE server starts advertising, then the ESP32 Bluetooth LE client starts scanning and lasts for 3 s.
ESP32 Bluetooth LE server:
Command:
AT+BLEADVSTART
Response:
OK
ESP32 Bluetooth LE client:
Command:
AT+BLESCAN=1,3
Response:
OK +BLESCAN:"5b:3b:6c:51:90:49",-87,02011a020a0c0aff4c001005071c3024dc,,1 +BLESCAN:"c4:5b:be:93:ec:66",-84,0201060303111809095647543147572d58020a03,,0 +BLESCAN:"24:0a:c4:d6:e4:46",-29,,,0
Note:
The scan results you obtain may be different from those in the above response.
Establish the Bluetooth LE connection.
ESP32 Bluetooth LE client:
Command:
AT+BLECONN=0,"24:0a:c4:d6:e4:46"
Response:
+BLECONN:0,"24:0a:c4:d6:e4:46" OK
Note:
When entering the above command, replace the address with your ESP32 Bluetooth LE server address.
If the Bluetooth LE connection is established successfully, message
+BLECONN:0,"24:0a:c4:d6:e4:46
will be prompted.If the Bluetooth LE connection is broken, message
+BLECONN:0,-1
will be prompted.
ESP32 Bluetooth LE client discovers services.
Command:
AT+BLEGATTCPRIMSRV=0
Response:
+BLEGATTCPRIMSRV:0,1,0x1801,1 +BLEGATTCPRIMSRV:0,2,0x1800,1 +BLEGATTCPRIMSRV:0,3,0xA002,1 +BLEGATTCPRIMSRV:0,4,0xA003,1 OK
Note:
When discovering services, the ESP32 Bluetooth LE client will get two more default services (UUID: 0x1800 and 0x1801) than what the ESP32 Bluetooth LE server will get. So, for the same service, the <srv_index> received by the ESP32 Bluetooth LE client equals the <srv_index> received by the ESP32 Bluetooth LE server + 2. For example, for service 0xA002, the <srv_index> queried on the ESP32 Bluetooth LE client is 3, if the ESP32 Bluetooth LE server is queried through the command AT+BLEGATTSSRV?, then <srv_index> is 1.
ESP32 Bluetooth LE client discovers characteristics.
Command:
AT+BLEGATTCCHAR=0,3
Response:
+BLEGATTCCHAR:"char",0,3,1,0xC300,0x02 +BLEGATTCCHAR:"desc",0,3,1,1,0x2901 +BLEGATTCCHAR:"char",0,3,2,0xC301,0x02 +BLEGATTCCHAR:"desc",0,3,2,1,0x2901 +BLEGATTCCHAR:"char",0,3,3,0xC302,0x08 +BLEGATTCCHAR:"desc",0,3,3,1,0x2901 +BLEGATTCCHAR:"char",0,3,4,0xC303,0x04 +BLEGATTCCHAR:"desc",0,3,4,1,0x2901 +BLEGATTCCHAR:"char",0,3,5,0xC304,0x08 +BLEGATTCCHAR:"char",0,3,6,0xC305,0x10 +BLEGATTCCHAR:"desc",0,3,6,1,0x2902 +BLEGATTCCHAR:"char",0,3,7,0xC306,0x20 +BLEGATTCCHAR:"desc",0,3,7,1,0x2902 +BLEGATTCCHAR:"char",0,3,8,0xC307,0x02 +BLEGATTCCHAR:"desc",0,3,8,1,0x2901 OK
Set Bluetooth LE encryption parameters. Set
auth_req
toSC_MITM_BOND
, server’siocap
toKeyboardOnly
, client’siocap
toKeyboardDisplay
,key_size
to16
,init_key
to3
,rsp_key
to3
.ESP32 Bluetooth LE server:
Command:
AT+BLESECPARAM=13,2,16,3,3
Response:
OK
ESP32 Bluetooth LE client:
Command:
AT+BLESECPARAM=13,4,16,3,3
Response:
OK
Note:
In this example, ESP32 Bluetooth LE server enters the pairing code and ESP32 Bluetooth LE client displays the pairing code.
ESP-AT supports
Legacy Pairing
andSecure Connections
encryption methods, but the latter has a higher priority. If the peer also supportsSecure Connections
, thenSecure Connections
will be used for encryption.
ESP32 Bluetooth LE client initiates encryption request.
Command:
AT+BLEENC=0,3
Response:
OK
Note:
If the ESP32 Bluetooth LE server successfully receives the encryption request, message
+BLESECREQ:0
will be prompted on the ESP32 Bluetooth LE server side.ESP32 Bluetooth LE server responds to the pairing request.
Command:
AT+BLEENCRSP=0,1
Response:
OK
Note:
If the ESP32 Bluetooth LE client successfully receives the pairing response, a 6-digit pairing code will generate on the ESP32 Bluetooth LE client side.
In this example, message
+BLESECNTFYKEY:0,793718
will be prompted on the ESP32 Bluetooth LE client side. Pairing code is793718
.
ESP32 Bluetooth LE server replies pairing code.
Command:
AT+BLEKEYREPLY=0,793718
Response:
OK
After running this command, there will be corresponding messages prompt on both the ESP32 Bluetooth LE server and the ESP32 Bluetooth LE client.
ESP32 Bluetooth LE server:
+BLESECKEYTYPE:0,16 +BLESECKEYTYPE:0,1 +BLESECKEYTYPE:0,32 +BLESECKEYTYPE:0,2 +BLEAUTHCMPL:0,0
ESP32 Bluetooth LE client:
+BLESECNTFYKEY:0,793718 +BLESECKEYTYPE:0,2 +BLESECKEYTYPE:0,16 +BLESECKEYTYPE:0,1 +BLESECKEYTYPE:0,32 +BLEAUTHCMPL:0,0
You can ignore the message starting with
+BLESECKEYTYPE
. In terms of the second parameter in the message+BLEAUTHCMPL:0,0
,0
means encryption is successful, and1
means encryption fails.
Establish SPP connection between two ESP32 development boards and transmit data in UART-Bluetooth LE Passthrough Mode
Below is an example of using two ESP32 development boards, one as a Bluetooth LE server (only as Bluetooth LE server role), the other one as a Bluetooth LE client (only as Bluetooth LE client role). The example shows how to build Bluetooth LE SPP (Serial Port Profile, UART-Bluetooth LE passthrough mode) with AT commands.
Important
In the following steps, the operations starting with ESP32 Bluetooth LE server
only need to be executed at ESP32 Bluetooth LE server, and the operations starting with ESP32 Bluetooth LE client
only need to be executed at ESP32 Bluetooth LE client.
Bluetooth LE initialization.
ESP32 Bluetooth LE server:
Command:
AT+BLEINIT=2
Response:
OK
ESP32 Bluetooth LE client:
Command:
AT+BLEINIT=1
Response:
OK
ESP32 Bluetooth LE server creates services.
Command:
AT+BLEGATTSSRVCRE
Response:
OK
ESP32 Bluetooth LE server starts services.
Command:
AT+BLEGATTSSRVSTART
Response:
OK
ESP32 Bluetooth LE server gets Bluetooth LE address.
Command:
AT+BLEADDR?
Response:
+BLEADDR:"24:0a:c4:d6:e4:46" OK
Note:
The address you obtain may be different from that in the above response. Keep yours handy as you will need it in one of the following steps.
Set Bluetooth LE advertising data.
Command:
AT+BLEADVDATA="0201060A09457370726573736966030302A0"
Response:
OK
ESP32 Bluetooth LE server starts advertising.
Command:
AT+BLEADVSTART
Response:
OK
ESP32 Bluetooth LE client enables a scanning for three seconds.
Command:
AT+BLESCAN=1,3
Response:
OK +BLESCAN:"24:0a:c4:d6:e4:46",-78,0201060a09457370726573736966030302a0,,0 +BLESCAN:"45:03:cb:ac:aa:a0",-62,0201060aff4c001005441c61df7d,,1 +BLESCAN:"24:0a:c4:d6:e4:46",-26,0201060a09457370726573736966030302a0,,0
Note:
The scan results you obtain may be different from those in the above response.
Establish the Bluetooth LE connection.
ESP32 Bluetooth LE client:
Command:
AT+BLECONN=0,"24:0a:c4:d6:e4:46"
Response:
+BLECONN:0,"24:0a:c4:d6:e4:46" OK
Note:
When entering the above command, replace the address your ESP32 Bluetooth LE server address.
If the Bluetooth LE connection is established successfully, message
+BLECONN:0,"24:0a:c4:d6:e4:46
will be prompted.If the Bluetooth LE connection is broken, message
+BLECONN:0,-1
will be prompted.
ESP32 Bluetooth LE server discovers local services.
Command:
AT+BLEGATTSSRV?
Response:
+BLEGATTSSRV:1,1,0xA002,1 +BLEGATTSSRV:2,1,0xA003,1 OK
ESP32 Bluetooth LE server discovers local characteristics.
Command:
AT+BLEGATTSCHAR?
Response:
+BLEGATTSCHAR:"char",1,1,0xC300,0x02 +BLEGATTSCHAR:"desc",1,1,1,0x2901 +BLEGATTSCHAR:"char",1,2,0xC301,0x02 +BLEGATTSCHAR:"desc",1,2,1,0x2901 +BLEGATTSCHAR:"char",1,3,0xC302,0x08 +BLEGATTSCHAR:"desc",1,3,1,0x2901 +BLEGATTSCHAR:"char",1,4,0xC303,0x04 +BLEGATTSCHAR:"desc",1,4,1,0x2901 +BLEGATTSCHAR:"char",1,5,0xC304,0x08 +BLEGATTSCHAR:"char",1,6,0xC305,0x10 +BLEGATTSCHAR:"desc",1,6,1,0x2902 +BLEGATTSCHAR:"char",1,7,0xC306,0x20 +BLEGATTSCHAR:"desc",1,7,1,0x2902 +BLEGATTSCHAR:"char",1,8,0xC307,0x02 +BLEGATTSCHAR:"desc",1,8,1,0x2901 +BLEGATTSCHAR:"char",2,1,0xC400,0x02 +BLEGATTSCHAR:"desc",2,1,1,0x2901 +BLEGATTSCHAR:"char",2,2,0xC401,0x02 +BLEGATTSCHAR:"desc",2,2,1,0x2901 OK
ESP32 Bluetooth LE client discovers services.
Command:
AT+BLEGATTCPRIMSRV=0
Response:
+BLEGATTCPRIMSRV:0,1,0x1801,1 +BLEGATTCPRIMSRV:0,2,0x1800,1 +BLEGATTCPRIMSRV:0,3,0xA002,1 +BLEGATTCPRIMSRV:0,4,0xA003,1 OK
Note:
When discovering services, the ESP32 Bluetooth LE client will get two more default services (UUID: 0x1800 and 0x1801) than what the ESP32 Bluetooth LE server will get. So, for the same service, the <srv_index> received by the ESP32 Bluetooth LE client equals the <srv_index> received by the ESP32 Bluetooth LE server + 2. For example, for service 0xA002, the <srv_index> queried on the ESP32 Bluetooth LE client is 3, if the ESP32 Bluetooth LE server is queried through the command AT+BLEGATTSSRV?, then <srv_index> is 1.
ESP32 Bluetooth LE client discovers characteristics.
Command:
AT+BLEGATTCCHAR=0,3
Response:
+BLEGATTCCHAR:"char",0,3,1,0xC300,0x02 +BLEGATTCCHAR:"desc",0,3,1,1,0x2901 +BLEGATTCCHAR:"char",0,3,2,0xC301,0x02 +BLEGATTCCHAR:"desc",0,3,2,1,0x2901 +BLEGATTCCHAR:"char",0,3,3,0xC302,0x08 +BLEGATTCCHAR:"desc",0,3,3,1,0x2901 +BLEGATTCCHAR:"char",0,3,4,0xC303,0x04 +BLEGATTCCHAR:"desc",0,3,4,1,0x2901 +BLEGATTCCHAR:"char",0,3,5,0xC304,0x08 +BLEGATTCCHAR:"char",0,3,6,0xC305,0x10 +BLEGATTCCHAR:"desc",0,3,6,1,0x2902 +BLEGATTCCHAR:"char",0,3,7,0xC306,0x20 +BLEGATTCCHAR:"desc",0,3,7,1,0x2902 +BLEGATTCCHAR:"char",0,3,8,0xC307,0x02 +BLEGATTCCHAR:"desc",0,3,8,1,0x2901 OK
ESP32 Bluetooth LE client Configures Bluetooth LE SPP.
Set a characteristic that enables writing permission to TX channel for sending data. Set another characteristic that supports notification or indication to RX channel for receiving data.
Command:
AT+BLESPPCFG=1,3,5,3,7
Response:
OK
ESP32 Bluetooth LE client enables Bluetooth LE SPP.
Command:
AT+BLESPP
Response:
OK >
This response indicates that AT has entered Bluetooth LE SPP mode and can send and receive data.
Note:
After the ESP32 Bluetooth LE client enables Bluetooth LE SPP, data received from serial port will be transmitted to the Bluetooth LE server directly.
ESP32 Bluetooth LE server Configures Bluetooth LE SPP.
Set a characteristic that supports notification or indication to TX channel for sending data. Set another characteristic that enables writing permission to RX channel for receiving data.
Command:
AT+BLESPPCFG=1,1,7,1,5
Response:
OK
ESP32 Bluetooth LE server enables Bluetooth LE SPP.
Command:
AT+BLESPP
Response:
OK >
This response indicates that AT has entered Bluetooth LE SPP mode and can send and receive data.
Note:
After the ESP32 Bluetooth LE server enables Bluetooth LE SPP, the data received from serial port will be transmitted to the Bluetooth LE client directly.
If the ESP32 Bluetooth LE client does not enable Bluetooth LE SPP first, or uses other device as Bluetooth LE client, then the Bluetooth LE client needs to listen to the notification or indication first. For example, if the ESP32 Bluetooth LE client does not enable Bluetooth LE SPP first, then it should use command
AT+BLEGATTCWR=0,3,7,1,1
to enable listening function first, so that the ESP32 Bluetooth LE server can transmit successfully.For the same service, the <srv_index> on the ESP32 Bluetooth LE client side equals the <srv_index> on the ESP32 Bluetooth LE server side + 2.
Establish SPP connection between ESP32 and mobile phone and transmit data in UART-Bluetooth LE passthrough mode
The example shows how to establish SPP connection between an ESP32 development board (only serving as the Bluetooth LE server role) and a mobile phone (only serve as the Bluetooth LE client role) and how to transmit data between them in UART-Bluetooth LE passthrough mode.
Important
In the following steps, the operations starting with ESP32 Bluetooth LE server
only need to be executed at ESP32 Bluetooth LE server, and those Bluetooth LE client only need to be executed at the Bluetooth debugging assistant of the mobile phone.
First, you need to download the Bluetooth LE debugging assistant on the mobile phone, such as nRF Connect app (Android) and LightBlue (iOS).
Bluetooth LE initialization.
ESP32 Bluetooth LE server:
Command:
AT+BLEINIT=2
Response:
OK
ESP32 Bluetooth LE server creates services.
Command:
AT+BLEGATTSSRVCRE
Response:
OK
ESP32 Bluetooth LE server starts services.
Command:
AT+BLEGATTSSRVSTART
Response:
OK
ESP32 Bluetooth LE server gets its MAC address.
Command:
AT+BLEADDR?
Response:
+BLEADDR:"24:0a:c4:d6:e4:46" OK
Note:
The address you obtain may be different from that in the above response. Keep yours handy as you will need it in one of the following steps.
Set Bluetooth LE advertising data.
Command:
AT+BLEADVDATA="0201060A09457370726573736966030302A0"
Response:
OK
ESP32 Bluetooth LE server starts advertising.
Command:
AT+BLEADVSTART
Response:
OK
Establish the Bluetooth LE connection.
Open the nRF debugging assistant on your mobile phone, and open SCAN to start scanning. When you find the MAC address of the ESP32 Bluetooth LE server, click
CONNECT
. Then, ESP32 should print the log similar to+BLECONN:0,"60:51:42:fe:98:aa"
, which indicates that Bluetooth LE connection has been established.ESP32 Bluetooth LE server discovers local services.
Command:
AT+BLEGATTSSRV?
Response:
+BLEGATTSSRV:1,1,0xA002,1 +BLEGATTSSRV:2,1,0xA003,1 OK
ESP32 Bluetooth LE server discovers local characteristics.
Command:
AT+BLEGATTSCHAR?
Response:
+BLEGATTSCHAR:"char",1,1,0xC300,0x02 +BLEGATTSCHAR:"desc",1,1,1,0x2901 +BLEGATTSCHAR:"char",1,2,0xC301,0x02 +BLEGATTSCHAR:"desc",1,2,1,0x2901 +BLEGATTSCHAR:"char",1,3,0xC302,0x08 +BLEGATTSCHAR:"desc",1,3,1,0x2901 +BLEGATTSCHAR:"char",1,4,0xC303,0x04 +BLEGATTSCHAR:"desc",1,4,1,0x2901 +BLEGATTSCHAR:"char",1,5,0xC304,0x08 +BLEGATTSCHAR:"char",1,6,0xC305,0x10 +BLEGATTSCHAR:"desc",1,6,1,0x2902 +BLEGATTSCHAR:"char",1,7,0xC306,0x20 +BLEGATTSCHAR:"desc",1,7,1,0x2902 +BLEGATTSCHAR:"char",1,8,0xC307,0x02 +BLEGATTSCHAR:"desc",1,8,1,0x2901 +BLEGATTSCHAR:"char",2,1,0xC400,0x02 +BLEGATTSCHAR:"desc",2,1,1,0x2901 +BLEGATTSCHAR:"char",2,2,0xC401,0x02 +BLEGATTSCHAR:"desc",2,2,1,0x2901 OK
Bluetooth LE client discovers services.
Click
UnKnown Service
ofUUID:0xA002
on the mobile phone nRF debugging assistant client.ESP32 Bluetooth LE client discovers characteristics.
In the next-level option of
UnKnown Service
ofUUID:0xA002
of the mobile phone nRF debugging assistant client, click the right button of the service feature whose Properties is NOTIFY or INDICATE (here ESP-AT default Properties The service characteristics of NOTIFY or INDICATE are 0xC305 and 0xC306) and start to listen for the service characteristics of NOTIFY or INDICATE.ESP32 Bluetooth LE server configures Bluetooth LE SPP.
Set a characteristic that supports notification or indication to TX channel for sending data. Set another characteristic that enables writing permission to RX channel for receiving data.
Command:
AT+BLESPPCFG=1,1,7,1,5
Response:
OK
ESP32 Bluetooth LE server enables Bluetooth LE SPP.
Command:
AT+BLESPP
Response:
OK >
This response indicates that AT has entered Bluetooth LE SPP mode and can send and receive data.
Bluetooth LE client sends data.
In the nRF debugging assistant client, select the 0xC304 service characteristic value and send the data
test
to the ESP32 Bluetooth LE server. Then, the ESP32 Bluetooth LE server can receive thetest
.ESP32 Bluetooth LE server sends data.
The ESP32 Bluetooth LE server sends
test
, and then the nRF debugging assistant client can receivetest
.