esp-at application: BLE Command Set

Table of Contents

• 一: Overview
• 二: Classification of Commands
  • 2.1 Roles
  • 2.2 Functions
• 三: BLE Application Example
  • 3.1 iBeacon Demo
  • 3.2 Scanning Surrounding Devices
  • 3.3 Establishing BLE Connection
  • 3.4 Transferring Data
    • 3.4.1 Server: Create and Start Services
    • 3.4.2 Server: Query for Local Services
    • 3.4.3 Client: Discover Services
    • 3.4.4 Client: Read and Write
    • 3.4.5 Client: Register notification
    • 3.4.6 Server: Send Data to the Client
• 四: BLE Encryption
  • 4.1 Encryption Parameter Setting
  • 4.2 Combinations of Encryption Parameters
  • 4.3 Encryption Example
• 五: BLE SPP Implementation

一: Overview

ESP-AT BLE commands support two roles: BLE server and BLE client. A device can be used either as a server or a client at a time.

When used as a BLE server, the device can be connected to 3 clients at the same time; when used as a BLE client, the device can be connected to 3 servers at the same time.

Besides common GATT and GAP commands, ESP-AT BLE also supports BLE HID, which is used to emulate a mouse, keyboard, etc.

ESP-AT BLE commands can almost satisfy all your needs, including customizing sevices, customizing adversiting data, discovering service, transferring data, updating connection parameters, updating MTU size, and setting encryption? parameters.
In addition, ESP-AT BLE has a private BLE transparent transmission protocol. On top of classic Bluetooth transparent transmission, you can also use BLE transparent transmission.

二: Classification of Commands

ESP-AT BLE commands are classified as follows, for the convenience of those not familiar with the BLE protocol.

2.1 Roles

ESP-AT BLE commands are based on GAP and GATT profiles. Before inializing a device, please determine whether to use it as a client or a server.

Initialize the device as a client:

AT+BLEINIT=1

OK

Initialize the device as a server:

AT+BLEINIT=2

OK

To switch a device from being a server to a client, please deinit the protocol stack and reintialize the device as a client.

Turn Off BLE:

AT+BLEINIT=0

OK

Commands for the client and the server are somewhat different. Please check description below for details:

Commands specific to BLE client:

AT+BLESCANPARAM      // Set scanning parameters
AT+BLESCAN           // Enable or disable scanning
AT+BLECFGMTU         // Exchange MTU size
AT+BLECONN           // Connect to remote devices
AT+BLEGATTCPRIMSRV   // Discover included services. Access primary services
AT+BLEGATTCINCLSRV   // Access included services within primary services
AT+BLEGATTCCHAR      // Search characteristics within services
AT+BLEGATTCWR        // Write to characteristics
AT+BLEGATTCRD        // Read from characteristics
AT+BLECONNPARAM      // Update connection parameters

Commands specific to BLE server:

AT+BLEADVPARAM       // Set advertising parameters
AT+BLEADVDATA        // Set advertising data
AT+BLESCANRSPDATA    // Scan response data
AT+BLEADVSTART       // Enable advertising
AT+BLEADVSTOP        // Disable advertising
AT+BLEGATTSSRVCRE    // Create services
AT+BLEGATTSSRVSTART  // Start services
AT+BLEGATTSSRV       // Search local services
AT+BLEGATTSCHAR      // Search characteristics within local services
AT+BLEGATTSNTFY      // Send a notification to the client
AT+BLEGATTSIND       // Send an indication to the client
AT+BLEGATTSSETATTR   // Set characteristics locally

Commands used by BLE client and BLE server:

AT+BLEINIT           // Initialize the BLE protocol stack
AT+BLEADDR           // Get BLE MAC address
AT+BLENAME           // Set or get BLE name
AT+BLEDISCONN        // Break connection to the remote device
AT+BLEDATALEN        // Set packet data length
AT+BLESPPCFG         // Configure BLE transparent transmission parameters
AT+BLESPP            // Enter BLE transparent transmission mode
AT+BLESECPARAM       // Set BLE encryption parameters
AT+BLEENC            // Initiate BLE encryption request
AT+BLEENCRSP         // Respond to BLE encryption request
AT+BLEKEYREPLY       // Enter passkey of the other side
AT+BLEENCDEV         // Get information about bonded devices
AT+BLEENCCLEAR       // Delete information about bonded devices
AT+BLESETKEY         // Set BLE static passkey

2.2 Functions

There are over 30 commands, and they have the following main functions:

• Initialization
• Adversiting and Scanning
• Connection and Communication
• Parameter Update
• Encryption

Initialization
Initialization is the first step. Please enable the BLE protocol stack, and configure local parameters such as:

• Scanning parameters: AT+BLESCANPARAM
• Advertising parameters: AT+BLEADVPARAM
• Device name: AT+BLENAME
• Encryption parameters: AT+BLENAME
• Advertising data: AT+BLEADVDATA, AT+BLESCANRSPDATA

If these parameters are not set, the default will be used (please check the default using the search command, or refer to ESP-AT Command Set).

Adversiting and Scanning
The purpose of following commands is implied by their names.

• Advertising: AT+BLEADVSTART, AT+BLEADVSTOP
• Scanning: AT+BLESCAN

Advertising is the prerequisite for connection. A server, the server must be in advertising mode (can be connected) to connect to a client.
If the client gets the server's MAC address in advance, it can initiate connections without scanning;
If the client does not have the server's MAC address, please scan first.

Connection and Communication
Generally BLE is used based on connection, except for beacons.

Connection-related commands:

• Connect: AT+BLECONN
• Disconnect: AT+BLEDISCONN

Connection can only be initiated by the client; disconnection can be initiated by both the client and the server.

BLE data communication is based on the Attribute Protocol, so before connection the BLE server should enable service by running the following two commands:

• Create services: AT+BLEGATTSSRVCRE
• Start services: AT+BLEGATTSSRVSTART

The above two commands should be executed after AT+BLEINIT=2 and before connection to the client. Their order cannot be reversed, but other commands can be inserted inbetween, usually before AT+BLEADVSTART as recommended (because after advertising is started the server might be connected to a remote device, and the client cannot discover services as a result).

The client discovers services after connection:

• Discover primary services of the server: AT+BLEGATTCPRIMSRV
• Discover included services: AT+BLEGATTCINCLSRV
• Discover char within services: AT+BLEGATTCCHAR

The server queries for local services and char:

• Query for services: AT+BLEGATTSSRV
• Query for char within services: AT+BLEGATTSCHAR

Service query is necessary, since \<index> parameters obtained by service query are needed for reads and writes in ESP-AT BLE. For detailed information, please refer to the next chapter.

With service parameters, data can be transferred between the client and the server. The client sends data to the server by write:

• Write char or desc: AT+BLEGATTCWR
• Read char or desc: AT+BLEGATTCRD

The server sends data to the client by either notify or indicate.

• Notify: AT+BLEGATTSNTFY
• Indicate: AT+BLEGATTSIND

Parameter Update

For specific application scenatios, some parameters need to be updated, especially MTU and connection parameters:

• Update MTU size: AT+BLECFGMTU
• Update connection parameters: AT+BLECONNPARAM

MTU size can only be updated by the client. The largest size supported by ESP-AT is 517, and the default value is 23. One advantage of extending MTU size is that more bytes of data could be sent in one packet. The length of data in packet is（MTU size - 3）at most, so by default 20 bytes of data could be sent in one packet.

Connection parameters can be updated anytime after connection is establishd. The next chapter will explain the influence of different connection parameters.

Encryption

ESP-AT supports all BLE security levels. You can freelly set encryption parameters, initiate or accept encryption, pop out passkey, enter passkey, bonding, etc.

• Set encryption parameters: AT+BLESECPARAM
• Initiate encryption: AT+BLEENC
• Accept or refuse encryption: AT+BLEENCRSP
• Set static passkey: AT+BLESETKEY
• Enter KEY: AT+BLEKEYREPLY
• Confirm KEY: AT+BLECONFREPLY
• Check bonding devices: AT+BLEENCDEV
• Clear bonding information: AT+BLEENCCLEAR

3. BLE Application Example

Commands are specific to application scenarios. Take an easy scenario as an example.

3.1 iBeacon Demo

iBeacon is used mainly for advertising, indoor positioning, etc. It sends BLE advertising packets in a specified format. For details about ibeacon, please refer to [iBeacon.pdf] released by Apple(https://developer.apple.com/ibeacon/Getting-Started-with-iBeacon.pdf).

See how iBeacon advertising applies to discovering surrounding devices using WeChat Shake:

Initialize the device as the server

AT+BLEINIT=2

OK

Set advertising parameters
If you directly configure advertising packets and start advertising without setting parameters, surrounding devices can still be discovered using WeChat Shake. However, it is recommended to configure the device as advertising without connection, so as to avoid being connected to unpreditable devices.

AT+BLEADVPARAM=64,64,3,0,7   //The third parameter '3' indicates the advertising packet is ADV_TYPE_NONCONN_IND

OK

For descriptions of other parameters, please refer to ESP AT Command Set.

Configure advertising packets

AT+BLEADVDATA="0201061AFF4C000215FDA50693A4E24FB1AFCFC6EB0764782527B7F206C5"

OK

You can redefine advertising packets according to the iBeacon format.

Once advertising data has been set, the device can start advertising.

AT+BLEADVSTART

OK

Now you can discover iBeacon packets using WeChat Shake.

Google’s eddystone works similiarly using advertising packets in a specified format.

Tips:

• You can directly start advertising without configuring the advertising packet. In this case, the payload of the packet is empty, but connection to the client won’t be affected.
• One advertising packet contains 31 bytes at most. If your data is longer than 31 bytes, you can configure scan rsp data (also 31 bytes at most).

3.2 Scanning Surrounding Bluetooth Devices

Scanning is a common scenario, for example scanning beacon packets around, scanning devices around to be connected, etc.
The command for scanning in ESP-AT is AT+BLESCAN.
Before scanning, please initialize the device as the client:

AT+BLEINIT=1

OK

Start continous scanning:

AT+BLESCAN=1

OK

Scan for three seconds:

AT+BLESCAN=1,3

OK

Stop scanning:

AT+BLESCAN=0

OK

Example:

AT+BLESCAN=1

OK
+BLESCAN:c4:4f:33:16:f8:c3,-50,,,0
+BLESCAN:4d:71:ae:b0:72:08,-40,02011a0aff4c001005131c5fc0b3,,1
+BLESCAN:c4:4f:33:16:f8:c3,-55,,,0
+BLESCAN:58:81:89:b9:a2:de,-45,02010613ff4c000c0e0806040a6279452dfb65b171ddf9,,1
+BLESCAN:58:81:89:b9:a2:de,-47,02010613ff4c000c0e0806040a6279452dfb65b171ddf9,,1
+BLESCAN:ac:bc:32:c2:0e:da,-46,0201060aff4c0010050b1c7ac126,,0
+BLESCAN:ac:bc:32:c2:0e:da,-55,0201060aff4c0010050b1c7ac126,,0
+BLESCAN:4c:38:cc:bf:3f:64,-68,02010613ff4c000c0e009a8b60fd84a3fa91cb767de4a2,,1
+BLESCAN:c4:4f:33:16:f8:c3,-47,,,0
+BLESCAN:c4:4f:33:16:f8:c3,-56,,,0
+BLESCAN:77:64:1d:9a:46:ea,-44,0201060aff4c00100541187179a3,,1
+BLESCAN:c4:4f:33:16:f8:c3,-48,,,0
+BLESCAN:c4:4f:33:16:f8:c3,-57,,,0
AT+BLESCAN=0

OK

As shown in the scanning log above, all scanning results start with +BLESCAN:, followed by MAC address (e.g. "4d:71:ae:b0:72:08"), RSSI value, adv data and scan rsp data, and address type (0: public; 1: random).

Tips:

• If continuous scanning is enabled, the device will print scanning log until there is no BLE advertising packets around.
• To avoid too much information, it is recommended to scan for limited amount of time (e.g. 3 or 5 seconds) by using the timing function.
• To scan response data, please use the format of BLE advertising packets only. If the server advertises raw data such as {0x00, 0x01, 0x02, 0x03}, the content and length of data scanned are usually incorrect.
• In ESP-AT, only the client can scan.
• If MAC address is right, and the device scanned still cannot be connected, please check the address type (see details in 3.3).

3.3 Establishing BLE Connection

There are two connection-related commands, AT+BLECONN and AT+BLEDISCONN.
Establish connection:

+BLECONN:0,"c4:4f:33:16:f8:c3"

OK

To establish connection, two parameters should be entered: conn_index and mac addr.

conn_index is specified by users and used to differentiate connectons. When there are multiple connections, this parameter should be unique for each connection. Once the connection is broken, the parameter value can be reused. In this example, conn_index is 0. It can also be 9527, so long as the value is unique.

The third parameter is optional. It specifies address type of the device on the other side. By default the address of the other side is public. If the address is random, please set the third parameter to 1.

Check connection:

AT+BLECONN?
+BLECONN:0,c4:4f:33:16:f8:c3

OK

If the device is connected, a log will be printed as shown above. The first parameter is conn_index, the same with what has been entered when establishing connection.

Disconnect:

AT+BLEDISCONN=0
+BLEDISCONN:0,"c4:4f:33:16:f8:c3"

OK

Above is the command for active disconnection. If the device loses connection passively, a log will also be printed:

+BLEDISCONN:0,"xx:xx:xx:xx:xx:xx"

Tips:

• Connection can only be initiated by the client, and can be broken by both the client and the server.
• If address of the other side is random, please add the third parameter 1.

3.4 Transferring Data

BLE data transfer is based on the Attribute Protocol. After the server is initialized, please create and start services.

3.4.1 Server: Create and Start Services

AT+BLEGATTSSRVCRE   // create services

OK

AT+BLEGATTSSTART    // start services

OK

Only the server could send the above commands, and a service should be created before started. It is recommended to start services before advertising is enabled.

3.4.2 Server: Query for Local Services

Many ESP-AT BLE commands use index as a parameter, such as conn_index for establishing connection. Services uses the following index:

• service index
• characteristic index
• descriptor index

In ESP-AT, index is the basis of all service-related procedures. Please first program ble_data.bin, and only then can the server create services. After that, the server can query for local services, for example:

AT+BLEINIT=2

OK
AT+BLEGATTSSRVCRE

OK
AT+BLEGATTSSRV?
+BLEGATTSSRV:1,0,0xA002,1

OK
AT+BLEGATTSCHAR?
+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

OK

Parameter description:

+BLEGATTSSRV:<srv_index>,<start>,<srv_uuid>,<srv_type>

As shown in the above log, the server has only one service, whose index is 1. The second parameter suggests that this service has not been enabled yet. The third parameter is UUID. The fourth parameter indicates that the service is primary.

You can also query for characteristics within a service and their descriptors:

+BLEGATTSCHAR:"char",<srv_index>,<char_index>,<char_uuid>,<char_prop>
+BLEGATTSCHAR:"desc",<srv_index>,<char_index>,<desc_index> 

As shown in the above log, the service (0xA002) whose index is 1 has eight characteristics, and each characteristic has its corresponding descriptors.

For example:

+BLEGATTSCHAR:"char",1,6,0xC305,0x10
+BLEGATTSCHAR:"desc",1,6,1,0x2902

The abovecharacteristic (UUID 0xC305) is the sixth characteristic in the first service(0xA002), with 0x10 as its prop. This characteristic has onedescriptor, whose UUID is 0x2902.

Implied by UUID 0x2902, this descriptor is a ccc (client Characteristic Configuration Descriptor), where the client writes to enable notify or indicate. This means that notification can be enabled on the corresponding characteristic.

To help your understanding, it is recommended to read the ATT/GATT section in the protocol.

3.4.3 Client: Discover Services

Once connection is established, the client can discover services using the following commands:

• AT+BLEGATTCPRIMSRV
• AT+BLEGATTCINCLSRV
• AT+BLEGATTCCHAR

AT+BLEGATTCPRIMSRV is used to discover primary services of the device on the other side. This command should include conn_index, namely conn_index mentioned in the example below.

Why this parameter is needed for service discovery by the client, but unnecessary for service query by the server?
If one server is connected to multiple clients, services are shared among them. However, if one client is connected to two servers, services on the two servers are mutually independent. Therefore, this parameter is needed to specify to which server a service belongs.

AT+BLEINIT=1

OK
AT+BLECONN=0,"c4:4f:33:16:f8:c3"
+BLECONN:0,"c4:4f:33:16:f8:c3"

OK
AT+BLEGATTCPRIMSRV=0
+BLEGATTCPRIMSRV:0,1,0x1801,1
+BLEGATTCPRIMSRV:0,2,0x1800,1
+BLEGATTCPRIMSRV:0,3,0xA002,1

OK
AT+BLEGATTCINCLSRV=0,3

OK
AT+BLEGATTCCHAR=0,3
+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

After initialized, the client initiates connection and discovers services. The results are:

• +BLEGATTCPRIMSRV:0,1,0x1801,1
• +BLEGATTCPRIMSRV:0,2,0x1800,1
• +BLEGATTCPRIMSRV:0,3,0xA002,1

There are 3 services on the server. 0x1801 and 0x1800 are GAP and GATT respectively, and the third service 0xA002 is what you just created.

Below is characteristics and descriptors in the third service. You can compare this log with the one of creating a service on the server.

// server
AT+BLEGATTSCHAR?
+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

OK

// client
AT+BLEGATTCCHAR=0,3
+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

All parameters are the same except index. index is only valid locally, for users to edit any property values more accurately.

3.4.4 Client: Read and Write

The client can write data to the server using AT+BLEGATTCWR, and read data using AT+BLEGATTCRD.

For example, read the first characteristic 0xC300:

AT+BLEGATTCRD=0,3,1
+BLEGATTCRD:0,1,0   //length = 1,  value = 0 

OK

Write to characteristic 0xC301:

AT+BLEGATTCWR=0,3,4,10
>   // Enter ten characters abcdefghij
OK

The log of writing to the server:

+WRITE:0,1,4,,10,abcdefghij

The first parameter is conn_index, followed by serv_index, char_index, desr_index, length and data.

If the client writes to a characteristic, desc_index will be ignored.

Tips

• If the character entered is longer than the specified length, an ERROR will be reported.
• If the client writes to an unwritable characteristic, or reads an unreadable characteristic, an ERROR will be reported.

3.4.5 Client: Register Notification

On top of read and write, BLE characteristics contain notify and indicate, which are used when the server sends data to the client. For successful data transmission, the client needs to register notification in advance, or in other words write the value of CCC.

For notify, please write 0x1; for indicate, please write 0x2 (to description 0x2902).

For example, in default ESP-AT services, the property of 0xC305 is notify, and the property of 0xC306 is indicate. We write to descriptor 0x2902 in the two characteristics respectively:

// client
AT+BLEGATTCWR=0,3,6,1,2
>    // write 0x01
OK
// server
+WRITE:0,1,6,1,2,<0x01>,<0x00>

AT+BLEGATTCWR=0,3,7,1,2
>    // write 0x02
OK
// server
+WRITE:0,1,6,1,2,<0x02>,<0x00>

Writing CCC value is necessary for the server to notify and indicate.

Tips

• ESP-AT will internally convert wrong values written to descriptors to the right ones.

3.4.6 Server: Send Data to the Client

Once CCC value has been written, we can send data using notify and indicate.

// server
AT+BLEGATTSNTFY=0,1,6,8
> //enter 123456789
OK

// client
+NOTIFY:0,3,6,8,12345678

// server
AT+BLEGATTSIND=0,1,7,9
> //enter aaabbbccc
OK

// client
+INDICATE:0,3,7,9,aaabbbccc

For meanings of above parameters, please refer to the command set.

四: BLE Encryption

This chapter explains BLE encryption.

BLE encryption commands suit the following purposes:

• Setting encryption parameters
• Initiating encryption requests
• Responding to encryption requests
• Exchanging KEY, i.e. popping out or entering passkey
• Checking or clearing bonding information

Tips:

• Encryption and bonding are different. Bonding is to store a long-term key locally after encryption.

4.1 Encryption Parameter Setting

After initialization, BLE encryption parameters can be set any time before encryption repeatedly. The latest setting will overwrite the previous one.

AT+BLESECPARAM=<auth_req>,<iocap>,<key_size>,<init_key>,<rsp_key>[,<auth_option>]

OK

Please pay attention to the first two parameters. For other parameters, please check the default setting in the example.

The first parameter auth_req:

• 0 : NO_BOND
• 1 : BOND
• 4 : MITM
• 8 : SC_ONLY
• 9 : SC_BOND
• 12 : SC_MITM
• 13 : SC_MITM_BOND

This parameter specifies the security level requested, for instance MITM, security connection or bonding.

The second parameter IO CAP:

• 0 : DisplayOnly
• 1 : DisplayYesNo
• 2 : KeyboardOnly
• 3 : NoInputNoOutput
• 4 : Keyboard displa

This parameter specifies whether input and output are available.

Note:

If auth_req is configured as MITM yet IO CAP as NoInputNoOutput, then the security level cannot be MITM but just work. This is reasonable, because MITM is expectation, and IO is capability. Without sufficient capability, expectations cannot be met. Similiarly, when the expectation is beyond the other side’s capability, the result is also just work.

4.2 Combinations of Encryption Parameters

Different IO settings combined varies in results:

• one side has input capability, and the other side has output capability
• two sides have both input and output capabilities

For combinations alike, please refer to Core Specification

Based on different combinations, there are two common scenarios: 1. pop out the passkey for the other side to enter; 2. enter the passkey the other side provides

4.3 Encryption Example

The example below shows encryption and bonding using two ESP-AT devices. Assume connection has been established.

First, set encryption parameters of the two devices.

// client
AT+BLESECPARAM=13,4,16,3,3    // IO: Keyboard displa

// server
AT+BLESECPARAM=13,2,16,3,3    // IO: KeyboardOnly

One device has output capability, the other has output capability, and the security level requested is MITM. It should be the client that pops out the passkey, and the server that enters the passkey.

Second, initiate an encryption request. The request could be initiated either by the client or the server. Here the request is initiated by the client.

AT+BLEENC=0,3    // Please refer to command set for parameter description

OK

The server side pops out a log with an encryption request:

+BLESECREQ:0     // The first device connected has sent an encryption request

The server needs to respond to this request. Here the server accept the request.

AT+BLEENCRSP=0,1   // Approve encryption

OK

Third, exchange KEY. As described above, the client pops out the passkey.

+BLESECNTFYKEY:0,344804   // Passkey: 344804

The server enters the passkey.

AT+BLEKEYREPLY=0,344804

If the passkey is right, encryption succeeds with the following log:

// client
+BLESECKEYTYPE:0,2
+BLESECKEYTYPE:0,16
+BLESECKEYTYPE:0,1
+BLESECKEYTYPE:0,32
+BLEAUTHCMPL:0,0

// server
+BLESECKEYTYPE:0,16
+BLESECKEYTYPE:0,1
+BLESECKEYTYPE:0,32
+BLESECKEYTYPE:0,2
+BLEAUTHCMPL:0,0

You can ignore BLESECKEYTYPE and pay attention to +BLEAUTHCMPL:0,0 only. If the second parameter is 0, it indicates that encryption succeeded; if it is not 0, it indicates encryption failed. The first parameter is conn_index, depending on your configuration.

Above example just shows one scenario. If we change IO settings, the results will be different. Whatever the setting is, encrytion is to pop out and enter passkeys on the two sides or just work without human intervention.

五: BLE SPP Implementation

There is no standard BLE SPP. BLE SPP in this article is defined by Espressif and is not campatible with standards of our counterparts. Such BLE SPP can be implemented using two ESP32 modules, or phones and counterpart chips on basis of our method.

BLE SPP allows you to transfer data using two characteristics: one whose property is write, another whose property is notify or indicate.

Initialize the two ESP32 devices:

// client:

AT+BLEINIT=1

OK

// server:

AT+BLEINIT=2

OK

Create and start services on the server, enable advertising, and wait to be connected.

AT+BLEGATTSSRVCRE

OK

AT+BLEGATTSSRVSTART

OK

AT+BLEADVSTART

OK

The client initiates a connection request. The client can scan for the address of the server.

AT+BLECONN=0,”XX:XX:XX:XX:XX:XX”

OK

When connection is established, a log will be printed on the server side.

+BLECONN:0,”XX:XX:XX:XX:XX:XX”

The client discovers services. The server queris for its own services and set SPP parameters.

// client:

AT+BLEGATTCPRIMSRV=0

AT+BLEGATTCCHAR=0,3

AT+BLESPPCFG=1,3,3,3,7

// server:

AT+BLEGATTSSRV?

AT+BLEGATTSCHAR?

AT+BLESPPCFG=1,1,7,1,3

SPP parameters specify the two characteristics used to transfer data.

AT+BLESCANPARAM=<option>[,<tx_service_index>,<tx_char_index>,<rx_service_index>,<rx_char_index>]

The first parameter must be configured as 1. When this parameter = 0, it indicates clearing configuration.

The four parameters followed are:

• tx_service_index
• tx_char_index
• rx_service_index
• rx_char_index

They specify the characteristic in the specific service used to transfer data.

To send data, the client must choose a characteristic whose property is write or write without rsp. In this example, the client uses the third characteristic in the third service (property: write) to send data, and the seventh characteristic (property: indicate) to receive data from the server.

Now the two devices are ready to enter SPP mode:

// client:

AT+BLESPP

// server:

AT+BLESPP