蓝牙 AT 协议参考

本页面向开发者提供 AC630N 蓝牙 SDK 中 AT 命令协议（spp_at_com / le_at_com）的完整参考：它定义了设备通过经典蓝牙 SPP 或低功耗蓝牙 BLE GATT 通道接收/响应文本型 AT 命令的统一机制，涵盖命令接口、GATT Profile 结构、数据流、事件回调、配置与扩展方式。

Purpose and Scope

本页围绕 apps/common/third_party_profile/jieli/ 下的 AT 命令组件展开，包括：

• EDR/SPP 侧 AT 命令接口（spp_at_com.h / spp_at_com.c）
• BLE 侧 AT 命令接口（le_at_com.h / le_at_com.c）
• BLE GATT Profile 中 AT 服务的特征（UUID ae30/ae3a 服务族）与 Handle 布局
• 事件回调（register_event_cbk）与数据收发路径

不涵盖：RCSP（杰理私有 App 控制协议）的完整命令集、通用 GATT 服务层实现、TWS 同步机制、固件升级流程。这些属于各自的独立页面主题；本页仅在必要时提及它们与 AT 组件的交互点（如 rcsp_bluetooth.h 的引用关系）。

概述

AT 命令（Attention Command）是一种经典的文本行协议：主机（手机 App、串口调试工具等）通过传输通道发送以 AT 开头的命令行，设备解析后执行操作并回传结果。本 SDK 将其作为蓝牙透传演示（Demo）的一种模式实现——BLE 侧由 TCFG_BLE_DEMO_SELECT == DEF_BLE_DEMO_AT_COM 编译开关启用，SPP 侧通过 at_spp_init() 初始化。

该协议的设计意图：

1. 统一控制面：通过 AT 命令字符串即可完成蓝牙地址/名称读取与设置、可见性控制、配对模式切换、断开连接、广播数据设置等常用操作，便于主机端跨平台对接。
2. 双通道支持：经典蓝牙（SPP，edr_* 前缀）与低功耗蓝牙（BLE GATT，ble_* 前缀）各有一套对称的 API，上层业务无需关心底层传输差异。
3. 事件驱动：设备主动上报的状态（连接/断开、数据到达、发送完成等）通过注册的回调函数通知主机侧业务代码。

架构

下图展示了 AT 协议组件在 SDK 中的位置与数据流向：

flowchart TD
    subgraph sg_Host["主机侧 (Phone / PC / MCU)"]
        App["App / 调试工具"]
    end

    subgraph sg_Transport["蓝牙传输层"]
        SPP["SPP 通道 (经典蓝牙)"]
        GATT["BLE GATT 通道"]
    end

    subgraph sg_AT["AT 命令组件层"]
        SppAT["spp_at_com<br/>edr_at_* API"]
        LeAT["le_at_com<br/>ble_at_* API"]
        EventCbk["事件回调<br/>register_event_cbk"]
    end

    subgraph sg_Core["蓝牙协议栈 / 平台服务"]
        BTStack["BTSTACK 协议栈"]
        VM["VM 存储 (user_cfg)"]
        RCSP["rcsp_bluetooth (可选)"]
    end

    App -->|"AT 文本行"| SPP
    App -->|"GATT Write"| GATT
    SPP --> SppAT
    GATT --> LeAT
    SppAT --> BTStack
    LeAT --> BTStack
    SppAT --> VM
    LeAT --> VM
    LeAT -.-> RCSP
    BTStack -->|"Notify/事件"| EventCbk
    SppAT --> EventCbk
    LeAT --> EventCbk

各组件职责说明：

• spp_at_com（EDR/SPP 侧）：封装经典蓝牙的 AT 命令能力，接口以 edr_at_* 命名，涵盖地址、名称、可见性、配对、PIN 码、COD、SPP 数据发送等（见 spp_at_com.h）。at_spp_init() 负责初始化。
• le_at_com（BLE 侧）：封装低功耗蓝牙的 AT 命令能力，接口以 ble_at_* 命名，通过 GATT 特征收发数据，整体仅在 DEF_BLE_DEMO_AT_COM 演示模式下编译（见 le_at_com.h）。
• 事件回调：ble_at_register_event_cbk / edr_at_register_event_cbk 注册主机侧处理函数，设备侧状态变化（连接、数据、发送完成）经由 at_send_event_callbak 通知上层（见 le_at_com.c）。
• 底层依赖：btstack/ble_api.h、btstack/bluetooth.h、btstack/le_user.h 提供协议栈能力；vm.h / user_cfg.h 提供参数持久化；rcsp_bluetooth.h / JL_rcsp_api.h 为可选 RCSP 集成（见 le_at_com.c）。

BLE GATT Profile 结构与 Handle 布局

BLE 侧 AT 服务使用杰理 GATT 生成工具（jieli gatt_inc_generator.exe）产出的二进制 profile_data[] 描述 GATT 数据库（见 le_at_com.h）。表中每一行按 长度(16) + 类型/标志(16) + Handle(16) + UUID(16/128) + 值(...) 的二进制格式描述一个 ATT 条目：

static const uint8_t profile_data[] = {
    // 0x0001 PRIMARY_SERVICE  1800
    0x0a, 0x00, 0x02, 0x00, 0x01, 0x00, 0x00, 0x28, 0x00, 0x18,
    // 0x0002 CHARACTERISTIC 2a00 READ | WRITE | DYNAMIC
    0x0d, 0x00, 0x02, 0x00, 0x02, 0x00, 0x03, 0x28, 0x0a, 0x03, 0x00, 0x00, 0x2a,
    // 0x0003 VALUE 2a00 READ | WRITE | DYNAMIC
    0x08, 0x00, 0x0a, 0x01, 0x03, 0x00, 0x00, 0x2a,
    ...
    // END
    0x00, 0x00,
};

Source: le_at_com.h

AT 服务特征表

该 Profile 定义了两个自定义服务族（ae30 与 ae3a）及标准 GAP 服务，核心特征及 Handle 映射如下（宏定义见 le_at_com.h）：

Source: le_at_com.h

设计要点：

• 写无应答通道（Write Without Response） 用于主机下发 AT 命令，保证低延迟、无需 ATT 应答，适合高频指令。
• Notify/Indicate 通道 用于设备上报 AT 结果或数据；Indicate（ae05）比 Notify 多了主机应答确认，适合可靠性要求高的场景。
• CCCD（0x2902）用于主机订阅通知：主机必须先向 CCCD 写 0x0001 才能收到 Notify。
• 当 RCSP_BTMATE_EN 开启时，额外编译进 ae00 服务（Handle 0x0080–0x0085，特征 ae01/ae02），用于与 RCSP App 对接（见 le_at_com.h）。

传输与数据缓冲机制

BLE 侧的关键缓冲与传输参数在 le_at_com.c 中定义：

#define ATT_LOCAL_PAYLOAD_SIZE    (200)   //note: need >= 20
#define ATT_SEND_CBUF_SIZE        (512)   //note: need >= 20,缓存大小，可修改
#define ATT_RAM_BUFSIZE           (ATT_CTRL_BLOCK_SIZE + ATT_LOCAL_PAYLOAD_SIZE + ATT_SEND_CBUF_SIZE)
static u8 att_ram_buffer[ATT_RAM_BUFSIZE] __attribute__((aligned(4)));

#define ADV_INTERVAL_MIN          (160)

static const struct conn_update_param_t connection_param_table[] = {
    {16, 24, 0, 600},//11
    {12, 28, 0, 600},//3.7
    {8,  20, 0, 600},
};

Source: le_at_com.c

• ATT_LOCAL_PAYLOAD_SIZE：单包 ATT 载荷上限（默认 200 字节，至少 20 字节以满足 BLE 4.0 最小 MTU）。
• ATT_SEND_CBUF_SIZE：发送环形缓存（512 字节），当主机未及时读取时数据在此排队，可调大以提升吞吐。
• ATT_RAM_BUFSIZE：三者之和，att_ram_buffer 4 字节对齐分配，供协议栈 ATT 层使用。
• connection_param_table：连接参数候选表 {min_interval, max_interval, latency, timeout}（单位 1.25ms / 10ms），按序尝试更新连接间隔，兼顾吞吐与功耗。
• 广播间隔 ADV_INTERVAL_MIN = 160（对应 100ms）。

此外还有 AT 临时解析缓冲区 at_tmp_buffer[512 + 4]、广播数据缓冲 adv_data[ADV_RSP_PACKET_MAX]（31 字节上限）与扫描应答缓冲 scan_rsp_data[]（见 le_at_com.c），默认设备名为 "br22_ble_test"。

安全与配对

BLE 侧安全参数集中定义（见 le_at_com.c）：

//加密设置
static const uint8_t sm_min_key_size = 7;

//1-just_works,2--passkey,3--yes or no
static uint8_t sm_pair_mode;

//用户可配对的，这是样机跟客户开发的app配对的秘钥
const u8 link_key_data[16] = {0x06, 0x77, 0x5f, 0x87, 0x91, 0x8d, 0xd4, 0x23,
                              0x00, 0x5d, 0xf1, 0xd8, 0xcf, 0x0c, 0x14, 0x2b};
#define EIR_TAG_STRING   0xd6, 0x05, 0x08, 0x00, 'J', 'L', 'A', 'I', 'S', 'D','K'
static const char user_tag_string[] = {EIR_TAG_STRING};

Source: le_at_com.c

• sm_min_key_size = 7：SMP 最小密钥长度（7 字节，BLE 安全规范下限）。
• sm_pair_mode：配对方式枚举——1 为 Just Works（免密），2 为 Passkey（输入 PIN），3 为 Yes/No（数值确认），由 ble_at_set_pair_mode() 控制。
• link_key_data[16]：预置长期密钥（LTK），用于样机与客户 App 的固定配对，避免每次重新配对。
• EIR_TAG_STRING / user_tag_string：厂商自定义 EIR 标签 JLAISDK，可随广播/扫描应答发出，供 App 识别设备身份。

核心流程

BLE AT 命令收发流程

下图展示了主机通过 GATT 下发 AT 命令、设备处理并上报结果的完整时序：

sequenceDiagram
    participant App as 主机 App
    participant GATT as BLE GATT 服务 (le_at_com)
    participant BT as BTSTACK 协议栈
    participant Cbk as 业务回调 (app_recieve_callback)

    App->>GATT: GATT Write (ae01, "AT+...")
    GATT->>GATT: ble_at_recivev_data(handle, packet, size)
    GATT->>Cbk: 调用 app_recieve_callback(priv, buf, len)
    Cbk-->>GATT: 处理结果
    GATT->>GATT: 组装响应数据
    GATT->>BT: ATT Notify (ae02, 结果)
    BT-->>App: Notify 上报
    Note over App,GATT: 可选：ae05 INDICATE 通道（需主机应答）
    App->>GATT: GATT Write (ae10, 读写通道)
    GATT-->>App: ATT Read (ae10 返回数据)

关键实现点（见 le_at_com.c 的内部函数声明）：

• ble_at_recivev_data(u16 handle, const u8 *packet, int size)：ATT 写到达时解析 handle 与数据，分发到对应业务。
• ble_at_send_event(u8 opcode, const u8 *packet, int size)：将设备侧事件（连接状态、数据到达、发送完成）打包后经 at_send_event_callbak 上报。
• app_send_user_data(u16 handle, u8 *data, u16 len, u8 handle_type) 及其检查/执行子函数：统一的数据发送入口，发送前经 app_send_user_data_check() 校验缓存余量，实际发送由 app_send_user_data_do() 完成。
• app_ble_state_callback：BLE 连接/断开状态变化回调，驱动 ble_work_state 状态机。

EDR/SPP AT 流程

SPP 侧为对称设计：at_spp_init() 完成初始化后，主机经 SPP 通道发送 AT 行，edr_at_* API 执行操作，edr_at_register_event_cbk() 注册的事件回调承载状态上报（接口见 spp_at_com.h）。

使用示例

以下示例展示了上层业务如何接入 AT 命令能力（BLE 侧需在 TCFG_BLE_DEMO_SELECT == DEF_BLE_DEMO_AT_COM 条件下编译）。

示例 1：BLE 侧初始化与事件回调注册

#include "at.h"
#include "le_at_com.h"

// 注册事件回调（连接状态、数据、发送完成）
ble_at_register_event_cbk(my_event_handler);

// 设置本地名称与可见性
ble_at_set_name("my_device", 10);
ble_at_set_visibility(1);

// 发送数据到默认通知通道 (ae02)
ble_at_send_data_default((u8 *)"AT+OK\r\n", 8);

// 设置自定义广播数据与扫描应答数据
ble_at_set_adv_data(adv_buf, adv_len);
ble_at_set_rsp_data(rsp_buf, rsp_len);

Source: le_at_com.h（接口原型取自头文件，实际接入示例由上层业务实现）

示例 2：SPP 侧设备控制

#include "spp_at_com.h"

// 初始化 SPP AT 组件
at_spp_init();

// 设置经典蓝牙地址与名称
edr_at_set_address(mac_addr);
edr_at_set_name("AC630N_SPP", 10);

// 控制可见性（inquiry + page scan）与配对模式
edr_at_set_visibility(1, 1);
edr_at_set_pair_mode(2);          // PIN 码配对
edr_at_set_pincode((u8 *)"1234");

// 向对端发送 SPP 数据
edr_at_send_spp_data((u8 *)"hello", 5);

// 查询当前链路状态
u8 st = edr_at_get_staus();

Source: spp_at_com.h

示例 3：GATT 数据库二进制描述（Profile 片段）

BLE AT 服务的 GATT 数据库以紧凑二进制数组描述，前 8 字节 0x0a 0x00 0x02 0x00 0x01 0x00 0x00 0x28 表示：条目长 10 字节、类型 Primary Service（0x2800）、Handle 0x0001、UUID 1800：

static const uint8_t profile_data[] = {
    // 0x0001 PRIMARY_SERVICE  1800
    0x0a, 0x00, 0x02, 0x00, 0x01, 0x00, 0x00, 0x28, 0x00, 0x18,
    // 0x0004 PRIMARY_SERVICE  ae30
    0x0a, 0x00, 0x02, 0x00, 0x04, 0x00, 0x00, 0x28, 0x30, 0xae,
    // 0x0005 CHARACTERISTIC ae01 WRITE_WITHOUT_RESPONSE | DYNAMIC
    0x0d, 0x00, 0x02, 0x00, 0x05, 0x00, 0x03, 0x28, 0x04, 0x06, 0x00, 0x01, 0xae,
};

Source: le_at_com.h

API 参考

SPP/EDR 侧（spp_at_com.h）

Source: spp_at_com.h

BLE 侧（le_at_com.h）

Source: le_at_com.h

返回值约定：所有接口返回 int，通常 0 表示成功、非 0 表示失败；get_staus 返回 u8 状态字。具体错误码需参考 bt_common.h 与协议栈返回定义。

配置选项

AT 协议组件的主要编译期配置（宏）与运行期参数如下：

Source: le_at_com.c / le_at_com.h

失败模式、边界与并发

数据缓冲与背压

• ATT_SEND_CBUF_SIZE（512 字节）为发送环形缓存：当主机侧未及时使能 Notify 或读取缓慢时，数据在缓存中排队；app_send_user_data_check() 在发送前检查余量，缓存满时发送会被拒绝或阻塞，上层应等待 ble_resume_send_wakeup 回调再续传。
• 单包 ATT_LOCAL_PAYLOAD_SIZE 限制为 200 字节：超长数据必须由上层分片，BLE 4.0 默认 MTU 下实际单包不超过 20 字节，SDK 会按 MTU 自动切包。

广播数据长度边界

adv_data[] / scan_rsp_data[] 均为 ADV_RSP_PACKET_MAX（31 字节），ble_at_set_adv_data() 超过 31 字节的输入会被截断或拒绝；ATT_RAM_BUFSIZE < 64 时编译期直接报错（#error），防止广播/应答缓冲不足（见 le_at_com.c）。

并发与中断上下文

• con_handle 声明为 volatile hci_con_handle_t，连接句柄在协议栈回调与业务任务间共享，读取侧须考虑内存屏障。
• AT 组件依赖 BTSTACK 任务模型（btstack/btstack_task.h），GATT 事件在协议栈上下文触发，业务回调中不应执行长时间阻塞操作，避免影响链路调度。
• 配对流程（ble_at_confirm_gkey、Passkey/Yes-No 交互）是异步的，主机须按 sm_pair_mode 完成对应握手后才能继续传输数据。

未连接状态

所有发送类接口在 con_handle 为空（未连接）时直接返回，test_send_audio_data() 中的 if (!con_handle) return; 即体现了这一约定（见 le_at_com.c）。

性能与运维

• 吞吐路径：BLE 数据上行走 Notify（ae02/ae04），下行走 Write Without Response（ae01/ae03），两种方式都免去 ATT 应答等待；需要可靠传输时改用 ae05 Indicate。
• 连接参数协商：connection_param_table 提供三档候选（16/24、12/28、8/20 的 interval 组合），connection_update_cnt 控制切换时机，SDK 逐档尝试以平衡吞吐与功耗。
• 测试钩子：TEST_SEND_DATA_RATE 用于吞吐测量（周期计数 + server_timer_handle），TEST_AUDIO_DATA_UPLOAD 演示 128 字节/包的音频文件上传，验证大数据量通道可靠性。
• 调试手段：log_info / log_info_hexdump（映射到 printf / printf_buf）可打印 AT 交互内容与十六进制包；printf_buf 打印对排障非常有帮助。

扩展点

• 新增 AT 命令：在 ble_at_recivev_data 的分发逻辑中增加对特定 handle（如 ae03/ae3b 扩展通道）与命令前缀的匹配分支，复用 app_send_user_data() 回传结果。
• 自定义 GATT 服务：参照 profile_data[] 的二进制条目格式（长度/类型/Handle/UUID/值）追加新服务段，并在 le_at_com.h 的 #if 0 示例中可看到 128 位 UUID 服务的写法（0000F530-... 服务族）。
• 事件上报扩展：通过 at_send_event_callbak(u8 event_type, const u8 *packet, int size) 增加新事件类型码，主机侧按 event_type 分发。
• RCSP 集成：RCSP_BTMATE_EN 开启后编译 ae00 服务与 rcsp_bluetooth.h 依赖，可将 AT 能力与 RCSP App 控制协议并存（见 le_at_com.h）。

测试

仓库中 AT 组件的可测试性由以下机制支撑：

• 编译期开关 TCFG_BLE_DEMO_SELECT == DEF_BLE_DEMO_AT_COM 使 BLE AT 组件仅在目标 Demo 下编译，便于独立验证。
• TEST_SEND_DATA_RATE 与 TEST_AUDIO_DATA_UPLOAD 提供内置自测路径：前者验证通知通道吞吐，后者验证分片上传正确性。
• TEST_SEND_HANDLE_VAL 指定测试使用的目标 Handle（默认 ATT_CHARACTERISTIC_ae02_01_VALUE_HANDLE），可切换到 ae05 Indicate 通道验证应答机制（见 le_at_com.c）。
• Handle 宏（ATT_CHARACTERISTIC_*_VALUE_HANDLE）将 Profile 数据与代码解耦，任何 Profile 调整只需同步宏即可，减少回归风险。

相关链接

• spp_at_com.h — SPP AT 接口
• spp_at_com.c — SPP AT 实现
• le_at_com.h — BLE AT 接口与 GATT Profile
• le_at_com.c — BLE AT 实现
• 相关主题：RCSP 协议参考（rcsp_bluetooth.h / JL_rcsp_api.h）、透传数据 Demo（trans_data_demo/）、GATT 服务层参考