透传与数传示例

本文档介绍 AW33N BLE SDK 中 apps/demo/transfer 目录下的透传（Transparent Transmission）与数传（Data Transfer）示例工程，覆盖连接态 GATT 透传、非连接广播数传、dongle 数据转发等完整实现机制与配置方法。

Purpose and Scope

本页面向需要基于 AW33N 芯片实现 BLE 数据透传（UART↔BLE、设备↔手机、dongle↔PC 转发）的开发者，详细说明：

• 连接态透传示例（examples/trans_data/）：基于 GATT Server/Client 的双向数据通道，包含 MTU 协商、流控、连接参数更新、高速数传测试；
• 非连接广播数传示例（examples/nonconn_trans/）：基于广播/扫描通道的 24G 无连接数据传输；
• dongle 数传示例（examples/dongle/）：dongle 作为中心设备接收从机数据并转发给 PC（含 OTA 数据透传、RCSP 透传）；
• 透传相关的关键宏配置、连接参数表、初始化回调链与状态机。

以下内容不属于本页范围，请在对应页面查阅：

• BLE 协议栈底层（HCI 传输层）实现，参见 apps/include_lib/bt_controller_include/hci_transport.h；
• 具体板级外设配置（board/bd57/AW33N_transfer.cbp 工程配置）；
• 单连接/多连接 GATT 公共 profile 细节（gatt_common/le_gatt_common.h）。

概述

"透传"是指上层应用不解析数据内容、仅将数据从一个通道原样搬运到另一个通道的通信方式。在 AW33N BLE SDK 中，透传典型场景包括：

1. BLE ↔ UART 透传：MCU 通过串口接收数据，封装为 GATT Write/Notify 发送给手机 App；手机下发的数据经 GATT 回调写入串口发出（app_trans.c 中 common_uart_init 即为该链路服务）。
2. BLE ↔ BLE 转发（dongle）：dongle 作为 GATT Central 连接从机，将从机 Notify 的数据透传给 PC（USB/串口），并将 PC 数据写回从机（ota_dg_central.c、ble_dg_central.c）。
3. 无连接广播数传：不建立连接，利用广播包扩展数据承载数传（app_nonconn_trans.c，基于 ble_noconn_deal 模块）。

整个透传示例以 ble_init_cfg_t 回调结构体为骨架，把 profile 初始化、协议栈启动、模块使能与退出都绑定到统一的 BLE 生命周期上；应用层则通过 app_state_machine 状态机 + 消息循环（get_msg）驱动。

架构

flowchart TD
    subgraph sg_App["应用层 apps/demo/transfer/examples"]
        TransData["trans_data/app_trans.c<br/>连接态透传"]
        NonConn["nonconn_trans/app_nonconn_trans.c<br/>广播数传"]
        Dongle["dongle/app_dongle.c<br/>dongle 转发"]
    end

    subgraph sg_Profile["BLE Profile 层"]
        CommProfile["comm_ble_profile_init<br/>(gatt_common)"]
        NoconnDeal["ble_noconn_deal<br/>非连接广播处理"]
        TransProfile["ble_trans_profile.h<br/>自定义特征 ae02"]
    end

    subgraph sg_Stack["协议栈层"]
        BtStack["btstack 任务"]
        Controller["BLE 控制器"]
    end

    subgraph sg_DataPath["数据通道"]
        Uart["通用串口 common_uart"]
        UsbPc["USB/PC 端"]
        Phone["手机 App (NRF/lightblue)"]
    end

    TransData -->|"ble_init_cfg_t 回调"| CommProfile
    TransData -->|"读写通知"| TransProfile
    NonConn --> NoconnDeal
    Dongle -->|"GATT Central"| CommProfile

    CommProfile --> BtStack
    NoconnDeal --> BtStack
    BtStack --> Controller

    Phone -->|"GATT 连接"| Controller
    Uart -->|"uart2ble / ble2uart"| TransData
    Dongle -->|"数据转发"| UsbPc

架构说明

• ble_init_cfg_t 回调绑定：三个示例（app_trans.c、app_nonconn_trans.c、dongle）都定义了自己的 ble_init_cfg_t 配置，把 ble_profile_init、bt_ble_init、bt_ble_before_start_init、bt_ble_exit、ble_module_enable 五个生命周期钩子绑定到各自实现，实现同一套启动流程、不同业务逻辑。
• Profile 层解耦：连接态透传复用 gatt_common 的公共 profile 初始化（comm_ble_profile_init），自定义特征（ae02 系列）在 ble_trans_profile.h 中声明；非连接数传走 ble_noconn_deal 广播通道，不经过 GATT。
• 数据通道：连接态透传通过 GATT Write/Notify 与手机交互，通过 common_uart_init(TCFG_COMMON_UART_BAUDRATE, COMMON_UART_TX_PIN, COMMON_UART_RX_PIN) 与串口交互；dongle 示例把 BLE 数据转发到 USB/PC。

核心实现

1. 连接态透传应用框架（app_trans.c）

app_trans.c 是连接态透传示例的入口，整个应用被编译开关 CONFIG_APP_LE_TRANS 保护。应用启动链路如下：

1. le_trans_app_start()：设置系统时钟（clk_set("sys"/"lsb"/"sfc")）、初始化蓝牙时钟（clock_bt_init()）、调用 le_trans_bt_start() 启动协议栈、初始化通用串口（供 ble2uart/uart2ble 使用）、进入消息循环；
2. le_trans_bt_start()：设置 PLL 参数（bt_pll_para(TCFG_CLOCK_OSC_HZ, sys_clk, 0, 0)），调用 btstack_ble_start_before_init(&le_trans_data_config, 0) 注入回调配置，再 btstack_init() 启动协议栈；
3. le_trans_run_loop()：死循环 get_msg() 取消息，交给 app_comm_process_handler(msg) 统一分发；若 tans_exit_app 置位则调用 le_trans_bt_exit() 退出。

关键回调配置如下（ble_init_cfg_t 结构体）：

static const ble_init_cfg_t le_trans_data_config = {
    .same_address = 0,
    .appearance = 0,
    .ble_profile_init = comm_ble_profile_init,
    .bt_ble_init  = le_trans_bt_ble_init,
    .bt_ble_before_start_init = le_trans_bt_ble_before_start_init,
    .bt_ble_exit = le_trans_bt_ble_exit,
    .ble_module_enable = le_trans_ble_module_enable,
};

Source: app_trans.c

该结构体是 SDK 所有 BLE 应用的统一"契约"：same_address 控制经典蓝牙与 BLE 是否共用地址；ble_profile_init 负责注册 GATT 服务；bt_ble_init/bt_ble_exit 对应协议栈启动/退出；ble_module_enable 控制 BLE 模块使能。

2. 应用状态机与软关机

le_trans_state_machine() 实现 struct application 状态机回调，APP_STA_START 状态下根据 it->action 分发：ACTION_LE_TRANS_MAIN 触发 le_trans_app_start()。软关机路径 le_trans_set_soft_poweroff() 体现了透传应用的链路管理策略：先主动调用 btstack_ble_exit(0) 断开 BLE 链路，避免等待链路超时；再根据低功耗模式（TCFG_LOWPOWER_PATTERN）决定是延时软关机（SOFT_MODE 下通过 sys_timeout_add 延时 WAIT_DISCONN_TIME_MS）还是等待断开（SOFT_BY_POWER_MODE 下置 app_power_soft.wait_disconn = 1）。

static void le_trans_set_soft_poweroff(void)
{
    log_info("le_trans_set_soft_poweroff\n");
#if (TCFG_LOWPOWER_PATTERN == SOFT_MODE)
    le_trans_is_active = 1;
#endif
    //必须先主动断开蓝牙链路,否则要等链路超时断开
    btstack_ble_exit(0);
    //延时，确保BT退出链路断开

    if (ble_comm_dev_is_connected(GATT_ROLE_SERVER) || ble_comm_dev_is_connected(GATT_ROLE_CLIENT)) {
#if (TCFG_LOWPOWER_PATTERN == SOFT_MODE)
        //soft 方式非必须等链路断开
        sys_timeout_add((void *)POWER_EVENT_POWER_SOFTOFF, (void *)app_power_event_to_user, WAIT_DISCONN_TIME_MS);
#elif (TCFG_LOWPOWER_PATTERN == SOFT_BY_POWER_MODE)
        //must wait disconn
        app_power_soft.wait_disconn = 1;
#endif
    } else {
        app_power_set_soft_poweroff(NULL);
    }
}

Source: app_trans.c

3. 透传参数与缓冲配置（ble_trans.h）

ble_trans.h 是连接态透传的核心配置头文件，集中了影响吞吐、时延与兼容性的所有开关：

连接参数更新采用"排队请求"策略：trans_connection_update_enable = 1 使能更新，trans_connection_param_table[] 中按顺序排列多组参数，哪组被对方接受就使用哪组——这是应对 iOS/Android 对连接参数策略差异的通用做法：

//--------------- 
//连接参数更新请求设置
//是否使能参数请求更新,0--disable, 1--enable
static uint8_t trans_connection_update_enable = 1; ///0--disable, 1--enable
//请求的参数数组表,排队方式请求;哪组对方接受就用那组
static const struct conn_update_param_t trans_connection_param_table[] = {
#if CONFIG_BLE_HIGH_SPEED
    {6, 12,  10, 400},// ios fast
#endif
    {16, 24, 10, 400},//11
    {12, 28, 10, 400},//3.7
    {8,  20, 0, 400},
};

Source: ble_trans.h

参数组 {interval_min, interval_max, latency, timeout} 中，高速模式（CONFIG_BLE_HIGH_SPEED）下第一组 {6, 12, 10, 400} 对应 iOS 快速连接参数；随后按 {16,24,10,400}、{12,28,10,400}、{8,20,0,400} 依次尝试，兼顾吞吐与功耗。

4. 非连接广播数传（app_nonconn_trans.c）

app_nonconn_trans.c 实现 24G 无连接数传（CONFIG_APP_NONCONN_24G），其回调配置把 profile 初始化指向 noconn_ble_profile_init，数据通路基于 ble_noconn_deal.h 模块的广播/扫描通道，不建立 GATT 连接。noconn_state_idle_set_active(uint8_t active) 用于设置低功耗空闲状态标志：

static const ble_init_cfg_t noconn_data_config = {
    .same_address = 0,
    .appearance = 0,
    .ble_profile_init = noconn_ble_profile_init,
    .bt_ble_init  = noconn_bt_ble_init,
    .bt_ble_exit = noconn_bt_ble_exit,
    .ble_module_enable = noconn_ble_module_enable,
};

Source: app_nonconn_trans.c

无连接数传的典型应用是遥控器、寻物器（Find My）等不需要双向连接的场景：发送端周期性广播载荷，接收端在扫描通道捕获并解析，牺牲双向确认换取极低功耗与无配对流程。

5. dongle 数据转发

dongle 示例（examples/dongle/）中，透传方向为：从机 → dongle → PC。ota_dg_central.c 注释明确描述了这一链路："dongle发送给pc端(从机透传给dongle,dongle转发给pc)"以及"dongle RCSP透传给dongle,dongle转发给pc"；ble_dg_central.c 中 dg_central_buf_total[128] 是 RCSP 透传接收 buffer。findmy_product_test.c 进一步定义了多通道透传规划：channel_1 为 dongle→PC、channel_2 为 PC→USB 透传、channel_3~9 为远端升级透传。

核心流程

连接态透传启动与数据通路

以下时序图展示连接态透传从应用启动到数据收发的完整流程（基于 app_trans.c 与 ble_trans.h 的实际代码路径）：

sequenceDiagram
    participant App as le_trans_app_start
    participant Bt as btstack 协议栈
    participant Profile as comm_ble_profile_init
    participant Uart as common_uart
    participant Phone as 手机 App

    App->>App: clk_set(sys/lsb/sfc) + clock_bt_init
    App->>Bt: le_trans_bt_start()<br/>bt_pll_para + btstack_init
    Bt->>Profile: 注册 GATT 服务/特征 (ae02)
    App->>Uart: common_uart_init(波特率, TX/RX 引脚)
    App->>App: le_trans_run_loop()<br/>get_msg + app_comm_process_handler

    Phone->>Bt: 连接 + MTU 交换 (ATT_MTU_REQUEST_ENALBE)
    Bt->>App: 连接事件
    App->>Bt: trans_connection_param_table 排队请求<br/>更新连接参数

    Uart->>App: uart2ble: 串口收到数据
    App->>Bt: GATT Notify/Write (TEST_TRANS_NOTIFY_HANDLE)
    Bt->>Phone: 数据包 (TEST_PAYLOAD_LEN 每包)

    Phone->>Bt: GATT Write (ATT_WRITE_REQUEST 0x12)
    Bt->>App: 写事件回调
    App->>Uart: ble2uart: 数据发往串口

关键设计意图

• 先断链再关机：le_trans_set_soft_poweroff() 中先 btstack_ble_exit(0) 主动断开链路，否则软关机要等链路超时（最多数秒），影响用户体验；SOFT_MODE 下允许不等断开、延时执行软关机事件，SOFT_BY_POWER_MODE 则必须等断开。
• 消息循环驱动：应用不直接轮询 GATT 事件，而是通过 get_msg() + app_comm_process_handler() 统一处理消息，BLE 事件由协议栈转换为消息进入该循环，保证单线程访问 GATT 资源。
• 排队连接参数：连接参数表按"对方接受即停"的排队方式逐个请求，避免 iOS 拒绝某组参数后无参数可用；高速模式优先请求 {6,12,10,400}（iOS fast）。
• 缓存包数权衡：ATT_PACKET_NUMS_MAX = 2 只缓存 2 个 ATT 包，用有限的 RAM（ATT_SEND_CBUF_SIZE）换取可接受的发送吞吐；TEST_PAYLOAD_LEN = ATT_LOCAL_MTU_SIZE - 3 保证每包都填满 MTU，最大化单包有效载荷。

数据模型与协议要点

透传示例的"数据模型"是 GATT 自定义服务，特征在 ble_trans_profile.h 中声明（如 ATT_CHARACTERISTIC_ae02_01_VALUE_HANDLE），ble_trans.h 通过宏引用：

#define EIR_TAG_STRING   0xd6, 0x05, 0x08, 0x00, 'J', 'L', 'A', 'I', 'S', 'D','K'

//定义的产品信息,for test
#define  PNP_VID_SOURCE   0x02
#define  PNP_VID          0x05ac //0x05d6
#define  PNP_PID          0x022C //
#define  PNP_PID_VERSION  0x011b //1.1.11

Source: ble_trans.h

user_tag_string[] 与 trans_PNP_ID[] 在头文件中直接由宏展开为静态数组，随广播/扫描响应发出，帮助手机端识别"这是一台 JLAISDK 透传设备"。

使用示例

示例 1：定义透传应用的 BLE 初始化配置

以下代码展示了如何把透传应用挂接到 SDK 统一的 BLE 生命周期。任何新透传应用（如自定义数传通道）都应复制该结构体并替换回调实现：

static const ble_init_cfg_t le_trans_data_config = {
    .same_address = 0,
    .appearance = 0,
    .ble_profile_init = comm_ble_profile_init,
    .bt_ble_init  = le_trans_bt_ble_init,
    .bt_ble_before_start_init = le_trans_bt_ble_before_start_init,
    .bt_ble_exit = le_trans_bt_ble_exit,
    .ble_module_enable = le_trans_ble_module_enable,
};

Source: app_trans.c

示例 2：启动协议栈并进入消息循环

static void le_trans_bt_start()
{
    u32 sys_clk =  clk_get("sys");
    bt_pll_para(TCFG_CLOCK_OSC_HZ, sys_clk, 0, 0);
    /* bt_osc_offset_ext_save(-15); // 10pF晶振 */

    btstack_ble_start_before_init(&le_trans_data_config, 0);

    btstack_init();
}

Source: app_trans.c

启动前先 bt_pll_para 配置 PLL，再调用 btstack_ble_start_before_init 注入回调，最后 btstack_init() 拉起协议栈——顺序不可颠倒，回调注入必须在协议栈任务创建之前完成。

示例 3：初始化通用串口用于 BLE↔UART 透传

    // 配置一个通用串口做ble2uart or uart2ble
#if TCFG_COMMON_UART_ENABLE
    common_uart_init(TCFG_COMMON_UART_BAUDRATE, COMMON_UART_TX_PIN, COMMON_UART_RX_PIN);
#endif

Source: app_trans.c

TCFG_COMMON_UART_BAUDRATE、COMMON_UART_TX_PIN、COMMON_UART_RX_PIN 在 app_config.h 中定义，串口波特率直接决定 uart2ble 方向的注入速率上限。

示例 4：非连接数传的回调绑定

无连接数传与连接态透传使用完全相同的 ble_init_cfg_t 契约，只是 profile 初始化指向广播通道处理：

static const ble_init_cfg_t noconn_data_config = {
    .same_address = 0,
    .appearance = 0,
    .ble_profile_init = noconn_ble_profile_init,
    .bt_ble_init  = noconn_bt_ble_init,
    .bt_ble_exit = noconn_bt_ble_exit,
    .ble_module_enable = noconn_ble_module_enable,
};

Source: app_nonconn_trans.c

API 参考

透传应用生命周期函数（app_trans.c / ble_trans.h）

非连接数传函数（app_nonconn_trans.c）

流控接口（ble_trans.h 注释约定）

• att_server_flow_enable：流控使能接口，ATT_DATA_RECIEVT_FLOW = 1 时必须先调用；
• att_server_flow_hold：控制流控开关；
• 限制：流控只能控制对方使用带响应的 READ/WRITE 命令（如 ATT_WRITE_REQUEST = 0x12），对无响应的 Write Command 无效。

配置选项

编译开关（app_config.h 联动）

ble_trans.h 运行期参数

调参指南

• 提高吞吐：CONFIG_BLE_HIGH_SPEED = 1 + 减小 ATT_LOCAL_MTU_SIZE 对应 MTU 协商到最大 + TEST_TRANS_TIMER_MS = 5，同时首组连接参数选 {6,12,10,400}；
• 提高兼容性：iOS 设备对连接参数有严格限制（interval ≥ 15ms 等），保留 {16,24,10,400} 等宽松参数组作为排队后备；
• 降低功耗：减小 TEST_TRANS_TIMER_MS 只影响测试发包频率，业务功耗由连接参数 latency（表内第 3 项，如 10）控制——latency 越大，设备可跳过更多连接事件。

失败模式、边界情况与并发

连接断开与关机竞态

le_trans_set_soft_poweroff() 中 btstack_ble_exit(0) 后，链路断开是异步的。若此时仍处于连接状态（ble_comm_dev_is_connected 返回真），SOFT_MODE 通过 sys_timeout_add 延时 WAIT_DISCONN_TIME_MS 再发软关机事件；SOFT_BY_POWER_MODE 则置 wait_disconn = 1 由电源管理等待断开事件。若处理不当，可能在链路未断时进入低功耗导致协议栈异常。

流控限制

ATT_DATA_RECIEVT_FLOW 只能约束带响应的 ATT 操作（如 ATT_WRITE_REQUEST = 0x12）。若对端使用 Write Command（无响应、无流控），接收端必须依赖自身缓存（ATT_PACKET_NUMS_MAX = 2）承受突发，缓存溢出即丢包——这是透传吞吐设计的核心边界。

MTU 协商依赖对端

ATT_MTU_REQUEST_ENALBE = 0 时依赖对端（如手机 App）主动发起 MTU 交换；对 NRF 等不主动交换的工具，TEST_PAYLOAD_LEN 将保持默认 23-3=20 字节，单包吞吐受限。置 1 可让设备端主动发起交换解决该问题。

连接参数被拒

连接参数表采用排队策略，某组被拒后自动尝试下一组；若全部被拒，则维持当前参数。因此表格顺序即优先级，iOS 场景应将 iOS 友好参数（interval ≥ 15ms）放在靠前位置。

并发/任务模型

应用通过消息循环（le_trans_run_loop）串行处理事件，GATT 写事件、按键事件、定时器事件均转换为消息进入同一队列，避免多任务并发访问 ATT 缓存。le_trans_is_active/noconn_is_active 等静态标志用于跨模块状态同步，修改时注意原子性。

性能与运维注意事项

• 单包载荷：TEST_PAYLOAD_LEN = ATT_LOCAL_MTU_SIZE - 3，MTU 每增大 1 字节单包多传 1 字节；高速模式（MTU 247 时单包 244 字节 + 5ms 定时 + 短连接间隔）可达到该平台透传吞吐上限；
• 测试手段：置 TEST_TRANS_CHANNEL_DATA = 1 并设置 TEST_TRANS_NOTIFY_HANDLE 可记录收发速度；LE_DEBUG_TIMER_INFO = 1 可打开 1s 定时调试日志；
• 日志：app_trans.c 使用 LOG_TAG "[LE_TRANS]" 日志体系，LOG_ERROR/DEBUG/INFO/CLI_ENABLE 可独立开关，便于现场定位透传丢包问题；
• 板级适配：串口引脚（COMMON_UART_TX_PIN/RX_PIN）与晶振参数（TCFG_CLOCK_OSC_HZ）须按 board/bd57/AW33N_transfer.cbp 对应板子配置，PLL 参数错误会导致协议栈无法起振。

扩展点

1. 自定义特征：复制 trans_data 示例，在 ble_trans_profile.h 中新增特征 UUID 与句柄宏，comm_ble_profile_init 中注册即可扩展新的数传通道（如命令通道、OTA 通道并存）；
2. 新增透传方向：参考 ota_dg_central.c 的"从机→dongle→PC"模式，实现多跳转发（如 BLE→USB、BLE→BLE）；
3. 连接参数策略：修改 trans_connection_param_table[] 即可适配不同对端平台而不改业务代码；
4. 非连接通道：基于 ble_noconn_deal 扩展广播载荷格式，用于 Find My、遥控器等低功耗单向数传（参见 findmy_product_test.c 的多通道规划）；
5. UART 协议：common_uart 只做透明搬运，可在串口侧自行封装帧头/校验，实现可靠的 uart2ble 分包重组。

相关链接

• app_trans.c（连接态透传应用）
• ble_trans.h（透传参数配置）
• ble_trans.c / ble_trans_profile.h（透传 profile 实现）
• app_nonconn_trans.c（非连接广播数传）
• ota_dg_central.c（dongle 转发/OTA 透传）
• ble_dg_central.c（dongle 中心设备 RCSP 透传）
• findmy_product_test.c（多通道透传规划）