esp-at application: BT Command Set
Introduction
ESP-AT commands support two classic bluetooth (BT) profiles: SPP and A2DP, but not all modules support BT commands by default. Only the release bin of WROVER-32 (ESP32-WROVER) support BT SPP commands by default.
If you need to use A2DP commands, please select modules with a PSRAM, and change the partition, since the default space allocated toapp.bin is 1.5MB, smaller than the size of firmware (1.7MB). In this case, it is recommended to use modules with a flash of 8M or above and a PSRAM.
Note:
- Only versions after
v2.0.0.0supportBT SPPcommands by default. Previous versions do not haveBTfeature; - You can use
make SILENCE=1to compile firemware. This command will reduce the size ofbinwithoutlogs.
1. Basic BT Commands
When using classic bluetooth, please initialize the bluetooth protocol stack. This is the prerequisite to use other BT commands.
Initialize BT
AT+BTINIT=1
OK
You can disable the protocol stack after use.
Turn Off BT
AT+BTINIT=0
OK
After initializing BT, you can set device name, discovery mode, encryption parameters, etc.
Set Device Name
AT+BTNAME="EXAMPLE"
OK
This step is self-evident.
Set Discovery Mode
AT+BTSCANMODE=2
OK
When the above parameter = 2, the device can be discovered and connected. For the meaning of 0 and 1, please refer to the command set.
It is recommend to set the parameter to 2. To make a device unconnectable after get connected, please re-set this parameter to 0.
Tips
- This parameter must be set for successful connection.
Set Security Parameter
AT+BTSECPARAM=3,1,"9527" // NO input NO output, fixed PIN code, 9527
OK
This command is used to set IO capabillity, PIN type and PIN code.
Tips
ESP-AT BTsupports bothSimple pairandLegacy pair. If the device other side supportsSimple pair,Legacy pairwill be ignored.
Discover Surrounding Device
// General inquiry mode, inquiry duration: 10, inquiry response: 10
AT+BTSTARTDISC=0,10,10
OK
For the definition and scope of parameters, please refer to the command set. For example:
AT+BTINIT=1
OK
AT+BTSCANMODE=2
OK
AT+BTSTARTDISC=0,10,10
+BTSTARTDISC:50:8f:4c:f2:84:19,xcg,0x2,0x3,0x2d0,-65
+BTSTARTDISC:50:8f:4c:f2:84:19,,0x2,0x3,0x2d0,-69
+BTSTARTDISC:50:8f:4c:f2:84:19,,0x2,0x3,0x2d0,-70
+BTSTARTDISC:50:8f:4c:f2:84:19,,0x2,0x3,0x2d0,-64
+BTSTARTDISC:a8:9c:ed:b0:06:ff,,0x2,0x3,0x2d0,-65
OK
Likewise, for description of parameters, please refer to the command set.
+BTSTARTDISC:<bt_addr>,<dev_name>,<major_dev_class>,<minor_dev_class>,<major_srv_class>
2. BT SPP Command
This section explains commands related to SPP Profile.
Please first initialize the BT protocol stack and the SPP Profile.
Initialize the SPP Profile
AT+BTSPPINIT=2
OK
Optional values of this parameter:
- 0: Disable
SPP profile - 1: Initialized as
Master - 2 Initialized as
Slave
In normal application scenarios, a module is connected to your PC or phone. Here we take a module initialized as a Slave as an example.
If you need two ESP32 AT modules for test, they can be initialized respectively as the Master and the Slave.
Enable the SPP Service
AT+BTSPPSTART
OK
This step is necessary and is recommended to be taken immediately after the module is initialized as the Slave. If the module is initialized as the Master, this step can be skipped.
Wait for Connection
Now the module should appear in your PC or phone’s Bluetooth setting window PC. Please click Connect.
Sometimes, if the module’connection to your PC is broken shortly after the connection, and there is no connection log, please open the serial port tool, choose SPP port, and click Connect. Then you should see the connection log.
+BTSPPCONN:<conn index>,<remote_addr>
Send Data
Command:
// conn_index: 0, data length: 30
AT+BTSPPSEND=0,30
>
OK
This command is used to send data of a specified length. To enter BT SPP transparent transmission mode, please type in exe:
AT+BTSPPSEND
>
To exit the transparent transmission mode, please type in '+++'.
Receive Data
If your PC or phone sends data to the device, a log will be produced in ESP-AT:
+BTDATA:<length>,<data>
For transparent transmission, the log only contains data.
Connect
If you connect two ESP32 BTdevices, then the connection is initiated by the Master:
For example:
// conn_index: 0, sec_mode: 0 -> No security, remote_address
AT+BTSPPCONN=0,0,"24:0a:c4:09:34:23"
OK
Tips
- The seond parameter above should be set to 0.
3. BT A2DP Command
A2DP has two roles: A2DP Sink and A2DP Source.
After the BT protocol stack is initialized, the device can be initialized as the Sink or the Source.
3.1 Initialize the Device as the Sink
Before initializing the device as the Sink, please run the following commands:
AT+BTINIT=1
OK
AT+BTSCANMODE=2
OK
It is optional to set the device name and security parameters.
Then initialize the A2DP Profile:
AT+BTA2DPINIT=2
OK
Now you can wait for your device to be connected. If the Source plays music, the Sink could:
- Pause
- Play
- Fast Forward
- Next Track
- Previous Track
AT+BTA2DPCTRL=<conn_index>,<ctrl>
OK
-
ctrl: types of control.
- 0 : stop play
- 1 : start play
- 2 : forward
- 3 : backward
- 4 : fastward start
- 5 : fastward stop
Tips:
- When the device is the
A2DP Sink, please add codes ofI2S. You can put codes for initializingI2Sinto externalapp_main. - Please add driver codes of the
decoder.
3.2 Initialize the Device as the Source
Before initilizing the device theA2DP Source, please run commands described at the beginning of 3.2.
Then initialize the A2DP Profile:
AT+BTA2DPINIT=2
OK
Set audio source:
AT+BTA2DPSRC="https://dl.espressif.com/dl/audio/ff-16b-2c-44100hz.mp3"
ESP AT only supports MP3 format, and will later extend to other formats and audio files read from local flash.
Before you play music, please make sure that your device is connected to the Internet via a router.
Play music:
AT+BTA2DPCTRL=<conn_index>,<ctrl>
OK
-
conn_index: index of classic bluetooth A2DP connection; only 0 is supported for the single connection right now.
-
ctrl: types of control.
- 0 : stop play
- 1 : start play
- 2 : suspend