- Add callback_task with ISR-based UART command parser (@command\n protocol) - Add log_printf with mutex protection to prevent printf interleaving - Add per-motor enable/disable (motor enable yaw|pitch) - Add PID tuning via UART (pid roll kp 15) - Add cmd_parser module (registration + tokenize + dispatch) - Add UART layer architecture (interface → HAL → BSP) - Add filter modules (lowpass, moving_average, notch, rate_limiter) - Rewrite I2C bus and UART bus modules - Rewrite PID controller and MF4010V2 motor driver - Fix soft I2C driver Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2.1 KiB
2.1 KiB
ADR-005: UART 分层架构设计
Status
Accepted
Context
项目需要统一的 UART 抽象层,支持打印调试、传感器通信和对外数据交互。目前 USART1 已由 CubeMX 配置 (115200-8N1,PA9/PA10),但缺少分层封装,应用代码直接调用 HAL_UART_Transmit 会破坏 6 层架构约束。
需求:
- 支持多种传输模式:阻塞(polling)、中断(IT)、DMA
- 通过 CAN/LED 相同的 Interface → HAL → BSP → Module 四层结构集成
- 不干扰 CubeMX 生成的 MX_USART1_UART_Init() 初始化流程
- 为未来多 UART 实例(如 USART2/USART3)预留扩展
Decision
采用与 CAN/LED/I2C 一致的 ops 回调注册模式实现 UART 分层架构:
Module (uart_t) → Interface (uart_if) → HAL (hal_uart) → BSP (bsp_uart)
操作集合覆盖:
- 基础:init, deinit
- 阻塞:send, receive(含 timeout)
- 中断:send_it, receive_it
- DMA:send_dma, receive_dma
- 控制:abort
- 单字节:putc, getc
Alternatives Considered
- 直接封装 HAL_UART_Transmit/Receive — 最简单,但破坏分层约束,且无法在 Module 层做状态管理。
- 使用 retarget-stdio / _write 钩子 + syscall — 只能覆盖 printf 场景,无法支持中断/DMA 接收。
- 通过 DMA + 环形缓冲区的完整驱动 — 功能更强,但增加复杂性,适合后续独立优化。
Consequences
- Positive: 与现有架构完全一致,贡献者无需学习新模式。
- Positive: 11 个 ops 覆盖大部分 UART 使用场景,且接口可组合使用(如 init + send + receive + deinit)。
- Positive: HAL 实现中通过
h->gState检测避免重复初始化,兼容 CubeMX 的 MX_USART1_UART_Init()。 - Negative: 当前只实现了 USART1 的 BSP,多实例需手工扩展 bsp_uart.c 数组。
- Negative: 未实现 DMA 完成回调的异步通知,DMA 函数为"即发即忘"式调用。
Trade-offs
异构传输模式支持 vs 实现复杂度:采用全 ops 声明但简化实现的策略。DMA/IT 函数透传 HAL 调用, 高层模块后续可围绕回调机制(HAL_UART_TxCpltCallback)构建响应式收发框架。