MCU 嵌入式固件代码审查

技能文档

---
name: majiayu000-mcu-embedded-review
title: MCU 嵌入式固件代码审查
category: 开发工具
description: 审查 RP2350（Raspberry Pi Pico 2 W）与 ESP32-S3（Heltec）微控制器的嵌入式 Rust 固件代码，重点关注 Embassy 异步运行时、静态/堆内存约束、WS2812 LED 控制、CAN 附件协议与 SLCAN 桥接。当用户审查 MCU 固件改动、排查 LED 控制器问题、评估 Embassy 异步模式、检查静态内存分配、验证 SLCAN 实现，或评审 WS2812 LED、CAN 外设等硬件相关代码时触发。触发词：固件审查、嵌入式代码评审、Embassy、no_std、SLCAN、MCU 固件。
---

# MCU 嵌入式固件代码审查

本技能面向 RP2350 与 ESP32-S3 两类微控制器的嵌入式 Rust 固件，提供系统化的代码审查指导。

## 概述

两类 MCU 平台分别承担外设控制职责：

1. **RP2350（Pico 2 W）**：LED 控制器、USB 外设
2. **ESP32-S3（Heltec）**：工具附件、LoRa 通信、OLED 显示

二者均运行 Rust `no_std` 环境，但运行时与内存约束不同。

**目录结构示例：**
```
mcu/
├── bins/
│   ├── rp2350/         # Pico 2 W 固件（LED 控制器等）
│   │   └── src/main.rs
│   └── esp32s3/        # Heltec 固件（附件、SLCAN）
│       └── src/main.rs
├── crates/
│   ├── mcu-core/       # 共享协议与类型
│   ├── mcu-leds/       # LED 控制库
│   └── ...
```

**平台关键差异：**

| 特性           | RP2350 (Pico 2 W)                | ESP32-S3 (Heltec)              |
|----------------|----------------------------------|--------------------------------|
| **运行时**     | Embassy 异步（`#[embassy_executor::main]`） | 轮询循环（`#[main]`）       |
| **内存**       | 520 KB SRAM，静态分配            | 512 KB SRAM，堆分配            |
| **Rust 版本**  | 2021                             | 2024                           |
| **LED 控制**   | PIO 状态机（WS2812）             | RMT 外设（WS2811/WS2812）      |
| **USB**        | USB CDC 串口（设备模式）         | USB 串口（经 UART 桥接）       |
| **显示**       | 无                               | OLED SSD1306（I2C）            |
| **无线**       | WiFi（Pico W 芯片）              | WiFi、BLE、LoRa                |
| **CAN**        | 外置 MCP2515（SPI）              | 内置 TWAI（CAN 2.0）           |

## 技能工作流

### 步骤1：确认目标平台与运行时模式

审查前先确认代码针对哪个平台：

- RP2350 使用 Embassy 异步运行时，入口为 `#[embassy_executor::main]`
- ESP32-S3 使用阻塞式轮询循环，入口为 `#[main]`

在 ESP32-S3 上使用 async/await、在 RP2350 上使用堆分配都是典型错误，需优先排查。

### 步骤2：审查 RP2350 Embassy 异步模式

检查要点：

- [ ] main 函数标注 `#[embassy_executor::main]`
- [ ] 异步 main 签名：`async fn main(spawner: Spawner)`
- [ ] 任务通过 `spawner.spawn(task_name()).unwrap()` 启动
- [ ] 所有外设在启动任务前完成初始化
- [ ] 中断绑定使用 `bind_interrupts!` 宏

参考示例：

```rust
// Good: Embassy async main
#[embassy_executor::main]
async fn main(spawner: Spawner) {
    // 1. Initialize peripherals
    let p = embassy_rp::init(Default::default());

    // 2. Bind interrupts
    bind_interrupts!(struct Irqs {
        USBCTRL_IRQ => InterruptHandler<USB>;
    });

    // 3. Create drivers
    let driver = Driver::new(p.USB, Irqs);

    // 4. Spawn tasks
    spawner.spawn(usb_task(driver)).unwrap();
    spawner.spawn(led_controller_task(p.PIO0)).unwrap();

    // 5. Main loop (or empty if all work in tasks)
    loop {
        Timer::after_millis(1000).await;
    }
}
```

危险信号：

- 异步上下文中出现阻塞调用（`std::thread::sleep`）
- 异步操作缺少 `.await`
- spawn 错误未处理（直接 unwrap 应视为需确认）
- 外设所有权未移入任务

 Embassy 任务检查要点：

- [ ] 任务函数标注 `#[embassy_executor::task]`
- [ ] 函数为 async 签名
- [ ] 含无限循环或显式返回
- [ ] 错误处理合理（记录错误，不 panic）

```rust
// Good: Embassy task
#[embassy_executor::task]
async fn led_controller_task(mut pio: PIO0) {
    loop {
        // Wait for command
        let cmd = LED_COMMAND_CHANNEL.receive().await;

        // Update LEDs
        match update_leds(&mut pio, cmd) {
            Ok(_) => {}
            Err(e) => error!("LED update failed: {:?}", e),
        }
    }
}
```

详细模式见 [rp2350-patterns.md](references/rp2350-patterns.md)。

### 步骤3：审查 RP2350 静态内存分配

RP2350 无堆分配器，所有内存必须静态化。

检查要点：

- [ ] 可变静态数据使用 `StaticCell`
- [ ] 全局静态用 `static` + `StaticCell` 包装
- [ ] 不使用 `Box`、`Vec`、`String` 等堆类型
- [ ] 数组使用固定尺寸

静态通道与 USB 缓冲分配示例见 [code-examples.md](references/code-examples.md)。

危险信号：堆类型、缺少 `StaticCell` 包装、无界缓冲（应使用定长数组）。

### 步骤4：审查 PIO 驱动 WS2812 LED（RP2350）

可编程 I/O 状态机生成 WS2812 协议所需的精确时序。

检查要点：

- [ ] PIO 程序通过 `pio.load_program()` 加载
- [ ] 状态机时钟分频配置正确
- [ ] 数据传输使用 DMA
- [ ] 颜色数据为 GRB 格式（不是 RGB）

WS2812 协议时序：

- **Bit 0**：高电平 400ns，低电平 850ns
- **Bit 1**：高电平 800ns，低电平 450ns
- **复位**：低电平 >50µs

PIO 初始化与颜色发送示例见 [rp2350-patterns.md](references/rp2350-patterns.md)。

危险信号：RGB 字节序（WS2812 应为 GRB）、时钟分频错误（破坏时序）、阻塞写（应使用 DMA + await）、缺少复位延时（>50µs）。

USB CDC 串口（用于调试与 SLCAN 桥接）检查要点：`Driver::new()` 创建驱动、实例化 CDC-ACM 类、读写方法使用 await、处理线路编码（波特率等）。

### 步骤5：审查 ESP32-S3 轮询循环模式

位置：`mcu/bins/esp32s3/src/main.rs`

检查要点：

- [ ] 入口为 `#[main]`（而非 `#[embassy_executor::main]`）
- [ ] 无限循环中做非阻塞检查
- [ ] 使用 `delay.delay_millis()` 控制节奏
- [ ] UART 读取前先检查 `read_ready()`

```rust
// Good: Polling loop
#[main]
fn main() -> ! {
    // 1. Initialize peripherals
    let peripherals = Peripherals::take();
    let mut delay = Delay::new();

    // 2. Initialize UART
    let mut uart = Uart::new(peripherals.UART0, /* ... */);

    // 3. Main loop
    loop {
        // Non-blocking UART read
        if uart.read_ready() {
            let mut buf = [0u8; 64];
            if let Ok(n) = uart.read(&mut buf) {
                process_command(&buf[..n]);
            }
        }

        // Update LEDs
        update_leds();

        // Small delay (don't busy-wait)
        delay.delay_millis(1);
    }
}
```

危险信号：阻塞读（未先检查 `read_ready()`）、忙等循环（无延时）、误用 async/await。

详细模式见 [esp32s3-patterns.md](references/esp32s3-patterns.md)。

### 步骤6：审查 ESP32-S3 堆分配（esp-alloc）

ESP32-S3 有堆分配器，允许 `Vec`、`String` 等，但仍应节约使用。

检查要点：

- [ ] main 中调用 `esp_alloc::heap_allocator!()`
- [ ] 堆类型使用克制（仍是嵌入式环境）
- [ ] 关键路径优先使用定长缓冲
- [ ] 无无界增长（内存泄漏）

示例：main 开头调用 `esp_alloc::heap_allocator!()`，随后可预分配 `Vec::with_capacity(256)` 并复用缓冲。

最佳实践：堆用于初始化和低频操作，不要在热循环中分配。

### 步骤7：审查 RMT 驱动 LED 与 OLED 显示（ESP32-S3）

RMT（Remote Control Transceiver）生成精确脉冲序列驱动 WS2811/WS2812。

检查要点：

- [ ] RMT 通道时钟配置正确
- [ ] 脉冲序列匹配 WS2812 时序
- [ ] 使用阻塞发送或中断驱动
- [ ] 注意内存限制（8 个 RMT 通道，每通道 64 项）

RMT 通道初始化与逐位发送示例见 [esp32s3-patterns.md](references/esp32s3-patterns.md)。

危险信号：RGB 字节序、时序计算错误、RMT 缓冲溢出（>64 项）。

OLED 显示（SSD1306，状态显示用）检查要点：I2C 频率正确、驱动初始化、启动时清屏、刷新频率不宜过高（I2C 较慢）。

初始化示例见 [code-examples.md](references/code-examples.md)。

### 步骤8：审查 LED 控制器库与动画系统

位置：`mcu/crates/mcu-leds/src/lib.rs`

LED 模式状态机检查要点：

- [ ] `LedMode` 枚举包含所有模式（Off、Solid、Pulse、Chase、Flash）
- [ ] 状态机根据 CAN 消息切换模式
- [ ] 使用擦除动画实现平滑过渡
- [ ] 提供机器人状态便捷方法（`idle()`、`teleop()` 等）

LED 模式说明：

- `Off`：全部熄灭
- `Solid(r, g, b, brightness)`：固定颜色
- `Pulse(r, g, b, period_ms)`：呼吸效果（正弦波）
- `Flash(r, g, b, period_ms)`：开关频闪
- `Chase(r, g, b, speed)`：流动效果

机器人状态便捷方法示例见 [code-examples.md](references/code-examples.md)。

检查要点补充：

- [ ] 急停频闪足够快（200ms）以保证醒目
- [ ] 呼吸周期合理（1-3 秒）
- [ ] 亮度钳制在 [0, 255]
- [ ] 颜色值钳制在 [0, 255]

动画系统检查要点：擦除过渡带软边（渐变混合）、呼吸用正弦波（平滑，示例见 [code-examples.md](references/code-examples.md)）、Chase 循环回绕、帧率稳定（30-60 Hz）。

### 步骤9：审查 CAN 附件协议

位置：`mcu/crates/mcu-core/src/protocol.rs`

**CAN ID 范围**：0x200-0x2FF（16 个附件槽位，每个偏移 0x10）

**每附件 8 类消息**：

- `+0x00`：心跳（A → H，周期信标）
- `+0x01`：识别请求（H → A，查询身份）
- `+0x02`：识别响应（A → H，设备信息）
- `+0x03`：命令（H → A，控制附件）
- `+0x04`：应答（A → H，命令 ACK）
- `+0x05`：传感器数据（A → H，周期上报）
- `+0x06`：配置（H → A，设置参数）
- `+0x07`：错误报告（A → H，故障指示）

**示例**：附件 0（基址 0x200）：心跳 0x200、命令 0x203、传感器 0x205。

检查要点：

- [ ] CAN ID 按 `BASE + SLOT * 0x10 + OFFSET` 计算
- [ ] 使用扩展 CAN ID（29 位）
- [ ] 心跳频率 1 Hz
- [ ] 命令在 100ms 内应答

### 步骤10：审查 SLCAN 协议实现

SLCAN（Serial Line CAN）用于经 USB 调试 CAN 总线。位置：`mcu/bins/esp32s3/src/slcan.rs`

帧格式：

```
t<ID><LEN><DATA>\r   （标准帧）
T<ID><LEN><DATA>\r   （扩展帧）
```

示例：

```
T00000B0010A\r       # Extended ID 0x0B00, length 1, data 0x0A
t10348AABBCCDD\r     # Standard ID 0x103, length 4, data 0xAABBCCDD
```

命令表：

| 命令    | 说明                 | 响应        |
|---------|----------------------|-------------|
| `O\r`   | 打开 CAN 总线        | `\r`（OK）  |
| `C\r`   | 关闭 CAN 总线        | `\r`        |
| `S4\r`  | 设置波特率 500kbps   | `\r`        |
| `V\r`   | 获取版本             | `V1234\r`   |
| `N\r`   | 获取序列号           | `NABCD\r`   |

检查要点：

- [ ] 帧解析校验 ID 长度（3 或 8 个十六进制字符）
- [ ] 数据长度校验（0-8 字节）
- [ ] 非法命令返回错误（如 `\x07`）
- [ ] 每条消息以回车符（`\r`）结尾

解析示例与完整实现参考见 [code-examples.md](references/code-examples.md) 与 [esp32s3-patterns.md](references/esp32s3-patterns.md)。

### 步骤11：核查内存约束

**RP2350（Pico 2 W）**

- SRAM 共 520 KB：栈约 16 KB、静态数据约 50 KB（USB 缓冲、通道等）、可用约 450 KB
- Flash 4 MB：程序约 100 KB，数据空间充裕

检查要点：

- [ ] 栈大小合理（<16 KB）
- [ ] 栈上无大数组（改用静态）
- [ ] 可变静态数据使用 StaticCell
- [ ] 无无界递归

**ESP32-S3（Heltec）**

- SRAM 共 512 KB：堆约 400 KB（可配置）、每任务栈约 8 KB、DMA 约 50 KB
- Flash 8 MB：程序约 500 KB、SPIFFS/LittleFS 约 7 MB

检查要点：

- [ ] 堆分配有追踪（无泄漏）
- [ ] 大缓冲只分配一次（不在循环内重复分配）
- [ ] 每任务栈大小合理

### 步骤12：审查嵌入式测试代码

单元测试（no_std）检查要点：

- [ ] 使用 `#[cfg(test)]` 模块
- [ ] 测试函数带 `#[test]` 属性
- [ ] 用 trait 模拟硬件
- [ ] 测试中不引入 `std`

单元测试示例见 [code-examples.md](references/code-examples.md)。

集成测试（上板）常用 `defmt` 日志与 probe-rs 调试：

```bash
# Flash and run with logging
cargo run --release
# or
probe-rs run --chip RP2350
```

### 步骤13：对照常见错误清单复核

核对以下高频错误（完整代码对照见 [code-examples.md](references/code-examples.md)）：

- ESP32-S3 上误用 Embassy/async（应使用 `#[main]` 阻塞入口）
- RP2350 上使用堆类型 `Vec`/`String`/`Box`（无 alloc，无法编译）
- WS2812 颜色误用 RGB 字节序（应为 GRB）

### 步骤14：构建与烧录验证

审查后可用以下命令构建验证：

```bash
# Build RP2350
cd mcu
cargo build --release -p rover-leds

# Build ESP32-S3
cd mcu/bins/esp32s3
cargo build --release

# Flash RP2350 (requires picotool)
picotool load target/thumbv8m.main-none-eabihf/release/rover-leds -t elf -f

# Flash ESP32-S3 (requires espflash)
espflash flash --monitor target/xtensa-esp32s3-none-elf/release/heltec-attachment
```

## 参考资料

- [rp2350-patterns.md](references/rp2350-patterns.md) — Embassy 异步、StaticCell、PIO 用法详解
- [esp32s3-patterns.md](references/esp32s3-patterns.md) — 轮询循环、RMT、esp-alloc、SLCAN 详解

使用说明

# MCU 嵌入式固件代码审查

面向 RP2350（Pico 2 W）与 ESP32-S3（Heltec）的嵌入式 Rust 固件审查技能，覆盖 Embassy 异步、内存约束、LED 控制、CAN 协议与 SLCAN 桥接。

## 使用

对固件仓库发起审查时，引用本技能并指定平台与关注点即可：

```
请用 mcu-embedded-review 审查 mcu/bins/rp2350 的 LED 控制器改动，
重点检查 Embassy 任务与静态内存分配。
```

## 工作原理

技能按 14 步工作流逐层走查：确认平台运行时模式 → 审查 Embassy 异步 / 轮询循环 → 核查静态/堆内存分配 → 检查 PIO/RMT LED 驱动时序 → 审查 CAN 附件协议与 SLCAN 解析 → 核对内存约束 → 检查测试代码 → 对照常见错误清单 → 构建验证。详细平台模式查阅 references/ 下的参考文档。

如何安装此技能？

访问技能市场，点击「安装」按钮，按提示将技能包放入 AI 编程助手的 skills 目录即可。