Sig Mesh 方案

本文档介绍杰理 AC63 系列蓝牙 SoC SDK 中基于 Sig Mesh（BLE Mesh，SIG 标准蓝牙 Mesh） 的完整解决方案：协议栈的移植结构、适配层设计、聚合 API、配网（Provisioning）流程、节点/模型（Model）架构以及可配置参数，帮助开发者快速理解如何基于该方案构建灯控、传感器、能源监测等 Mesh 产品。

Purpose and Scope

本页覆盖 apps/common/third_party_profile/sig_mesh/ 目录下移植的 Sig Mesh 协议栈及其在 apps/mesh/ 中的应用工程，具体包括：

• 协议栈分层结构与目录职责（适配层、核心层、API 层）
• sig_mesh_api 聚合头文件与核心 API（buffer 工具、mesh_setup、地址宏等）
• 节点消息、PB-ADV 配网、代理（Proxy）、LPN/Friend 等协议参数的配置方式
• apps/mesh/examples/ 中各类应用模型（AliGenie 灯、腾讯 Mesh、NLC 系列）的工程组织
• 从芯片启动到 Mesh 节点入网、收发消息的端到端控制流

以下相关内容属于其他目录页的范畴，本页不做展开：

• 通用 BLE 协议栈（GAP/GATT 基础）——参见 BLE 协议栈相关目录页
• 杰理私有协议（如 JL 私有 Mesh/音箱互联）——参见对应三方集成页
• 具体产品的 App 联调与云端对接细节——各示例模型（AliGenie/Tencent）各自的集成页

Overview

Sig Mesh 是蓝牙技术联盟（SIG）定义的 BLE Mesh 标准，核心价值在于：

1. 多对多通信：通过"广播-中继-重传"机制，让所有节点相互可达，无需中心网关；
2. 配网安全：基于 ECDH-P256 与 128-bit AES-CCM 的分层密钥体系（Network Key / Application Key / Device Key）；
3. 低功耗：LPN（Low Power Node）与 Friend 节点机制显著降低电池供电节点的功耗；
4. 标准化模型：基于 Element + Model 的寻址与状态模型，灯具、传感器等设备类型都有标准化模型（Light Lightness、Generic OnOff、Sensor 等）。

在本 SDK 中，该方案以 Zephyr BLE Mesh 协议栈移植 的形式存在：apps/common/third_party_profile/sig_mesh/ 是协议栈本体（含 adaptation/ 适配层），apps/mesh/ 是应用工程（含多套示例模型）。协议栈通过 #pragma 段映射将代码/数据放入独立的 .ble_mesh_* 内存段，方便链接脚本统一布局与调试，体现了"库化移植、与应用解耦"的设计意图。

Architecture

flowchart TD
    subgraph sg_App["应用层 apps/mesh"]
        Example["examples/ 示例模型<br/>AliGenie_light / tencent_mesh / *_nlc"]
        Config["api/mesh_config_common.c<br/>协议参数配置"]
    end

    subgraph sg_API["API 聚合层 sig_mesh/api"]
        ApiC["sig_mesh_api.c"]
        ApiH["sig_mesh_api.h<br/>汇总 include 全部子模块头文件"]
        SubApi["子模块 API 头文件<br/>access / cfg / cfg_cli / health / keys<br/>proxy / dfu / scene / rpr / sar_cfg ..."]
    end

    subgraph sg_Core["协议栈核心 sig_mesh/"]
        Access["access.c/.h<br/>Access Layer：Element + Model"]
        AdvExt["adv_ext.c<br/>扩展广播"]
        NetBuf["net/buf 缓冲区"]
        SubCore["其余协议栈源文件<br/>（网络层/传输层/配网）"]
    end

    subgraph sg_Adapt["适配层 sig_mesh/adaptation"]
        BleCore["ble_core/<br/>hci_core / adv_core<br/>scan_core / gatt_core"]
        Kernel["kernel/<br/>atomic / kernel_work<br/>iterable_sections"]
        Misc["misc/<br/>byteorder / slist / list_gen"]
        Storage["storage.c / utils.c"]
        Log["mesh_log.h"]
    end

    Example --> ApiC
    Config --> ApiH
    ApiC --> ApiH
    ApiH --> SubApi
    SubApi --> Access
    Access --> AdvExt
    Access --> NetBuf
    AdvExt --> BleCore
    NetBuf --> Misc
    Access --> SubCore
    SubCore --> BleCore
    SubCore --> Storage
    SubCore --> Kernel
    Kernel --> Misc
    BleCore --> Log
    Storage --> Misc

架构说明：

• 应用层（apps/mesh）：examples/ 下每个 .c 文件对应一种产品模型（通过 CONFIG_MESH_MODEL == SIG_MESH_XXX 宏编译隔离，例如 AliGenie_light.c 对应 SIG_MESH_ALIGENIE_LIGHT），mesh_config_common.c 集中放置全工程共享的协议参数（广播间隔、LPN/Friend、PB-ADV 等）。
• API 聚合层：sig_mesh_api.h 是一个"伞形头文件"，一次性引入 basic_depend.h、mesh_config.h、access.h、main.h、proxy.h、cfg.h、health_cli/srv、keys.h、cdb.h、dfu*、scene*、rpr* 等几十个子模块头文件；sig_mesh_api.c 提供 buffer 读写工具与 mesh_setup() 等入口。应用只需 include 这一个头文件即可使用全部 Mesh 能力。
• 协议栈核心：access.c 实现 Access Layer（Element/Model 注册与消息分发），adv_ext.c 处理扩展广播；网络层、传输层、配网等 Zephyr 原生实现以源文件形式位于本目录（含 net/buf 网络缓冲区）。
• 适配层（adaptation）：将 Zephyr 依赖的 BLE 控制器接口（HCI/ADV/SCAN/GATT）、内核原语（原子操作、工作队列）、基础容器（slist、byteorder）与日志、存储抽象到 SDK 自有的实现上，是"把第三方协议栈接到杰理蓝牙协议栈"的关键隔离层。

关于示例模型（AliGenie / Tencent / NLC）的详细用法，参见各自的目录页；本页聚焦协议栈本身。

协议栈目录结构与职责

apps/common/third_party_profile/sig_mesh/ 目录布局如下（关键文件）：

各子模块 API 头文件（api/cfg*.h、api/health*.h、api/keys.h、api/dfu*.h、api/scene*.h、api/rpr*.h、api/sar_cfg*.h、api/heartbeat.h、api/cdb.h 等）对应 Zephyr Mesh 的 Configuration Client/Server、Health Client/Server、Key 管理、DFU（Device Firmware Update）、Scene、Remote Provisioning、SAR 配置、Heartbeat 等标准特性，均被 sig_mesh_api.h 汇总暴露。

核心控制流

启动与入网流程

节点上电后依次经历：HCI 初始化 → 协议栈初始化（含回调注册）→ 读取/建立持久化配置 → 未配网广播（Unprovisioned Beacon）→ 配网（PB-ADV / PB-GATT）→ 入网成为节点（Node）→ 收发 Mesh 消息。其中协议栈初始化入口为 mesh_setup()：

void mesh_setup(void (*init_cb)(void))
{
    LOG_INF("--func=%s", __FUNCTION__);

    hci_core_init();

    //< mesh init
    if (init_cb) {
        init_cb();
    }
}

Source: sig_mesh_api.c

设计意图：mesh_setup() 先调用适配层 hci_core_init() 拉起 BLE 控制器（HCI 通路），再回调应用传入的 init_cb 完成 Mesh 协议栈与应用模型的初始化。将"底层初始化"与"应用初始化"分离，使各示例工程可以复用同一启动骨架，只需替换自己的 init_cb。

sequenceDiagram
    participant App as 应用 (apps/mesh)
    participant HCI as hci_core (adaptation)
    participant Stack as Mesh 协议栈
    participant PB as PB-ADV/PB-GATT 配网
    participant Phone as 配网器 (Provisioner)

    App->>HCI: mesh_setup() → hci_core_init()
    HCI-->>App: HCI Ready
    App->>Stack: init_cb：注册 Element/Model<br/>读取持久化配置
    Stack->>Stack: 未配网？广播 Unprovisioned Beacon
    Phone->>PB: 扫描到未配网设备，发起配网
    PB->>PB: ECDH-P256 密钥协商 + 邀请/交换公钥
    PB-->>Stack: 分配单播地址、下发 Network Key
    Stack-->>App: Provision 完成回调 (bt_mesh_comp_provision)
    App->>Stack: 订阅组地址、绑定 AppKey
    Phone->>Stack: 发送 OnOff/Level 等模型消息
    Stack-->>Phone: 状态确认（可选 ack）

消息发送路径

节点发出消息时，应用层通过 access.c 的模型发送接口构造消息并附加 OpCode 头；buffer_head_init() 负责把 1/2/3 字节 OpCode 编码为网络字节序的帧头：

u32 buffer_head_init(u32 opcode)
{
    if (opcode < 0x100) {
        /* 1-byte OpCode */
        return opcode;
    }

    if (opcode < 0x10000) {
        /* 2-byte OpCode */
        return sys_cpu_to_be16(opcode);
    }

    /* 3-byte OpCode */
    u8 b0 = (opcode >> 16) & 0xff;
    u16 cid = sys_cpu_to_le16(opcode & 0xffff);

    return cid << 8 | b0;
}

Source: sig_mesh_api.c

SIG Mesh 规范规定 OpCode 采用小端在前（little-endian first）编码：1 字节 OpCode 直接使用；2 字节 OpCode 需转为大端存储；3 字节 OpCode 为厂商自定义格式（0xC0 前缀 + 16-bit Company ID），因此其低 16 位（Company ID）按小端处理、最高字节按顺序排列。该函数集中处理这种编码差异，后续 buffer 写入无需再关心字节序。

内存段映射

整个协议栈通过 #pragma 段映射把代码与数据放入专用段，便于链接脚本统一管理、与用户代码隔离，也方便做 RAM/Flash 占用统计：

#if MESH_RAM_AND_CODE_MAP_DETAIL
#ifdef SUPPORT_MS_EXTENSIONS
#pragma bss_seg(".ble_mesh_joint_bss")
#pragma data_seg(".ble_mesh_joint_data")
#pragma const_seg(".ble_mesh_joint_const")
#pragma code_seg(".ble_mesh_joint_code")
#endif
#else /* MESH_RAM_AND_CODE_MAP_DETAIL */
#pragma bss_seg(".ble_mesh_bss")
#pragma data_seg(".ble_mesh_data")
#pragma const_seg(".ble_mesh_const")
#pragma code_seg(".ble_mesh_code")
#endif /* MESH_RAM_AND_CODE_MAP_DETAIL */

Source: sig_mesh_api.c

设计意图：MESH_RAM_AND_CODE_MAP_DETAIL 开启时使用 _joint_ 细分段（便于按模块精细化布局），否则统一放入 _ble_mesh_ 段。配合 SDK 的链接脚本，开发者可以在 map 文件中一眼看出 Mesh 协议栈整体占用，并可将整个 Mesh 功能整体搬移到指定 RAM 区域。

使用示例

构造 Mesh 消息 buffer

协议栈对 Zephyr net_buf_simple 做了轻量封装，应用在模型回调中可用如下工具按小端/大端顺序写入负载：

u8 *buffer_add_u8_at_tail(void *buf, u8 val)
{
    return net_buf_simple_add_u8((struct net_buf_simple *)buf, val);
}

void buffer_add_le16_at_tail(void *buf, u16 val)
{
    net_buf_simple_add_le16((struct net_buf_simple *)buf, val);
}

void buffer_add_be32_at_tail(void *buf, u32 val)
{
    net_buf_simple_add_be32((struct net_buf_simple *)buf, val);
}

u16 buffer_pull_be16_from_head(void *buf)
{
    return net_buf_simple_pull_be16((struct net_buf_simple *)buf);
}

void *buffer_memcpy(void *buf, const void *mem, u32 len)
{
    return net_buf_simple_add_mem((struct net_buf_simple *)buf, mem, len);
}

Source: sig_mesh_api.c

这些函数统一了"尾部追加（add）"与"头部取出（pull）"两种访问方式，覆盖 u8/le16/be16/le32/be32 全部常见负载类型；应用层不再直接操作 net_buf_simple 内部指针，降低了越界风险，也便于将来替换底层缓冲区实现。

节点地址与模型列表宏

sig_mesh_api.h 提供地址区间判断宏与模型列表快捷宏，模型注册与消息路由判定均依赖它们：

#define BT_MESH_ADDR_IS_UNICAST(addr) ((addr) && (addr) < 0x8000)
#define BT_MESH_ADDR_IS_GROUP(addr) ((addr) >= 0xc000 && (addr) <= 0xff00)
#define BT_MESH_ADDR_IS_VIRTUAL(addr) ((addr) >= 0x8000 && (addr) < 0xc000)
#define BT_MESH_ADDR_IS_RFU(addr) ((addr) >= 0xff00 && (addr) <= 0xfffb)

/** Shorthand macro for defining a model list directly in the element. */
#define BT_MESH_MODEL_LIST(...) ((struct bt_mesh_model[]){ __VA_ARGS__ })

Source: sig_mesh_api.h

地址空间划分遵循 SIG 规范：0x0001–0x7FFF 单播地址、0x8000–0xBFFF 虚拟地址、0xC000–0xFF00 组地址、0xFF01–0xFFFB 保留（RFU）。BT_MESH_MODEL_LIST 使用 C99 复合字面量，可在 Element 定义处内联声明模型数组，使 Element/Model 树结构一目了然。

未配网节点行为配置

以下代码来自应用工程的公共配置模块，展示如何调整节点消息广播与代理广播的硬件参数：

const u16 config_bt_mesh_node_msg_adv_interval = ADV_SCAN_UNIT(10); // unit: ms
const u16 config_bt_mesh_node_msg_adv_duration = 50; // unit: ms

const u16 config_bt_mesh_proxy_unprovision_adv_interval = ADV_SCAN_UNIT(30); // unit: ms
const u16 config_bt_mesh_proxy_pre_node_adv_interval = ADV_SCAN_UNIT(10); // unit: ms
_WEAK_
const u16 config_bt_mesh_proxy_node_adv_interval = ADV_SCAN_UNIT(300); // unit: ms

Source: mesh_config_common.c

ADV_SCAN_UNIT(_ms) 定义为 (_ms) * 8 / 5，即把毫秒换算为 BLE 广播间隔的基本单位（0.625 ms）；所有配置项使用 const 只读变量，其中标 _WEAK_ 的项允许应用在别的编译单元重定义覆盖（弱符号机制），实现"默认值 + 按需覆盖"的配置策略。

配置选项

以下参数集中在 apps/mesh/api/mesh_config_common.c，均以 const 全局变量形式提供，_WEAK_ 标记的项可被用户重定义覆盖：

设计意图：所有参数集中在一个文件而非散落各处，便于产品工程师"一站式"调参；广播/扫描类参数统一换算为 0.625 ms 单位；LPN 与 Friend 参数互为配套（一方启用 LPN 需网络中存在 Friend），默认值按"1 个 Friend 服务 1 个 LPN、小队列"的低资源场景设置，适合 AC63 这类资源受限的 SoC。

API 参考

以下是 sig_mesh_api.c / sig_mesh_api.h 中直接暴露给应用的关键接口（协议栈内部 Zephyr 接口由各子模块头文件提供，此处不逐一展开）。

void mesh_setup(void (*init_cb)(void))

Mesh 协议栈初始化入口。

参数：

• init_cb：初始化回调，在 hci_core_init() 完成后被调用，通常在此注册 Element/Model、恢复持久化配置。

说明： 先初始化 BLE 控制器 HCI 通路，再执行应用侧 Mesh 初始化。见 sig_mesh_api.c。

void mesh_node_primary_addr_reset(u16 addr)

重置节点主地址（内部调用 bt_mesh_comp_provision(addr)，用于设备重新配网/恢复出厂时的地址复位）。

参数：

• addr：新的主单播地址。

见 sig_mesh_api.c。

Buffer 工具函数族

所有函数均为对 Zephyr net_buf_simple 的封装，见 sig_mesh_api.c。

地址/模型宏

• BT_MESH_ADDR_IS_UNICAST(addr) / BT_MESH_ADDR_IS_GROUP(addr) / BT_MESH_ADDR_IS_VIRTUAL(addr) / BT_MESH_ADDR_IS_RFU(addr)：地址区间判定。
• BT_MESH_MODEL_LIST(...)：在 Element 中内联定义模型数组。
• ADV_SCAN_UNIT(_ms)：毫秒 → 0.625 ms 广播单位换算。

见 sig_mesh_api.h。

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

• 广播缓存不足：config_bt_mesh_adv_buf_count 编译期强制 ≥ 3，小于 3 直接 #error，防止因 buffer 数量过少导致消息丢弃或死锁。
• 配网超时链：PB-ADV 配网过程受 prov_retransmit_timeout（300 ms 重传）、prov_transaction_timeout（30 s 事务）、prov_link_close_timeout（3 s 链路关闭）、prov_protocol_timeout（60 s 协议总超时）四层超时保护；配网器异常掉线时节点能自动回收配网链路资源，避免卡死。
• LPN/Friend 配套约束：启用 LPN 必须依赖网络中存在 Friend 节点；config_bt_mesh_lpn_auto_timeout = 0 表示默认不自动进入低功耗，需应用显式触发，避免产品未配置 Friend 时误入低功耗导致消息长时间不可达。
• 并发访问：协议栈与 BLE 控制器之间通过 HCI 通路串行化；kernel/atomic 与 kernel_work 适配层提供原子操作与工作队列，广播/扫描回调中的状态更新应使用这些原语，避免在中断上下文直接操作共享 buffer。
• 地址冲突：单播/组/虚拟地址宏用于入网后消息路由判定；若配网器分配地址与本地缓存冲突，可通过 mesh_node_primary_addr_reset() 复位后重新配网。

性能与运维注意点

• 内存占用可控：协议栈统一放入 .ble_mesh_bss/.data/.const/.code 段（或开启 MESH_RAM_AND_CODE_MAP_DETAIL 后的 _joint_ 细分段），链接后可精确评估 RAM/Flash 占用；产品裁剪时应优先关注 config_bt_mesh_adv_buf_count、Friend 队列大小等影响 RAM 的项。
• 广播参数是功耗关键：config_bt_mesh_proxy_node_adv_interval 默认 300 ms 且为 _WEAK_，电池供电产品可适当加大以省电，但会降低 App 通过 Proxy 连接发现节点的速度；节点消息广播间隔/持续时间则影响多跳网络中继的时延。
• 日志按模块开关：mesh_config_common.c 中为 MESH_HCI、MESH_GATT 等模块定义日志标签，值由 CONFIG_DEBUG_LIB() 控制，量产固件应关闭冗余日志以减小代码体积与运行开销。
• 重传与 QoS：Mesh 本身通过多跳重传保障可靠性，应用层无需自行 ACK；但对时效敏感的命令（如灯控）应控制消息注入频率，避免打满广播缓存导致排队延迟。

扩展点

1. 新增产品模型：在 apps/mesh/examples/ 下仿照 AliGenie_light.c / tencent_mesh.c 新建模型文件，以 #if (CONFIG_MESH_MODEL == SIG_MESH_XXX) 包裹，通过 CONFIG_MESH_MODEL 宏切换编译；模型内部通过 BT_MESH_MODEL_LIST 声明 Element 的模型组，并注册 opcode → 回调的收发映射。
2. 厂商自定义模型：使用 3 字节 OpCode（0xC0 前缀 + 16-bit Company ID）定义私有模型，发送时由 buffer_head_init() 自动编码帧头。
3. 协议参数覆盖：对 _WEAK_ 标记的配置项（如 config_bt_mesh_proxy_node_adv_interval、config_bt_mesh_adv_buf_count），可在应用工程其他编译单元重定义覆盖，无需修改协议栈文件。
4. 新特性接入：sig_mesh_api.h 已汇总 dfu*（固件升级）、scene*（场景）、rpr*（远程配网）、sar_cfg*（SAR 配置）、heartbeat、cdb（配置数据库）等标准扩展 API，按需在应用层调用即可。

相关链接

• sig_mesh_api.c — 聚合 API 实现（buffer 工具、mesh_setup）
• sig_mesh_api.h — 伞形头文件与地址/模型宏
• mesh_config_common.c — 全工程 Mesh 协议参数配置
• access.c — Access Layer（Element/Model 注册与分发）
• AliGenie_light.c — 天猫精灵灯控模型示例
• tencent_mesh.c — 腾讯 Mesh 示例
• 相关目录页：BLE 协议栈基础、AliGenie/Tencent/NLC 各自模型集成页