网络与系统库依赖

本页说明 gitee-repos-Other（杰理仓库整理 — 其他）中所含 Bootloader / OTA-loader 工程对系统库（lib.a 静态库、编译工具链）与网络/通信能力（串口升级、USB HID 升级、BLE RCSP）的依赖关系与接入方式。

Purpose and Scope

本页聚焦「网络与系统库依赖」这一横向主题，即：

• 仓库内固件工程（fw-Bootloader、ac792n-ota-loader）编译时所依赖的系统静态库（lib.a）与子仓库的匹配规则；
• 编译系统库（Codeblock / Make 工具链、合并归档工具等）及其版本要求；
• 工程使用的网络/通信协议通道（串口升级、USB HID 升级、BLE RCSP server）及其在代码中的载体；
• SDK 型号与 BootLoader 系列（bd19/br23/br25/br30/br34/sh54/sh55/wl82/br28）的对应关系。

以下内容不属于本页范围，请参见兄弟页面：fw-Bootloader 自身的升级流程与协议细节（见仓库内 doc/uboot升级使用说明v1.1.2.md、doc/uboot升级协议流程v1.1.2.md）；ac792n-ota-loader 的具体 OTA 实现逻辑归 OTA 加载器页面。本页只梳理「依赖了什么系统库、什么网络能力、如何匹配与构建」。

Overview

该仓库是一个仓库集合（aggregator），根 README.md 明确声明其定位为「杰理仓库整理 — 其他（不属于主要分类的仓库）」，当前收纳两个固件子工程：

来源：README.md

从「网络与系统库依赖」的角度看，这两个工程都属于裸机/轻系统固件，其依赖可以归纳为三层：

1. 系统静态库层（lib.a）：fw-Bootloader/README.md 明确说明「本工程提供的例子，需要结合对应命名规则的库文件(lib.a) 和对应的子仓库进行编译」，即工程本身不内嵌系统实现，而是按芯片系列的命名规则链接厂商提供的二进制库。
2. 构建系统层（工具链）：与标准 SDK 一致的 Codeblock（.cbp 工程）与 Make 双编译环境，以及 ac792n-ota-loader/tools/ 下的一批 Unix 风格辅助工具（make.exe、merge-archives.exe、override-seg.exe、ls.exe、rm.exe 等）。
3. 网络/通信协议层：Bootloader 支持「自定义串口升级」与「USB HID 升级」两条通道；ac792n-ota-loader 的 uboot 应用代码中包含 bluetooth/ble_rcsp_server.c（BLE RCSP 服务端），以及 common/ 下与配置、缓冲、LTV 格式相关的公共模块。

理解这一依赖结构的意义在于：boot 代码先于系统运行，无法复用完整 SDK 的运行时，因此必须依赖经过裁剪、按 CPU 命名的静态库，并通过严格的 CRC 校验保证 uboot.boot 镜像的完整性。

Architecture

下图展示仓库内两个工程与「系统库 / 工具链 / 网络通信」三层依赖之间的关系：

flowchart TD
    subgraph sg_Repo["gitee-repos-Other（杰理仓库整理 — 其他）"]
        subgraph sg_Boot["fw-Bootloader（JL 系列 user boot）"]
            Boot["user_boot 多 CPU 工程入口<br/>br28 / br23 / br25 / br30 ..."]
            BootDoc["doc/ 升级使用说明与协议流程"]
        end
        subgraph sg_Ota["ac792n-ota-loader（AC792N ota-loader）"]
            OtaApp["uboot 应用代码<br/>common / bluetooth 模块"]
            OtaTools["tools/ 编译辅助工具<br/>make / merge-archives / override-seg"]
        end
    end

    subgraph sg_Sys["系统库与构建依赖"]
        Libs["静态系统库 lib.a<br/>（按命名规则匹配）"]
        SubRepo["对应子仓库"]
        Toolchain["标准 SDK 工具链<br/>Codeblock (.cbp) / Make"]
    end

    subgraph sg_Net["网络/通信能力"]
        Uart["串口升级通道"]
        UsbHid["USB HID 升级通道"]
        Ble["BLE RCSP server"]
    end

    Boot --> Libs
    Boot --> SubRepo
    Boot --> Toolchain
    Boot --> Uart
    Boot --> UsbHid
    OtaApp --> Libs
    OtaApp --> SubRepo
    OtaApp --> Ble
    OtaTools --> Toolchain
    BootDoc -.-> Uart
    BootDoc -.-> UsbHid

图注： 两个工程都依赖「按命名规则匹配的 lib.a + 对应子仓库」这一系统库组合；编译必须依赖标准 SDK 工具链。通信能力方面，Bootloader 暴露串口与 USB HID 两条升级通道（协议细节见其 doc/ 目录），而 ota-loader 的 uboot 应用代码中由 ble_rcsp_server.c 承载 BLE RCSP 服务端能力。图中虚线表示文档对协议通道的说明关系，实线表示编译/链接/代码调用关系。

系统静态库依赖（lib.a）

依赖规则与设计意图

fw-Bootloader/README.md 是仓库内关于库依赖最直接的权威说明：

本工程提供的例子，需要结合对应命名规则的库文件(lib.a) 和对应的子仓库进行编译.

来源：fw-Bootloader/README.md

这背后是杰理 SDK 的一贯做法：芯片厂商将硬件驱动、系统服务以预编译静态库（lib.a）形式发布，源码工程只保留用户可定制部分。对 boot 类工程而言，这样做的设计意图很明确：

• 裁剪与安全：boot 镜像体积极小且运行在系统初始化之前，无法承载完整 SDK 源码；预编译库既能控制体积，也避免用户改动底层关键逻辑；
• 多芯片复用：同一套 user boot 源码通过链接不同命名的 lib.a 即可适配不同芯片系列（见下文 SDK 对应表）；
• 子仓库隔离：示例代码需要「对应的子仓库」配合，说明库与源码之间存在版本/接口强耦合，必须按命名规则配对，否则会出现链接错误或接口不匹配。

库合并工具

在 ac792n-ota-loader 中，库的链接/合并由构建脚本驱动。仓库包含：

• tools/utils/do_merge_libs.bat — 合并静态库的批处理脚本；
• tools/utils/merge-archives.exe — 归档（.a）合并工具；
• tools/utils/override-seg.exe — 段覆盖工具；
• tools/make_prompt.bat — 构建提示/环境辅助脚本。

来源：do_merge_libs.bat、make_prompt.bat

这些工具的存在说明 ota-loader 的构建产物需要把多个来源的 lib.a 与工程目标文件合并、并做段级覆盖——这是嵌入式 boot 工程常见的「链接后修补」流程（例如调整加载地址、覆盖弱符号实现）。脚本的具体内容未在本页读取范围内，但工具命名（override-seg、merge-archives）与文件清单一致。

系统库与编译工具链依赖

工具链要求

fw-Bootloader/README.md 规定：

使用的工具链与标准SDK一致。如遇到《"错误:uboot.boot数据的CRC校验错误"错误:生成失败，无效的F文件，请重新选择系统找不到指定的文件。》这样的错误，需要更新最新的工具：https://doc.zh-jieli.com/Tools/zh-cn/other_info/index.html

来源：fw-Bootloader/README.md

设计意图：CRC 校验与 F 文件（固件打包文件）生成都依赖上位机工具。工具版本过旧会导致打包参数与 boot 端校验逻辑不一致——因此「工具链与标准 SDK 一致」且必须保持最新，本质上是保证构建侧与运行侧校验算法一致的强约束。

编译环境

SDK 同时支持两套编译环境：

• Codeblock：进入对应 CPU 工程目录，双击后缀为 .cbp 的工程文件编译（例如 AC701N 对应 user_boot\cpu\br28\br28_uboot.cbp）；
• Make：命令行 make 环境。

来源：fw-Bootloader/README.md

ac792n-ota-loader 侧，tools/utils/ 下提供了一批 Unix 风格命令的 Windows 实现（find.exe、fixbat.exe、ls.exe、make.exe、mkdir_win.exe、rm.exe、true.exe、uname.exe 等），表明其构建流程依赖类 Unix shell 语义，并在 Windows 上用本地可执行文件补齐这些命令——这也是「系统库依赖」的一部分（构建环境依赖）。

网络/通信能力依赖

Bootloader 的升级通道

fw-Bootloader/README.md 声明该 user boot「支持用户进行自定义串口升级和 usb_hid 升级」，即固件下载走两条通道：

来源：fw-Bootloader/README.md

两条通道共享同一份 uboot.boot 镜像与升级协议框架，只是物理传输层不同——这是 boot 设计上的关键抽象：升级协议与传输通道解耦，从而在串口与 USB HID 之间复用同一下载流程。

ota-loader 的 BLE 能力

ac792n-ota-loader/uboot/apps/code/bluetooth/ble_rcsp_server.c 是仓库中唯一的「网络协议」实现文件。从命名看，它实现的是 BLE RCSP（Remote Control Service Protocol）服务端——一种基于 BLE 的遥控/透传协议，常用于杰理方案的手机 App 与设备通信。它位于 uboot 应用代码中，说明 ota-loader 在 boot 阶段即可提供 BLE 服务。

来源：ble_rcsp_server.c

公共系统模块

ac792n-ota-loader/uboot/apps/code/common/ 下的公共源文件构成 ota-loader 的「系统支撑层」：

来源：common.c、custom_cfg.c、lbuf_new.c、ltv_format.c

注：以上职责为基于文件命名与工程布局的推断；函数级实现细节未在本页源码读取范围内，详见 ota-loader 的兄弟页面。

SDK 型号与 BootLoader 系列对应表

fw-Bootloader/README.md 给出了「网络/系统库依赖」中最关键的匹配表——SDK 芯片型号决定链接哪一套 boot 系统库：

来源：fw-Bootloader/README.md

设计意图与使用方式：bd19/br23/br25/br30/br34/sh54/sh55/wl82/br28 是各 CPU 系列的 boot 代号，同时是 user_boot\cpu\<代号>\<代号>_uboot.cbp 工程目录的命名依据。例如 AC701N 使用 br28_uboot.cbp 作为工程入口——选定工程入口即等价于选定系统库集合。新增芯片支持时，只需新增一个 CPU 目录并配套对应命名的 lib.a，无需改动 boot 主流程，这是该仓库可扩展性的核心。

Core Flow — 从依赖到固件的构建与升级流程

构建流程（依赖参与的关键路径）

flowchart TD
    Start([开始]) --> Pick["按 SDK 型号选择工程入口<br/>如 AC701N → user_boot/cpu/br28/br28_uboot.cbp"]
    Pick --> Env{"工具链就绪？<br/>Codeblock / Make + 最新工具"}
    Env -->|"否"| Update["更新最新工具<br/>doc.zh-jieli.com/Tools"]
    Update --> Env
    Env -->|"是"| Link["链接系统库 lib.a<br/>+ 对应子仓库<br/>（do_merge_libs.bat / merge-archives）"]
    Link --> Build["编译生成 uboot.boot"]
    Build --> Crc{"CRC 校验通过？"}
    Crc -->|"否"| Err["报错：uboot.boot数据的CRC校验错误<br/>或 生成失败，无效的F文件"]
    Err --> Update
    Crc -->|"是"| Dld["加入原 SDK 下载目录调试"]
    Dld --> Upg["用户升级：串口 / USB HID 通道"]
    Upg --> End([结束])

流程中的每一步都与本页主题直接相关：

1. 选工程入口 = 选定 CPU 系列（br28 等），也就确定了要链接哪一套系统库；
2. 工具链校验 = 保证打包工具与 boot 端 CRC/校验算法一致（工具链是隐式系统依赖）；
3. 链接系统库 = 把按命名规则匹配的 lib.a 与子仓库代码合并进 boot 镜像；
4. CRC 校验 = boot 镜像完整性的第一道关卡，失败时 README 明确要求更新工具；
5. 加入 SDK 下载目录 = uboot.boot 最终作为标准 SDK 烧录流程的一部分被下载；
6. 升级通道 = 串口 / USB HID，两者共享同一升级协议。

升级交互时序

sequenceDiagram
    participant U as 用户/上位机工具
    participant B as Bootloader (user boot)
    participant P as 通信通道（串口 / USB HID）
    participant F as 固件区 (uboot.boot)

    U->>B: 通过串口或 USB HID 发起升级
    B->>P: 建立协议连接（协议见 doc/uboot升级协议流程）
    P-->>B: 连接就绪
    B->>F: 校验镜像 CRC
    F-->>B: 校验结果（失败则返回错误提示）
    B-->>U: 升级流程开始 / 错误提示
    B->>F: 写入新固件
    F-->>B: 写入完成
    B-->>U: 升级完成

说明：时序图中的协议交互细节以仓库内 doc/uboot升级协议流程v1.1.2.md 为准；本页仅依据 README 声明（支持串口/USB HID 升级、存在 CRC 校验）绘制高层时序。

Usage Examples

示例 1：仓库根 README 的包含仓库表（依赖的顶层入口）

## 包含仓库

| 目录 | 说明 |
|------|------|
| fw-Bootloader | JL 系列定制 Bootloader |
| ac792n-ota-loader | JL AC792N系列定制 ota-loader |

Source: README.md

该表是理解「网络与系统库依赖」的起点：两个子工程各自链接不同的系统库集合，但共享同一套杰理工具链约定。

示例 2：库文件依赖的官方声明

本工程提供的例子，需要结合对应命名规则的库文件(lib.a) 和对应的子仓库进行编译.

Source: fw-Bootloader/README.md

这是整个仓库中关于「系统库依赖」最核心的一句话：编译前必须备齐命名匹配的 lib.a 与对应子仓库，否则工程无法构建。

示例 3：工具链版本约束与典型错误

如遇到《"错误:uboot.boot数据的CRC校验错误"错误:生成失败，无效的F文件，请重新选择系统找不到指定的文件。》这样的错误，需要更新最新的工具：https://doc.zh-jieli.com/Tools/zh-cn/other_info/index.html

Source: fw-Bootloader/README.md

该示例同时揭示了两个典型故障模式（CRC 校验错误、无效 F 文件）及其唯一的官方处置手段（更新工具链），是运维排查的第一优先级动作。

示例 4：工程入口选择（按 CPU 系列）

| SDK型号    | BootLoader对应  |
|  ----      | ----        |
| AC791N         | wl82 |
| AC701N         | br28 |

例如: SDK型号使用的是AC701N, 使用user_boot\cpu\br28\br28_uboot.cbp作为工程入口。

Source: fw-Bootloader/README.md

「工程入口 = CPU 系列 = 系统库集合」三位一体，是选择依赖时的操作指南。

Configuration Options

本仓库的「配置」体现在依赖选择与构建参数上，均以 README 文档和工程目录结构为载体：

关键源码入口（API 参考）

以下文件是本主题在代码层面的落点。函数级签名与内部实现未在本页源码读取范围内展开（详见各自兄弟页面），此处仅给出定位与依赖角色：

• ac792n-ota-loader/uboot/apps/code/common/common.c — 公共系统函数层，被 uboot 应用与协议模块共同依赖。查看
• ac792n-ota-loader/uboot/apps/code/common/custom_cfg.c — 定制配置解析入口，是量产差异化配置的扩展点。查看
• ac792n-ota-loader/uboot/apps/code/common/lbuf_new.c — 缓冲管理实现，为串口/BLE 等数据通道提供缓冲。查看
• ac792n-ota-loader/uboot/apps/code/common/ltv_format.c — LTV（Length-Type-Value）编解码，协议帧/配置数据的格式基础。查看
• ac792n-ota-loader/uboot/apps/code/bluetooth/ble_rcsp_server.c — BLE RCSP 服务端实现，ota-loader 的网络协议载体。查看
• ac792n-ota-loader/tools/utils/do_merge_libs.bat / merge-archives.exe / override-seg.exe — 系统库合并与段覆盖工具。查看

Failure Modes、边界情况与并发

已知故障模式（README 明文记录）

来源：fw-Bootloader/README.md

边界情况：

• 多芯片共用源码：同一 user boot 源码通过不同 lib.a 适配多系列芯片，若 lib.a 命名与 CPU 工程不匹配，链接阶段即失败——依赖选择错误是最常见的边界错误；
• boot 特殊性：README 免责声明指出「user boot 支持多系列芯片开发，鉴于boot的特殊性，请务必进行充分测试」，即 boot 镜像任何依赖变更都必须全量回归。

并发与一致性

本页读取的文档层面未描述 boot 阶段的并发模型；从工程性质推断，boot 代码运行于系统初始化前、通常为单任务/事件驱动模型（ble_rcsp_server.c 属于事件回调式协议处理）。镜像一致性由构建期 CRC 校验保证，而非运行期并发控制。若需确认具体并发行为，请以 ota-loader 页面及对应源码为准。

Performance 与运维注意

• 工具链版本管理：构建工具与 boot 端校验算法强耦合，升级 SDK 时必须同步更新工具，否则出现 CRC 类伪故障；
• 产物交付路径：uboot.boot 不单独烧录，必须加入原 SDK 下载目录——部署时先确认 SDK 与 boot 版本配套；
• 升级通道选择：量产场景倾向 USB HID（免驱、速度稳定），调试场景倾向串口；两者协议一致，可平滑切换；
• 库合并开销：merge-archives/override-seg 在链接后处理，属于构建期开销，不影响运行期性能。

Extension Points

1. 新增芯片系列：在 user_boot\cpu\<代号>\ 下新增 CPU 工程（如 br28_uboot.cbp），配套提供命名匹配的 lib.a 与子仓库，即可扩展 BootLoader 到新 SDK 型号——对应表是扩展的注册清单；
2. 定制配置：custom_cfg.c 是量产差异化配置的挂载点，新增配置项应在该模块实现解析；
3. 协议扩展：新增升级通道（如 BLE OTA）时，ble_rcsp_server.c（BLE RCSP 服务端）与 ltv_format.c（帧格式）提供了协议侧基础，串口/USB HID 共用升级协议框架可复用；
4. 构建定制：do_merge_libs.bat 与 make_prompt.bat 是构建流程的定制入口，可调整库合并顺序与段覆盖策略。

Related Links

• 仓库根 README（包含仓库清单）
• fw-Bootloader README（库依赖与 SDK 对应表）
• fw-Bootloader 升级使用说明
• fw-Bootloader 升级协议流程
• 杰理官方工具链文档
• BLE RCSP 服务端源码
• 库合并脚本 do_merge_libs.bat