备注

当前文档对应的版本为 ESP-IDF v5.5.0

SDMMC 示例

[English]

示例说明

本示例展示如何在 ESP32 上初始化并配置 NVS，对单个整数值或字符串值进行读写操作，并检测操作结果是否成功。通过该示例，开发者可以学习 NVS 的初始化流程、基本读写方法及结果验证方式。

运行方法

示例完整代码见 SDMMC 示例。运行前的项目说明、各芯片引脚配置、构建及烧录步骤详见示例目录下的 README.md 文件。

可通过 menuconfig 中的 SD/MMC Example Configuration > SD/MMC bus width 设置 SD 总线宽度。

头文件说明

本示例所使用的头文件涵盖了标准库、FreeRTOS、系统控制与日志、以及 NVS 存储等功能模块，构建了任务调度、系统运行管理、调试信息输出和非易失性数据读写的核心功能，为应用的运行与持久化存储提供完整支撑。

各头文件按功能分类如下：

  1. 标准库功能：提供基础的字符串处理、文件操作和文件属性访问功能。

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

  1. FAT 文件系统：提供 FAT 文件系统的挂载、读写及虚拟文件系统管理功能。

#include "esp_vfs_fat.h"

  1. SD/MMC 驱动：提供 SD/MMC 卡通信协议、命令处理以及主机控制器配置功能。

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

  1. 测试 IO 文件：测试程序提供的 I/O 接口函数，用于 SD 卡读写测试。

#include "sd_test_io.h"

  1. 外部电源控制：用于通过芯片内部 LDO 控制 SD 卡供电，适用于需要外部电源管理的硬件平台。仅在启用 SOC_SDMMC_IO_POWER_EXTERNAL 宏时有效。

#include "sd_pwr_ctrl_by_on_chip_ldo.h"

宏定义说明

  1. 缓冲区大小：用于指定示例程序中字符数组或缓冲区的最大长度，保证在读写操作或字符串处理时不会超出预定义大小。

#define EXAMPLE_MAX_CHAR_SIZE    64

  1. 挂载路径：指定 SD 卡挂载到系统中的路径，示例程序将通过该路径访问 SD 卡上的文件。

#define MOUNT_POINT "/sdcard"

  1. 速度模式判断：用于在程序中判断 SD 卡是否处于高速模式，从而调整初始化参数或读写策略。具体说明可参考 速度模式配置。

#define EXAMPLE_IS_UHS1    (CONFIG_EXAMPLE_SDMMC_SPEED_UHS_I_SDR50 || CONFIG_EXAMPLE_SDMMC_SPEED_UHS_I_DDR50)

结构体/全局常量说明

以下结构体以及全局常量仅在启用 CONFIG_EXAMPLE_DEBUG_PIN_CONNECTIONS 宏时编译。主要用于开发和调试阶段：

  • 验证 SD/MMC 总线各引脚是否正确连接。

  • 使用 ADC 测量信号电压，检查电气完整性。

  • 打印引脚名称与编号对应关系，辅助开发者理解硬件接口布局。

在正常部署或生产环境中，可以禁用该配置，以节省存储和运行资源。

结构体类型定义：定义了一个结构体 pin_configuration_t，将引脚名称、编号及可选 ADC 通道封装为一个结构体，便于统一管理，可提供给调试或测试函数使用，例如打印每条线状态、测量电压、验证总线连接。结构体成员包括：

全局常量：用于简化类型与字符串转换的处理逻辑，并且保证遍历时的安全性与可读性。

  • 定义数组 name[] 存储 SD/MMC 总线各引脚的名称字符串，用于在调试或打印信息时快速识别每个信号对应的物理引脚。

  • 定义数组 pins[] 存储 SD/MMC 总线各引脚对应的 GPIO 编号。在调试或初始化时，程序可以通过该数组快速访问每条数据线的物理引脚。如果配置为四线模式，数组中会包含 D1~D3 引脚编号，否则只包含 D0。

  • 定义 pin_count 存储引脚总数，用于遍历数组或执行初始化，避免硬编码循环次数，提高代码可维护性。

  • 定义 ADC 通道数组 adc_channels[] 存储每个引脚对应的 ADC 通道编号，通过 ADC 检测 SD 总线信号电压，以确认引脚连接和电气特性。仅在启用 CONFIG_EXAMPLE_ENABLE_ADC_FEATURE 宏时定义

任务函数说明

该示例封装了任务函数，用于实现 SD 卡上的文件操作。具体操作流程和实现细节可参考文件操作说明，此处不再赘述：

  • s_example_write_file() 用于 创建文件并写入，调用时需提供目标文件路径和待写入内容。

  • s_example_read_file() 用于 读取文件 以及 处理并打印读取内容，调用时需提供目标文件路径。

主函数说明

该函数作为程序入口，演示了在 ESP32 上使用 SD 存储卡进行初始化、文件读写、重命名和删除操作的完整流程。通过此示例，开发者可以学习 SD 存储卡的初始化以及文件操作方法。

以下为函数的主要实现步骤，鉴于大部分流程已在 通用步骤 中详细介绍，可查看文档中 SD 存储卡通用步骤 小节的对应标题。对于重复内容此处不再赘述，仅重点说明本示例中的关键实现与差异部分。

  1. 挂载配置

  • 通过配置宏 CONFIG_EXAMPLE_FORMAT_IF_MOUNT_FAILED 选择挂载失败时是否自动格式化。

  1. 卡信息结构体指针

  2. 挂载点路径

  • 通过宏定义 MOUNT_POINT 定义挂载点路径，并保存至字符串 mount_point[]。

  1. 主机控制器配置

  • 通过配置宏判断速度模式并配置对应参数。

  • 通过配置宏 CONFIG_EXAMPLE_SD_PWR_CTRL_LDO_INTERNAL_IO 判断是否通过芯片内部 LDO 控制 SD 卡供电：

    • 通过 sd_pwr_ctrl_ldo_config_t 结构体配置通道 ID。

    • 创建句柄变量 pwr_ctrl_handle 并初始化为 NULL。

    • 调用 sd_pwr_ctrl_new_on_chip_ldo() 初始化配置，并将返回的句柄保存至 pwr_ctrl_handle。

    • 将该句柄赋值给 sdmmc_host_t 结构体中的对应成员。

  1. 插槽配置

  • 通过配置宏配置对应的标志位、数据宽度以及各信号线的 GPIO 引脚。

  1. 调用 esp_vfs_fat_sdmmc_mount() 并传入以上配置，完成 SD 卡初始化和文件系统挂载。

  • 若初始化失败且启用了 CONFIG_EXAMPLE_DEBUG_PIN_CONNECTIONS 宏，可通过调用 check_sd_card_pins() 检查 SD 卡相关 GPIO 的连接状态和电平是否正常，帮助定位引脚接线错误或硬件故障。

  1. 调用 sdmmc_card_print_info() 打印已初始化 SD/MMC 卡的详细信息，包括卡类型（SD/SDHC/MMC）、容量、总线宽度、频率、驱动能力、电压等参数，有助于验证卡片是否正确识别和配置。相关使用及参数说明可参考 SD/SDIO/MMC 驱动程序。

  2. 文件操作

  • 调用任务函数 s_example_write_file() 创建文件并写入。

  • 检查文件并重命名。

  • 调用任务函数 s_example_read_file() 读取文件以及处理并打印读取内容。

  • 格式化 SD 卡文件系统：启用 CONFIG_EXAMPLE_FORMAT_SD_CARD 时执行。

    • 调用 esp_vfs_fat_sdcard_format() 将 SD 卡挂载点对应的存储格式化为 FAT 文件系统。相关使用及参数说明可参考 FAT 文件系统。

    • 格式化完成后调用 stat() 检查指定文件是否存在并打印相应日志，用于验证格式化是否生效。

  • 再次调用任务函数 s_example_write_file() 创建新文件文件并写入。

  • 调用任务函数 s_example_read_file() 读取文件以及处理并打印读取内容。

  1. 删除内部 LDO电源控制驱动：启用 CONFIG_EXAMPLE_SD_PWR_CTRL_LDO_INTERNAL_IO 时执行。

  • 调用 sd_pwr_ctrl_del_on_chip_ldo() 删除已注册的内部 LDO 电源控制句柄。