第 13 章：调试、测试与工程架构

#[embassy_executor::task]
async fn sensor_task(mut i2c: I2c<'static>) {
    loop {
        let temp = read_sensor(&mut i2c).await;  // ← 你想在这里调试
        process(temp).await;
        Timer::after_secs(1).await;
    }
}

#[embassy_executor::task]
async fn comm_task(mut uart: Uart<'static>) {
    loop {
        let cmd = uart.read_until(b'\n').await;
        handle_command(cmd).await;
    }
}

// 基本类型
defmt::info!("temperature: {=i16}°C", temp);
defmt::info!("voltage: {=u16:mV}", adc_value);  // 带单位
defmt::info!("status: {=u8:#04x}", reg);        // 十六进制，4位宽

// 数组和切片
defmt::debug!("rx buf: {=[u8]:x}", &buf[..len]);  // 十六进制打印缓冲区

// 自定义类型：实现 defmt::Format trait
#[derive(defmt::Format)]
struct SensorReading {
    temperature: i16,
    humidity: u16,
    timestamp: u32,
}

let reading = SensorReading { temperature: 253, humidity: 650, timestamp: 12345 };
defmt::info!("reading: {}", reading);
// 输出: reading: SensorReading { temperature: 253, humidity: 650, timestamp: 12345 }

#[embassy_executor::task]
async fn sensor_task(spawner: Spawner, i2c: I2c<'static>) {
    defmt::info!("sensor_task: spawned");
    loop {
        defmt::trace!("sensor_task: poll start");
        
        let reading = read_sensor(&i2c).await;
        defmt::trace!("sensor_task: read done, t={=i16}", reading);
        
        DATA_CHANNEL.send(reading).await;
        defmt::trace!("sensor_task: sent to channel");
        
        Timer::after_millis(100).await;
        defmt::trace!("sensor_task: timer done, loop");
    }
}

{
    "version": "0.2.0",
    "configurations": [
        {
            "type": "probe-rs-debug",
            "request": "launch",
            "name": "Debug Embassy App",
            "chip": "STM32F407VGTx",
            "flashingConfig": {
                "flashingEnabled": true,
                "resetAfterFlashing": true
            },
            "coreConfigs": [
                {
                    "coreIndex": 0,
                    "programBinary": "target/thumbv7em-none-eabihf/debug/my-app"
                }
            ]
        }
    ]
}

// 修复 1：在循环中加入 yield
loop {
    do_something();
    embassy_time::Timer::after_millis(1).await;  // 让出 CPU
}

// 修复 2：使用 embassy 的 yield_now
loop {
    do_something();
    embassy_executor::yield_now().await;
}

// 修复 3：为等待设置超时
match timeout(Duration::from_secs(5), wait_for_condition()).await {
    Ok(_) => do_something(),
    Err(_) => defmt::error!("timeout waiting for condition!"),
}

// 死锁场景：Channel 容量为 1
static CH: Channel<NoopRawMutex, u8, 1> = Channel::new();

// 任务 A：生产者
#[embassy_executor::task]
async fn producer() {
    loop {
        CH.send(1).await;  // Channel 满时挂起
        CH.send(2).await;  // 等任务 B 消费后才能继续
    }
}

// 任务 B：消费者（但逻辑有 bug，永远不消费）
#[embassy_executor::task]
async fn consumer() {
    let _ = CH.receive().await;
    // bug: 这里 panic 了，但被静默吞掉
    // 之后再也不消费了
}

// Embassy 任务栈大小通过 task 宏的参数控制
// 默认通常是 4096 字节，对于复杂任务可能不够

// 方法 1：增大特定任务的栈
#[embassy_executor::task(pool_size = 4)]  // 这个任务最多 4 个实例
async fn complex_task() {
    let large_buf = [0u8; 2048];  // 栈上分配 2KB
    // ...
}

// 方法 2：将大缓冲区改为静态分配（不占栈）
static LARGE_BUF: StaticCell<[u8; 2048]> = StaticCell::new();

#[embassy_executor::task]
async fn complex_task() {
    let buf = LARGE_BUF.init([0u8; 2048]);  // 在静态内存中，不占栈
    // ...
}

// 方法 3：使用堆分配（如果启用了 alloc）
// 不推荐在嵌入式中使用，但某些场景下是务实的选择

project/
├── main.c              // 入口 + 超级循环
├── app/
│   ├── sensor_app.c    // 传感器应用逻辑
│   └── comm_app.c      // 通信应用逻辑
├── hal/
│   ├── hal_i2c.c       // I2C 硬件抽象
│   └── hal_uart.c      // UART 硬件抽象
├── drivers/
│   ├── bme280.c        // BME280 传感器驱动
│   └── esp8266.c       // WiFi 模块驱动
├── protocol/
│   ├── modbus.c        // Modbus 协议
│   └── mqtt.c          // MQTT 协议
├── config.h            // 全局配置
└── Makefile

project/
├── Cargo.toml
├── .cargo/
│   └── config.toml         // target、runner、rustflags
├── memory.x                // 链接脚本（Flash/RAM 布局）
├── build.rs                // 构建脚本
├── src/
│   ├── main.rs             // 入口：初始化 + 任务生成
│   ├── config.rs           // 配置常量（替代 config.h）
│   ├── tasks/              // 异步任务
│   │   ├── mod.rs
│   │   ├── sensor.rs       // 传感器采集任务
│   │   ├── comm.rs         // 通信任务
│   │   └── control.rs      // 控制任务
│   ├── drivers/            // 硬件驱动（面向 embedded-hal）
│   │   ├── mod.rs
│   │   ├── bme280.rs       // BME280 驱动
│   │   └── motor.rs        // 电机驱动
│   ├── protocol/           // 通信协议
│   │   ├── mod.rs
│   │   ├── modbus.rs
│   │   └── frame.rs        // 帧编解码
│   └── shared.rs           // 共享状态定义（Channel、Signal）
└── tests/                  // 集成测试（可选）
    └── hil_test.rs

#![no_std]
#![no_main]

mod config;
mod tasks;
mod drivers;
mod protocol;
mod shared;

use embassy_executor::Spawner;
use embassy_stm32::Config;
use shared::{SENSOR_CHANNEL, COMMAND_SIGNAL};

#[embassy_executor::main]
async fn main(spawner: Spawner) {
    // 1. 硬件初始化
    let p = embassy_stm32::init(Config::default());
    
    // 2. 外设配置
    let i2c = /* ... */;
    let uart = /* ... */;
    
    // 3. 生成任务（把外设的所有权转移给任务）
    spawner.spawn(tasks::sensor::run(i2c)).unwrap();
    spawner.spawn(tasks::comm::run(uart)).unwrap();
    spawner.spawn(tasks::control::run()).unwrap();
    
    // 4. main 任务可以做一些低优先级的事，或者直接退出
    defmt::info!("all tasks spawned");
}

use embassy_time::Timer;
use embassy_stm32::i2c::I2c;
use crate::drivers::bme280::Bme280;
use crate::shared::SENSOR_CHANNEL;
use crate::config::SENSOR_INTERVAL_MS;

#[embassy_executor::task]
pub async fn run(i2c: I2c<'static>) {
    let mut sensor = Bme280::new(i2c);
    sensor.init().await.unwrap();
    
    loop {
        match sensor.read().await {
            Ok(reading) => {
                defmt::debug!("sensor: t={=i16} h={=u16}", reading.temperature, reading.humidity);
                // 如果 Channel 满了，这里会等待（不会丢数据）
                SENSOR_CHANNEL.send(reading).await;
            }
            Err(e) => {
                defmt::error!("sensor read failed: {}", e);
            }
        }
        Timer::after_millis(SENSOR_INTERVAL_MS).await;
    }
}

use embedded_hal_async::i2c::I2c;

pub struct SensorReading {
    pub temperature: i16,  // 0.01°C
    pub humidity: u16,     // 0.01%
}

pub struct Bme280<I2C: I2c> {
    i2c: I2C,
    address: u8,
}

impl<I2C: I2c> Bme280<I2C> {
    pub fn new(i2c: I2C) -> Self {
        Self { i2c, address: 0x76 }
    }
    
    pub async fn init(&mut self) -> Result<(), I2C::Error> {
        // 读取芯片 ID，验证通信
        let mut id = [0u8; 1];
        self.i2c.write_read(self.address, &[0xD0], &mut id).await?;
        if id[0] != 0x60 {
            // 芯片 ID 不匹配
            return Err(/* ... */);
        }
        // 配置传感器...
        Ok(())
    }
    
    pub async fn read(&mut self) -> Result<SensorReading, I2C::Error> {
        let mut buf = [0u8; 6];
        self.i2c.write_read(self.address, &[0xF7], &mut buf).await?;
        // 解析原始数据...
        Ok(SensorReading { temperature, humidity })
    }
}

workspace/
├── Cargo.toml              // workspace 定义
├── firmware/               // 主固件
│   ├── Cargo.toml
│   └── src/
│       ├── main.rs
│       └── tasks/
├── drivers/                // 驱动库（可跨项目复用）
│   ├── bme280/
│   │   ├── Cargo.toml
│   │   └── src/lib.rs
│   └── motor/
│       ├── Cargo.toml
│       └── src/lib.rs
├── protocol/               // 协议库
│   ├── modbus/
│   │   ├── Cargo.toml
│   │   └── src/lib.rs
│   └── frame/
│       ├── Cargo.toml
│       └── src/lib.rs
└── shared-types/           // 共享类型定义
    ├── Cargo.toml
    └── src/lib.rs

// src/protocol/frame.rs

pub fn encode_frame(cmd: u8, payload: &[u8]) -> heapless::Vec<u8, 256> {
    let mut frame = heapless::Vec::new();
    frame.push(0xAA).unwrap();  // 帧头
    frame.push(cmd).unwrap();
    frame.push(payload.len() as u8).unwrap();
    frame.extend_from_slice(payload).unwrap();
    let crc = crc8(&frame);
    frame.push(crc).unwrap();
    frame
}

pub fn decode_frame(data: &[u8]) -> Result<(u8, &[u8]), FrameError> {
    if data.len() < 4 { return Err(FrameError::TooShort); }
    if data[0] != 0xAA { return Err(FrameError::BadHeader); }
    let len = data[2] as usize;
    if data.len() < 3 + len + 1 { return Err(FrameError::Truncated); }
    let crc = crc8(&data[..3 + len]);
    if crc != data[3 + len] { return Err(FrameError::BadCrc); }
    Ok((data[1], &data[3..3 + len]))
}

#[cfg(test)]
mod tests {
    use super::*;
    
    #[test]
    fn test_encode_decode_roundtrip() {
        let payload = [0x01, 0x02, 0x03];
        let frame = encode_frame(0x10, &payload);
        let (cmd, data) = decode_frame(&frame).unwrap();
        assert_eq!(cmd, 0x10);
        assert_eq!(data, &payload);
    }
    
    #[test]
    fn test_decode_bad_crc() {
        let mut frame = encode_frame(0x10, &[0x01]);
        let last = frame.len() - 1;
        frame[last] ^= 0xFF;  // 破坏 CRC
        assert!(matches!(decode_frame(&frame), Err(FrameError::BadCrc)));
    }
    
    #[test]
    fn test_decode_too_short() {
        assert!(matches!(decode_frame(&[0xAA, 0x10]), Err(FrameError::TooShort)));
    }
}

// 测试用的 Mock I2C
#[cfg(test)]
mod mock {
    use embedded_hal_async::i2c::{I2c, ErrorType, ErrorKind};
    
    pub struct MockError;
    
    impl embedded_hal_async::i2c::Error for MockError {
        fn kind(&self) -> ErrorKind { ErrorKind::Other }
    }
    
    pub struct MockI2c {
        // 预设的响应数据
        pub responses: heapless::Vec<(u8, heapless::Vec<u8, 32>), 8>,
        pub write_log: heapless::Vec<u8, 64>,
    }
    
    impl ErrorType for MockI2c {
        type Error = MockError;
    }
    
    impl I2c for MockI2c {
        async fn write_read(
            &mut self,
            address: u8,
            write: &[u8],
            read: &mut [u8],
        ) -> Result<(), Self::Error> {
            self.write_log.extend_from_slice(write).unwrap();
            // 根据预设响应填充 read 缓冲区
            if let Some((_, resp)) = self.responses.pop() {
                read.copy_from_slice(&resp[..read.len()]);
            }
            Ok(())
        }
        
        async fn write(&mut self, _addr: u8, _data: &[u8]) -> Result<(), Self::Error> {
            Ok(())
        }
        
        async fn read(&mut self, _addr: u8, _buf: &mut [u8]) -> Result<(), Self::Error> {
            Ok(())
        }
    }
}

#[cfg(test)]
mod tests {
    use super::mock::MockI2c;
    use super::Bme280;
    
    #[tokio::test]  // 或 embassy 的测试运行时
    async fn test_bme280_init() {
        let mut mock = MockI2c {
            responses: heapless::Vec::new(),
            write_log: heapless::Vec::new(),
        };
        // 预设：读取芯片 ID 寄存器返回 0x60
        mock.responses.push((0xD0, heapless::Vec::from_slice(&[0x60]).unwrap())).unwrap();
        
        let mut sensor = Bme280::new(mock);
        assert!(sensor.init().await.is_ok());
    }
}

// tests/hil_test.rs
// 这个测试需要连接真实硬件

#![no_std]
#![no_main]

use embassy_stm32::i2c::I2c;
use defmt::info;

#[embassy_executor::main]
async fn main(_spawner: embassy_executor::Spawner) {
    let p = embassy_stm32::init(Default::default());
    
    // 测试 1：I2C 通信
    let i2c = I2c::new(p.I2C1, p.PB8, p.PB9, /* ... */);
    let mut sensor = Bme280::new(i2c);
    sensor.init().await.expect("BME280 init failed");
    
    let reading = sensor.read().await.expect("BME280 read failed");
    assert!(reading.temperature > -4000 && reading.temperature < 8500);
    info!("HIL test passed: temp={=i16}", reading.temperature);
    
    // 测试通过，输出特殊标记
    defmt::info!("TEST PASSED");
    
    // 触发断点，让 probe-rs 知道测试完成
    cortex_m::asm::bkpt();
}

use embassy_stm32::wdg::IndependentWatchdog;

#[embassy_executor::main]
async fn main(spawner: Spawner) {
    let p = embassy_stm32::init(Default::default());
    
    // 配置独立看门狗：2 秒超时
    let mut wdg = IndependentWatchdog::new(p.IWDG);
    wdg.start(embassy_time::Duration::from_secs(2));
    
    // 在主循环或关键任务中定期喂狗
    spawner.spawn(watchdog_task(wdg)).unwrap();
}

#[embassy_executor::task]
async fn watchdog_task(mut wdg: IndependentWatchdog<'static>) {
    loop {
        wdg.feed();
        Timer::after_millis(500).await;  // 每 500ms 喂一次（超时 2s）
    }
}

┌─────────────────────────────────────────┐
│              Flash 布局                   │
├──────────┬──────────┬──────────────────┤
│ Bootloader │  App A   │     App B       │
│ (16 KB)   │ (活跃)   │   (待更新)       │
├──────────┼──────────┼──────────────────┤
│ 0x08000000│0x08004000│  0x08040000      │
└──────────┴──────────┴──────────────────┘

更新流程：
1. 通过 UART/WiFi/BLE 接收新固件 → 写入 App B 区域
2. 校验 CRC/签名
3. 设置标志位：下次启动从 App B 启动
4. 复位
5. Bootloader 检查标志 → 跳转到 App B
6. App B 运行成功 → 确认标志（标记为"已验证"）
7. 如果 App B 崩溃 → Bootloader 回滚到 App A

// 产品级日志策略
// 1. 正常运行：只记录 INFO 级别（启动、连接、断开）
// 2. 异常：记录 ERROR + 上下文（错误码、当前状态、最近 N 条操作）
// 3. 持久化：将关键错误写入 Flash 的日志区域
// 4. 上报：通过通信接口（UART/WiFi/BLE）发送给上位机

#[derive(defmt::Format)]
struct ErrorRecord {
    timestamp: u32,
    error_code: u16,
    task_id: u8,
    context: [u8; 16],
}

// 环形缓冲区存储最近 32 条错误
static ERROR_LOG: StaticCell<RingBuffer<ErrorRecord, 32>> = StaticCell::new();

// 在 build.rs 中嵌入版本信息
// build.rs:
fn main() {
    let git_hash = std::process::Command::new("git")
        .args(["rev-parse", "--short", "HEAD"])
        .output()
        .map(|o| String::from_utf8_lossy(&o.stdout).trim().to_string())
        .unwrap_or_else(|_| "unknown".to_string());
    
    println!("cargo:rustc-env=GIT_HASH={}", git_hash);
    println!("cargo:rustc-env=BUILD_TIME={}", chrono::Utc::now().format("%Y-%m-%d %H:%M:%S"));
}

// 在固件中：
const FIRMWARE_VERSION: &str = env!("CARGO_PKG_VERSION");
const GIT_HASH: &str = env!("GIT_HASH");
const BUILD_TIME: &str = env!("BUILD_TIME");

// 启动时打印
defmt::info!("FW v{} ({}), built {}", FIRMWARE_VERSION, GIT_HASH, BUILD_TIME);

# 1. 编译 Release 固件
cargo build --release --features release

# 2. 生成二进制文件
cargo objcopy --release -- -O binary firmware.bin

# 3. 计算校验和
sha256sum firmware.bin > firmware.bin.sha256

# 4. 批量烧录（使用 probe-rs）
probe-rs download --chip STM32F407VGTx --binary-format bin \
    --base-address 0x08000000 firmware.bin

# 5. 验证烧录
probe-rs verify --chip STM32F407VGTx firmware.bin

# 6. 设置选项字节（读保护、写保护）
probe-rs reset --chip STM32F407VGTx