[ESP32 Only] Classic Bluetooth® AT Commands

ESP32 AT firmware supports Bluetooth® Core Specification Version 5.0.

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

[ESP32 Only] AT+BTINIT: Classic Bluetooth Initialization

Query Command

Function:

Check 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

Command:

AT+BTINIT=<init>

Function:

Initialize or deinitialize Classic Bluetooth.

Response:

OK

Parameter

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

Example

AT+BTINIT=1

[ESP32 Only] AT+BTNAME: Query/Set Classic Bluetooth Device Name

Query Command

Function:

Obtain the Classic Bluetooth device name.

Command:

AT+BTNAME?

Response:

+BTNAME:<device_name>
OK

Set Command

Function:

Set the Classic Bluetooth device name. The maximum length is 32.

Command:

AT+BTNAME=<device_name>

Response:

OK

Parameter

  • <device_name>: the Classic Bluetooth device name.

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"

[ESP32 Only] 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

[ESP32 Only] 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

[ESP32 Only] AT+BTSPPINIT: Classic Bluetooth SPP Profile Initialization

Query Command

Function:

Check 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

[ESP32 Only] 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"

[ESP32 Only] 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

[ESP32 Only] 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 ESP device 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

[ESP32 Only] 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

[ESP32 Only] AT+BTA2DPINIT: Classic Bluetooth A2DP Profile Initialization

Query Command

Function:

Check the initialization status of Classic Bluetooth A2DP profile.

Command:

AT+BTA2DPINIT?

Response:

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

+BTA2DPINIT:1
OK

Otherwise, AT will return:

+BTA2DPINIT:0
OK

Set Command

Function:

Initialize or deinitialize Classic Bluetooth A2DP profile.

Command:

AT+BTA2DPINIT=<role>,<init_val>

Response:

OK

Parameters

  • <role>:
    • 0: source.
    • 1: sink.
  • <init_val>:
    • 0: deinitialize Classic Bluetooth A2DP profile.
    • 1: initialize Classic Bluetooth A2DP profile.

Example

AT+BTA2DPINIT=0,1

[ESP32 Only] 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>,fail

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"

[ESP32 Only] 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

[ESP32 Only] 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"

[ESP32 Only] 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

[ESP32 Only] 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"

[ESP32 Only] 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

[ESP32 Only] 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"

[ESP32 Only] 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

[ESP32 Only] AT+BTENCDEV: Query Classic Bluetooth Encryption Device List

Query Command

Function:

Obtain the bonded devices.

Command:

AT+BTENCDEV?

Response:

+BTENCDEV:<enc_dev_index>,<mac_address>
OK

Parameters

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

Example

AT+BTENCDEV?

[ESP32 Only] 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 bonded devices.

Example

AT+BTENCCLEAR

[ESP32 Only] 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

[ESP32 Only] AT+BTPOWER: 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.