.. _arduino_sdmmc:

========================
1.4 SD Card (SDMMC)
========================

Read and write files on a Micro SD card using the SDMMC 1-bit interface.

Overview
========

This example teaches file system operations on the ESP32-S3 using the high-speed SDMMC interface. It mounts an SD card, detects its type and size, then runs through a full file I/O test: creating, reading, writing, appending, renaming, and deleting files.

.. note::
   This example is based on the official open-source SD card file system example available in Arduino IDE. To make the program structure clearer for this kit, we separated the file management functions into a dedicated ``.ino`` file so the main sketch stays easier to read.

What You'll Learn
=================

* Mounting an SD card with the ``SD_MMC`` library in 1-bit mode
* Configuring custom SDMMC pins with ``setPins()``
* File system operations: list, create, read, write, append, rename, delete
* Measuring read/write throughput

Before You Begin
================

Complete the setup steps in :ref:`preparation` before continuing.

.. note::
   Use the recommended Arduino IDE settings in :ref:`arduino_board_settings` unless this lesson says otherwise.

Open the example sketch from the code package:

``LAFVIN-ESP32-S3-Multimedia-Kit-main/1.Arduino/4.SDMMC/4.SDMMC.ino``

.. note::
   You need a Micro SD card formatted as **FAT32**. Insert it into the onboard card slot before powering the board.

======== ========
Signal   ESP32-S3
======== ========
CLK      GPIO 39
CMD      GPIO 38
D0       GPIO 40
======== ========

The board uses **SDMMC 1-bit mode**. Only one data line (D0) is connected. This keeps more GPIOs free for other peripherals while still providing adequate speed for audio and image applications.

Upload and Test
===============

#. Insert a FAT32-formatted Micro SD card into the slot.
#. Connect the board with a USB Type-C data cable.
#. Open ``4.SDMMC.ino`` in Arduino IDE.
#. In the **Tools** menu, select ``ESP32S3 Dev Module`` as the board and choose the correct serial port.
#. Click **Upload**.
#. Open **Serial Monitor** at ``115200`` baud and observe the file operation test::

      SD Card Type: SDHC
      SD Card Size: 8192MB
      --- Starting file operation test ---
      Listing directory: /
        FILE: hello.txt  SIZE: 24
      ---
      Creating Dir: /mydir
      Dir created
      ---
      51200 bytes read for 45 ms
      1048576 bytes written for 120 ms
      Total space: 7580MB
      Used space: 12MB

How the Code Works
==================

**Pin Configuration and Mount**

Unlike SPI mode, the SDMMC interface requires explicit pin assignment before mounting.

.. code-block:: cpp

   #include "SD_MMC.h"

   int clk = 39;
   int cmd = 38;
   int d0 = 40;

   SD_MMC.setPins(clk, cmd, d0);
   SD_MMC.begin("/sdcard", true);   // true = 1-bit mode

**Card Detection**

The sketch checks whether a card is present and then reads its type and capacity.

.. code-block:: cpp

   uint8_t cardType = SD_MMC.cardType();
   // CARD_MMC, CARD_SD (SDSC), CARD_SDHC, or CARD_NONE

   uint64_t cardSize = SD_MMC.cardSize() / (1024 * 1024);

**File Operations**

The file operation test demonstrates the most common filesystem actions.

.. code-block:: cpp

   writeFile(SD_MMC, "/hello.txt", "Hello ");
   appendFile(SD_MMC, "/hello.txt", "World!\n");
   readFile(SD_MMC, "/hello.txt");
   renameFile(SD_MMC, "/hello.txt", "/foo.txt");
   deleteFile(SD_MMC, "/foo.txt");

In the provided sketch:

* ``sd_helpers.ino`` contains reusable helper functions for each file operation
* The 1-bit mode is set by the second parameter of ``SD_MMC.begin()``
* Performance test writes 1MB (2048 x 512-byte blocks) and measures elapsed time

Try This Next
=============

* Create folders to organize your own files (e.g., ``/music``, ``/photos``)
* Try logging sensor data to a CSV file on the SD card