nodemcu-firmware/docs/modules/sdmmc.md

SDMMC Module

Since	Origin / Contributor	Maintainer	Source
2017-04-17	Arnim Läuger	Arnim Läuger	sdmmc.c

!!! note

MMC cards are not yet supported on HS1/HS2 interfaces due to missing functionality in the IDF driver. Use the SD SPI mode on HSPI/VSPI instead.

SD Card connection

!!! caution

The adapter does not require level shifters since SD and ESP are supposed to be powered with the same voltage. If your specific model contains level shifters then make sure that both sides can be operated at 3V3.

SDMMC Mode

If the SD card is operated in SDMMC mode, then the card has to be wired to the ESP pins of the HS1_* or HS2_* interfaces. There are several naming schemes used on different adapters - the following list shows alternative terms:

SD mode name	SPI mode name	ESP32 HS1 I/F	ESP32 HS2 I/F
CLK	CK, SCLK	GPIO6, HS1_CLK, SD_CLK	GPIO14, HS2_CLK, MTMS
CMD	DI, MOSI	GPIO11, HS1_CMD, SD_CMD	GPIO15, HS2_CMD, MTDO
DAT0	DO, MISO	GPIO7, HS1_DATA0, SD_DATA_0	GPIO2, HS2_DATA0
DAT1	n/a	GPIO8, HS1_DATA1, SD_DATA_1	GPIO4, HS2_DATA1
DAT2	n/a	GPIO9, HS1_DATA2, SD_DATA_2	GPIO12, HS2_DATA2, MTDI
DAT3	CS, SS	GPIO10, HS1_DATA3, SD_DATA_3	GPIO13, HS2_DATA3, MTCK
DAT4 (MMC)	n/a	GPIO16, HS1_DATA4	n/a
DAT5 (MMC)	n/a	GPIO17, HS1_DATA5	n/a
DAT6 (MMC)	n/a	GPIO5, HS1_DATA6	n/a
DAT7 (MMC)	n/a	GPIO18, HS1_DATA7	n/a
VDD	VCC, VDD	3V3 supply	3V3 supply
VSS1, VSS2	VSS, GND	common ground	common ground

Connections to CLK, CMD, and DAT0 are mandatory and enable basic operation in 1-bit mode. For 4-bit mode DAT1, DAT2, and DAT3 are required additionally.

!!! important

Connecting DAT0 to GPIO2 can block firmware flashing depending on the electrical configuration at this pin. Disconnect GPIO2 from the card adapter during flashing if unsure.

SD SPI Mode

In SD SPI mode the SD or MMC card is operated by the SPI host interfaces (HSPI or VSPI). Both hosts can be assigned to any GPIO pins.

SPI mode name	ESP32 HSPI, VSPI I/F
CK, SCLK	Any GPIO
DI, MOSI	Any GPIO
DO, MISO	Any GPIO
n/a	n/a
n/a	n/a
CS, SS	Any GPIO
n/a	n/a
n/a	n/a
n/a	n/a
n/a	n/a
VCC, VDD	3V3 supply
VSS, GND	common ground

sdmmc.init()

Initialize the SDMMC and probe the attached SD card.

Syntax

sdmmc.init(slot[, cfg])

Parameters SDMMC Mode

• slot SDMMC slot, one of sdmmc.HS1 or sdmmc.HS2
• cfg optional table containing slot configuration:
  • cd_pin card detect pin, none if omitted
  • wp_pin write-protect pin, none if omitted
  • fmax maximum communication frequency, defaults to 20  if omitted
  • width bis width, defaults to sdmmc.W1BIT if omitted, one of:
    • sdmmc.W1BIT
    • sdmmc.W4BIT
    • sdmmc.W8BIT, not supported yet

Parameters SD SPI Mode

• slot SD SPI slot, one of sdmmc.HSPI or sdmmc.VSPI
• cfg mandatory table containing slot configuration:
  • sck_pin SPI SCK pin, mandatory
  • mosi_pin, SPI MOSI pin, mandatory
  • miso_pin, SPI MISO pin, mandatory
  • cs_pin, SPI CS pin, mandatory
  • cd_pin card detect pin, none if omitted
  • wp_pin write-protect pin, none if omitted
  • fmax maximum communication frequency, defaults to 20  if omitted

Returns

Card object.

Error is thrown for invalid parameters or if SDMMC hardware or card cannot be initialized.

card:get_info()

Retrieve information from the SD card.

Syntax

card:get_info()

Returns

Table containing the card's OCR, CID, CSD, SCR, and RCA with elements:

• ocr Operation Conditions Register
• cid Card IDentification
  • date manufacturing date
  • mfg_id manufacturer ID
  • name product name
  • oem_id OEM/product ID
  • revision product revision
  • serial product serial number
• csd Card-Specific Data
  • capacity total number of sectors
  • card_command_class card command class for SD
  • csd_ver CSD structure format
  • mmc_ver MMC version (for CID format)
  • read_block_len block length for reads
  • sector_size sector size in bytes
  • tr_speed maximum transfer speed
• scr
  • sd_spec SD physical layer specification version, reported by card
  • bus_width bus widths supported by card
• rca Relative Card Address

card:mount()

Mount filesystem on SD card.

Syntax

card:mount(ldrv[, slot])

Parameters

• ldrv name of logical drive, "/SD0", "/SD1", etc.
• slot one of sdmmc.HS1 or sdmmc.HS2, defaults to sdmmc.HS2 if omitted

Returns

true if successful, false otherwise

Error is thrown for invalid parameters or if filesystem is already mounted.

card:read()

Read one or more sectors.

Syntax

card:read(start_sec, num_sec)

Parameters

• start_sec first sector to read from
• num_sec number of sectors to read (>= 1)

Returns

String containing the sector data.

Error is thrown for invalid parameters or if sector(s) cannot be read.

card:umount()

Unmount filesystem.

Syntax

card:umount()

Parameters

None

Returns

nil

Error is thrown if filesystem is not mounted or if it cannot be unmounted.

card:write()

Write one or more sectors.

Syntax

card:write(start_sec, data)

Parameters

• start_sec first sector to write to
• data string of data to write, must be multiple of sector size (512 bytes)

Returns

nil

Error is thrown for invalid parameters or if sector(s) cannot be written.