ESP32 Classic Bluetooth® AT Commands

[中文]

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

  • 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

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.