SD Storage

Provides Storage Management support for SD cards.

This code is ported from the SD Card library.

Currently uses only SPI communication, which offers only a limited interface and is not supported by SDUC cards.

SD Card connections

../../../../_images/mmc.jpg

See https://en.wikipedia.org/wiki/SD_card

MMC pin

SD pin

miniSD pin

microSD pin

Name

I/O

Logic

Description

1

1

1

2

nCS

I

PP

SPI Card Select [CS] (Negative logic)

2

2

2

3

DI

I

PP

SPI Serial Data In [MOSI]

3

3

3

VSS

S

S

Ground

4

4

4

4

VDD

S

S

Power

5

5

5

5

CLK

I

PP

SPI Serial Clock [SCLK]

6

6

6

6

VSS

S

S

Ground

7

7

7

7

DO

O

PP

SPI Serial Data Out [MISO]

8

8

8

NC nIRQ

O

OD

Unused (memory cards) Interrupt (SDIO cards) (negative logic)

9

9

1

NC

Unused

10

NC

Reserved

11

NC

Reserved

Usage

  • Code should be built with ENABLE_STORAGE_SIZE64 =1 unless using a very small card (1 or 2GB):

  • Add required libraries to your project’s component.mk file:

    COMPONENT_DEPENDS := SdStorage FatIFS
    
  • Create and initialise a Card Device instance:

    #include <Storage/SD/Card.h>
    
    // GPIO used for Chip Select (Esp8266)
    #define PIN_CARD_CS 5
    
    // Create the SD card Device and register with the Storage library
    auto card = new Storage::SD::Card("card1", SPI);
    Storage::registerDevice(card);
    
    if(!card->begin(PIN_CARD_CS)) {
        // Handle error here
        return;
    }
    
    // Display some information
    Serial << "CSD" << endl << card->csd << endl;
    Serial << "CID" << endl << card->cid;
    

At this point, the card can be accessed directly using Storage::Device methods. If the card has been formatted then the partitions can be accessed using the standard Storage API. For example:

Storage::Partition part;

// Find the first FAT partition on the card
part = *card->partitions().find(Storage::Partition::SubType::Data::fat);

// Get the first partition (of any type)
part = *card->partitions().begin();

// Iterate through all partitions
for(part: card->partitions()) {
    Serial << part << endl;
}
  • To create a partition table on the card:

    #include <Storage/Disk/GPT.h>
    
    Storage::Disk::GPT::PartitionTable table;
    // Create one partition using 100% of all available space
    table.add("My FAT partition", 0, 100);
    auto err = Storage::Disk::formatDisk(*card, table);
    Serial << "formatDisk: " << err << endl;
    if(!!err) {
        // If formatting fails, the disk will left in an indeterminate state!
        ...
        return;
    }
    
    // Fetch the first (and only) partition
    auto part = card->partitions().begin();
    

Note

To use the entire card as a single partition, it is not necessary to pre-format the disk. Instead, construct a partition spanning the entire disk:

auto part = card->editablePartitions().add("My Partition",
  Storage::Partition::SubType::Data::fat, 0, card->getSize());

This approach is sometimes referred to as an SFD (Single Filing-system Device).

The partition can now be formatted with the required filing system (FAT):

int res = IFS::FAT::formatVolume(part);
Serial << "formatVolume : " << IFS::Error::toString(res) << endl;

Once formatted, the partition can be mounted as usual:

auto fatfs = IFS::createFatFilesystem(part);
if(fatfs != nullptr) {
    if(fatfs->mount() == FS_OK) {
        // OK, access the filing system
        Serial << fatfs->getContent("My file.txt") << endl;
    } else {
        // Mount failed, destroy the objects
        delete fs;
        delete card; // Also de-registers the card with the Storage API
    }
}

API Documentation

namespace SD
class Card : public Storage::Disk::BlockDevice
#include <Card.h>

Public Functions

bool begin(uint8_t chipSelect, uint32_t freq = 0)

Initialise the card.

Parameters:
  • chipSelect

  • freq – SPI frequency in Hz, use 0 for maximum supported frequency

inline virtual String getName() const override

Obtain unique device name.

inline virtual uint32_t getId() const override

Obtain device ID.

Return values:

uint32_t – typically flash chip ID

inline virtual Type getType() const override

Obtain device type.

inline virtual size_t getBlockSize() const override

Obtain smallest allocation unit for erase operations.

struct CID
#include <CID.h>

Public Members

uint8_t mid

Manufacturer ID.

char oid[2]

OEM / Application ID.

char pnm[5]

Product name.

uint8_t prv

Product revision.

uint32_t psn

Product serial number.

uint16_t mdt

Manufacturing date.

uint8_t not_used

Always 1.

uint8_t crc

7-bit checksum

struct CSD
#include <CSD.h>

Subclassed by Storage::SD::CSD1, Storage::SD::CSD2, Storage::SD::CSD3

struct CSD1 : public Storage::SD::CSD
#include <CSD.h>
struct CSD2 : public Storage::SD::CSD
#include <CSD.h>
struct CSD3 : public Storage::SD::CSD
#include <CSD.h>

References

SoC support

  • esp32

  • esp32c2

  • esp32c3

  • esp32s2

  • esp32s3

  • esp8266

  • host

  • rp2040