esp-at application: BT Command Set

AT Application: https://github.com/espressif/esp-at
AT Documentation: https://docs.espressif.com/projects/esp-at/en/latest/

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.0 support BT SPP commands by default. Previous versions do not have BT feature;
• You can use make SILENCE=1 to compile firemware. This command will reduce the size of bin without logs.

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 BT supports both Simple pair and Legacy pair. If the device other side supports Simple pair, Legacy pair will 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 of I2S. You can put codes for initializing I2S into external app_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