Rust嵌入式SD卡管理库embedded-sdmmc使用指南

简介

embedded-sdmmc是一个轻量级的Rust库，专门为嵌入式系统设计，用于管理SD卡上的FAT16/FAT32文件系统。它提供了一个简单的API来访问SD卡上的文件和目录，无需复杂的文件系统驱动程序。

主要特性

• 支持FAT16和FAT32文件系统
• 零堆分配(no_std兼容)
• 提供阻塞和异步接口
• 支持文件和目录操作
• 体积小巧，适合资源受限的嵌入式环境

使用方法

添加依赖

在Cargo.toml中添加：

[dependencies]
embedded-sdmmc = "0.3"

完整示例代码

以下是一个完整的嵌入式SD卡文件操作示例，包含了初始化、文件读写等操作：

use embedded_sdmmc::{Controller, SdMmcSpi, TimeSource, Volume, VolumeIdx, Mode, Error};
use embedded_hal::blocking::delay::DelayMs;
use embedded_hal::digital::v2::OutputPin;
use embedded_hal::blocking::spi::{Transfer, Write};

// 定义时间源结构体
struct DummyTimesource;
impl TimeSource for DummyTimesource {
    fn get_timestamp(&self) -> embedded_sdmmc::Timestamp {
        embedded_sdmmc::Timestamp {
            year_since_1970: 0,
            zero_indexed_month: 0,
            zero_indexed_day: 0,
            hours: 0,
            minutes: 0,
            seconds: 0,
        }
    }
}

// 初始化SD卡控制器
fn init_sd_card<P, D, SPI>(
    spi: SPI, 
    cs: P, 
    delay: &mut D
) -> Result<Controller<SdMmcSpi<SPI, P>, DummyTimesource>, Error<SPI::Error, P::Error>>
where
    P: OutputPin,
    D: DelayMs<u8>,
    SPI: Transfer<u8> + Write<u8>,
{
    let sdmmc = SdMmcSpi::new(spi, cs);
    let mut controller = Controller::new(sdmmc, DummyTimesource);
    controller.device().init(delay)?;
    Ok(controller)
}

fn main() -> Result<(), Error<(), ()>> {
    // 假设已经初始化了SPI接口、CS引脚和延时器
    // let spi = ...; // SPI接口实例
    // let cs = ...;  // 片选引脚
    // let mut delay = ...; // 延时器
    
    // 初始化SD卡控制器
    let mut controller = init_sd_card(spi, cs, &mut delay)?;
    
    // 打开第一个卷(通常SD卡只有一个卷)
    let volume = controller.get_volume(VolumeIdx(0))?;
    
    // 打开根目录
    let root_dir = controller.open_root_dir(&volume)?;
    
    // 读取目录内容
    println!("Directory contents:");
    controller.iterate_dir(&volume, &root_dir, |entry| {
        println!("- {} ({} bytes)", entry.name, entry.size);
        Ok(())
    })?;
    
    // 创建新文件并写入数据
    println!("Creating test file...");
    let mut file = controller.open_file_in_dir(
        &volume,
        &root_dir,
        "test.txt",
        Mode::ReadWriteCreateOrTruncate,
    )?;
    
    // 写入数据
    controller.write(&mut file, b"Hello, SD Card from Rust!")?;
    
    // 关闭文件
    controller.close_file(file)?;
    println!("File written successfully.");
    
    // 重新打开文件读取内容
    println!("Reading file contents...");
    let mut file = controller.open_file_in_dir(
        &volume,
        &root_dir,
        "test.txt",
        Mode::ReadOnly,
    )?;
    
    // 读取数据
    let mut buffer = [0u8; 32];
    let bytes_read = controller.read(&volume, &mut file, &mut buffer)?;
    println!("Read content: {}", core::str::from_utf8(&buffer[..bytes_read]).unwrap());
    
    // 关闭文件
    controller.close_file(file)?;
    
    Ok(())
}

高级用法

异步接口示例

use embedded_sdmmc::async_::Controller;
use embedded_sdmmc::{VolumeIdx, Mode};

async fn async_sd_card_example() {
    // 初始化异步控制器
    let mut controller = Controller::new(sdmmc, DummyTimesource);
    controller.device().init().await.unwrap();
    
    // 获取卷和目录
    let volume = controller.get_volume(VolumeIdx(0)).await.unwrap();
    let root_dir = controller.open_root_dir(&volume).await.unwrap();
    
    // 异步文件操作
    let mut file = controller.open_file_in_dir(
        &volume,
        &root_dir,
        "async_test.txt",
        Mode::ReadWriteCreateOrTruncate,
    ).await.unwrap();
    
    // 写入数据
    controller.write(&mut file, b"Async write test").await.unwrap();
    controller.close_file(file).await.unwrap();
}

大文件处理示例

fn process_large_file(
    controller: &mut Controller<impl embedded_sdmmc::BlockDevice, DummyTimesource>,
    volume: &Volume,
    dir: &embedded_sdmmc::Directory,
) -> Result<(), embedded_sdmmc::Error<(), ()>> {
    // 打开大文件
    let mut file = controller.open_file_in_dir(
        volume,
        dir,
        "large_data.bin",
        Mode::ReadOnly,
    )?;
    
    // 缓冲区
    let mut buffer = [0u8; 1024];
    let mut total_read = 0;
    
    // 流式读取
    loop {
        let bytes_read = controller.read(volume, &mut file, &mut buffer)?;
        if bytes_read == 0 {
            break; // 文件结束
        }
        
        // 处理数据
        process_data(&buffer[..bytes_read]);
        total_read += bytes_read;
    }
    
    println!("Total bytes processed: {}", total_read);
    controller.close_file(file)?;
    Ok(())
}

注意事项

1. 确保SD卡已正确格式化为FAT16/FAT32文件系统
2. 在嵌入式系统中使用时，注意SPI时钟频率不要超过SD卡的规格
3. 文件操作后务必关闭文件，避免数据损坏
4. 对于写操作，考虑添加适当的延时以确保数据完全写入
5. 错误处理很重要，所有操作都应检查返回值

embedded-sdmmc为嵌入式系统提供了一个简单可靠的SD卡文件系统访问方案，特别适合需要轻量级存储解决方案的应用场景。