From 6510f10b26124d7ead39a3cbbe4daeeb4f39bc4d Mon Sep 17 00:00:00 2001 From: Lizongdi <1210855344@qq.com> Date: Thu, 11 Jun 2026 09:13:27 +0800 Subject: [PATCH] =?UTF-8?q?=E5=88=9D=E7=89=88=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 337 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 337 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..1329b1c --- /dev/null +++ b/README.md @@ -0,0 +1,337 @@ +# 32G431 嵌入式工程 — 代码架构与构建系统汇报 + +> **芯片平台**: STM32G431 (ARM Cortex-M4, 170MHz, FPU) +> **构建系统**: CMake + Ninja + GCC ARM 工具链 +> **代码来源**: STM32CubeMX 生成框架 + 自研业务模块 (git submodule) + +--- + +## 一、工程总体架构 + +``` +32g431/ ← 工程根目录 +├── CMakeLists.txt ← 顶层构建入口 +├── CMakePresets.json ← 预设构建配置（一键切换产品型号） +├── gcc-arm-none-eabi.cmake ← 交叉编译工具链定义 +├── STM32G431XX_FLASH.ld ← 链接脚本（Flash 布局） +├── startup_stm32g431xx.s ← 启动文件 +├── 32g431.ioc ← CubeMX 配置文件（可视化管脚/时钟配置） +│ +├── Core/ ← 【CubeMX 生成层】MCU 基础初始化 +│ ├── Src/ +│ │ ├── main.c ← 硬件入口：时钟 / 外设初始化 → 跳转业务代码 +│ │ ├── gpio.c / dma.c / usart.c / fdcan.c / tim.c / iwdg.c +│ │ ├── stm32g4xx_hal_msp.c ← HAL MSP 回调实现 +│ │ ├── stm32g4xx_it.c ← 中断服务函数 +│ │ └── syscalls.c / sysmem.c / system_stm32g4xx.c +│ └── Inc/ ← 对应头文件 + stm32g4xx_hal_conf.h +│ +├── Drivers/ ← 【芯片原厂层】ST 官方驱动 +│ ├── CMSIS/ ← ARM 标准 CMSIS 头文件 +│ └── STM32G4xx_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 分层关系图 + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ 应用层 (App Layer) │ +│ ┌──────────────┐ ┌──────────────┐ ┌───────────────────────┐ │ +│ │ Spoolend │ │ RBcore │ │ optional │ │ +│ │ 卷筒末端控制 │ │ 机器人核心 │ │ MK32 / TI5 电机驱动 │ │ +│ └──────┬───────┘ └──────┬───────┘ └───────────┬───────────┘ │ +└─────────┼──────────────────┼──────────────────────┼─────────────┘ + │ │ │ +┌─────────▼──────────────────▼──────────────────────▼─────────────┐ +│ BSP 层 (板级支持包) │ +│ ┌──────────────────────────────────────────────────────────┐ │ +│ │ bspMCU │ │ +│ │ bsp_uart / bsp_CAN / bsp_i2c / bsp_pin / bsp_cap / │ │ +│ │ bsp_usb / l_uart / l_can / stmflash / My_freeRTOS / │ │ +│ │ My_Lwip / My_print │ │ +│ └──────────────────────────────────────────────────────────┘ │ +└────────────────────────────────┬────────────────────────────────┘ + │ +┌────────────────────────────────▼────────────────────────────────┐ +│ 中间件层 (Middleware Layer) │ +│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌────────────────┐ │ +│ │ lua │ │ log │ │ list │ │ ringbuffer │ │ +│ │ 脚本引擎 │ │日志框架 │ │数据结构 │ │ 环形缓冲区 │ │ +│ └──────────┘ └──────────┘ └──────────┘ └────────────────┘ │ +│ ┌──────────────────────────────────────────────────────────┐ │ +│ │ common │ │ +│ │ 内存池 / 标准IO重定向 / 线程封装 / 时间工具 │ │ +│ └──────────────────────────────────────────────────────────┘ │ +│ ┌──────────────────────────────────────────────────────────┐ │ +│ │ peripheral │ │ +│ │ ATParser / button / led / com (通信协议) │ │ +│ └──────────────────────────────────────────────────────────┘ │ +└────────────────────────────────┬────────────────────────────────┘ + │ +┌────────────────────────────────▼────────────────────────────────┐ +│ HAL 层 (硬件抽象层) │ +│ ┌──────────────────────────────────────────────────────────┐ │ +│ │ STM32G4xx HAL Driver + LL Driver │ │ +│ │ GPIO / UART / FDCAN / TIM / DMA / IWDG / RCC / PWR ... │ │ +│ └──────────────────────────────────────────────────────────┘ │ +└────────────────────────────────┬────────────────────────────────┘ + │ +┌────────────────────────────────▼────────────────────────────────┐ +│ CMSIS 层 (ARM 标准层) │ +│ core_cm4.h / cmsis_gcc.h / mpu_armv7.h │ +└────────────────────────────────┬────────────────────────────────┘ + │ +┌────────────────────────────────▼────────────────────────────────┐ +│ 硬件 (STM32G431RB) │ +│ Cortex-M4 · 170MHz · 128KB Flash · 32KB SRAM │ +└─────────────────────────────────────────────────────────────────┘ +``` + +### 2.2 各层职责说明 + +| 层级 | 目录 | 职责 | 关键文件 | +|------|------|------|----------| +| **硬件层** | — | STM32G431 芯片 | — | +| **CMSIS 层** | `Drivers/CMSIS/` | ARM Cortex-M4 核心寄存器定义、中断向量、MPU 配置 | `core_cm4.h` | +| **HAL 层** | `Drivers/STM32G4xx_HAL_Driver/` | ST 官方外设驱动库，屏蔽寄存器差异 | `stm32g4xx_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 构建流程图 + +``` +CMakePresets.json gcc-arm-none-eabi.cmake + │ │ + │ 选择预设 (Spool-end / robot) │ 定义交叉编译工具链 + ▼ ▼ +┌────────────────────────────────────────────────────────────┐ +│ CMake Configure │ +│ cmake --preset Spool-end │ +│ │ +│ ① 读取预设 → 设置 BUILD_LUA=ON, BUILD_BSPMCU=ON ... │ +│ ② 加载 toolchain → arm-none-eabi-gcc / -mcpu=cortex-m4 │ +│ ③ 扫描 robot/ 子模块 → 按 option 启用对应模块 │ +│ ④ 生成编译宏 (BUILD_BSPMCU, BUILD_SPOOLEND ...) │ +│ ⑤ 生成链接依赖树 │ +└──────────────────────────┬─────────────────────────────────┘ + │ + ▼ +┌────────────────────────────────────────────────────────────┐ +│ Build (Ninja) │ +│ │ +│ 各模块编译为 .a 静态库： │ +│ libcommon.a libperipheral.a libbspMCU.a │ +│ liblua.a libSpoolend.a liblog.a │ +│ liblist.a libringbuffer.a libRBcore.a │ +│ │ +│ 最终链接 → 32g431.elf → 32g431.bin / 32g431.hex │ +└────────────────────────────────────────────────────────────┘ +``` + +### 3.2 模块化构建机制 + +工程在 `robot/CMakeLists.txt` 中定义了一套**声明式模块注册机制**： + +```cmake +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` 一行启用： + +```json +"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 子模块： + +```ini +[submodule "robot"] + path = robot + url = http://123.207.52.103:3000/LiZongdi/robot.git +``` + +| 优势 | 说明 | +|------|------| +| **代码复用** | robot 仓库可被多个硬件工程引用，**一处修改，多处受益** | +| **独立迭代** | robot 业务代码与 CubeMX 生成的硬件配置解耦，各自独立版本管理 | +| **版本锁定** | 主工程记录 robot 的具体 commit，确保**构建结果可复现** | + +--- + +## 六、从 CubeMX 到 CMake 的工作流 + +``` +┌─────────────────────┐ +│ STM32CubeMX (.ioc) │ ← 可视化配置管脚、时钟、外设、中断 +└──────────┬──────────┘ + │ 生成代码 + ▼ +┌─────────────────────┐ ┌──────────────────────┐ +│ Core/Src & Inc │ │ robot/ (submodule) │ +│ (CubeMX 生成) │ │ (手写业务代码) │ +└──────────┬──────────┘ └──────────┬───────────┘ + │ │ + │ ┌─────────────────┘ + ▼ ▼ +┌──────────────────────────────────────┐ +│ CMakeLists.txt │ +│ add_subdirectory(cmake/stm32cubemx)│ +│ add_subdirectory(robot) │ +│ target_link_libraries(...) │ +└──────────────────┬───────────────────┘ + │ + ▼ +┌──────────────────────────────────────┐ +│ 32g431.elf → .bin / .hex │ +│ 烧录到 STM32G431 │ +└──────────────────────────────────────┘ +``` + +> **CubeMX 负责硬件配置，CMake 负责构建编排，robot 子模块负责业务逻辑**——三者职责清晰，互不干扰。 + +--- + +## 七、总结 + +本工程采用 **四层架构 + 模块化构建** 的设计： + +1. **硬件层** (CMSIS + HAL) — ST 官方驱动，稳定可靠 +2. **BSP 层** (bspMCU) — 硬件抽象，向上提供统一接口 +3. **中间件层** (library + peripheral + lua) — 通用组件，跨平台复用 +4. **应用层** (Spoolend / RBcore / optional) — 产品业务逻辑 + +CMake 构建系统带来了以下工程化收益： +- **模块可插拔**：通过 preset 一键切换产品配置 +- **依赖显式化**：编译/链接错误减少，新人上手快 +- **跨平台复用**：同一份代码可编译固件和 PC 测试程序 +- **构建可复现**：submodule 版本锁定 + preset 参数固化 +