# third_party **Repository Path**: elvin_gitee/third_party ## Basic Information - **Project Name**: third_party - **Description**: 本仓库不产出固件。它是一个嵌入式工程的第三方依赖基线:把协议、存储、基础运行时、算法、控制、外设与工具等各类库 按同一套标准 vendor 进来,每库一页接入说明,版本与许可证可追溯,本地改动全部外置为补丁。 - **Primary Language**: Unknown - **License**: LGPL-2.1 - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 2 - **Forks**: 0 - **Created**: 2026-11-13 - **Last Updated**: 2026-11-21 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # third_party —— 嵌入式 协议 / 存储 / 算法 依赖基线 > 本仓库**不产出固件**。它是一个嵌入式工程的第三方依赖基线:把协议、存储、基础运行时、算法、控制、外设与工具等各类库 > 按同一套标准 vendor 进来,每库一页接入说明,版本与许可证可追溯,本地改动全部外置为补丁。 > > 目标不是「收集了很多库」,而是:**换一个工程、换一个人、换一年以后,还能照着文档把库正确接进去。** ## 一、这个仓库是什么 | 是 | 不是 | |---|---| | 可 `git clone` 后直接取源码的库集合 | 带构建系统的 SDK(本仓库无 CMake/Makefile 根脚本) | | 每个库一页「能力 / 编译单元 / 配置宏 / 外部接口 / 坑」的接入文档 | 上游文档的镜像(上游文档只做链接) | | 版本、commit、许可证、补丁的单一登记处(SBOM) | 改过的上游代码(改动一律外置补丁) | | 选型判据:什么场景用哪个库、什么场景必须自建 | 通用框架(BSP/驱动/服务层不在本仓库) | 厂商芯片 SDK(启动文件、device 头、外设库)**不属于**本仓库,它随具体工程走; 本仓库只收「与芯片无关、可跨工程复用」的库。唯一的例外是 CMSIS-DSP——它是算法库, 但依赖工程侧提供 CMSIS-Core 头文件,这一依赖在 [`docs/libs/cmsis-dsp.md`](docs/libs/cmsis-dsp.md) 里写明。 ## 二、目录结构 ```text third_party/ ├─ modbus/nanomodbus/ Modbus RTU/TCP ├─ canopen/canopennode/ CANopen 协议栈 ├─ net/mqttclient/ MQTT 客户端(socket 抽象 + TLS) ├─ net/thttpd/ HTTP 服务器(网关/PC 侧参考) ├─ usb/cherryusb/ USB 设备/主机栈 ├─ net/lwip/ TCP/IP 协议栈 ├─ net/libcoap/ CoAP(RFC7252) ├─ ble/nimble/ BLE 协议栈 ├─ crypto/mbedtls/ TLS / PSA 密码学 ├─ crypto/micro-ecc/ ECDH/ECDSA ├─ crypto/monocypher/ 哈希/AEAD/签名 ├─ log/easylogger/ 分级日志 ├─ log/cmbacktrace/ HardFault 回溯 ├─ test/cmock/ mock 生成器(Ruby) ├─ test/cexception/ 异常断言 ├─ test/fff/ 伪函数框架 ├─ codec/qcbor/ CBOR 编解码 ├─ codec/nanopb/ protobuf 编解码 ├─ display/u8g2/ 单色屏图形库 ├─ audio/speex/ 语音编解码 ├─ fs/sfud/ SPI Flash 通用驱动 ├─ boot/hdiffpatch/ 差分升级 ├─ rtos/rtthread-nano/ RT-Thread Nano(RTOS) ├─ display/lvgl/ 彩色 GUI(LVGL 9) ├─ gps/minmea/ NMEA 0183 解析 ├─ fs/littlefs/ 掉电安全文件系统 ├─ fs/fatfs/ FAT 文件系统 ├─ boot/mcuboot/ 安全 Bootloader / OTA ├─ compress/heatshrink/ LZSS 压缩 ├─ json/cjson/ JSON ├─ libc/printf/ 小体积 printf ├─ dsp/cmsis-dsp/ ARM DSP 库 ├─ dsp/savitzky-golay/ SG 平滑滤波 ├─ math/libfixmath/ Q16.16 定点数学 ├─ math/libfixmatrix/ 定点矩阵/向量/四元数 ├─ math/libfixkalman/ 定点 Kalman ├─ control/adrc/ ADRC(TD + ESO) ├─ fs/flashdb/ KV/时序数据库 ├─ input/multibutton/ 按键事件驱动 ├─ shell/letter-shell/ 嵌入式命令行(shell) ├─ test/unity/ 单元测试框架(Unity) ├─ test/cutest/ 轻量单测框架(CuTest) ├─ fsm/efsmc/ 事件驱动有限状态机(EFSMC) ├─ manifests/ 每库一份机器可读描述(编译单元 / 宏 / port / 硬约束) ├─ tools/ 取子库与校验:lib.ps1、check_repo.ps1、tests/ ├─ docs/ 接入文档(本仓库的正文) ├─ third-party.md SBOM:版本 / commit / 许可证 / 上游 / 体积 ├─ PATCHES.md 本地补丁登记表(当前为空) └─ libraries.md 旧版库总览(已拆分为 docs/,保留作索引) ``` **按需取子库**:工程不整仓复制,用 `tools/lib.ps1 vendor -Lib <库> -Dest <工程>/third_party/opensource` 只取需要的库(默认整库、可复现、写 lock);离线交接用 `export` 打 zip(含 commit/hash), 跟随基线用稀疏检出。三者命令与取舍见 [`docs/distribution.md`](docs/distribution.md) §四。 **为什么要两层目录**:第一层是领域(`modbus/` `fs/` `math/`),第二层是具体库(`nanomodbus/`)。 领域层回答「我要干什么」,库层回答「我用谁」。同一领域放多个候选库是允许的(如 `fs/` 下 littlefs 与 FatFs), 选型由 [`docs/catalog.md`](docs/catalog.md) 决定,不靠目录名字暗示。 ## 三、库清单速览 | 领域 | 库 | 版本 | 许可证 | 一句话 | |---|---|---|---|---| | 协议 | [nanoMODBUS](docs/libs/nanomodbus.md) | v1.23.0 | MIT | Modbus RTU/TCP,回调式、无 malloc | | 协议 | [CANopenNode](docs/libs/canopennode.md) | v4.1 | Apache-2.0 | CANopen 栈(NMT/SDO/PDO/EMCY + CiA 402) | | 协议 | [mqttclient](docs/libs/mqttclient.md) | `20175e2` | Apache-2.0 | MQTT 客户端(QoS2 + TLS + RTOS 适配) | | 协议 | [minmea](docs/libs/minmea.md) | v1.0.0 | WTFPL / MIT(三选一,按 MIT 用) | NMEA 0183 逐行解析 | | 存储/升级 | [littlefs](docs/libs/littlefs.md) | v2.11.3 | BSD-3-Clause | 掉电安全 + 磨损均衡的 Flash FS | | 存储/升级 | [FatFs](docs/libs/fatfs.md) | R0.15 w/patch1 | ChaN FatFs License | FAT 文件系统,SD 卡场景 | | 存储/升级 | [MCUboot](docs/libs/mcuboot.md) | v2.5.0 | Apache-2.0 | 安全 Bootloader / OTA(方案级,非库) | | 存储/升级 | [heatshrink](docs/libs/heatshrink.md) | v0.4.1 | ISC | LZSS 压缩,静态窗口可用 | | 基础运行时 | [cJSON](docs/libs/cjson.md) | v1.7.19 | MIT | JSON 解析/生成,必须换分配器 | | 基础运行时 | [mpaland/printf](docs/libs/printf.md) | v4.2.1 | MIT | 可裁剪 printf,与 newlib 二选一 | | 数值算法 | [CMSIS-DSP](docs/libs/cmsis-dsp.md) | v1.18.0 | Apache-2.0 | FIR/IIR/FFT/统计/矩阵/PID/LMS | | 数值算法 | [libfixmath](docs/libs/libfixmath.md) | `46e89b7` | MIT | Q16.16 定点数学 | | 数值算法 | [libfixmatrix](docs/libs/libfixmatrix.md) | `a8d583e` | MIT | 定点矩阵/向量/四元数 | | 数值算法 | [libfixkalman](docs/libs/libfixkalman.md) | `fda184f` | MIT | 定点 Kalman | | 数值算法 | [Savitzky-Golay](docs/libs/savitzky-golay.md) | `3a050f0` | MIT | 保峰多项式平滑 | | 控制 | [ADRC_Lib](docs/libs/adrc.md) | `b4c2e63` | MIT | TD 跟踪微分 + ESO 扩张观测 | | 架构与调试 | [EFSMC](docs/libs/efsmc.md) | `7eab023` | MIT | 事件驱动状态机(查表模型) | | 架构与调试 | [letter-shell](docs/libs/letter-shell.md) | `03432e8` | MIT | 串口命令行 shell | | 架构与调试 | [Unity](docs/libs/unity.md) | `54f864c` | MIT | 单元测试框架 | | 架构与调试 | [CuTest](docs/libs/cutest.md) | `357376c` | zlib 系 | 极简单测框架(2 文件) | | 存储/升级 | [FlashDB](docs/libs/flashdb.md) | `360a68d` | Apache-2.0 | KV + 时序数据库(掉电安全) | | 外设与接口 | [MultiButton](docs/libs/multibutton.md) | `5848818` | MIT | 按键事件驱动(单击/双击/长按) | | 协议 | [thttpd](docs/libs/thttpd.md) | `69008d1` | BSD-2 风格 | HTTP 服务器(网关/PC 侧参考) | | 外设与接口 | [CherryUSB](docs/libs/cherryusb.md) | 1.6.1 | Apache-2.0 | USB 设备/主机协议栈 | | 协议 | [lwIP](docs/libs/lwip.md) | master | BSD-3-Clause | TCP/IP 协议栈(含 DHCP/DNS/SNTP) | | 协议 | [libcoap](docs/libs/libcoap.md) | develop | BSD-2-Clause | CoAP 客户端/服务端 | | 协议 | [NimBLE](docs/libs/nimble.md) | master | Apache-2.0 | BLE 协议栈 | | 安全 | [mbedTLS](docs/libs/mbedtls.md) | v3.6.7 | Apache-2.0 | TLS/密码学(PSA) | | 安全 | [micro-ecc](docs/libs/micro-ecc.md) | master | BSD-2 | ECDH/ECDSA(小体积) | | 安全 | [Monocypher](docs/libs/monocypher.md) | master | BSD-2/CC0 | 哈希/AEAD/签名 | | 可观测性 | [EasyLogger](docs/libs/easylogger.md) | master | MIT | 分级日志 | | 可观测性 | [CmBacktrace](docs/libs/cmbacktrace.md) | master | MIT | HardFault 现场回溯 | | 测试 | [CMock](docs/libs/cmock.md) | master | MIT | 根据头文件生成 mock | | 测试 | [CException](docs/libs/cexception.md) | master | MIT | Try/Catch 异常断言 | | 测试 | [fff](docs/libs/fff.md) | master | MIT | 伪函数/参数捕获 | | 编解码 | [QCBOR](docs/libs/qcbor.md) | master | BSD-3 | CBOR 编码/解码 | | 编解码 | [nanopb](docs/libs/nanopb.md) | master | zlib | protobuf 编解码 | | 显示 | [u8g2](docs/libs/u8g2.md) | master | BSD-2 | 单色屏图形库(字库大) | | 音频 | [Speex](docs/libs/speex.md) | master | BSD-3 | 窄带语音编解码 | | 存储 | [SFUD](docs/libs/sfud.md) | master | MIT | JEDEC SFDP SPI Flash 驱动 | | 升级 | [hdiffpatch](docs/libs/hdiffpatch.md) | master | MIT | 差分升级(配合 MCUboot) | | 运行时 | [RT-Thread Nano](docs/libs/rtthread-nano.md) | 4.1.1 | Apache-2.0 | 抢占式 RTOS(Nano 发行包) | | 显示 | [LVGL](docs/libs/lvgl.md) | 9.6.0 | MIT | 彩色 GUI(TFT/触摸) | 版本/commit/上游 URL/体积/修改情况的权威登记在 [`third-party.md`](third-party.md);本表只做速览,二者不一致时以 SBOM 为准。 ## 四、怎么用:三个动作 1. **选型** —— 读 [`docs/catalog.md`](docs/catalog.md):按「领域 + 硬约束(有无 malloc、有无浮点、是否可裁剪、是否要 RTOS)」筛, 再决定「用库」还是「自建」(自建清单也在该页)。 2. **接入** —— 读该库的 `docs/libs/<库>.md`:照「编译单元 / 配置宏 / 需要你实现的外部接口 / 集成检查清单」四节抄。 通用接入模型(编译单元与宏的放置位置、malloc 审计、ISR 约束)见 [`docs/integration.md`](docs/integration.md)。 3. **登记** —— 新增或升级库时,同步更新 `third-party.md`(SBOM)与 `docs/libs/<库>.md`(接入页),缺一个都算没做完。 ## 五、仓库纪律 1. **能不改就不改**。必须改时,不改上游文件:补丁放 `patches/<库>/`,并在 `PATCHES.md` 登记(文件、原因、日期、回滚方式)。 若某个库需要深度改造,整库收编进使用方工程,不要在本仓库里「边用边改」。 2. **原样入库**。`.gitattributes` 关闭行尾改写,避免「我们改了厂商代码」的伪 diff。 3. **新增/升级单独提交**,不 amend。旧版本永远可回滚。 4. **许可证先看原文**,不看 README 声明。许可证不可静态链接、不允许闭源分发的库不入库。 5. **文档与代码同一次提交**。库页里的编译单元清单、宏名、原型必须与源码一致;不一致就是 bug。 ## 六、文档地图 | 文件 | 回答什么问题 | |---|---| | [`docs/README.md`](docs/README.md) | 我是谁,该按什么顺序读 | | [`docs/catalog.md`](docs/catalog.md) | 选哪个库;什么必须自建;哪些评估过但不收 | | [`docs/protocols-selfbuild.md`](docs/protocols-selfbuild.md) | 哪些行业协议必须自研、最小子集与验收标准 | | [`docs/integration.md`](docs/integration.md) | 接入标准、宏放哪、malloc/ISR/裁剪的通用约束 | | [`docs/licensing.md`](docs/licensing.md) | 许可证矩阵与合规义务 | | [`docs/libs/`](docs/libs/) | 每个库一页:能力、编译单元、宏、外部接口、坑 | | [`docs/lib-page-template.md`](docs/lib-page-template.md) | 新增库页时照抄的模板与写作规则 | | [`docs/distribution.md`](docs/distribution.md) | 怎么只取需要的库(vendor/导出/稀疏检出)、manifest 字段、编码前查库门禁 | | [`third-party.md`](third-party.md) | 版本/commit/许可证/体积的权威登记(SBOM) | | [`PATCHES.md`](PATCHES.md) | 本地补丁登记(当前为空 = 没改过上游) | ## 七、当前状态与已知缺口 ### 7.1 已具备 - **按需分发**:工程不整仓复制。`tools/lib.ps1 vendor` 按 `requires` 闭包取库,写 `third_party/libs.lock.json` (基线 commit + 每库 `tree_sha256`/文件数);离线交接用 `export` 打 zip(包内 `README-EXPORT.md` 带 commit 与 hash); 跟随基线可用稀疏检出(命令与限制见 [`docs/distribution.md`](docs/distribution.md) §4.1)。 - **机器可读描述**:`manifests/` 已覆盖 43/43,逐库给出编译单元、头文件、配置宏、外部接口与硬约束 (分配器 / 浮点 / OS / ISR / 重入)。`tools/check_repo.ps1` 校验 manifest ↔ 源码 ↔ 库页 ↔ SBOM, 当前 **0 error / 0 warning**。 - **技能**:`hlca-third-party-libs`(独立仓库维护,不随本库分发)把选型、接入、登记、升级做成四模式流程, 与 `hlca-firmware-dev` 双向联动;自带 4 个检查脚本与 11 项自测。 - **演练证据**:littlefs + nanoMODBUS 的主机侧全链路(22 项断言,含坏 CRC、损坏 superblock 等异常路径)已跑通, 记录在技能仓库 `drills/`。 ### 7.2 已知缺口 - **无构建脚本**:本仓库只提供源码、manifest 与接入说明,没有根 CMakeLists。接入方按 manifest 的 `compile.must/optional` 把文件加进自己的构建。 - **未做编译验证**:这些库在本仓库内没有被逐个编译过;manifest 的编译单元来自库页与源码扫描, 目前只有 littlefs、nanomodbus 做过主机侧编译冒烟。首次接入必须自己编一次并回填结果。 - **manifest 的约束仍需人工复核**:`allocator`/`float`/`os` 来自 catalog 与库页,`<功能组>`、`(二选一)`、 条件行等写法已按规则归一,但语义(尤其 mbedtls/lwip/nimble 这类多条件库)仍要人确认后再用于选型。 - **无 CI**:检查脚本可在本地或 CI 里跑,但仓库尚未接流水线;建议把 `check_repo.ps1` 作为提交门。 - **MCUboot 是方案级**:源码树 vendor 完整度有限(`ext/` 下 mbedtls 子模块为空),不能当库链接,详见其库页。 - **CMSIS-DSP 缺 CMSIS-Core**:需要接入方工程提供 CMSIS-Core 的 `Include` 一级(至少 `cmsis_compiler.h`); 本库源码不引用 `core_cm*.h` 或厂商 device 头。 - **部分库需要改造才能进裸机**:Savitzky-Golay 的 API 是「创建/销毁 + 内部 malloc」(源码是 C11,C++17 只用于测试), ADRC 是参考实现级、无单测。每页的「集成检查清单」已列出前置条件。 - **`core` 裁剪的体积收益未逐库实测**:`core` 会去掉 tests/examples/demo 等,哪些库值得裁仍需按工程预算实测。