Note

The version of the document corresponds to ESP-IDF v5.5.0

SDMMC Example

[中文]

Note

This document is automatically translated using AI. Please excuse any detailed errors. The official English version is still in progress.

Example Description

This example demonstrates how to initialize and configure NVS on ESP32, perform read and write operations on a single integer value or string value, and check whether the operation is successful. Through this example, developers can learn the initialization process of NVS, basic read and write methods, and result verification methods.

Running Method

The complete code of the example can be found at SDMMC Example. For project description, pin configuration of each chip, build and burn steps before running, please refer to the README.md file in the example directory.

The SD bus width can be set in SD/MMC Example Configuration > SD/MMC bus width in menuconfig.

Header File Description

The header files used in this example cover standard libraries, FreeRTOS, system control and logging, and NVS storage and other functional modules, building the core functions of task scheduling, system operation management, debugging information output and non-volatile data read and write, providing complete support for application operation and persistent storage.

The header files are classified by function as follows:

  1. Standard Library Functions: Provide basic string processing, file operation and file attribute access functions.

#include <string.h>
#include <sys/unistd.h>
#include <sys/stat.h>

  1. FAT File System: Provides mounting, reading and writing, and virtual file system management functions of the FAT file system.

#include "esp_vfs_fat.h"

  1. SD/MMC Driver: Provides SD/MMC card communication protocol, command processing and host controller configuration functions.

#include "sdmmc_cmd.h"
#include "driver/sdmmc_host.h"

  1. Test IO File: The I/O interface functions provided by the test program, used for SD card read and write tests.

#include "sd_test_io.h"

  1. External Power Control: Used to control the power supply of the SD card through the internal LDO of the chip, suitable for hardware platforms that require external power management. Only effective when the SOC_SDMMC_IO_POWER_EXTERNAL macro is enabled.

#include "sd_pwr_ctrl_by_on_chip_ldo.h"

Macro Definition Description

  1. Buffer Size: Used to specify the maximum length of character arrays or buffers in the example program, ensuring that it will not exceed the predefined size during read and write operations or string processing.

#define EXAMPLE_MAX_CHAR_SIZE    64

  1. Mount Path: Specifies the path where the SD card is mounted in the system. The example program will access the files on the SD card through this path.

#define MOUNT_POINT "/sdcard"

  1. Speed Mode Judgment: Used to judge whether the SD card is in high-speed mode in the program, so as to adjust the initialization parameters or read and write strategies. For specific instructions, please refer to Speed Mode Configuration.

#define EXAMPLE_IS_UHS1    (CONFIG_EXAMPLE_SDMMC_SPEED_UHS_I_SDR50 || CONFIG_EXAMPLE_SDMMC_SPEED_UHS_I_DDR50)

Structure/Global Constant Description

The following structure and global constants are only compiled when the CONFIG_EXAMPLE_DEBUG_PIN_CONNECTIONS macro is enabled. Mainly used for development and debugging stages:

  • Verify whether the pins of the SD/MMC bus are correctly connected.

  • Use ADC to measure signal voltage and check electrical integrity.

  • Print the correspondence between pin names and numbers to help developers understand the hardware interface layout.

In normal deployment or production environments, this configuration can be disabled to save storage and runtime resources.

Structure Type Definition: A structure pin_configuration_t is defined, which encapsulates the pin name, number, and optional ADC channel into a structure for unified management, which can be provided for debugging or testing functions, such as printing the status of each line, measuring voltage, and verifying bus connections. The structure members include:

Global Constants: Used to simplify the processing logic of type and string conversion, and ensure safety and readability during traversal.

  • The array name[] is defined to store the name strings of each pin of the SD/MMC bus, which can quickly identify the physical pin corresponding to each signal when debugging or printing information.

  • The array pins[] is defined to store the GPIO numbers corresponding to each pin of the SD/MMC bus. During debugging or initialization, the program can quickly access the physical pin of each data line through this array. If configured in four-line mode, the array will include pin numbers D1~D3, otherwise only D0.

  • pin_count is defined to store the total number of pins, which is used for traversing arrays or performing initialization, avoiding hard-coded loop times, and improving code maintainability.

  • The ADC channel array adc_channels[] is defined to store the ADC channel number corresponding to each pin, and the SD bus signal voltage is detected through ADC to confirm the pin connection and electrical characteristics. Only defined when the CONFIG_EXAMPLE_ENABLE_ADC_FEATURE macro is enabled.

Task Function Description

This example encapsulates task functions for implementing file operations on the SD card. For specific operation procedures and implementation details, please refer to the file operation instructions, which will not be repeated here:

  • s_example_write_file() is used to create files and write, and you need to provide the target file path and content to be written when calling.

  • s_example_read_file() is used to read files and process and print the read content, and you need to provide the target file path when calling.

Main Function Description

This function serves as the program entry point, demonstrating the complete process of initializing, reading and writing files, renaming, and deleting operations on the ESP32 using an SD storage card. Through this example, developers can learn the initialization and file operation methods of the SD storage card.

The following are the main implementation steps of the function. Considering that most of the process has been detailed in General Steps, you can view the corresponding title in the SD Storage Card General Steps section of the document. For repeated content, it will not be repeated here, only the key implementation and differences in this example are emphasized.

  1. Mount Configuration

  • Choose whether to automatically format when mounting fails through the configuration macro CONFIG_EXAMPLE_FORMAT_IF_MOUNT_FAILED.

  1. Card Information Structure Pointer

  2. Mount Point Path

  • Define the mount point path through the macro definition MOUNT_POINT and save it to the string mount_point[].

  1. Host Controller Configuration

  • Determine the speed mode through the configuration macro and configure the corresponding parameters.

  • Determine whether to control the SD card power supply through the chip’s internal LDO through the configuration macro CONFIG_EXAMPLE_SD_PWR_CTRL_LDO_INTERNAL_IO:

    • Configure the channel ID through the sd_pwr_ctrl_ldo_config_t structure.

    • Create a handle variable pwr_ctrl_handle and initialize it to NULL.

    • Call sd_pwr_ctrl_new_on_chip_ldo() to initialize the configuration and save the returned handle to pwr_ctrl_handle.

    • Assign this handle to the corresponding member of the sdmmc_host_t structure.

  1. Slot Configuration

  • Configure the corresponding flags, data width, and GPIO pins of each signal line through the configuration macro.

  1. Call esp_vfs_fat_sdmmc_mount() and pass in the above configuration to complete the initialization and file system mounting of the SD card.

  • If the initialization fails and the CONFIG_EXAMPLE_DEBUG_PIN_CONNECTIONS macro is enabled, you can call check_sd_card_pins() to check whether the connection status and level of the related GPIO of the SD card are normal, which helps to locate pin wiring errors or hardware faults.

  1. Call sdmmc_card_print_info() to print detailed information about the initialized SD/MMC card, including card type (SD/SDHC/MMC), capacity, bus width, frequency, driving ability, voltage, etc., which helps to verify whether the card is correctly identified and configured. For related usage and parameter explanation, please refer to SD/SDIO/MMC Driver.

  2. File Operation

  • Call the task function s_example_write_file() to create and write a file.

  • Check the file and rename it.

  • Call the task function s_example_read_file() to read the file and process and print the read content.

  • Format the SD card file system: Execute when CONFIG_EXAMPLE_FORMAT_SD_CARD is enabled.

    • Call esp_vfs_fat_sdcard_format() to format the storage corresponding to the SD card mount point as a FAT file system. For related usage and parameter explanation, please refer to FAT File System.

    • After formatting, call stat() to check whether the specified file exists and print the corresponding log to verify whether the formatting has taken effect.

  • Call the task function s_example_write_file() again to create a new file and write to it.

  • Call the task function s_example_read_file() to read the file and process and print the read content.

  1. Delete the internal LDO power control driver: Execute when CONFIG_EXAMPLE_SD_PWR_CTRL_LDO_INTERNAL_IO is enabled.

  • Call sd_pwr_ctrl_del_on_chip_ldo() to delete the registered internal LDO power control handle.