[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: Query/Set power of Classic Bluetooth.
[ESP32 Only] 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
[ESP32 Only] 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.
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:
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
[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:
Query 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>,-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"
[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:
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?
[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 bound 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¶
<major>: major class.
<minor>: minor class.
<service>: service class.
Example¶
AT+BTCOD=6,32,32 // the printer
[ESP32 Only] 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.