STM32 两轮自平衡小车 · 分层重构工程

一个从零重构的 STM32F103 两轮自平衡小车固件工程。目标不是"先让它跑起来"，而是"先让它可理解、可维护" —— 在架构清晰、接口明确、调试链路可观测的前提下，再进入整车闭环调参。

本项目为重构工程：不照搬旧版实现，只复用其硬件资源结论、串口协议思路与安全状态机设计。详见 docs/PROJECT_UNDERSTANDING.md。

---

目录结构

采用严格的分层设计，每一层只做一件事：

balance_car/
├── board/        板级资源装配、引脚 / 方向 / 句柄映射
├── drivers/      MCU 外设驱动封装（adc / pwm / encoder / soft_i2c / uart）
├── devices/      具体器件驱动（mpu6050 / tb6612）
├── modules/      整车功能模块（imu / motor / battery_monitor / safety）
├── control/      姿态估计、角度环、速度环
├── app/          状态机、调度、命令协议、遥测输出
├── docs/         架构说明、调试记录、变更记录（18 份文档）
└── Two_balance_car/  STM32CubeIDE 工程主体

分层依赖方向单向：board → drivers → devices → modules → control → app。

---

硬件规格

项目	规格
主控	STM32F103C8T6
控制节拍	TIM1 周期中断，5ms 基础调度
电机 PWM	TIM3 两路输出
编码器	TIM4 / TIM2 编码器模式
串口	USART1，115200 8N1，RX 使用中断 + 环形缓冲
IMU	MPU6050（软件 I2C）
电机驱动	TB6612
使能 / 急停	PA4 / PA5
电机方向脚	PB12 / PB13 / PB14 / PB15

完整硬件基线见 docs/HARDWARE_BASELINE.md，代码到接线的映射见 docs/WIRING_FROM_CODE.md。

---

当前状态

• ✅ IMU → attitude_estimator → angle_loop → VOFA/STATUS 链路已打通
• ✅ USART1 命令接收改为 RX 中断 + 环形缓冲
• ✅ pwm → tb6612 → motor 执行链已接入（默认不打开实际电机输出）
• ✅ 速度环接口已补齐（默认不开闭环）
• ✅ 电池电压采样与安全监控模块就位
• 🔧 正在收口 board 层、drv_uart 层与工程整理

安全设计：电机输出默认关断；具备明确的安全模式与故障位；所有输出经由安全状态机裁决。

---

控制结构

双环串级：

• 姿态外环 — 角度 PID，输出速度 / 力矩倾向
• 速度内环 — 速度 PI，结合前馈输出 PWM
• 驱动层 — PWM 限幅、斜坡、起转补偿、左右电机协调

详见 docs/ANGLE_LOOP_FROM_REFERENCE.md 与 docs/ATTITUDE_ESTIMATOR_VOFA.md。

---

串口命令协议

单字节命令，便于台架脚本控制：

命令	作用
A / E	ARM（使能控制）
D / S	DISARM（断开控制）
T	进入离线测试模式
+ / -	人工调整命令
K	KEEPALIVE
C	清除故障
? / Q	查询状态
Z	写入角度零偏

状态以可解析文本帧 STAT,... 上报，字段涵盖：安全模式、故障位、电池电压、左右 PWM、编码器增量、IMU 新鲜度 / 姿态 / 角速度、角度环阻塞原因、速度目标与测量值、固件签名。

这套"可控 + 可观测"的设计是自动化回归测试的基础，详见 docs/USART1_BRINGUP_PLAN.md。

---

文档索引

docs/ 下共 18 份文档，按用途分组：

架构与理解

• PROJECT_UNDERSTANDING.md — 重构工程的起点与约束
• ASSIGNMENT_ARCHITECTURE.md — 分层架构设计
• FILE_LAYOUT_PLAN.md — 文件布局规划
• HARDWARE_BASELINE.md — 冻结的硬件基线
• WIRING_FROM_CODE.md — 代码反推接线

开发与集成

• DEVELOPMENT_MANUAL.md — 开发手册（15 KB）
• APP_INTEGRATION.md — 应用层集成说明
• WORKFLOW.md — 工作流程
• DECISIONS.md — 关键决策记录

控制与调试

• ANGLE_LOOP_FROM_REFERENCE.md — 角度环实现
• ANGLE_LOOP_VOFA.md — 角度环 VOFA 波形
• ATTITUDE_ESTIMATOR_VOFA.md — 姿态估计波形
• MOTOR_EXECUTION_CHAIN.md — 电机执行链
• EXTERNAL_TUNING_REFERENCE.md — 外部调参参考（14 KB）
• DEBUG_LOG.md — 调试记录

过程记录

• CHANGELOG.md — 变更记录（22 KB）
• IMU_REFACTOR_AUDIT.md — IMU 重构审计
• USART1_BRINGUP_PLAN.md — 串口打通计划

---

参考工程

第一完成版参考工程仅作为硬件映射、调试思路和控制语义的参考，不直接照搬实现。

---

开发约定

• 每完成一块同步更新文档与 Git 提交
• 提交信息遵循规范前缀：feat: / fix: / refactor: / docs: / tune: / chore:
• 改动保持可解释、可维护
• 拒绝"先凑起来再说"的临时开发