初版文档

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 参数固化
+