ESP32 Classic Bluetooth® AT Commands

ESP32 AT firmware supports Bluetooth® Core Specification Version 4.2.

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.

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.

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+BLEENCCLEAR

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