嵌入式工程 — 代码架构与构建系统汇报

芯片平台: STM32H743 (ARM Cortex-M7, 400MHz, FPU) 构建系统: CMake + Ninja + GCC ARM 工具链 代码来源: STM32CubeMX 生成框架 + 自研业务模块 (git submodule)

---

一、工程总体架构

robot_h743/                          ← 工程根目录
├── CMakeLists.txt               ← 顶层构建入口
├── CMakePresets.json            ← 预设构建配置（一键切换产品型号）
├── gcc-arm-none-eabi.cmake      ← 交叉编译工具链定义
├── STM32H743XG_FLASH.ld         ← 链接脚本（Flash 布局）
├── startup_stm32h743xx.s        ← 启动文件
├── robot_h743.ioc               ← CubeMX 配置文件（可视化管脚/时钟配置）
│
├── Core/                        ← 【CubeMX 生成层】MCU 基础初始化
│   ├── Src/
│   │   ├── main.c               ←   硬件入口：时钟 / 外设初始化 → 跳转业务代码
│   │   ├── gpio.c / dma.c / usart.c / fdcan.c / tim.c / iwdg.c
│   │   ├── stm32h7xx_hal_msp.c  ←   HAL MSP 回调实现
│   │   ├── stm32h7xx_it.c       ←   中断服务函数
│   │   └── syscalls.c / sysmem.c / system_stm32h7xx.c
│   └── Inc/                     ←   对应头文件 + stm32h7xx_hal_conf.h
│
├── Drivers/                     ← 【芯片原厂层】ST 官方驱动
│   ├── CMSIS/                   ←   ARM 标准 CMSIS 头文件
│   └── STM32H7xx_HAL_Driver/    ←   HAL + LL 驱动库（源码 + 头文件）
│
├── robot/                       ← 【自研业务层】⭐ 核心应用代码 (git submodule)
│   ├── main/                    ←   程序入口（支持编译为可执行文件或静态库）
│   ├── bspMCU/                  ←   板级支持包（硬件抽象）
│   ├── Spoolend/                ←   线轴端控制板业务逻辑
│   ├── RBcore/                  ←   机器人核心业务逻辑
│   ├── peripheral/              ←   外部外设驱动（传感器 / 通信模块）
│   ├── optional/                ←   可选电机/遥控器驱动（MK32 / TI5MOTOR）
│   ├── lua/                     ←   Lua 脚本引擎（运行时可配置）
│   └── library/                 ←   公共基础库
│       ├── common/              ←   内存池 / 标准IO / 线程封装 / 时间工具
│       ├── log/                 ←   EasyLogger 日志框架
│       ├── list/                ←   uthash 系列数据结构
│       └── ringbuffer/          ←   环形缓冲区
│
├── cmake/                       ← CMake 辅助脚本
└── build/                       ← 构建输出目录

---

二、分层架构详解

2.1 分层关系图

2.2 各层职责说明

层级	目录	职责	关键文件
硬件层	—	STM32H743 芯片	—
CMSIS 层	Drivers/CMSIS/	ARM Cortex-M7 核心寄存器定义、中断向量、MPU 配置	core_cm7.h
HAL 层	Drivers/STM32H7xx_HAL_Driver/	ST 官方外设驱动库，屏蔽寄存器差异	stm32h7xx_hal_*.c/h
CubeMX 生成层	Core/Src/ & Core/Inc/	由 STM32CubeMX 可视化工具自动生成，负责时钟树、GPIO、DMA、中断等基础初始化	main.c, gpio.c, usart.c, fdcan.c
中间件层	robot/library/	通用基础组件，与硬件无关，可跨平台复用	common/, log/, list/, ringbuffer/
中间件层	robot/peripheral/	外部传感器/模块驱动，通信协议封装	ATParser.c, com.c, button.c, led.c
中间件层	robot/lua/	Lua 5.x 脚本引擎，支持运行时动态配置控制逻辑	lua.c, lvm.c, lapi.c 等
BSP 层	robot/bspMCU/	板级支持包：CAN/UART/I2C/USB/CAP 驱动 + FreeRTOS/LwIP 集成 + Lua 绑定	bsp_CAN.c, bsp_uart.c, My_freeRTOS.c, l_can.c
应用层	robot/Spoolend/	线轴端控制业务逻辑：Modbus 通信、Flash 参数存储	Spoolend.c, modbus.c, flash_operation.c
应用层	robot/RBcore/	机器人核心控制：运动算法、驱动接口	BHBF_robot.c, drv_interface.c
应用层	robot/optional/	可选电机组件：MK32 电机 / TI5 电机驱动	msp_MK32.c, msp_TI5MOTOR.c

---

三、CMake 构建系统

3.1 构建流程图

3.2 模块化构建机制

工程在 robot/CMakeLists.txt 中定义了一套声明式模块注册机制：

add_module(common     library/common  ON  OFF)   # 默认启用
add_module(log        library/log     OFF OFF)   # 默认禁用
add_module(peripheral peripheral      OFF ON)    # 默认禁用，含测试
add_module(lua        lua             OFF ON)    # 默认禁用，含测试
add_module(bspMCU     bspMCU          OFF OFF)
add_module(Spoolend   Spoolend        OFF OFF)
add_module(RBcore     RBcore          OFF OFF)
add_module(optional   optional        OFF OFF)

通过 CMakePresets.json 中的 option 一行启用：

"cacheVariables": {
    "BUILD_LUA": "ON",
    "BUILD_BSPMCU": "ON",
    "BUILD_SPOOLEND": "ON",
    ...
}

优势：不同产品型号只需新建一个 preset，声明需要哪些模块，无需修改 CMakeLists.txt。

3.3 当前预设配置

预设名称	用途	启用模块
Spool-end	线轴端控制器产品	common + peripheral + lua + bspMCU + Spoolend + log + ringbuffer + list
robot	继承 Spool-end + 额外	再加 RBcore + optional + FreeRTOS + LwIP + TALNET

3.4 CMake 构建系统的核心优势

优势	说明
跨平台统一构建	同一套 CMakeLists 可编译裸机固件、Linux 主机测试程序、Windows DLL，无需维护多套 Makefile
子模块独立构建	每个子模块自带 CMakeLists.txt，既可被顶层工程引用，也可独立编译调试（Standalone 模式）
条件编译自动化	通过 option() + cacheVariables，一个 preset 定义一组产品配置，编译宏自动生成，减少 #ifdef 手工维护
依赖关系显式化	target_link_libraries() 明确声明模块间依赖，CMake 自动推导编译顺序，避免"头文件找不到"和"链接顺序错误"
编译命令导出	CMAKE_EXPORT_COMPILE_COMMANDS=ON 生成 compile_commands.json，IDE/clangd 可直接索引，代码跳转/补全精确
预设配置 (Presets)	CMakePresets.json 将构建参数集中管理，新人只需 cmake --preset robot 即可一键配置，零学习成本上手
工具链抽象	gcc-arm-none-eabi.cmake 集中定义编译器标志、链接脚本、CPU 参数，切换芯片只需改一处
构建产物隔离	out-of-source build（build/ 目录），源码树干净，多配置并行构建不冲突

---

四、关键模块详细说明

4.1 bspMCU — 板级支持包

bspMCU 是硬件与业务逻辑之间的桥梁，提供统一的硬件操作接口：

robot/bspMCU/
├── bsp_uart.c      ← UART 驱动（含 DMA + 中断收发）
├── bsp_CAN.c       ← FDCAN 驱动（基于 HAL FDCAN）
├── bsp_i2c.c       ← I2C 总线驱动
├── bsp_pin.c       ← GPIO 引脚封装
├── bsp_cap.c       ← 电容检测
├── bsp_usb.c       ← USB 驱动
├── l_uart.c        ← UART Lua 绑定
├── l_can.c         ← CAN Lua 绑定
├── l_stm32.c       ← STM32 通用 Lua 绑定
├── My_freeRTOS.c   ← FreeRTOS 集成
├── My_Lwip.c       ← LwIP 网络协议栈集成
├── My_print.c      ← 打印输出重定向
└── stmflash.c      ← Flash 读写操作

依赖链：bspMCU → peripheral → list → ringbuffer → stm32cubemx

4.2 Spoolend — 线轴控制板业务

robot/Spoolend/
├── Spoolend.c          ← 主业务逻辑（初始化 + 任务循环）
├── modbus.c            ← Modbus 协议栈实现
├── flash_operation.c   ← Flash 参数存储/读取
└── include/
    ├── modbus.h
    └── flash_operation.h

依赖链：Spoolend → bspMCU → ...

4.3 Lua 脚本引擎

将 Lua 5.x 源码完整纳入工程，通过 l_uart.c / l_can.c 等绑定，实现用 Lua 脚本控制硬件：

• 串口操作 → l_uart.c
• CAN 通信 → l_can.c
• STM32 通用操作 → l_stm32.c

这使得控制逻辑可以通过脚本动态修改，无需重新烧录固件。

4.4 公共基础库 (library)

子模块	功能	依赖
common	内存池 (rd_mempool)、标准 IO 重定向 (rd_stdio)、线程封装 (rd_thread)、时间工具 (rd_time)	—
log	EasyLogger 轻量级日志框架（支持分级、异步、Flash 存储）	common
list	uthash 系列宏：uthash.h utlist.h utarray.h utstring.h 等	—
ringbuffer	通用环形缓冲区实现	—

---

五、Git Submodule 管理

robot/ 目录是一个独立的 git 子模块：

[submodule "robot"]
    path = robot
    url = http://123.207.52.103:3000/LiZongdi/robot.git

优势	说明
代码复用	robot 仓库可被多个硬件工程引用，一处修改，多处受益
独立迭代	robot 业务代码与 CubeMX 生成的硬件配置解耦，各自独立版本管理
版本锁定	主工程记录 robot 的具体 commit，确保构建结果可复现

---

六、从 CubeMX 到 CMake 的工作流

CubeMX 负责硬件配置，CMake 负责构建编排，robot 子模块负责业务逻辑——三者职责清晰，互不干扰。

---

七、总结

本工程采用 四层架构 + 模块化构建 的设计：

1. 硬件层 (CMSIS + HAL) — ST 官方驱动，稳定可靠
2. BSP 层 (bspMCU) — 硬件抽象，向上提供统一接口
3. 中间件层 (library + peripheral + lua) — 通用组件，跨平台复用
4. 应用层 (Spoolend / RBcore / optional) — 产品业务逻辑

CMake 构建系统带来了以下工程化收益：

• 模块可插拔：通过 preset 一键切换产品配置
• 依赖显式化：编译/链接错误减少，新人上手快
• 跨平台复用：同一份代码可编译固件和 PC 测试程序
• 构建可复现：submodule 版本锁定 + preset 参数固化