[ESP32 Only] Classic Bluetooth® AT 命令集¶
ESP32 AT 固件支持 蓝牙核心规范 5.0 版本。
- [ESP32 Only] AT+BTINIT：Classic Bluetooth 初始化
- [ESP32 Only] AT+BTNAME：查询/设置 Classic Bluetooth 设备名称
- [ESP32 Only] AT+BTSCANMODE：设置 Classic Bluetooth 扫描模式
- [ESP32 Only] AT+BTSTARTDISC：开始发现周边 Classic Bluetooth 设备
- [ESP32 Only] AT+BTSPPINIT：Classic Bluetooth SPP 协议初始化
- [ESP32 Only] AT+BTSPPCONN：查询/建立 SPP 连接
- [ESP32 Only] AT+BTSPPDISCONN：断开 SPP 连接
- [ESP32 Only] AT+BTSPPSTART：开启 Classic Bluetooth SPP 协议
- [ESP32 Only] AT+BTSPPSEND：发送数据到对方 Classic Bluetooth SPP 设备
- [ESP32 Only] AT+BTA2DPINIT：Classic Bluetooth A2DP 协议初始化
- [ESP32 Only] AT+BTA2DPCONN：查询/建立 A2DP 连接
- [ESP32 Only] AT+BTA2DPDISCONN：断开 A2DP 连接
- [ESP32 Only] AT+BTA2DPSRC：查询/设置音频文件 URL
- [ESP32 Only] AT+BTA2DPCTRL：控制音频播放
- [ESP32 Only] AT+BTSECPARAM：查询/设置 Classic Bluetooth 安全参数
- [ESP32 Only] AT+BTKEYREPLY：输入简单配对密钥 (Simple Pair Key)
- [ESP32 Only] AT+BTPINREPLY：输入传统配对密码 (Legacy Pair PIN Code)
- [ESP32 Only] AT+BTSECCFM：给对方设备回复确认结果（传统连接阶段）
- [ESP32 Only] AT+BTENCDEV：查询 Classic Bluetooth 加密设备列表
- [ESP32 Only] AT+BTENCCLEAR：清除 Classic Bluetooth 加密设备列表
- [ESP32 Only] AT+BTCOD：设置设备类型
- [ESP32 Only] AT+BTPOWER：查询/设置 Classic Bluetooth 的 TX 功率
[ESP32 Only] AT+BTINIT：Classic Bluetooth 初始化¶
查询命令¶
功能：
查询 Classic Bluetooth 初始化状态
命令：
AT+BTINIT?
响应：
若已初始化，则返回：
+BTINIT:1
OK
若未初始化，则返回：
+BTINIT:0
OK
参数¶
- <init>：
- 0: 注销 Classic Bluetooth；
- 1: 初始化 Classic Bluetooth。
示例¶
AT+BTINIT=1
[ESP32 Only] AT+BTNAME：查询/设置 Classic Bluetooth 设备名称¶
参数¶
- <device_name>：Classic Bluetooth 设备名称，最大长度为：32。
说明¶
- 若 AT+SYSSTORE=1，配置更改将保存在 NVS 区。
- 默认 Classic Bluetooth 设备名称为 “ESP32_AT”。
示例¶
AT+BTNAME="esp_demo"
[ESP32 Only] AT+BTSCANMODE：设置 Classic Bluetooth 扫描模式¶
参数¶
- <scan_mode>：
- 0: 不可发现且不可连接；
- 1: 可连接但不可发现；
- 2: 既可发现也可连接；
- 3: 可发现但不可连接。
示例¶
AT+BTSCANMODE=2 // 既可发现也可连接
[ESP32 Only] AT+BTSTARTDISC：开始发现周边 Classic Bluetooth 设备¶
设置命令¶
功能：
开始发现 Classic Bluetooth 设备
命令：
AT+BTSTARTDISC=<inq_mode>,<inq_len>,<inq_num_rsps>
响应：
+BTSTARTDISC:<bt_addr>,<dev_name>,<major_dev_class>,<minor_dev_class>,<major_srv_class>,<rssi>
OK
参数¶
- <inq_mode>：
- 0: general inquiry mode；
- 1: limited inquiry mode。
- <inq_len>：inquiry 时长，范围：0x01 ~ 0x30。
- <inq_num_rsps>：可以收到的 inquiry responses 的数量，若设为 0，AT 将收到无限个 response。
- <bt_addr>：Classic Bluetooth 地址。
- <dev_name>：设备名称。
- <major_dev_class>：主要设备类型：
- 0x0: 其他；
- 0x1: 计算机；
- 0x2: 电话（手机、无绳、支付电话、调制解调器）；
- 0x3: LAN、网络接入点；
- 0x4: 音频/视频（耳机、扬声器、立体声、视频显示、VCR）；
- 0x5: 配件（鼠标、游戏杆、键盘）；
- 0x6: 成像（打印、扫描仪、相机、显示）；
- 0x7: 可穿戴；
- 0x8: 玩具；
- 0x9: 健康；
- 0x1F: 未分类。
- <minor_dev_class>：请参考 次要设备类型 (Minor Device Class field)。
- <major_srv_class>：主要服务类型：
- 0x0: 无效值；
- 0x1: 有限可发现模式 (Limited Discoverable Mode)；
- 0x8: 定位（位置标志）；
- 0x10: 网络，如 LAN、点对点；
- 0x20: 渲染，如打印、扬声器；
- 0x40: 捕捉，如扫描仪、麦克风；
- 0x80: 对象传输，如 v-Inbox、v-Folder；
- 0x100: 音频，如扬声器、麦克风、耳机服务；
- 0x200: 电话，如无绳电话、调制解调器、耳机服务；
- 0x400: 信息，如 WEB 服务器、WAP 服务器。
- <rssi>：信号强度。
示例¶
AT+BTINIT=1
AT+BTSCANMODE=2
AT+BTSTARTDISC=0,10,10
[ESP32 Only] AT+BTSPPINIT：Classic Bluetooth SPP 协议初始化¶
查询命令¶
功能：
查询 Classic Bluetooth SPP 协议初始化状态
命令：
AT+BTSPPINIT?
响应：
若已初始化，则返回：
+BTSPPINIT:1
OK
若未初始化，则返回：
+BTSPPINIT:0
OK
参数¶
- <init>：
- 0: 注销 Classic Bluetooth SPP 协议；
- 1: 初始化 Classic Bluetooth SPP 协议，角色为 master；
- 2: 初始化 Classic Bluetooth SPP 协议，角色为 slave。
示例¶
AT+BTSPPINIT=1 // master
AT+BTSPPINIT=2 // slave
[ESP32 Only] AT+BTSPPCONN：查询/建立 SPP 连接¶
查询命令¶
功能：
查询 Classic Bluetooth SPP 连接
命令：
AT+BTSPPCONN?
响应：
+BTSPPCONN:<conn_index>,<remote_address>
OK
如果未建立连接，则返回：
+BTSPPCONN:-1
设置命令¶
功能：
建立 Classic Bluetooth SPP 连接
命令：
AT+BTSPPCONN=<conn_index>,<sec_mode>,<remote_address>
响应：
OK
若建立连接成功，则 AT 返回：
+BTSPPCONN:<conn_index>,<remote_address>
若建立连接失败，则 AT 返回：
+BTSPPCONN:<conn_index>,-1
参数¶
- <conn_index>：Classic Bluetooth SPP 连接号，当前只支持单连接，连接号为 0。
- <sec_mode>：
- 0x0000: 无安全保障；
- 0x0001: 需要授权（仅对外连接需要）；
- 0x0036: 需要加密；
- 0x3000: 中间人保护；
- 0x4000: 最少 16 位密码。
- <remote_address>：对方 Classic Bluetooth SPP 设备地址。
示例¶
AT+BTSPPCONN=0,0,"24:0a:c4:09:34:23"
[ESP32 Only] AT+BTSPPDISCONN：断开 SPP 连接¶
执行命令¶
功能：
断开 Classic Bluetooth SPP 连接
命令：
AT+BTSPPDISCONN=<conn_index>
响应：
OK
若命令运行成功，则返回：
+BTSPPDISCONN:<conn_index>,<remote_address>
若命令运行失败，则返回：
+BTSPPDISCONN:-1
参数¶
- <conn_index>：Classic Bluetooth SPP 连接号，当前只支持单连接，连接号为 0。
- <remote_address>：对方 Classic Bluetooth A2DP 设备地址。
示例¶
AT+BTSPPDISCONN=0
[ESP32 Only] AT+BTSPPSEND：发送数据到对方 Classic Bluetooth SPP 设备¶
参数¶
- <conn_index>：Classic Bluetooth SPP 连接号，当前只支持单连接，连接号为 0。
- <data_len>：发送数据的长度。
示例¶
AT+BTSPPSEND=0,100
AT+BTSPPSEND
[ESP32 Only] AT+BTSPPSTART：开启 Classic Bluetooth SPP 协议¶
示例¶
AT+BTSPPSTART
[ESP32 Only] AT+BTA2DPINIT：Classic Bluetooth A2DP 协议初始化¶
查询命令¶
功能：
查询 Classic Bluetooth A2DP 协议的初始化状态
命令：
AT+BTA2DPINIT?
响应：
若已初始化，则返回：
+BTA2DPINIT:1
OK
若未初始化，则返回：
+BTA2DPINIT:0
OK
参数¶
- <role>：角色
- 0: source；
- 1: sink。
- <init_val>：
- 0: 注销 Classic Bluetooth A2DP 协议；
- 1: 初始化 Classic Bluetooth A2DP 协议。
示例¶
AT+BTA2DPINIT=0,1
[ESP32 Only] AT+BTA2DPCONN：查询/建立 A2DP 连接¶
查询命令¶
功能：
查询 Classic Bluetooth A2DP 连接
命令：
AT+BTA2DPCONN?
响应：
+BTA2DPCONN:<conn_index>,<remote_address>
OK
若未建立连接，则 AT 不会返回 <conn_index> 和 <remote_address> 参数。
设置命令¶
功能：
建立 Classic Bluetooth A2DP 连接
命令：
AT+BTA2DPCONN=<conn_index>,<remote_address>
响应：
OK
若建立连接成功，则返回：
+BTA2DPCONN:<conn_index>,<remote_address>
若建立连接失败，则返回：
+BTA2DPCONN:<conn_index>,-1
参数¶
- <conn_index>：Classic Bluetooth A2DP 连接号，当前只支持单连接，连接号为 0。
- <remote_address>：对方 Classic Bluetooth A2DP 设备地址。
示例¶
AT+BTA2DPCONN=0,0,0,"24:0a:c4:09:34:23"
[ESP32 Only] AT+BTA2DPDISCONN：断开 A2DP 连接¶
执行命令¶
功能：
断开 Classic Bluetooth A2DP 连接
命令：
AT+BTA2DPDISCONN=<conn_index>
响应：
+BTA2DPDISCONN:<conn_index>,<remote_address>
OK
参数¶
- <conn_index>：Classic Bluetooth A2DP 连接号，当前只支持单连接，连接号为 0。
- <remote_address>：对方 Classic Bluetooth A2DP 设备地址。
示例¶
AT+BTA2DPDISCONN=0
[ESP32 Only] AT+BTA2DPSRC：查询/设置音频文件 URL¶
参数¶
- <conn_index>：Classic Bluetooth A2DP 连接号，当前只支持单连接，连接号为 0。
- <url>：源文件路径，当前只支持 HTTP、HTTPS 和 FLASH。
- <type>：音频文件类型，如 “mp3”。
说明¶
- 当前只支持 mp3 格式文件。
示例¶
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：控制音频播放¶
参数¶
- <conn_index>：Classic Bluetooth A2DP 连接号，当前只支持单连接，连接号为 0。
- <ctrl>：控制类型：
- 0: A2DP Sink，停止播放；
- 1: A2DP Sink，开始播放；
- 2: A2DP Sink，快进；
- 3: A2DP Sink，后退；
- 4: A2DP Sink，快进启动；
- 5: A2DP Sink，快进停止；
- 0: A2DP Source，停止播放；
- 1: A2DP Source，开始播放；
- 2: A2DP Source，暂停播放。
示例¶
AT+BTA2DPCTRL=0,1 // 开始播放音频
[ESP32 Only] AT+BTSECPARAM：查询/设置 Classic Bluetooth 安全参数¶
查询命令¶
功能：
查询 Classic Bluetooth 安全参数
命令：
AT+BTSECPARAM?
响应：
+BTSECPARAM:<io_cap>,<pin_type>,<pin_code>
OK
参数¶
- <io_cap>：输入输出能力：
- 0: DisplayOnly；
- 1: DisplayYesNo；
- 2: KeyboardOnly；
- 3: NoInputNoOutput。
- <pin_type>：使用可变或固定密码：
- 0: 可变密码；
- 1: 固定密码。
- <pin_code>：传统配对密码，最大长度：16 字节。
说明¶
- 若设置
<pin_type>为 0，则会自动忽略<pin_code>参数。
示例¶
AT+BTSECPARAM=3,1,"9527"
[ESP32 Only] AT+BTKEYREPLY：输入简单配对密钥 (Simple Pair Key)¶
参数¶
- <conn_index>：Classic Bluetooth 连接号，当前只支持单连接，连接号为 0。
- <Key>：简单配对密钥 (Simple Pair Key)。
示例¶
AT+BTKEYREPLY=0,123456
[ESP32 Only] AT+BTPINREPLY：输入传统配对密码 (Legacy Pair PIN Code)¶
参数¶
- <conn_index>：Classic Bluetooth 连接号，当前只支持单连接，连接号为 0。
- <Pin>：传统配对密码 (Legacy Pair PIN Code)。
示例¶
AT+BTPINREPLY=0,"6688"
[ESP32 Only] AT+BTSECCFM：给对方设备回复确认结果（传统连接阶段）¶
参数¶
- <conn_index>：Classic Bluetooth 连接，当前只支持单连接，连接号为 0。
- <accept>：拒绝或接受：
- 0: 拒绝；
- 1: 接受。
示例¶
AT+BTSECCFM=0,1
[ESP32 Only] AT+BTENCDEV：查询 Classic Bluetooth 加密设备列表¶
参数¶
- <enc_dev_index>：绑定设备序号。
- <mac_address>：MAC 地址。
示例¶
AT+BTENCDEV?
[ESP32 Only] AT+BTENCCLEAR：清除 Classic Bluetooth 加密设备列表¶
参数¶
- <enc_dev_index>：绑定设备序号。
示例¶
AT+BTENCCLEAR
[ESP32 Only] AT+BTCOD：设置设备类型¶
参数¶
- <major>：主要设备类型 (major class)；
- <minor>：次要设备类型 (minor class)；
- <service>：服务类型 (service class)。
示例¶
AT+BTCOD=6,32,32 // 打印机
[ESP32 Only] AT+BTPOWER：查询/设置 Classic Bluetooth 的 TX 功率¶
查询命令¶
功能：
查询 Classic Bluetooth 的 TX 功率
命令：
AT+BTPOWER?
响应：
+BTPOWER:<min_tx_power>,<max_tx_power>
OK
参数¶
- <min_tx_power>：最小功率水平，范围：[0,7]。
- <max_tx_power>：最大功率水平，范围：[0,7]。
示例¶
AT+BTPOWER=5,6 // 设置 Classic Bluetooth tx 功率