[ESP32 Only] Bluetooth® Low Energy AT Commands

ESP32 AT firmware supports Bluetooth® Core Specification Version 5.0.

[ESP32 Only] AT+BLEINIT: Bluetooth LE Initialization

Query Command

Function:

Check the initialization status of Bluetooth LE.

Command:

AT+BLEINIT?

Response:

If Bluetooth LE is not initialized, AT will return:

+BLEINIT:0
OK

If Bluetooth LE is initialized, AT will return:

+BLEINIT:<role>
OK

Set Command

Function:

Initialize the role of Bluetooth LE.

Command:

AT+BLEINIT=<init>

Response:

OK

Parameter

  • <init>:
    • 0: deinit Bluetooth LE
    • 1: client role
    • 2: server role

Notes

  • The file “at_customize.bin” has to be downloaded, so that the relevant commands can be used. Please refer to How To Customize ble services for more details.
  • Before using other Bluetooth LE AT commands, you should run this command first to trigger the initialization process.
  • After the initialization, the Bluetooth LE role cannot be changed unless you run AT+RST to restart the system first and then re-initialize the Bluetooth LE role.
  • If you use an ESP device as a Bluetooth LE server, a service bin should be downloaded into flash.
    • To learn how to generate a service bin, please refer to esp-at/tools/readme.md.
    • The download address of the service bin is the “ble_data” address in esp-at/module_config/module_${platform}_default/at_customize.csv.

Example

AT+BLEINIT=1

[ESP32 Only] AT+BLEADDR: Set Bluetooth LE Device Address

Query Command

Function:

Obtain the Bluetooth LE public address.

Command:

AT+BLEADDR?

Response:

+BLEADDR:<BLE_public_addr>
OK

Set Command

Function:

Set the Bluetooth LE address type.

Command:

AT+BLEADDR=<addr_type>[,<random_addr>]

Response:

OK

Parameter

  • <addr_type>:
    • 0: public address
    • 1: random address

Note

  • A static address should meet the following requirements:
    • The two most significant bits of the address should be equal to 1.
    • At least one bit of the random part of the address should be 0.
    • At least one bit of the random part of the address should be 1.

Example

AT+BLEADDR=1,"f8:7f:24:87:1c:7b"    // Set Random Device Address, Static Address
AT+BLEADDR=1                        // Set Random Device Address, Private Address
AT+BLEADDR=0                        // Set Public Device Address

[ESP32 Only] AT+BLENAME: Set Bluetooth LE Device Name

Query Command

Function:

Obtain the Bluetooth LE device name.

Command:

AT+BLENAME?

Response:

+BLENAME:<device_name>
OK

Set Command

Function:

Set the Bluetooth LE device name.

Command:

AT+BLENAME=<device_name>

Response:

OK

Parameter

  • <device_name>: the Bluetooth LE device name. The maximum length is 32. Default: “BLE_AT”.

Note

  • The configuration changes will be saved in the NVS area if AT+SYSSTORE=1.

Example

AT+BLENAME="esp_demo"

[ESP32 Only] AT+BLESCANPARAM: Set Parameters of Bluetooth LE Scanning

Query Command

Function:

Obtain the parameters of Bluetooth LE scanning.

Command:

AT+BLESCANPARAM?

Response:

+BLESCANPARAM:<scan_type>,<own_addr_type>,<filter_policy>,<scan_interval>,<scan_window>
OK

Set Command

Function:

Set the parameters of Bluetooth LE scanning.

Command:

AT+BLESCANPARAM=<scan_type>,<own_addr_type>,<filter_policy>,<scan_interval>,<scan_window>

Response:

OK

Parameters

  • <scan_type>:
    • 0: passive scan
    • 1: active scan
  • <own_addr_type>:
    • 0: public address
    • 1: random address
    • 2: RPA public address
    • 3: RPA random address
  • <filter_policy>:
    • 0: BLE_SCAN_FILTER_ALLOW_ALL
    • 1: BLE_SCAN_FILTER_ALLOW_ONLY_WLST
    • 2: BLE_SCAN_FILTER_ALLOW_UND_RPA_DIR
    • 3: BLE_SCAN_FILTER_ALLOW_WLIST_PRA_DIR
  • <scan_interval>: scan interval
  • <scan_window>: scan window

Note

  • The parameter <scan_window> CANNOT be larger than <scan_interval>.

Example

AT+BLEINIT=1   // role: client
AT+BLESCANPARAM=0,0,0,100,50

[ESP32 Only] AT+BLESCAN: Enable Bluetooth LE Scanning

Set Command

Function:

Enable/disable scanning.

Command:

AT+BLESCAN=<enable>[,<interval>][,<filter_type>,<filter_param>]

Response:

+BLESCAN:<addr>,<rssi>,<adv_data>,<scan_rsp_data>,<addr_type>
OK

Parameters

  • <enable>:

    • 1: enable continuous scanning.
    • 0: disable continuous scanning.

  • [<interval>]: optional parameter. Unit: second.

    • If you want to disable the scanning, this parameter should be omitted.
    • If you want to enable the scanning, set a value for this parameter:
    • When you set it to 0, it means that scanning is continuous.
    • When set it to a value other than 0, for example, AT+BLESCAN=1,3, it means that scanning will last for 3 seconds and then stop automatically. The scanning results will be returned.

  • [<filter_type>]: filtering option.

    • 1: MAC.
    • 2: “NAME”.

  • <filter_param>: filtering parameter showing the remote device MAC address or remote device name.

  • <addr>: Bluetooth LE address.

  • <rssi>: signal strength.

  • <adv_data>: advertising data.

  • <scan_rsp_data>: scan response data.

  • <addr_type>: the address type of broadcasters.

Example

AT+BLEINIT=1    // role: client
AT+BLESCAN=1    // start scanning
AT+BLESCAN=0    // stop scanning
AT+BLESCAN=1,3,1,"24:0A:C4:96:E6:88"  // start scanning, filter type is MAC address
AT+BLESCAN=1,3,2,"ESP-AT"  // start scanning, filter type is device name

[ESP32 Only] AT+BLESCANRSPDATA: Set Bluetooth LE Scan Response

Set Command

Function:

Set scan response.

Command:

AT+BLESCANRSPDATA=<scan_rsp_data>

Response:

OK

Parameter

  • <scan_rsp_data>: scan response data is a HEX string. For example, if you want to set the response data to “0x11 0x22 0x33 0x44 0x55”, the command should be AT+BLESCANRSPDATA="1122334455".

Example

AT+BLEINIT=2   // role: server
AT+BLESCANRSPDATA="1122334455"

[ESP32 Only] AT+BLEADVPARAM: Set Parameters of Bluetooth LE Advertising

Query Command

Function:

Query the parameters of advertising.

Command:

AT+BLEADVPARAM?

Response:

+BLEADVPARAM:<adv_int_min>,<adv_int_max>,<adv_type>,<own_addr_type>,<channel_map>,<adv_filter_policy>,<peer_addr_type>,<peer_addr>
OK

Set Command

Function:

Set the parameters of advertising.

Command:

AT+BLEADVPARAM=<adv_int_min>,<adv_int_max>, <adv_type>,<own_addr_type>,<channel_map>[,<adv_filter_policy>][,<peer_addr_type>] [,<peer_addr>]

Response:

OK

Parameters

  • <adv_int_min>: minimum advertising interval. Range: 0x0020 ~ 0x4000.
  • <adv_int_max>: maximum advertising interval. Range: 0x0020 ~ 0x4000.
  • <adv_type>:
    • 0: ADV_TYPE_IND
    • 2: ADV_TYPE_SCAN_IND
    • 3: ADV_TYPE_NONCONN_IND
  • <own_addr_type>: own Bluetooth LE address type.
    • 0: BLE_ADDR_TYPE_PUBLIC
    • 1: BLE_ADDR_TYPE_RANDOM
  • <channel_map>: channel of advertising.
    • 1: ADV_CHNL_37
    • 2: ADV_CHNL_38
    • 4: ADV_CHNL_39
    • 7: ADV_CHNL_ALL
  • [<adv_filter_policy>]: filter policy of advertising.
    • 0: ADV_FILTER_ALLOW_SCAN_ANY_CON_ANY
    • 1: ADV_FILTER_ALLOW_SCAN_WLST_CON_ANY
    • 2: ADV_FILTER_ALLOW_SCAN_ANY_CON_WLST
    • 3: ADV_FILTER_ALLOW_SCAN_WLST_CON_WLST
  • [<peer_addr_type>]: remote Bluetooth LE address type.
    • 0: PUBLIC
    • 1: RANDOM
  • [<peer_addr>]: remote Bluetooth LE address.

Example

AT+BLEINIT=2   // role: server
AT+BLEADVPARAM=50,50,0,0,4,0,0,"12:34:45:78:66:88"

[ESP32 Only] AT+BLEADVDATA: Set Bluetooth LE Advertising Data

Set Command

Function:

Set advertising data.

Command:

AT+BLEADVDATA=<adv_data>

Response:

OK

Parameter

  • <adv_data>: advertising data in HEX string. For example, to set the advertising data to “0x11 0x22 0x33 0x44 0x55”, the command should be AT+BLEADVDATA="1122334455".

Note

  • If advertising data is preset by command AT+BLEADVDATAEX=<dev_name>,<uuid>,<manufacturer_data>,<include_power>, it will be overwritten by this command.

Example

AT+BLEINIT=2   // role: server
AT+BLEADVDATA="1122334455"

[ESP32 Only] AT+BLEADVDATAEX: Automatically Set Bluetooth LE Advertising Data

Query Command

Function:

Query the parameters of advertising data.

Command:

AT+BLEADVDATAEX?

Response:

+BLEADVDATAEX:<dev_name>,<uuid>,<manufacturer_data>,<include_power>

OK

Set Command

Function:

Configure the advertising data and start advertising.

Command:

AT+BLEADVSTARTEX=<dev_name>,<uuid>,<manufacturer_data>,<include_power>

Response:

OK

Parameters

  • <dev_name>: string parameter showing a device name. For example, if you want to set the device name to “just-test”, the command should be AT+BLEADVSTARTEX="just-test",<uuid>,<manufacturer_data>,<include_power>.
  • <uuid>: string parameter. For example, if you want to set the UUID to “0xA002”, the command should be AT+BLEADVSTARTEX=<dev_name>,"A002",<manufacturer_data>,<include_power>.
  • <manufacturer_data>: manufacturer data in HEX string. For example, if you set the manufacturer data to “0x11 0x22 0x33 0x44 0x55”, the command should be AT+BLEADVSTARTEX=<dev_name>,<uuid>,"1122334455",<include_power>.
  • <include_power>: If you need to include the TX power in the advertising data, you should set the parameter to 1. Otherwise, set it to 0.

Note

  • If advertising data is preset by command AT+BLEADVDATA=<adv_data>, it will be overwritten by this command.

Example

AT+BLEINIT=2   // role: server
AT+BLEADVDATAEX="ESP-AT","A002","0102030405",1

[ESP32 Only] AT+BLEADVSTART: Start Bluetooth LE Advertising

Execute Command

Function:

Start advertising.

Command:

AT+BLEADVSTART

Response:

OK

Notes

  • If advertising parameters are NOT set by command AT+BLEADVPARAM=<adv_parameter>, the default parameters will be used.
  • If advertising data is NOT set by command AT+BLEADVDATA=<adv_data>, the advertising playload will be empty.
  • If advertising data is preset by command AT+BLEADVDATA=<adv_data>, it will be overwritten by AT+BLEADVDATAEX=<dev_name>,<uuid>,<manufacturer_data>,<include_power> and vice versa.

Example

AT+BLEINIT=2   // role: server
AT+BLEADVSTART

[ESP32 Only] AT+BLEADVSTOP: Stop Bluetooth LE Advertising

Execute Command

Function:

Stop advertising.

Command:

AT+BLEADVSTOP

Response:

OK

Note

  • After the start of advertising, if the Bluetooth LE connection is established successfully, it will stop advertising automatically. In such a case, this command does NOT need to be called.

Example

AT+BLEINIT=2   // role: server
AT+BLEADVSTART
AT+BLEADVSTOP

[ESP32 Only] AT+BLECONN: Establish Bluetooth LE Connection

Query Command

Function:

Query the Bluetooth LE connection.

Command:

AT+BLECONN?

Response:

+BLECONN:<conn_index>,<remote_address>
OK

If the connection has not been established, there will be no <conn_index> and <remote_address> in the response.

Set Command

Function:

Establish the Bluetooth LE connection.

Command:

AT+BLECONN=<conn_index>,<remote_address>[,<addr_type>,<timeout>]

Response:

OK

If the connection is established successfully, it will prompt:

+BLECONN:<conn_index>,<remote_address>

Otherwise, it will prompt:

+BLECONN:<conn_index>,-1

Parameters

  • <conn_index>: index of Bluetooth LE connection. Range: [0,2].
  • <remote_address>: remote Bluetooth LE address.
  • [<addr_type>]: the address type of broadcasters.
  • [<timeout>]: the timeout for the connection command. Unit: second. Range: [3,30].

Example

AT+BLEINIT=1   // role: client
AT+BLECONN=0,"24:0a:c4:09:34:23",0,10

Notes

  • It is recommended to scan devices by running AT+BLESCAN before initiating a new connection to ensure that the target device is in the broadcast state.
  • The maximum timeout for connection is 30 seconds.

[ESP32 Only] AT+BLECONNPARAM: Update Parameters of Bluetooth LE Connection

Query Command

Function:

Query the parameters of Bluetooth LE connection.

Command:

AT+BLECONNPARAM?

Response:

+BLECONNPARAM:<conn_index>,<min_interval>,<max_interval>,<cur_interval>,<latency>,<timeout>
OK

Set Command

Function:

Update the parameters of Bluetooth LE connection.

Command:

AT+BLECONNPARAM=<conn_index>,<min_interval>,<max_interval>,<latency>,<timeout>

Response:

OK

If the setting fails, it will prompt the message below:

+BLECONNPARAM: <conn_index>,-1

Parameters

  • <conn_index>: index of Bluetooth LE connection. Range: [0,2].
  • <min_interval>: minimum connecting interval. Range: 0x0006 ~ 0x0C80.
  • <max_interval>: maximum connecting interval. Range: 0x0006 ~ 0x0C80.
  • <cur_interval>: current connecting interval.
  • <latency>: latency. Range: 0x0000 ~ 0x01F3.
  • <timeout>: timeout. Range: 0x000A ~ 0x0C80.

Note

  • This command only supports the client role when updating its connection parameters. Of course, the connection has to be established first.

Example

AT+BLEINIT=1   // role: client
AT+BLECONN=0,"24:0a:c4:09:34:23"
AT+BLECONNPARAM=0,12,14,1,500

[ESP32 Only] AT+BLEDISCONN: End Bluetooth LE Connection

Execute Command

Function:

End the Bluetooth LE connection.

Command:

AT+BLEDISCONN=<conn_index>

Response:

OK  // The AT+BLEDISCONN command is received.
+ BLEDISCONN:<conn_index>,<remote_address>  // The command is successful.

Parameters

  • <conn_index>: index of Bluetooth LE connection. Range: [0,2].
  • <remote_address>: remote Bluetooth LE address.

Note

  • Only clients can call this command to terminate the connection.

Example

AT+BLEINIT=1   // role: client
AT+BLECONN=0,"24:0a:c4:09:34:23"
AT+BLEDISCONN=0

[ESP32 Only] AT+BLEDATALEN: Set Bluetooth LE Data Packet Length

Set Command

Function:

Set the length of Bluetooth LE data packet.

Command:

AT+BLEDATALEN=<conn_index>,<pkt_data_len>

Response:

OK

Parameters

  • <conn_index>: index of Bluetooth LE connection. Range: [0,2].
  • <pkt_data_len>: data packet’s length. Range: 0x001b ~ 0x00fb.

Note

  • The Bluetooth LE connection has to be established first.

Example

AT+BLEINIT=1   // role: client
AT+BLECONN=0,"24:0a:c4:09:34:23"
AT+BLEDATALEN=0,30

[ESP32 Only] AT+BLECFGMTU: Set Bluetooth LE MTU Length

Query Command

Function:

Query the length of the maximum transmission unit (MTU).

Command:

AT+BLECFGMTU?

Response:

+BLECFGMTU:<conn_index>,<mtu_size>
OK

Set Command

Function:

Set the length of the maximum transmission unit (MTU).

Command:

AT+BLECFGMTU=<conn_index>,<mtu_size>

Response:

OK  // The command is received.

Parameters

  • <conn_index>: index of Bluetooth LE connection. Range: [0,2].
  • <mtu_size>: MTU length.

Notes

  • Only the client can call this command to set the length of MTU. Note that the Bluetooth LE connection has to be established first.
  • The actual length of MTU needs to be negotiated. The OK response only means that the MTU length must be set. So, you should run command AT+BLECFGMTU? to query the actual MTU length.

Example

AT+BLEINIT=1   // role: client
AT+BLECONN=0,"24:0a:c4:09:34:23"
AT+BLECFGMTU=0,300

[ESP32 Only] AT+BLEGATTSSRVCRE: GATTS Creates Services

Execute Command

Function:

The Generic Attributes Server (GATTS) creates Bluetooth LE services.

Command:

AT+BLEGATTSSRVCRE

Response:

OK

Notes

  • If you are using an ESP device as a Bluetooth LE server, a service bin should be downloaded into flash in order to provide services.
    • To learn how to generate a service bin, please refer to esp-at/tools/readme.md.
    • The download address of the service bin is the “ble_data” address in esp-at/module_config/module_${platform}_default/at_customize.csv.
  • This command should be called immediately to create services, right after the Bluetooth LE server is initialized.
  • If a Bluetooth LE connection is established first, the service creation will fail.

Example

AT+BLEINIT=2   // role: server
AT+BLEGATTSSRVCRE

[ESP32 Only] AT+BLEGATTSSRVSTART: GATTS Starts Services

Execute Command

Function:

GATTS starts all services.

Command:

AT+BLEGATTSSTART

Set Command

Function:

GATTS starts a specific service.

Command:

AT+BLEGATTSSRVSTART=<srv_index>

Response:

OK

Parameter

  • <srv_index>: service’s index starting from 1.

Example

AT+BLEINIT=2   // role: server
AT+BLEGATTSSRVCRE
AT+BLEGATTSSRVSTART

[ESP32 Only] AT+BLEGATTSSRVSTOP: GATTS Stops Services

Execute Command

Function:

GATTS stops all services.

Command:

AT+BLEGATTSSTOP

Set Command

Function:

GATTS stops a specific service.

Command:

AT+BLEGATTSSRVSTOP=<srv_index>

Response:

OK

Parameter

  • <srv_index>: service’s index starting from 1.

Example

AT+BLEINIT=2   // role: server
AT+BLEGATTSSRVCRE
AT+BLEGATTSSRVSTART
AT+BLEGATTSSRVSTOP

[ESP32 Only] AT+BLEGATTSSRV: GATTS Discovers Services

Query Command

Function:

GATTS discovers services.

Command:

AT+BLEGATTSSRV?

Response:

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

Parameters

  • <srv_index>: service’s index starting from 1.
  • <start>:
    • 0: the service has not started.
    • 1: the service has already started.
  • <srv_uuid>: service’s UUID.
  • <srv_type>: service’s type.
    • 0: not primary service.
    • 1: primary service.

Example

AT+BLEINIT=2   // role: server
AT+BLEGATTSSRVCRE
AT+BLEGATTSSRV?

[ESP32 Only] AT+BLEGATTSCHAR: GATTS Discovers Characteristics

Query Command

Function:

GATTS discovers characteristics.

Command:

AT+BLEGATTSCHAR?

Response:

The response for a characteristic:

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

The response for a descriptor:

+BLEGATTSCHAR:"desc",<srv_index>,<char_index>,<desc_index>
OK

Parameters

  • <srv_index>: service’s index starting from 1.
  • <char_index>: characteristic’s index starting from 1.
  • <char_uuid>: characteristic’s UUID.
  • <char_prop>: characteristic’s properties.
  • <desc_index>: descriptor’s index.
  • <desc_uuid>: descriptor’s UUID.

Example

AT+BLEINIT=2   // role: server
AT+BLEGATTSSRVCRE
AT+BLEGATTSSRVSTART
AT+BLEGATTSCHAR?

[ESP32 Only] AT+BLEGATTSNTFY: GATTS Notifies of Characteristics

Set Command

Function:

GATTS notifies of its characteristics.

Command:

AT+BLEGATTSNTFY=<conn_index>,<srv_index>,<char_index>,<length>

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 notification starts.

If the data transmission is successful, AT returns:

OK

Parameters

  • <conn_index>: index of Bluetooth LE connection. Range: [0,2].
  • <srv_index>: service’s index. It can be fetched with command AT+BLEGATTSCHAR?.
  • <char_index>: characteristic’s index. It can be fetched with command AT+BLEGATTSCHAR?.
  • <length>: data length.

Example

AT+BLEINIT=2      // Role: server.
AT+BLEGATTSSRVCRE
AT+BLEGATTSSRVSTART
AT+BLEADVSTART    // Start advertising. After the client is connected, it must be configured to receive notifications.
AT+BLEGATTSCHAR?  // Check the characteristics which the client will be notified of.
// For example, to notify of 4-byte data using the 6th characteristic in the 3rd service, use the following command:
AT+BLEGATTSNTFY=0,3,6,4
// After the symbol ">" shows, enter the 4-byte data, such as "1234". Then the data will be transmitted automatically.

[ESP32 Only] AT+BLEGATTSIND: GATTS Indicates Characteristics

Set Command

Function:

GATTS indicates its characteristics.

Command:

AT+BLEGATTSIND=<conn_index>,<srv_index>,<char_index>,<length>

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.

If the data transmission is successful, AT returns:

OK

Parameters

  • <conn_index>: index of Bluetooth LE connection. Range: [0,2].
  • <srv_index>: service’s index. It can be fetched with command AT+BLEGATTSCHAR?.
  • <char_index>: characteristic’s index; it can be fetched with command AT+BLEGATTSCHAR?.
  • <length>: data length.

Example

AT+BLEINIT=2      // Role: server
AT+BLEGATTSSRVCRE
AT+BLEGATTSSRVSTART
AT+BLEADVSTART    // Start advertising. After the client is connected, it must be configured to receive indications.
AT+BLEGATTSCHAR?  // Check the characteristics which the client can receive indications.
// For example, to indicate 4 bytes of data using the 7th characteristic in the 3rd service, use the following command:
AT+BLEGATTSIND=0,3,7,4
// After the symbol ">" shows, input 4 bytes of data, such as "1234". Then the data will be transmitted automatically.

[ESP32 Only] AT+BLEGATTSSETATTR: GATTS Sets Characteristic

Set Command

Function:

GATTS sets its characteristic (descriptor).

Command:

AT+BLEGATTSSETATTR=<srv_index>,<char_index>,[<desc_index>],<length>

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 setting starts.

If the setting is successful, AT returns:

OK

Parameters

  • <srv_index>: service’s index. It can be fetched with command AT+BLEGATTSCHAR?.
  • <char_index>: characteristic’s index; it can be fetched with command AT+BLEGATTSCHAR?.
  • [<desc_index>]: descriptor’s index.
    • If it is set, this command is used to set the value of the descriptor. Otherwise, this command is used to set the value of the characteristic.
  • <length>: data length.

Note

  • If the value of <length> is larger than the maximum length allowed, the setting will fail. The service table is defined in components/customized_partitions/raw_data/ble_data.

Example

AT+BLEINIT=2   // Role: server.
AT+BLEGATTSSRVCRE
AT+BLEGATTSSRVSTART
AT+BLEGATTSCHAR?
// For example, to set 1 byte of data of the 1st characteristic in the 1st service, use the following command:
AT+BLEGATTSSETATTR=1,1,,1
// After the symbol ">" shows, input 1 byte of data, such as "8". Then the setting starts.

[ESP32 Only] AT+BLEGATTCPRIMSRV: GATTC Discovers Primary Services

Query Command

Function:

Generic Attributes Client (GATTC) discovers primary services.

Command:

AT+BLEGATTCPRIMSRV=<conn_index>

Response:

+ BLEGATTCPRIMSRV:<conn_index>,<srv_index>,<srv_uuid>,<srv_type>
OK

Parameters

  • <conn_index>: index of Bluetooth LE connection. Range: [0,2].
  • <srv_index>: service’s index starting from 1.
  • <srv_uuid>: service’s UUID.
  • <srv_type>: service’s type.
    • 0: not primary service.
    • 1: primary service.

Note

  • The Bluetooth LE connection has to be established first.

Example

AT+BLEINIT=1   // role: client
AT+BLECONN=0,"24:12:5f:9d:91:98"
AT+BLEGATTCPRIMSRV=0

[ESP32 Only] AT+BLEGATTCINCLSRV: GATTC Discovers Included Services

Set Command

Function:

GATTC discovers included services.

Command:

AT+BLEGATTCINCLSRV=<conn_index>,<srv_index>

Response:

+ BLEGATTCINCLSRV:<conn_index>,<srv_index>,<srv_uuid>,<srv_type>,<included_srv_uuid>,<included_srv_type>
OK

Parameters

  • <conn_index>: index of Bluetooth LE connection. Only 0 is supported for the single connection right now. Multiple Bluetooth LE connections will be supported in the future.
  • <srv_index>: service’s index. It can be fetched with command AT+BLEGATTCPRIMSRV=<conn_index>.
  • <srv_uuid>: service’s UUID.
  • <srv_type>: service’s type.
    • 0: not primary service.
    • 1: primary service.
  • <included_srv_uuid>: included service’s UUID.
  • <included_srv_type>: included service’s type.
    • 0: not primary service.
    • 1: primary service.

Note

  • The Bluetooth LE connection has to be established first.

Example

AT+BLEINIT=1   // role: client
AT+BLECONN=0,"24:12:5f:9d:91:98"
AT+BLEGATTCPRIMSRV=0
AT+BLEGATTCINCLSRV=0,1  // set a specific index according to the result of the previous command

[ESP32 Only] AT+BLEGATTCCHAR: GATTC Discovers Characteristics

Set Command

Function:

GATTC discovers characteristics.

Command:

AT+BLEGATTCCHAR=<conn_index>,<srv_index>

Response:

The response for a characteristic:

+BLEGATTCCHAR:"char",<conn_index>,<srv_index>,<char_index>,<char_uuid>,<char_prop>

The response for a descriptor:

+BLEGATTCCHAR:"desc",<conn_index>,<srv_index>,<char_index>,<desc_index>,<desc_uuid>
OK

Parameters

  • <conn_index>: index of Bluetooth LE connection. Range: [0,2].
  • <srv_index>: service’s index. It can be fetched with command AT+BLEGATTCPRIMSRV=<conn_index>.
  • <char_index>: characteristic’s index starting from 1.
  • <char_uuid>: characteristic’s UUID.
  • <char_prop>: characteristic’s properties.
  • <desc_index>: descriptor’s index.
  • <desc_uuid>: descriptor’s UUID.

Note

  • The Bluetooth LE connection has to be established first.

Example

AT+BLEINIT=1   // role: client
AT+BLECONN=0,"24:12:5f:9d:91:98"
AT+BLEGATTCPRIMSRV=0
AT+BLEGATTCCHAR=0,1 // set a specific index according to the result of the previous command

[ESP32 Only] AT+BLEGATTCRD: GATTC Reads Characteristics

Set Command

Function:

GATTC reads a characteristic or descriptor.

Command:

AT+BLEGATTCRD=<conn_index>,<srv_index>,<char_index>[,<desc_index>]

Response:

+BLEGATTCRD:<conn_index>,<len>,<value>
OK

Parameters

  • <conn_index>: index of Bluetooth LE connection. Range: [0,2].
  • <srv_index>: service’s index. It can be fetched with command AT+BLEGATTCPRIMSRV=<conn_index>.
  • <char_index>: characteristic’s index; it can be fetched with command AT+BLEGATTCCHAR=<conn_index>,<srv_index>.
  • [<desc_index>]: descriptor’s index.
    • If it is set, the value of the target descriptor will be read.
    • if it is not set, the value of the target characteristic will be read.
  • <len>: data length.
  • <char_value>: characteristic’s value. HEX string is read by command AT+BLEGATTCRD=<conn_index>,<srv_index>,<char_index>. For example, if the response is +BLEGATTCRD:1,30, it means that the value length is 1, and the content is “0x30”.
  • [<desc_value>]: descriptor’s value. HEX string is read by command AT+BLEGATTCRD=<conn_index>,<srv_index>,<char_index>,<desc_index>. For example, if the response is +BLEGATTCRD:4,30313233, it means that the value length is 4, and the content is “0x30 0x31 0x32 0x33”.

Notes

  • The Bluetooth LE connection has to be established first.
  • If the target characteristic cannot be read, it will return “ERROR”.

Example:

AT+BLEINIT=1   // Role: client.
AT+BLECONN=0,"24:12:5f:9d:91:98"
AT+BLEGATTCPRIMSRV=0
AT+BLEGATTCCHAR=0,3 // Set a specific index according to the result of the previous command.
// For example, to read 1st descriptor of the 2nd characteristic in the 3rd service, use the following command:
AT+BLEGATTCRD=0,3,2,1

[ESP32 Only] AT+BLEGATTCWR: GATTC Writes Characteristics

Set Command

Function:

GATTC writes characteristics or descriptors.

Command:

AT+BLEGATTCWR=<conn_index>,<srv_index>,<char_index>[,<desc_index>],<length>

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.

If the setting is successful, AT returns:

OK

Parameters

  • <conn_index>: index of Bluetooth LE connection. Range: [0,2].
  • <srv_index>: service’s index. It can be fetched with command AT+BLEGATTCPRIMSRV=<conn_index>.
  • <char_index>: characteristic’s index; it can be fetched with command AT+BLEGATTCCHAR=<conn_index>,<srv_index>.
  • [<desc_index>]: descriptor’s index.
    • If it is set, the value of the target descriptor will be written.
    • If it is not set, the value of the target characteristic will be written.
  • <length>: data length.

Notes

  • The Bluetooth LE connection has to be established first.
  • If the target characteristic cannot be written, it will return “ERROR”.

Example

AT+BLEINIT=1   // Role: client.
AT+BLECONN=0,"24:12:5f:9d:91:98"
AT+BLEGATTCPRIMSRV=0
AT+BLEGATTCCHAR=0,3 // Set a specific index according to the result of the previous command.
// For example, to write 6 bytes of data to the 4th characteristic in the 3rd service, use the following command:
AT+BLEGATTCWR=0,3,4,,6
// After the symbol ">" shows, input 6 bytes of data, such as "123456". Then the writing starts.

[ESP32 Only] AT+BLESPPCFG: Set Bluetooth LE SPP Parameters

Query Command

Function:

Obtain the parameters of Bluetooth LE Serial Port Profile (SPP).

Command:

AT+BLESPPCFG?

Response:

+BLESPPCFG:<tx_service_index>,<tx_char_index>,<rx_service_index>,<rx_char_index>
OK

Set Command

Function:

Set or reset the parameters of Bluetooth LE SPP.

Command:

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

Response:

OK

Parameters

  • <option>:
    • 0: all the SPP parameters will be reset, and the following four parameters don’t need input.
    • 1: you should input the following four parameters.
  • <tx_service_index>: tx service’s index. It can be fetched with command AT+BLEGATTCPRIMSRV=<conn_index> and AT+BLEGATTSSRVCRE?.
  • <tx_char_index>: tx characteristic’s index. It can be fetched with command AT+BLEGATTCCHAR=<conn_index>,<srv_index> and AT+BLEGATTSCHAR?.
  • <rx_service_index>: rx service’s index. It can be fetched with command AT+BLEGATTCPRIMSRV=<conn_index> and AT+BLEGATTSSRVCRE?.
  • <rx_char_index>: rx characteristic’s index. It can be fetched with command AT+BLEGATTCCHAR=<conn_index>,<srv_index> and AT+BLEGATTSCHAR?.

Notes

  • In Bluetooth LE client, the property of tx characteristic must be write with response or write without response, and the property of rx characteristic must be indicate or notify.
  • In Bluetooth LE server, the property of tx characteristic must be indicate or notify, and the property of rx characteristic must be write with response or write without response.

Example

AT+BLESPPCFG=0          // reset Bluetooth LE SPP parameters
AT+BLESPPCFG=1,3,5,3,7  // set Bluetooth LE SPP parameters
AT+BLESPPCFG?           // query Bluetooth LE SPP parameters

[ESP32 Only] AT+BLESPP: Enter Bluetooth LE SPP Mode

Execute Command

Function:

Enter Bluetooth LE SPP mode.

Command:

AT+BLESPP

Response:

>

Notes

  • If the Bluetooth LE SPP parameters are illegal, this command will return ERROR.
  • During the SPP transmission, AT will not prompt any connection status changes unless bit2 of AT+SYSMSG is 1.

Example

AT+BLESPP   // enter Bluetooth LE SPP mode

[ESP32 Only] AT+BLESECPARAM: Set Bluetooth LE Encryption Parameters

Query Command

Function:

Obtain the parameters of Bluetooth LE SMP.

Command:

AT+BLESECPARAM?

Response:

+BLESECPARAM:<auth_req>,<iocap>,<key_size>,<init_key>,<rsp_key>,<auth_option>
OK

Set Command

Function:

Set the parameters of Bluetooth LE SMP.

Command:

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

Response:

OK

Parameters

  • <auth_req>: authentication request.
    • 0 : NO_BOND
    • 1 : BOND
    • 4 : MITM
    • 8 : SC_ONLY
    • 9 : SC_BOND
    • 12 : SC_MITM
    • 13 : SC_MITM_BOND
  • <iocap>: input and output capability.
    • 0 : DisplayOnly
    • 1 : DisplayYesNo
    • 2 : KeyboardOnly
    • 3 : NoInputNoOutput
    • 4 : Keyboard display
  • <key_size>: key length. Range: 7 ~ 16 bytes.
  • <init_key>: initial key represented in bit combinations.
  • <rsp_key>: response key represented in bit combinations.
  • <auth_option>: authentication option of security.
    • 0 : Select the security level automatically.
    • 1 : If it cannot follow the preset security level, the connection will disconnect.

Note

  • The bit pattern for init_key & rsp_key is:
    • Bit0: used to exchange the encryption key in the init key & response key.
    • Bit1: Used to exchange the IRK key in the init key & response key.
    • Bit2: Used to exchange the CSRK key in the init key & response key.
    • Bit3: Used to exchange the link key (only used in the Bluetooth LE & BR/EDR coexist mode) in the init key & response key.

Example

AT+BLESECPARAM=1,4,16,3,3,0

[ESP32 Only] AT+BLEENC: Initiate Bluetooth LE Encryption Request

Set Command

Function:

Start a pairing request

Command:

AT+BLEENC=<conn_index>,<sec_act>

Response:

OK

Parameters

  • <conn_index>: index of Bluetooth LE connection. Range: [0,2].
  • <sec_act>:
    • 0 : SEC_NONE
    • 1 : SEC_ENCRYPT
    • 2 : SEC_ENCRYPT_NO_MITM
    • 3 : SEC_ENCRYPT_MITM

Note

  • Before running this command, please set the security parameters and connection with remote devices.

Example

AT+BLESECPARAM=1,4,16,3,3
AT+BLEENC=0,3

[ESP32 Only] AT+BLEENCRSP: Grant Security Request Access

Set Command

Function:

Set a pairing response.

Command:

AT+BLEENCRSP=<conn_index>,<accept>

Response:

OK

Parameters

  • <conn_index>: index of Bluetooth LE connection. Range: [0,2].
  • <accept>:
    • 0 : reject
    • 1 : accept

Example

AT+BLEENCRSP=0,1

[ESP32 Only] AT+BLEKEYREPLY: Reply the Key Value to the Peer Device in the Legacy Connection Stage

Set Command

Function:

Reply a pairing key.

Command:

AT+BLEKEYREPLY=<conn_index>,<key>

Response:

OK

Parameters

  • <conn_index>: index of Bluetooth LE connection. Range: [0,2].
  • <key>: pairing key.

Example

AT+BLEKEYREPLY=0,649784

[ESP32 Only] AT+BLECONFREPLY: Reply the Confirm Value to the Peer Device in the Legacy Connection Stage

Set Command

Function:

Reply to a pairing result.

Command:

AT+BLECONFREPLY=<conn_index>,<confirm>

Response:

OK

Parameters

  • <conn_index>: index of Bluetooth LE connection. Range: [0,2].
  • <confirm>:
    • 0 : No
    • 1 : Yes

Example

AT+BLECONFREPLY=0,1

[ESP32 Only] AT+BLEENCDEV: Query Bluetooth LE Encryption Device List

Query Command

Function:

Obtain the bounded devices.

Command:

AT+BLEENCDEV?

Response:

+BLEENCDEV:<enc_dev_index>,<mac_address>
OK

Parameters

  • <enc_dev_index>: index of the bonded devices.
  • <mac_address>: MAC address.

Example

AT+BLEENCDEV?

[ESP32 Only] AT+BLEENCCLEAR: Clear Bluetooth LE Encryption Device List

Set Command

Function:

Remove a device from the security database list with a specific index.

Command:

AT+BLEENCCLEAR=<enc_dev_index>

Response:

OK

Execute Command

Function:

Remove all devices from the security database.

Command:

AT+BLEENCCLEAR

Response:

OK

Parameter

  • <enc_dev_index>: index of the bonded devices.

Example

AT+BLEENCCLEAR

[ESP32 Only] AT+BLESETKEY: Set Bluetooth LE Static Pair Key

Query Command

Function:

Query the Bluetooth LE static pair key. If it is not set, AT will return -1.

Command:

AT+BLESETKEY?

Response:

+BLESETKEY:<static_key>
OK

Set Command

Function:

Set a Bluetooth LE static pair key for all Bluetooth LE connections.

Command:

AT+BLESETKEY=<static_key>

Response:

OK

Parameter

  • <static_key>: static Bluetooth LE pair key.

Example

AT+BLESETKEY=123456

[ESP32 Only] AT+BLEHIDINIT: Bluetooth LE HID Profile Initialization

Query Command

Function:

Check the initialization status of Bluetooth LE HID profile.

Command:

AT+BLEHIDINIT?

Response:

If Bluetooth LE HID device profile is not initialized, AT will return:

+BLEHIDINIT:0
OK

If Bluetooth LE HID device profile is initialized, AT will return:

+BLEHIDINIT:1
OK

Set Command

Function:

Initialize the Bluetooth LE HID profile.

Command:

AT+BLEHIDINIT=<init>

Response:

OK

Parameter

  • <init>:
    • 0: deinit Bluetooth LE HID profile
    • 1: init Bluetooth LE HID profile

Note

  • The Bluetooth LE HID command cannot be used at the same time with general GATT/GAP commands.

Example

AT+BLEHIDINIT=1

[ESP32 Only] AT+BLEHIDKB: Send Bluetooth LE HID Keyboard Information

Set Command

Function:

Send keyboard information.

Command:

AT+BLEHIDKB=<Modifier_keys>,<key_1>,<key_2>,<key_3>,<key_4>,<key_5>,<key_6>

Response:

OK

Parameters

  • <Modifier_keys>: modifier keys mask
  • <key_1>: key code 1
  • <key_2>: key code 2
  • <key_3>: key code 3
  • <key_4>: key code 4
  • <key_5>: key code 5
  • <key_6>: key code 6

Example

AT+BLEHIDKB=0,4,0,0,0,0,0   // input the string "a"

[ESP32 Only] AT+BLEHIDMUS: Send Bluetooth LE HID Mouse Information

Set Command

Function:

Send mouse information.

Command:

AT+BLEHIDMUS=<buttons>,<X_displacement>,<Y_displacement>,<wheel>

Response:

OK

Parameters

  • <buttons>: mouse button
  • <X_displacement>: X displacement
  • <Y_displacement>: Y displacement
  • <wheel>: wheel

Example

AT+BLEHIDMUS=0,10,10,0

[ESP32 Only] AT+BLEHIDCONSUMER: Send Bluetooth LE HID Consumer Information

Set Command

Function:

Send consumer information.

Command:

AT+BLEHIDCONSUMER=<consumer_usage_id>

Response:

OK

Parameter

  • <consumer_usage_id>: consumer ID, such as power, reset, help, volume and so on.

Example

AT+BLEHIDCONSUMER=233   // volume up

[ESP32 Only] AT+BLUFI: Start or Stop BluFi

Query Command

Function:

Check the status of BluFi.

Command:

AT+BLUFI?

Response:

If BluFi is not started, it will return:

+BLUFI:0
OK

If BluFi is started, it will return:

+BLUFI:1
OK

Set Command

Function:

Start or stop BluFi.

Command:

AT+BLUFI=<option>[,<auth floor>]

Response:

OK

Parameter

  • <option>:
    • 0: stop BluFi
    • 1: start BluFi
  • <auth floor>: Wi-Fi authentication mode floor. ESP-AT will not connect to the AP whose authmode is lower than this floor.
    • 0: OPEN (Default)
    • 1: WEP
    • 2: WPA_PSK
    • 3: WPA2_PSK
    • 4: WPA_WPA2_PSK
    • 5: WPA2_ENTERPRISE
    • 6: WPA3_PSK
    • 7: WPA2_WPA3_PSK

Example

AT+BLUFI=1

[ESP32 Only] AT+BLUFINAME: Set BluFi Device Name

Query Command

Function:

Query the BluFi name.

Command:

AT+BLUFINAME?

Response:

+BLUFINAME:<device_name>
OK

Set Command

Function:

Set the BluFi device name.

Command:

AT+BLUFINAME=<device_name>

Response:

OK

Parameter

  • <device_name>: the name of BluFi device.

Notes

  • If you need to set BluFi name, please set it before command AT+BLUFI=1. Otherwise, it will use the default name BLUFI_DEVICE.
  • The maximum length of BluFi name is 29 bytes.

Example

AT+BLUFINAME="BLUFI_DEV"
AT+BLUFINAME?

Provide feedback about this document