MCU嵌入式固件审查

技能文档

---
name: majiayu000-mcu-embedded-review
title: MCU嵌入式固件审查
category: 开发工具
description: 审查RP2350和ESP32-S3微控制器的嵌入式Rust固件，聚焦Embassy异步运行时、内存约束、LED控制、CAN附件协议和SLCAN桥接。当用户审查MCU固件变更、调试LED控制器问题、评估Embassy异步模式、检查静态内存分配或验证SLCAN实现时触发。
---

# MCU嵌入式固件代码审查技能

本技能为BVR漫游车系统中RP2350和ESP32-S3微控制器的嵌入式Rust固件提供全面的代码审查。

## 概述

BVR使用两个MCU平台进行外设控制：
1. **RP2350 (Pico 2 W)**：LED控制器、USB外设
2. **ESP32-S3 (Heltec)**：工具附件、LoRa通信、OLED显示屏

两者均在 `no_std` 环境中运行Rust，具有硬件特定的运行时和内存约束。

**架构：**
```
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 | Rust 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) |

## RP2350 (Pico 2 W) 模式

### Embassy异步运行时

**位置**：`mcu/bins/rp2350/src/main.rs`

**审查要点：**
- [ ] 主函数使用 `#[embassy_executor::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`
- 直接unwrap spawner（应处理spawn错误）
- 外设未移入任务（所有权违规）

### Embassy任务

**审查要点：**
- [ ] 任务函数使用 `#[embassy_executor::task]` 标记
- [ ] 异步函数签名
- [ ] 无限循环或显式返回
- [ ] 错误处理（记录错误，不要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没有堆分配器，所有内存必须是静态的。

**审查要点：**
- [ ] 使用 `StaticCell` 包装静态可变数据
- [ ] 全局静态变量使用 `static` 和 `StaticCell` 封装
- [ ] 不使用 `Box`、`Vec`、`String`（堆类型）
- [ ] 数组使用固定大小

**示例模式：**
```rust
use embassy_sync::blocking_mutex::raw::CriticalSectionRawMutex;
use embassy_sync::channel::{Channel, Sender, Receiver};
use static_cell::StaticCell;

// Good: Static channel for inter-task communication
static LED_CHANNEL: StaticCell<Channel<CriticalSectionRawMutex, LedCommand, 8>> = StaticCell::new();

fn init_channel() -> &'static Channel<CriticalSectionRawMutex, LedCommand, 8> {
    LED_CHANNEL.init(Channel::new())
}

// Good: Static USB buffers
static EP_MEMORY: StaticCell<[u8; 1024]> = StaticCell::new();
static CONFIG_DESC: StaticCell<[u8; 256]> = StaticCell::new();

// Bad: Heap allocation (won't compile in no_std without alloc)
// let vec = vec![1, 2, 3];  // ❌ No Vec
// let string = String::from("hello");  // ❌ No String
```

**危险信号：**
- 堆类型（`Vec`、`String`、`Box`）
- 静态可变数据缺少 `StaticCell` 包装
- 无界缓冲区（应使用固定大小数组）

### PIO驱动WS2812 LED

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

**审查要点：**
- [ ] PIO程序通过 `pio.load_program()` 加载
- [ ] 状态机配置了正确的频率
- [ ] 使用DMA进行高效数据传输
- [ ] 颜色数据使用GRB格式（非RGB）

**WS2812协议**：
- **位0**：400ns高电平，850ns低电平
- **位1**：800ns高电平，450ns低电平
- **复位**：>50us低电平

**示例模式：**
```rust
// Good: PIO-based WS2812 driver
use embassy_rp::pio::{Pio, Common, StateMachine};

async fn init_ws2812(pio: PIO0, pin: PIN_25) -> Ws2812<'static> {
    let Pio { mut common, sm0, .. } = Pio::new(pio);

    // Load PIO program (bit-bangs WS2812 protocol)
    let prg = pio_proc::pio_asm!(
        ".side_set 1 opt",
        ".wrap_target",
        "bitloop:",
        "  out x, 1       side 0 [1]",  // Shift out 1 bit
        "  jmp !x do_zero side 1 [2]",  // High if bit 1
        "do_one:",
        "  jmp bitloop    side 1 [4]",  // Stay high (800ns)
        "do_zero:",
        "  nop            side 0 [4]",  // Go low (400ns)
        ".wrap"
    );

    let program = common.load_program(&prg.program);

    // Configure state machine
    let mut cfg = Config::default();
    cfg.set_out_pins(&[&pin]);
    cfg.set_clock_divider(125);  // 800kHz for WS2812 timing

    let ws2812 = Ws2812::new(sm0, pin, program, cfg);
    ws2812
}

// Send color data (GRB format!)
async fn set_led_color(ws2812: &mut Ws2812<'_>, index: usize, r: u8, g: u8, b: u8) {
    let color = ((g as u32) << 16) | ((r as u32) << 8) | (b as u32);  // GRB
    ws2812.write(&[color]).await;
}
```

**危险信号：**
- RGB字节序（WS2812应为GRB）
- 时钟分频器不正确（会破坏时序）
- 阻塞写入（应使用DMA + await）
- 缺少复位延时（>50us）

### USB CDC串口

**用途**：用于调试和SLCAN桥接的USB串口通信。

**审查要点：**
- [ ] 使用 `Driver::new()` 创建USB驱动
- [ ] CDC-ACM类实例化正确
- [ ] 读写方法正确使用await
- [ ] 线路编码处理（波特率等）

**示例模式：**
```rust
use embassy_usb::class::cdc_acm::{CdcAcmClass, State};

#[embassy_executor::task]
async fn usb_task(driver: Driver<'static, USB>) {
    let mut config = embassy_usb::Config::new(0x1234, 0x5678);
    config.manufacturer = Some("Muni Robotics");
    config.product = Some("BVR LED Controller");

    let mut builder = Builder::new(driver, config, /* ... */);

    // Create CDC-ACM class
    let mut state = State::new();
    let mut cdc = CdcAcmClass::new(&mut builder, &mut state, 64);

    let usb = builder.build();

    loop {
        // Read from USB
        let mut buf = [0u8; 64];
        let n = cdc.read_packet(&mut buf).await.unwrap();

        // Echo back (for testing)
        cdc.write_packet(&buf[..n]).await.unwrap();
    }
}
```

## ESP32-S3 (Heltec) 模式

### 轮询循环（非异步）

**位置**：`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()` 就调用 `uart.read()`）
- 忙等待循环（无延时）
- 使用async/await语法（ESP32使用阻塞模式）

### 堆分配 (esp-alloc)

**用途**：ESP32-S3具有堆分配器，允许使用 `Vec`、`String` 等类型。

**审查要点：**
- [ ] 主函数中调用 `esp_alloc::heap_allocator!()`
- [ ] 堆类型谨慎使用（仍是嵌入式环境）
- [ ] 关键路径优先使用固定大小缓冲区
- [ ] 无无界增长（内存泄漏）

**示例模式：**
```rust
use esp_alloc as _;

#[main]
fn main() -> ! {
    // Initialize heap allocator
    esp_alloc::heap_allocator!();

    // Now can use heap types (use sparingly!)
    let mut buffer = Vec::with_capacity(256);  // Pre-allocate

    loop {
        // Heap allocation okay for non-critical paths
        let message = String::from("Status: OK");
        send_message(&message);

        buffer.clear();  // Reuse buffer (don't re-allocate)
    }
}
```

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

### RMT驱动WS2811/WS2812 LED 与 OLED显示屏

RMT外设用于驱动WS2811/WS2812 LED，OLED SSD1306通过I2C驱动显示屏。详细模式、审查要点和代码示例见 [references/esp32s3-details.md](references/esp32s3-details.md)。

## LED控制器库

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

### LED模式状态机

**用途**：管理LED模式以指示漫游车状态。

**审查要点：**
- [ ] `LedMode` 枚举包含所有模式（Off、Solid、Pulse、Chase、Flash）
- [ ] 状态机根据CAN消息更新模式
- [ ] 平滑过渡带擦除动画
- [ ] 提供漫游车状态的便捷方法（`idle()`、`teleop()` 等）

**LED模式：**
- `Off`：所有LED关闭
- `Solid(r, g, b, brightness)`：固定颜色
- `Pulse(r, g, b, period_ms)`：呼吸效果（正弦波）
- `Flash(r, g, b, period_ms)`：开/关频闪
- `Chase(r, g, b, speed)`：流动图案

**漫游车状态便捷方法：**
```rust
impl LedMode {
    pub fn idle() -> Self {
        Self::Solid(0, 0, 255, 200)  // Blue solid
    }

    pub fn teleop() -> Self {
        Self::Pulse(0, 255, 0, 2000)  // Green pulse, 2s period
    }

    pub fn autonomous() -> Self {
        Self::Pulse(0, 255, 255, 1500)  // Cyan pulse, 1.5s period
    }

    pub fn estop() -> Self {
        Self::Flash(255, 0, 0, 200)  // Red flash, 200ms (urgent!)
    }

    pub fn fault() -> Self {
        Self::Flash(255, 165, 0, 500)  // Orange flash, 500ms
    }
}
```

**审查要点：**
- [ ] 紧急停止频闪速度快（200ms）以确保最大可见性
- [ ] 脉冲周期合理（1-3秒）
- [ ] 亮度限制在 [0, 255]
- [ ] 颜色值限制在 [0, 255]

### 动画系统

动画系统提供平滑过渡和特效（擦除过渡、正弦波脉冲、追逐效果）。详细审查要点和代码示例见 [references/memory-and-testing.md](references/memory-and-testing.md)。

## CAN附件协议

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

### ID方案

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

**每个附件的消息**（每个附件8种消息类型）：
- `+0x00`：心跳（附件 -> 主机，周期性信标）
- `+0x01`：识别请求（主机 -> 附件，查询身份）
- `+0x02`：身份响应（附件 -> 主机，设备信息）
- `+0x03`：命令（主机 -> 附件，控制附件）
- `+0x04`：确认（附件 -> 主机，命令ACK）
- `+0x05`：传感器数据（附件 -> 主机，周期读数）
- `+0x06`：配置（主机 -> 附件，设置参数）
- `+0x07`：错误报告（附件 -> 主机，故障指示）

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

**审查要点：**
- [ ] CAN ID按 `BASE + SLOT * 0x10 + OFFSET` 计算
- [ ] 使用扩展CAN ID（29位）
- [ ] 心跳以1 Hz频率发送
- [ ] 命令在100ms内确认

## SLCAN协议

**用途**：串行CAN桥接，通过USB进行调试。

**位置**：`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`（成功） |
| `C\r` | 关闭CAN总线 | `\r` |
| `S4\r` | 设置比特率为500kbps | `\r` |
| `V\r` | 获取版本 | `V1234\r` |
| `N\r` | 获取序列号 | `NABCD\r` |

**审查要点：**
- [ ] 帧解析验证ID长度（3或8个十六进制数字）
- [ ] 数据长度检查（0-8字节）
- [ ] 无效命令返回错误（如 `\x07`）
- [ ] 回车符（`\r`）终止每条消息

**示例模式：**
```rust
// Good: SLCAN command parsing
fn parse_slcan(cmd: &[u8]) -> Result<SlcanCommand, SlcanError> {
    if cmd.is_empty() || cmd[cmd.len() - 1] != b'\r' {
        return Err(SlcanError::MissingCR);
    }

    match cmd[0] {
        b'O' => Ok(SlcanCommand::Open),
        b'C' => Ok(SlcanCommand::Close),
        b'S' => {
            // Parse bitrate (S0-S8)
            let rate = cmd[1] - b'0';
            if rate > 8 {
                return Err(SlcanError::InvalidBitrate);
            }
            Ok(SlcanCommand::SetBitrate(rate))
        }
        b't' => parse_standard_frame(&cmd[1..]),
        b'T' => parse_extended_frame(&cmd[1..]),
        _ => Err(SlcanError::UnknownCommand),
    }
}
```

## 内存约束与测试

RP2350（520KB SRAM，无堆分配器）和ESP32-S3（512KB SRAM，堆分配）的内存约束详情、嵌入式代码测试模式（单元测试与集成测试）见 [references/memory-and-testing.md](references/memory-and-testing.md)。

## 常见错误与审查命令

详见 [references/common-mistakes.md](references/common-mistakes.md)，包含常见编码错误示例和快速构建/烧录命令。

使用说明

# MCU嵌入式固件审查

审查RP2350和ESP32-S3微控制器的嵌入式Rust固件，聚焦Embassy异步运行时、内存约束、LED控制、CAN附件协议和SLCAN桥接。

## 适用场景

- 审查MCU固件代码变更
- 调试LED控制器问题
- 评估Embassy异步模式
- 检查静态内存分配
- 验证SLCAN实现

## 覆盖平台

| 平台 | 运行时 | LED驱动 | CAN |
|------|--------|---------|-----|
| RP2350 (Pico 2 W) | Embassy异步 | PIO状态机 | 外部MCP2515 |
| ESP32-S3 (Heltec) | 轮询循环 | RMT外设 | 内置TWAI |

## 使用示例

审查RP2350固件中的LED控制器代码：

```
请审查 mcu/bins/rp2350/src/main.rs 中的LED控制器任务，
检查Embassy异步模式是否正确，静态内存分配是否合理。
```

审查ESP32-S3的SLCAN桥接实现：

```
请审查 mcu/bins/esp32s3/src/slcan.rs 中的SLCAN协议解析，
检查帧格式验证和错误处理是否完善。
```

## 审查检查清单

- Embassy异步任务是否正确标记和启动
- 静态内存分配（RP2350无堆分配器）
- WS2812颜色数据使用GRB格式
- CAN ID按协议规范计算
- SLCAN帧解析包含完整验证
- 内存约束在安全范围内

如何安装此技能？

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