网络与蓝牙配置

本文档介绍 AC792N SDK 中网络（WiFi）与蓝牙（经典蓝牙 BLE）的配置体系，包括 BLE demo 选择机制、网络配网（NET_CFG）系列方案、经典蓝牙控制器配置以及 WiFi 应用（wifi_bbm / wifi_camera / wifi_soundbox）与 TWS 的配套配置。

Purpose and Scope

本页聚焦于 SDK 的"网络与蓝牙配置"能力，即：

BLE demo 选择机制：如何通过 TCFG_* 宏在编译期确定设备运行哪个 BLE 协议栈 demo（配网、透传、RCSP、HOGP 等）。
网络配网（NET_CFG）方案：BLE 配网 demo 家族（基础 NET_CFG、DUI、TURING、TENCENT、DUEROS、XC、TY）如何与各云平台对接。
经典蓝牙配置入口：btcontroller_mode.h / btcontroller_modules.h 等 BT 控制器模块。
WiFi 应用与蓝牙共存：wifi_bbm、wifi_camera、wifi_soundbox 三个 WiFi 应用中的 bt_tws.h、bt_slience_detect.h、bt_tone_player.h 等蓝牙配套组件。

以下内容不在此页范围，属兄弟页面：具体音频通路、具体云平台配网协议的报文细节（各 net_cfg 实现内部）、RCSP 完整协议规范。如需这些内容，请参见对应页面。

Overview

AC792N 是杰理科技（Jieli）面向 WiFi+蓝牙音频应用（音箱、摄像头、BBM 等）的 SoC。其网络与蓝牙配置的核心思路是：用一套编译期宏驱动，统一管理 BLE 协议栈的 demo 选择，从而在同一份固件工程中按需组合出不同产品形态：

纯蓝牙音箱（经典蓝牙 A2DP/HFP + 可选 BLE）
WiFi 音箱（WiFi 音频 + 配网 + 蓝牙共存）
带 RCSP（Jieli 手机伴侣协议）的设备
对接第三方云平台（DuerOS、Turing、Tencent、小米、涂鸦、喜马拉雅等）的配网设备

bt_profile_cfg.h 是整个配置体系的枢纽：它把分散在各处的功能开关宏（TCFG_BT_NET_CFG_EN、RCSP_MODE、TCFG_TRANS_DATA_EN 等）统一归一为一个 TCFG_BLE_DEMO_SELECT 枚举值，下游 BLE 协议栈代码只依赖这一个值即可确定编译分支。

Architecture

下图展示网络与蓝牙配置的整体架构与 BLE demo 选择的数据流：

flowchart TD
    subgraph sg_Config["编译期配置层 (app_config / board config)"]
        A["TCFG_USER_BLE_ENABLE"]
        B["RCSP_MODE"]
        C["TCFG_TRANS_MULTI_BLE_EN"]
        D["TCFG_TRANS_DATA_EN"]
        E["TCFG_BT_NET_CFG_EN"]
        F["TCFG_BT_NET_CFG_DUI_EN"]
        G["TCFG_BT_NET_CFG_TURING_EN"]
        H["TCFG_BT_NET_CFG_TENCENT_EN"]
        I["TCFG_BT_NET_CFG_DUEROS_EN"]
        J["TCFG_BLE_MASTER_CENTRAL_EN"]
        K["TCFG_BT_NET_CFG_XC_EN"]
        L["TCFG_BT_NET_CFG_TY_EN"]
        M["TCFG_BLE_HID_EN"]
        N["TCFG_NONCONN_24G_EN"]
    end

    subgraph sg_Selector["BT 配置枢纽 (bt_profile_cfg.h)"]
        P["TCFG_BLE_DEMO_SELECT"]
    end

    subgraph sg_BLE["BLE 协议栈 demo"]
        Q["DEF_BLE_DEMO_RCSP_DEMO"]
        R["DEF_BLE_DEMO_MULTI"]
        S["DEF_BLE_DEMO_TRANS_DATA"]
        T["DEF_BLE_DEMO_NET_CFG 系列"]
        U["DEF_BLE_DEMO_MASTER_CENTRAL"]
        V["DEF_BLE_DEMO_HOGP"]
        W["DEF_BLE_DEMO_NONCONN_24G"]
        X["DEF_BLE_DEMO_NULL"]
    end

    subgraph sg_App["应用形态"]
        Y["wifi_soundbox / wifi_camera / wifi_bbm"]
        Z["经典蓝牙 BT 控制器 (btcontroller_modules)"]
    end

    A --> P
    B --> P
    C --> P
    D --> P
    E --> P
    F --> P
    G --> P
    H --> P
    I --> P
    J --> P
    K --> P
    L --> P
    M --> P
    N --> P
    P --> Q
    P --> R
    P --> S
    P --> T
    P --> U
    P --> V
    P --> W
    P --> X
    T --> Y
    Z --> Y

架构说明：

左侧是应用层配置宏，分散在 app_config.h 及各产品板级配置中，属于"输入"。
中间 bt_profile_cfg.h 是唯一决策点，按优先级（#elif 链）把输入归一为 TCFG_BLE_DEMO_SELECT 一个值。
右侧是 BLE 协议栈实际编译/运行的 demo 分支，以及经典蓝牙控制器（btcontroller_mode.h、btcontroller_modules.h）与 WiFi 应用（wifi_bbm、wifi_camera、wifi_soundbox）这些消费该配置的下游模块。

这种"多输入 → 单一选择器 → 多输出"的设计意图是：避免协议栈代码里散落大量 #if TCFG_XXX_EN 判断，把"到底跑哪个 BLE demo"的决策集中到一个文件、一个宏上，既便于产品定制，也便于排查"为什么 BLE 没有使能"这类问题——直接看 TCFG_BLE_DEMO_SELECT 的值即可。

BLE Demo 选择机制（bt_profile_cfg.h）

demo 枚举定义

bt_profile_cfg.h 首先定义了一组 DEF_BLE_DEMO_* 枚举宏，作为 BLE 协议栈各 demo 的唯一标识：

//ble demo的例子
#define DEF_BLE_DEMO_NULL                 0xff //ble 没有使能
#define DEF_BLE_DEMO_MULTI                1
#define DEF_BLE_DEMO_NONCONN_24G          2
#define DEF_BLE_DEMO_RCSP_DEMO            4
#define DEF_BLE_DEMO_ADV                  5
#define DEF_BLE_DEMO_TRANS_DATA           6
#define DEF_BLE_DEMO_NET_CFG              7
#define DEF_BLE_DEMO_MASTER_CENTRAL       8
#define DEF_BLE_DEMO_HOGP                 9
#define DEF_BLE_DEMO_MI                   10
#define DEF_BLE_DEMO_NET_CFG_DUI          11
#define DEF_BLE_DEMO_NET_CFG_TURING       12
#define DEF_BLE_DEMO_NET_CFG_TENCENT      13
#define DEF_BLE_DEMO_NET_CFG_DUEROS       14
#define DEF_BLE_DEMO_NET_CFG_XC           15
#define DEF_BLE_DEMO_NET_CFG_TY           16

来源：bt_profile_cfg.h

设计要点：

DEF_BLE_DEMO_NULL = 0xff 表示 BLE 完全关闭，与"0"区分开，避免与合法的 demo 编号冲突。
编号 7、11~16 构成 NET_CFG 配网家族：同一套配网框架，针对不同云平台（DuerOS、Turing、腾讯、小米生态、喜马拉雅 XC、涂鸦 TY）提供差异化实现。
DEF_BLE_DEMO_ADV = 5 与 DEF_BLE_DEMO_MI = 10 是预留 demo，在当前选择链中未被引用，但保留编号以保持协议栈侧枚举的稳定。

选择链的优先级语义

选择逻辑放在 TCFG_USER_BLE_ENABLE 守卫内：只有 BLE 总开关打开时才进入决策；否则直接落到 DEF_BLE_DEMO_NULL：

//配置选择的demo
#if TCFG_USER_BLE_ENABLE

#if RCSP_MODE
#define TCFG_BLE_DEMO_SELECT          DEF_BLE_DEMO_RCSP_DEMO

#elif TCFG_TRANS_MULTI_BLE_EN
#define TCFG_BLE_DEMO_SELECT          DEF_BLE_DEMO_MULTI

#elif TCFG_TRANS_DATA_EN
#define TCFG_BLE_DEMO_SELECT          DEF_BLE_DEMO_TRANS_DATA

#elif TCFG_BT_NET_CFG_EN
#define TCFG_BLE_DEMO_SELECT          DEF_BLE_DEMO_NET_CFG

#elif TCFG_BT_NET_CFG_DUI_EN
#define TCFG_BLE_DEMO_SELECT          DEF_BLE_DEMO_NET_CFG_DUI

#elif TCFG_BT_NET_CFG_TURING_EN
#define TCFG_BLE_DEMO_SELECT          DEF_BLE_DEMO_NET_CFG_TURING

#elif TCFG_BT_NET_CFG_TENCENT_EN
#define TCFG_BLE_DEMO_SELECT          DEF_BLE_DEMO_NET_CFG_TENCENT

#elif TCFG_BT_NET_CFG_DUEROS_EN
#define TCFG_BLE_DEMO_SELECT          DEF_BLE_DEMO_NET_CFG_DUEROS

#elif TCFG_BLE_MASTER_CENTRAL_EN
#define TCFG_BLE_DEMO_SELECT          DEF_BLE_DEMO_MASTER_CENTRAL

#elif TCFG_BT_NET_CFG_XC_EN
#define TCFG_BLE_DEMO_SELECT          DEF_BLE_DEMO_NET_CFG_XC

#elif TCFG_BT_NET_CFG_TY_EN
#define TCFG_BLE_DEMO_SELECT          DEF_BLE_DEMO_NET_CFG_TY

#elif TCFG_BLE_HID_EN
#define TCFG_BLE_DEMO_SELECT          DEF_BLE_DEMO_HOGP

#elif TCFG_NONCONN_24G_EN
#define TCFG_BLE_DEMO_SELECT          DEF_BLE_DEMO_NONCONN_24G

#else
#define TCFG_BLE_DEMO_SELECT          DEF_BLE_DEMO_NULL//ble is closed

#endif

#else
#define TCFG_BLE_DEMO_SELECT          DEF_BLE_DEMO_NULL//ble is closed
#endif

来源：bt_profile_cfg.h

设计意图（WHY）：

优先级即产品优先级：RCSP_MODE 排在最前，因为 RCSP 是杰理手机伴侣协议，需要独占 BLE 连接做控制通道；其次是多连（MULTI）与透传（TRANS_DATA），再是各配网方案。若产品同时使能了多个 TCFG_*_EN，只有链上最先命中的宏生效——这是刻意为之的"确定性优先"，防止多个 demo 同时编译进固件导致 BLE 服务冲突。
配网家族内部互斥：DUI / TURING / TENCENT / DUEROS / XC / TY 六个配网宏共享同一个配网框架，只能选其一，因此使用同一 #elif 链保证互斥。
兜底即关闭：两个 #else 分支（TCFG_USER_BLE_ENABLE 未开、或开了但没有任何 demo 宏命中）都归一到 DEF_BLE_DEMO_NULL，保证 TCFG_BLE_DEMO_SELECT 在所有编译组合下都有定义，不会出现未定义宏的编译错误。

网络配网（NET_CFG）体系

配网家族与云平台映射

`TCFG_*` 开关	demo 值	典型对接平台/场景
`TCFG_BT_NET_CFG_EN`	`DEF_BLE_DEMO_NET_CFG (7)`	基础 BLE 配网 demo，通用配网流程
`TCFG_BT_NET_CFG_DUI_EN`	`DEF_BLE_DEMO_NET_CFG_DUI (11)`	度秘 DUI 语音平台配网
`TCFG_BT_NET_CFG_TURING_EN`	`DEF_BLE_DEMO_NET_CFG_TURING (12)`	图灵机器人平台配网
`TCFG_BT_NET_CFG_TENCENT_EN`	`DEF_BLE_DEMO_NET_CFG_TENCENT (13)`	腾讯云小微配网
`TCFG_BT_NET_CFG_DUEROS_EN`	`DEF_BLE_DEMO_NET_CFG_DUEROS (14)`	百度 DuerOS 配网
`TCFG_BT_NET_CFG_XC_EN`	`DEF_BLE_DEMO_NET_CFG_XC (15)`	喜马拉雅（XC）配网
`TCFG_BT_NET_CFG_TY_EN`	`DEF_BLE_DEMO_NET_CFG_TY (16)`	涂鸦（Tuya）配网

配网的本质流程：设备上电后以 BLE 广播/可连接方式暴露一个配网服务，手机 App 通过 BLE 把 WiFi SSID/密码 写入设备，设备收到后切换为 STA 模式连接路由器，再把连接结果（成功/失败）回传给 App。各云平台的差异主要体现在配网服务的 UUID、数据分包格式、加密方式和回传协议上，而"BLE 收配置 → 配置 WiFi 模块 → 上报状态"的骨架是统一的——这正是选择链把它们归为同一族 demo 的原因。

与 WiFi 应用的关系

SDK 中三个 WiFi 应用目录都带有蓝牙配套组件，说明"网络与蓝牙配置"在实际产品中是共存运行的：

sdk/apps/wifi_soundbox/ — WiFi 音箱，包含 include/bt_tws.h（TWS 真无线配对）、mode/bt/bt_slience_detect.h（蓝牙静音检测）
sdk/apps/wifi_camera/ — WiFi 摄像头，除 bt_tws.h、bt_slience_detect.h 外还有 include/bt_tone_player.h（蓝牙提示音播放）
sdk/apps/wifi_bbm/ — WiFi BBM，同样有 include/bt_tws.h、mode/bt/bt_slience_detect.h

典型产品形态：BLE 负责配网，经典蓝牙负责音频播放，WiFi 负责流媒体/云端。配网完成后 BLE 可断开或降级为后台服务，经典蓝牙与 WiFi 按产品策略分时或同时工作。

经典蓝牙控制器配置

经典蓝牙侧的两个核心配置头文件：

sdk/include_lib/btctrler/btcontroller_mode.h — BT 控制器工作模式（如双模/单模、主从能力）的声明
sdk/include_lib/btctrler/btcontroller_modules.h — BT 控制器模块（A2DP、HFP、AVRCP、SPP 等）开关

这两个文件是库（lib）对外暴露的配置接口，具体宏与库实现绑定，本仓库中未包含其实现源码；配置它们的宏通常定义在 app_config.h 或板级配置中，最终与 bt_profile_cfg.h 的 BLE 选择一起决定整机蓝牙能力。另外 sdk/apps/common/include/bt_common.h 提供应用层共用的蓝牙公共声明（TWS、提示音等）。

Core Flow：配网与蓝牙配置决策

sequenceDiagram
    participant Dev as 产品开发者
    participant Cfg as app_config.h / 板级配置
    participant Sel as bt_profile_cfg.h
    participant BLE as BLE 协议栈 demo
    participant App as WiFi 应用 (wifi_soundbox 等)

    Dev->>Cfg: 使能 TCFG_USER_BLE_ENABLE + 某配网宏
    Cfg->>Sel: 提供 TCFG_BT_NET_CFG_*_EN / RCSP_MODE 等宏
    Sel->>Sel: 按 #elif 优先级归一为 TCFG_BLE_DEMO_SELECT
    Sel->>BLE: 编译 DEF_BLE_DEMO_NET_CFG_* 分支
    BLE->>App: 启动 BLE 配网服务 (广播/可连接)
    App->>BLE: 手机写入 WiFi SSID/密码
    BLE->>App: 触发 WiFi STA 连接
    App->>BLE: 上报连接结果
    BLE-->>Dev: 设备入网成功，配网完成

关键步骤说明：

配置归一：所有 TCFG_*_EN 宏在 bt_profile_cfg.h 中被编译期解析，产物是唯一的 TCFG_BLE_DEMO_SELECT。这一步是纯静态的，不产生运行时开销。
demo 启动：BLE 协议栈依据该值初始化对应 demo（配网服务 / 透传 / RCSP / HOGP 等）。
配网交互：配网 demo 与 WiFi 应用协作完成"收 SSID/密码 → 连路由 → 回报状态"。
运行期共存：配网完成后，经典蓝牙（btcontroller_modules）与 WiFi 按产品逻辑继续运行，TWS（bt_tws.h）等组件负责双设备配对同步。

注：本仓库为 SDK 源码，bt_profile_cfg.h 之外的配网协议实现、BT 控制器库实现以二进制库形式提供，未包含在仓库源码中；以上配网交互流程基于该配置结构可推导的标准流程，具体报文细节请参考各云平台配网协议文档。

Configuration Options

以下配置项全部为编译期宏，定义于 app_config.h 或板级配置，由 bt_profile_cfg.h 消费。

配置宏	类型	默认/取值	说明
`TCFG_USER_BLE_ENABLE`	bool	0/1	BLE 总开关；为 0 时 `TCFG_BLE_DEMO_SELECT` 强制为 `DEF_BLE_DEMO_NULL`
`RCSP_MODE`	bool	0/1	最高优先级；使能后选择 `DEF_BLE_DEMO_RCSP_DEMO`，BLE 用于 RCSP 手机伴侣协议
`TCFG_TRANS_MULTI_BLE_EN`	bool	0/1	多连接透传 demo（MULTI），次高优先级
`TCFG_TRANS_DATA_EN`	bool	0/1	单连接透传 demo（TRANS_DATA）
`TCFG_BT_NET_CFG_EN`	bool	0/1	基础 BLE 配网 demo（NET_CFG）
`TCFG_BT_NET_CFG_DUI_EN`	bool	0/1	度秘 DUI 配网 demo
`TCFG_BT_NET_CFG_TURING_EN`	bool	0/1	图灵配网 demo
`TCFG_BT_NET_CFG_TENCENT_EN`	bool	0/1	腾讯配网 demo
`TCFG_BT_NET_CFG_DUEROS_EN`	bool	0/1	DuerOS 配网 demo
`TCFG_BLE_MASTER_CENTRAL_EN`	bool	0/1	BLE 主机（Central）demo
`TCFG_BT_NET_CFG_XC_EN`	bool	0/1	喜马拉雅（XC）配网 demo
`TCFG_BT_NET_CFG_TY_EN`	bool	0/1	涂鸦（TY）配网 demo
`TCFG_BLE_HID_EN`	bool	0/1	HOGP（BLE HID）demo
`TCFG_NONCONN_24G_EN`	bool	0/1	24G 非连接 demo
`TCFG_BLE_DEMO_SELECT`	enum（只读输出）	见上	归一化结果，由本文件计算，协议栈直接使用

使用约束：

六个配网宏（TCFG_BT_NET_CFG_EN 与 DUI/TURING/TENCENT/DUEROS/XC/TY）互斥，同一时间只能使能一个，否则按 #elif 顺序只取第一个命中项。
RCSP_MODE 优先级高于一切，若与透传/配网宏同时使能，透传与配网不生效——这是有意设计，RCSP 独占 BLE 控制通道。

Failure Modes, Edge Cases & Concurrency

编译期错误与配置冲突

BLE 未使能但下游引用 demo：TCFG_USER_BLE_ENABLE = 0 时选择值恒为 DEF_BLE_DEMO_NULL (0xff)。下游若未对该值做分支处理，可能进入"无 demo"路径——排查时应先确认该宏，再看 TCFG_BLE_DEMO_SELECT。
多宏同时使能：不报编译错误，但只有 #elif 链首个命中项生效。现象是"明明使能了 X 配网，实际跑的是 Y demo"，这是本配置体系最常见的坑；排查方法：打印/预编译展开 TCFG_BLE_DEMO_SELECT。
遗漏 app_config.h 包含：bt_profile_cfg.h 第一行 #include "app_config.h"，若包含顺序错误导致宏未定义，#if 会按 0 处理，可能静默退化为 DEF_BLE_DEMO_NULL。

运行期边界

配网过程要求 BLE 与 WiFi 模块分时共享射频（AC792N 为单天线共存场景），配网写 SSID/密码期间经典蓝牙音频可能短暂中断，这是共存设计的预期行为。
配网失败（WiFi 密码错误/路由器不可达）时，设备应保持在配网服务态以便重试；具体超时与重试策略由各配网 demo 实现（仓库中为库形式，未含源码）。

并发与一致性

所有配置决策发生在编译期，无运行期竞态；TCFG_BLE_DEMO_SELECT 是编译期常量，可安全用于协议栈任意线程/中断上下文的分支判断。

Performance & Operational Notes

bt_profile_cfg.h 是纯头文件宏，无运行时开销；选择链的 #if/#elif 在预处理阶段完成。
BLE demo 与经典蓝牙（A2DP/HFP）共用 BT 控制器（btcontroller_mode.h/btcontroller_modules.h），配置时应按产品形态裁剪模块宏以节省 RAM/Flash：纯配网产品可裁剪经典蓝牙 profile，音频产品可裁剪 BLE 配网服务。
配网广播间隔、连接参数等运行期性能参数不在本配置文件内，需在各配网 demo 的库配置项中调整。

Extension Points

新增云平台配网：仿照现有 DEF_BLE_DEMO_NET_CFG_* 模式，在 bt_profile_cfg.h 增加枚举编号 + 一个 TCFG_BT_NET_CFG_XXX_EN 宏 + 一个 #elif 分支，再在 BLE 协议栈侧注册对应 demo 实现。
产品形态切换：通过修改 app_config.h 中的 TCFG_* 宏组合，即可在同一工程内切换"纯蓝牙音箱 / WiFi 配网音箱 / RCSP 设备 / BLE HID 设备"，无需改动协议栈源码。
TWS 与提示音：WiFi 应用中的 bt_tws.h（TWS 配对同步）与 bt_tone_player.h（提示音播放）是独立的蓝牙配套模块，可单独使能/裁剪，不影响配网选择链。

Tests

本仓库未包含针对 bt_profile_cfg.h 的自动化测试；该文件属于编译期配置，其"正确性测试"即全宏组合编译——建议在 CI 中对所有 TCFG_*_EN 组合做编译冒烟，验证：1) 任意组合均可编译通过；2) TCFG_BLE_DEMO_SELECT 的值符合 #elif 优先级预期。

bt_profile_cfg.h（BLE demo 选择与配网配置）
bt_common.h（蓝牙公共声明）
btcontroller_mode.h（BT 控制器模式）
btcontroller_modules.h（BT 控制器模块）
wifi_soundbox bt_tws.h
wifi_camera bt_tone_player.h
相关兄弟页面：WiFi 配网协议实现（各 net_cfg demo）、RCSP 协议、音频通路配置