Embedded SD/MMC

This crate is intended to allow you to read/write files on a FAT formatted SD card on your Rust Embedded device, as easily as using the SdFat Arduino library. It is written in pure-Rust, is #![no_std] and does not use alloc or collections to keep the memory footprint low. In the first instance it is designed for readability and simplicity over performance.

Using the crate in an application

You will need something that implements the BlockDevice trait, which can read and write the 512-byte blocks (or sectors) from your card. If you were to implement this over USB Mass Storage, there's no reason this crate couldn't work with a USB Thumb Drive, but we only supply a BlockDevice implementation suitable for reading SD and SDHC cards over SPI.

use embedded_sdmmc::{SdCard, VolumeManager, Mode, VolumeIdx};
// Build an SD Card interface out of an SPI device, a chip-select pin and the delay object
let sdcard = SdCard::new(sdmmc_spi, delay);
// Get the card size (this also triggers card initialisation because it's not been done yet)
println!("Card size is {} bytes", sdcard.num_bytes()?);
// Now let's look for volumes (also known as partitions) on our block device.
// To do this we need a Volume Manager. It will take ownership of the block device.
let volume_mgr = VolumeManager::new(sdcard, time_source);
// Try and access Volume 0 (i.e. the first partition).
// The volume object holds information about the filesystem on that volume.
let volume0 = volume_mgr.open_volume(VolumeIdx(0))?;
println!("Volume 0: {:?}", volume0);
// Open the root directory (mutably borrows from the volume).
let root_dir = volume0.open_root_dir()?;
// Open a file called "MY_FILE.TXT" in the root directory
// This mutably borrows the directory.
let my_file = root_dir.open_file_in_dir("MY_FILE.TXT", Mode::ReadOnly)?;
// Print the contents of the file, assuming it's in ISO-8859-1 encoding
while !my_file.is_eof() {
    let mut buffer = [0u8; 32];
    let num_read = my_file.read(&mut buffer)?;
    for b in &buffer[0..num_read] {
        print!("{}", *b as char);
    }
}

For writing files:

let my_other_file = root_dir.open_file_in_dir("MY_DATA.CSV", embedded_sdmmc::Mode::ReadWriteCreateOrAppend)?;
my_other_file.write(b"Timestamp,Signal,Value\n")?;
my_other_file.write(b"2025-01-01T00:00:00Z,TEMP,25.0\n")?;
my_other_file.write(b"2025-01-01T00:00:01Z,TEMP,25.1\n")?;
my_other_file.write(b"2025-01-01T00:00:02Z,TEMP,25.2\n")?;

// Don't forget to flush the file so that the directory entry is updated
my_other_file.flush()?;

Open directories and files

By default the VolumeManager will initialize with a maximum number of 4 open directories, files and volumes. This can be customized by specifying the MAX_DIR, MAX_FILES and MAX_VOLUMES generic consts of the VolumeManager:

// Create a volume manager with a maximum of 6 open directories, 12 open files, and 4 volumes (or partitions)
let cont: VolumeManager<_, _, 6, 12, 4> = VolumeManager::new_with_limits(block, time_source);

Providing support for the library

If you are a hardware abstraction library author, you might be interested in adding support for embedded-sdmmc for your SD card interface. This can be done by implementing the BlockDevice trait provided by the embedded-sdmmc-types crate.

The sd_card_init example provides more information on how such an implementation could look like for SD card host controllers. If you are interfacing with a SD card via SPI, embedded-sdmmc provides an implementation which only requires you to provide a SPI driver implementing the SpiDevice trait.

The embedded-sdmmc-types README provides some more information.

Supported features

Open files in all supported methods from an open directory
Open an arbitrary number of directories and files
Read data from open files
Write data to open files
Close files
Delete files
Iterate root directory
Iterate sub-directories
Create directories
Log over defmt or the common log interface (feature flags).

No-std usage

This repository houses no examples for no-std usage, however you can check out the following examples:

Todo List (PRs welcome!)

Delete (empty) directories
Handle MS-DOS /path/foo/bar.txt style paths.

Changelog

The changelog is the CHANGELOG.md

License

Licensed under either of

Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Contributions must be in accordance with the notices in CONTRIBUTING.md.

embedded-sdmmc 0.10.0