Crate embedded_sdmmc

embedded-sdmmc

An SD/MMC Library written in Embedded Rust

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

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 suitable for reading SD and SDHC cards over SPI.

use embedded_sdmmc::{Error, Mode, SdCard, SdCardError, TimeSource, VolumeIdx, VolumeManager};

fn example<S, CS, D, T>(spi: S, cs: CS, delay: D, ts: T) -> Result<(), Error<SdCardError>>
where
    S: embedded_hal::spi::SpiDevice,
    CS: embedded_hal::digital::OutputPin,
    D: embedded_hal::delay::DelayNs,
    T: TimeSource,
{
    let sdcard = SdCard::new(spi, cs, delay);
    println!("Card size is {} bytes", sdcard.num_bytes()?);
    let mut volume_mgr = VolumeManager::new(sdcard, ts);
    let mut volume0 = volume_mgr.open_volume(VolumeIdx(0))?;
    println!("Volume 0: {:?}", volume0);
    let mut root_dir = volume0.open_root_dir()?;
    let mut my_file = root_dir.open_file_in_dir("MY_FILE.TXT", Mode::ReadOnly)?;
    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);
        }
    }
    Ok(())
}

Features

• log: Enabled by default. Generates log messages using the log crate.
• defmt-log: By turning off the default features and enabling the defmt-log feature you can configure this crate to log messages over defmt instead.

You cannot enable both the log feature and the defmt-log feature.

Modules

• blockdevice
  Block Device support
• fat
  FAT16/FAT32 file system implementation
• filesystem
  Generic File System structures
• sdcard
  The SD/MMC Protocol

Structs

• Attributes
  Indicates whether a directory entry is read-only, a directory, a volume label, etc.
• Block
  Represents a standard 512 byte block (also known as a sector). IBM PC formatted 5.25“ and 3.5“ floppy disks, SD/MMC cards up to 1 GiB in size and IDE/SATA Hard Drives up to about 2 TiB all have 512 byte blocks.
• BlockCount
  Represents the a number of blocks (or sectors). Add this to a BlockIdx to get an actual address on disk.
• BlockIdx
  Represents the linear numeric address of a block (or sector). The first block on a disk gets BlockIdx(0) (which usually contains the Master Boot Record).
• ClusterId
  Identifies a cluster on disk.
• DirEntry
  Represents a directory entry, which tells you about other files and directories.
• Directory
  Represents an open directory on disk.
• FatVolume
  Identifies a FAT16 or FAT32 Volume on the disk.
• File
  Represents an open file on disk.
• RawDirectory
  Represents an open directory on disk.
• RawFile
  Represents an open file on disk.
• RawVolume
  Represents a partition with a filesystem within it.
• SdCard
  Represents an SD Card on an SPI bus.
• ShortFileName
  An MS-DOS 8.3 filename. 7-bit ASCII only. All lower-case is converted to upper-case by default.
• Timestamp
  Represents an instant in time, in the local time zone. TODO: Consider replacing this with POSIX time as a u32, which would save two bytes at the expense of some maths.
• Volume
  Represents an open volume on disk.
• VolumeIdx
  A VolumeIdx is a number which identifies a volume (or partition) on a disk.
• VolumeManager
  A VolumeManager wraps a block device and gives access to the FAT-formatted volumes within it.

Enums

• Error
  Represents all the ways the functions in this crate can fail.
• FilenameError
  Various filename related errors that can occur.
• Mode
  The different ways we can open a file.
• SdCardError
  The possible errors this crate can generate.
• VolumeType
  This enum holds the data for the various different types of filesystems we support.

Constants

• MAX_FILE_SIZE
  Maximum file size supported by this library

Traits

• BlockDevice
  Represents a block device - a device which can read and write blocks (or sectors). Only supports devices which are <= 2 TiB in size.
• TimeSource
  Things that impl this can tell you the current time.