nodemcu-firmware/docs/modules/sdmmc.md

# SDMMC Module
| Since  | Origin / Contributor  | Maintainer  | Source  |
| :----- | :-------------------- | :---------- | :------ |
| 2017-04-17 | [Arnim Läuger](https://github.com/devsaurus) | [Arnim Läuger](https://github.com/devsaurus) | [sdmmc.c](../../components/modules/sdmmc.c)|

!!! note

    MMC cards are not yet supported due to missing functionality in the IDF driver.

## SD Card connection

The SD card is operated in SDMMC mode, thus 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.

!!! 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.

![1:1 micro-sd adapter](../img/micro_sd-small.jpg "1:1 micro-sd adapter")

## sdmmc.init()
Initialize the SDMMC and probe the attached SD card.

#### Syntax
`sdmmc.init(slot[, cfg])`

#### Parameters
- `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-protcet 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

#### 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.