Files
robinsonandClaude Opus 4.7 cf934cf6b7 [feat] UART command interface, per-motor control, filtering modules
- 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>
2026-05-21 01:38:11 +08:00

2.1 KiB
Raw Permalink Blame History

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)构建响应式收发框架。