ESP32 Classic Bluetooth® AT Commands

Introduction
AT+BTINIT: Classic Bluetooth initialization.
AT+BTNAME: Query/Set Classic Bluetooth device name.
AT+BTSCANMODE: Set Classic Bluetooth scan mode.
AT+BTSTARTDISC: Start Classic Bluetooth discovery.
AT+BTSPPINIT: Classic Bluetooth SPP profile initialization.
AT+BTSPPCONN: Query/Establish SPP connection.
AT+BTSPPDISCONN: End SPP connection.
AT+BTSPPSTART: Start Classic Bluetooth SPP profile.
AT+BTSPPSEND: Send data to remote Classic Bluetooth SPP device.
AT+BTA2DPINIT: Classic Bluetooth A2DP profile initialization.
AT+BTA2DPCONN: Establish A2DP connection.
AT+BTA2DPDISCONN: End A2DP connection.
AT+BTA2DPSRC: Query/Set the audio file URL.
AT+BTA2DPCTRL: Control the audio play.
AT+BTSECPARAM: Query/Set the Classic Bluetooth security parameters.
AT+BTKEYREPLY: Input the Simple Pair Key.
AT+BTPINREPLY: Input the Legacy Pair PIN Code.
AT+BTSECCFM: Reply the confirm value to the peer device in the legacy connection stage.
AT+BTENCDEV: Query Classic Bluetooth encryption device list.
AT+BTENCCLEAR: Clear Classic Bluetooth encryption device list.
AT+BTCOD: Set class of devices.
AT+BTPOWER: Query/Set power of Classic Bluetooth.

Introduction

ESP32 AT firmware supports Bluetooth® Core Specification Version 4.2.

Important

The default AT firmware does not support the AT commands listed on this page. If you need ESP32 to support Classic Bluetooth commands, you can compile the ESP-AT project by following the steps in Compile ESP-AT Project Locally documentation. In the project configuration during the fifth step, make the following selections (Each item below is independent. Choose it according to your needs):

Enable Generic Bluetooth commands: Component config -> AT -> AT bt command support
Enable SPP commands: Component config -> AT -> AT bt command support -> AT bt spp command support
Enable A2DP commands:Component config -> AT -> AT bt command support -> AT bt a2dp command support

AT+BTINIT: Classic Bluetooth Initialization

Query Command

Function:

Query the initialization status of Classic Bluetooth.

Command:

AT+BTINIT?

Response:

If Classic Bluetooth is initialized, AT will return:

+BTINIT:1
OK

If Classic Bluetooth is not initialized, AT will return:

+BTINIT:0
OK

Set Command

Function:

Initialize or deinitialize Classic Bluetooth.

Command:

AT+BTINIT=<init>

Response:

OK

Parameter

<init>:
- 0: deinitialize Classic Bluetooth.
- 1: initialize Classic Bluetooth.

Notes

To achieve better performance, it is recommended to disable SoftAP by sending the AT+CWMODE=0/1 command before using Classic Bluetooth function. For more details, please refer to the RF Coexistence documentation.
If Classic Bluetooth is initialized, AT+CIPMODE cannot be set to 1.

Example

AT+BTINIT=1

AT+BTNAME: Query/Set Classic Bluetooth Device Name

Query Command

Function:

Query the Classic Bluetooth device name.

Command:

AT+BTNAME?

Response:

+BTNAME:<device_name>
OK

Set Command

Function:

Set the Classic Bluetooth device name.

Command:

AT+BTNAME=<device_name>

Response:

OK

Parameter

<device_name>: the Classic Bluetooth device name. The maximum length is 32. Default: “ESP32_AT”.

Notes

The configuration changes will be saved in the NVS area if AT+SYSSTORE=1.
The default Classic Bluetooth device name is “ESP32_AT”.

Example

AT+BTNAME="esp_demo"

AT+BTSCANMODE: Set Classic Bluetooth Scan Mode

Set Command

Function:

Set the scan mode of Classic Bluetooth.

Command:

AT+BTSCANMODE=<scan_mode>

Response:

OK

Parameter

<scan_mode>:
- 0: Neither discoverable nor connectable.
- 1: Connectable but not discoverable.
- 2: Both discoverable and connectable.
- 3: Discoverable but not connectable.

Example

AT+BTSCANMODE=2   // both discoverable and connectable

AT+BTSTARTDISC: Start Classic Bluetooth Discovery

Set Command

Function:

Start Classic Bluetooth discovery.

Command:

AT+BTSTARTDISC=<inq_mode>,<inq_len>,<inq_num_rsps>

Response:

+BTSTARTDISC:<bt_addr>,<dev_name>,<major_dev_class>,<minor_dev_class>,<major_srv_class>,<rssi>

OK

Parameters

<inq_mode>:
- 0: general inquiry mode.
- 1: limited inquiry mode.
<inq_len>: inquiry duration. Range: 0x01 ~ 0x30.
<inq_num_rsps>: number of inquiry responses that can be received. If you set it to 0, AT will receive an unlimited number of responses.
<bt_addr>: Classic Bluetooth address.
<dev_name>: device name.
<major_dev_class>:
- 0x0: miscellaneous.
- 0x1: computer.
- 0x2: phone (cellular, cordless, pay phone, modem).
- 0x3: LAN, Network Access Point.
- 0x4: audio/video (headset, speaker, stereo, video display, VCR).
- 0x5: peripheral (mouse, joystick, keyboard).
- 0x6: imaging (printer, scanner, camera, display).
- 0x7: wearable.
- 0x8: toy.
- 0x9: health.
- 0x1F: uncategorized device.
<minor_dev_class>: please refer to Minor Device Class field.
<major_srv_class>:
- 0x0: an invalid value.
- 0x1: Limited Discoverable Mode.
- 0x8: positioning (location identification).
- 0x10: networking, such as LAN, Ad hoc.
- 0x20: rendering, such as printing, speakers.
- 0x40: capturing, such as scanner, microphone.
- 0x80: object transfer, such as v-Inbox, v-Folder.
- 0x100: audio, such as speaker, microphone, headerset service.
- 0x200: telephony, such as cordless telephony, modem, headset service.
- 0x400: information, such as WEB-server, WAP-server.
<rssi>: signal strength.

Example

AT+BTINIT=1
AT+BTSCANMODE=2
AT+BTSTARTDISC=0,10,10

AT+BTSPPINIT: Classic Bluetooth SPP Profile Initialization

Query Command

Function:

Query the initialization status of Classic Bluetooth SPP profile.

Command:

AT+BTSPPINIT?

Response:

If Classic Bluetooth SPP profile is initialized, it will return:

+BTSPPINIT:1
OK

If Classic Bluetooth SPP profile is not initialized, it will return:

+BTSPPINIT:0
OK

Set Command

Function:

Initialize or deinitialize Classic Bluetooth SPP profile.

Command:

AT+BTSPPINIT=<init>

Response:

OK

Parameter

<init>:
- 0: deinitialize Classic Bluetooth SPP profile.
- 1: initialize Classic Bluetooth SPP profile, the role is master.
- 2: initialize Classic Bluetooth SPP profile, the role is slave.

Example

AT+BTSPPINIT=1    // master
AT+BTSPPINIT=2    // slave

AT+BTSPPCONN: Query/Establish SPP Connection

Query Command

Function:

Query Classic Bluetooth SPP connection.

Command:

AT+BTSPPCONN?

Response:

+BTSPPCONN:<conn_index>,<remote_address>
OK

If the connection has not been established, AT will return:

+BTSPPCONN:-1

Set Command

Function:

Establish the Classic Bluetooth SPP connection.

Command:

AT+BTSPPCONN=<conn_index>,<sec_mode>,<remote_address>

Response:

OK

If the connection is established successfully, AT will return:

+BTSPPCONN:<conn_index>,<remote_address>

Otherwise, AT will return:

+BTSPPCONN:<conn_index>,-1

Parameters

<conn_index>: index of Classic Bluetooth SPP connection. Only 0 is supported for the single connection right now.
<sec_mode>:
- 0x0000: no security.
- 0x0001: authorization required (only needed for out going connection).
- 0x0036: encryption required.
- 0x3000: Man-In-The-Middle protection.
- 0x4000: Min 16 digit for pin code.
<remote_address>: remote Classic Bluetooth SPP device address.

Example

AT+BTSPPCONN=0,0,"24:0a:c4:09:34:23"

AT+BTSPPDISCONN: End SPP Connection

Execute Command

Function:

End the Classic Bluetooth SPP connection.

Command:

AT+BTSPPDISCONN=<conn_index>

Response:

OK

If the command is successful, it will prompt:

+BTSPPDISCONN:<conn_index>,<remote_address>

If the command is fail, it will prompt:

+BTSPPDISCONN:-1

Parameters

<conn_index>: index of Classic Bluetooth SPP connection. Only 0 is supported for the single connection right now.
<remote_address>: remote Classic Bluetooth A2DP device address.

Example

AT+BTSPPDISCONN=0

AT+BTSPPSEND: Send Data to Remote Classic Bluetooth SPP Device

Execute Command

Function:

Enter Classic Bluetooth SPP mode.

Command:

AT+BTSPPSEND

Response:

Set Command

Function:

Send data to the remote Classic Bluetooth SPP device.

Command:

AT+BTSPPSEND=<conn_index>,<data_len>

Response:

OK

Parameters

<conn_index>: index of Classic Bluetooth SPP connection. Only 0 is supported for the single connection right now.
<data_len>: the length of the data which is ready to be sent.

Notes

The wrap return is > after this command is executed. Then, the ESP32 enters UART Bluetooth passthrough mode. When the packet which only contains +++ is received, the device returns to normal command mode. Please wait for at least one second before sending the next AT command.

Example

AT+BTSPPSEND=0,100
AT+BTSPPSEND

AT+BTSPPSTART: Start Classic Bluetooth SPP Profile

Execute Command

Function:

Start Classic Bluetooth SPP profile.

Command:

AT+BTSPPSTART

Response:

OK

Note

During the SPP transmission, AT will not prompt any connection status changes unless bit2 of AT+SYSMSG is 1.

Example

AT+BTSPPSTART

AT+BTA2DPINIT: Classic Bluetooth A2DP Profile Initialization

Query Command

Function:

Query the initialization status of Classic Bluetooth A2DP profile.

Command:

AT+BTA2DPINIT?

Response:

If Classic Bluetooth A2DP profile is initialized, AT will return:

+BTA2DPINIT:<role>

OK

Otherwise, AT will return:

+BTA2DPINIT:0

OK

Set Command

Function:

Initialize or deinitialize Classic Bluetooth A2DP profile.

Command:

AT+BTA2DPINIT=<role>

Response:

OK

Parameters

<role>: role
- 0: deinitialize Classic Bluetooth A2DP profile.
- 1: source.
- 2: sink.

Example

AT+BTA2DPINIT=2

AT+BTA2DPCONN: Query/Establish A2DP Connection

Query Command

Function:

Query Classic Bluetooth A2DP connection.

Command:

AT+BTA2DPCONN?

Response:

+BTA2DPCONN:<conn_index>,<remote_address>
OK

If the connection has not been established, AT will NOT return the parameter <conn_index> and <remote_address>.

Set Command

Function:

Establish the Classic Bluetooth A2DP connection.

Command:

AT+BTA2DPCONN=<conn_index>,<remote_address>

Response:

OK

If the connection is established successfully, it will prompt the message below:

+BTA2DPCONN:<conn_index>,<remote_address>

Otherwise, it will return:

+BTA2DPCONN:<conn_index>,-1

Parameters

<conn_index>: index of Classic Bluetooth A2DP connection. Only 0 is supported for the single connection right now.
<remote_address>: remote Classic Bluetooth A2DP device address.

Example

AT+BTA2DPCONN=0,0,0,"24:0a:c4:09:34:23"

AT+BTA2DPDISCONN: End A2DP Connection

Execute Command

Function:

End the Classic Bluetooth A2DP connection.

Command:

AT+BTA2DPDISCONN=<conn_index>

Response:

+BTA2DPDISCONN:<conn_index>,<remote_address>
OK

Parameters

<conn_index>: index of Classic Bluetooth A2DP connection. Only 0 is supported for the single connection right now.
<remote_address>: remote Classic Bluetooth A2DP device address.

Example

AT+BTA2DPDISCONN=0

AT+BTA2DPSRC: Query/Set the Audio File URL

Query Command

Function:

Query the audio file URL.

Command:

AT+BTA2DPSRC?

Response:

+BTA2DPSRC:<url>,<type>
OK

Execute Command

Function:

Set the audio file URL.

Command:

AT+BTA2DPSRC=<conn_index>,<url>

Response:

OK

Parameters

<conn_index>: index of Classic Bluetooth A2DP connection. Only 0 is supported for the single connection right now.
<url>: the path of the source file. HTTP, HTTPS and FLASH are currently supported.
<type>: the type of audio file, such as “mp3”.

Note

Only mp3 format is currently supported.

Example

AT+BTA2DPSRC=0,"https://dl.espressif.com/dl/audio/ff-16b-2c-44100hz.mp3"
AT+BTA2DPSRC=0,"flash://spiffs/zhifubao.mp3"

AT+BTA2DPCTRL: Control the Audio Play

Execute Command

Function:

Control the audio play.

Command:

AT+BTA2DPCTRL=<conn_index>,<ctrl>

Response:

OK

Parameters

<conn_index>: index of Classic Bluetooth A2DP connection. Only 0 is supported for the single connection right now.
<ctrl>: types of control.
- 0: A2DP Sink, stop play.
- 1: A2DP Sink, start play.
- 2: A2DP Sink, forward.
- 3: A2DP Sink, backward.
- 4: A2DP Sink, fastward start.
- 5: A2DP Sink, fastward stop.
- 0: A2DP Source, stop play.
- 1: A2DP Source, start play.
- 2: A2DP Source, suspend.

Example

AT+BTA2DPCTRL=0,1  // start play audio

AT+BTSECPARAM: Query/Set the Classic Bluetooth Security Parameters

Query Command

Function:

Query Classic Bluetooth security parameters.

Command:

AT+BTSECPARAM?

Response:

+BTSECPARAM:<io_cap>,<pin_type>,<pin_code>
OK

Set Command

Function:

Set the Classic Bluetooth security parameters.

Command:

AT+BTSECPARAM=<io_cap>,<pin_type>,<pin_code>

Response:

OK

Parameters

<io_cap>: input and output capability.
- 0: DisplayOnly.
- 1: DisplayYesNo.
- 2: KeyboardOnly.
- 3: NoInputNoOutput.
<pin_type>: use variable or fixed PIN.
- 0: variable.
- 1: fixed.
<pin_code>: Legacy Pair PIN Code. Maximum: 16 bytes.

Note

If you set the parameter <pin_type> to 0, <pin_code> will be ignored.

Example

AT+BTSECPARAM=3,1,"9527"

AT+BTKEYREPLY: Input the Simple Pair Key

Execute Command

Function:

Input the Simple Pair Key.

Command:

AT+BTKEYREPLY=<conn_index>,<Key>

Response:

OK

Parameters

<conn_index>: index of Classic Bluetooth connection. Currently, only 0 is supported for the single connection.
<Key>: the Simple Pair Key.

Example

AT+BTKEYREPLY=0,123456

AT+BTPINREPLY: Input the Legacy Pair PIN Code

Execute Command

Function:

Input the Legacy Pair PIN Code.

Command:

AT+BTPINREPLY=<conn_index>,<Pin>

Response:

OK

Parameters

<conn_index>: index of Classic Bluetooth connection. Currently, only 0 is supported for the single connection.
<Pin>: the Legacy Pair PIN Code.

Example

AT+BTPINREPLY=0,"6688"

AT+BTSECCFM: Reply the Confirm Value to the Peer Device in the Legacy Connection Stage

Execute Command

Function:

Reply the confirm value to the peer device in the legacy connection stage.

Command:

AT+BTSECCFM=<conn_index>,<accept>

Response:

OK

Parameters

<conn_index>: index of Classic Bluetooth connection. Currently, only 0 is supported for the single connection.
<accept>: reject or accept.
- 0: reject.
- 1: accept.

Example

AT+BTSECCFM=0,1

AT+BTENCDEV: Query Classic Bluetooth Encryption Device List

Query Command

Function:

Query the bound devices.

Command:

AT+BTENCDEV?

Response:

+BTENCDEV:<enc_dev_index>,<mac_address>
OK

Parameters

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

Example

AT+BTENCDEV?

AT+BTENCCLEAR: Clear Classic Bluetooth Encryption Device List

Set Command

Function:

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

Command:

AT+BTENCCLEAR=<enc_dev_index>

Response:

OK

Execute Command

Function:

Remove all devices from the security database.

Command:

AT+BTENCCLEAR

Response:

OK

Parameter

<enc_dev_index>: index of the bound devices.

Example

AT+BTENCCLEAR

AT+BTCOD: Set Class of Devices

Set Command

Function:

Set the Classic Bluetooth class of devices.

Command:

AT+BTCOD=<major>,<minor>,<service>

Response:

OK

Parameters

<major>: major class.
<minor>: minor class.
<service>: service class.

Example

AT+BTCOD=6,32,32   // the printer

AT+BTPOWER: Query/Set TX power of Classic Bluetooth

Query Command

Function:

Query Classic Bluetooth tx power level.

Command:

AT+BTPOWER?

Response:

+BTPOWER:<min_tx_power>,<max_tx_power>
OK

Set Command

Function:

Set the Classic Bluetooth tx power.

Command:

AT+BTPOWER=<min_tx_power>,<max_tx_power>

Response:

OK

Parameters

<min_tx_power>: The minimum power level. Range: [0,7].
<max_tx_power>: The maximum power level. Range: [0,7].

Example

AT+BTPOWER=5,6   // set Classic Bluetooth tx power.

Provide feedback about this document