SD Card / TF Card Storage

fastbeeAbout 3 min

SD Card / TF Card Storage

SD cards can be used for logging, offline data caching, and large file storage. The SD card example in the Puzhong materials uses SPI mode to mount a FAT file system.

Current Support Status

The repository already has an SDIO peripheral type (type 37) and configuration framework, but runtime SD card mounting and file read/write actions are not yet built-in. LittleFS remains the primary file system for Web static resources and configuration files.

Therefore, the examples in this document are disabled by default and serve only as wiring records and future extension templates. When actual SD card data logging is needed, it is recommended to add SD/SPI drivers and file actions in the Full or custom build, to avoid adding excessive library and buffer overhead to the Lite firmware.

SPI Wiring

SD Card Pin	ESP32 Pin	Description
DI/CMD	GPIO23	MOSI
DO/DAT0	GPIO19	MISO
CLK	GPIO18	SCK
CS/DAT3	GPIO5	Chip Select
VCC	3.3V	Do not connect 5V directly to bare card
GND	GND	Common ground

SDIO Wiring

SD Card Pin	ESP32 Pin
CLK	GPIO14
CMD	GPIO15
DAT0	GPIO2
DAT1	GPIO4
DAT2	GPIO12
DAT3	GPIO13

GPIO12 is a boot-sensitive pin on classic ESP32; SDIO mode requires special attention to power-on levels.

Configuration

Method 1: Web Interface Configuration (Recommended)

⚠️ Note: The current firmware SD card driver is not fully implemented; the following configuration is a placeholder example and will not work properly when enabled.

Before saving SD card configuration, verify SPI/SDIO pins, chip select pin, and file system mount status.

Step 1: Navigate to Peripheral Management Page

Open a browser and navigate to the ESP32 IP address
After logging in, click Peripheral Configuration in the left menu

Step 2: Add SD Card Peripheral (Placeholder)

Click the Add Peripheral button
Fill in the configuration:
Field Value Description
Peripheral ID sd_spi_01 Unique identifier
Name SD Card-SPI Display name
Peripheral Type SDIO (type: 37) SD card storage
MISO Pin 19 DO/DAT0
MOSI Pin 23 DI/CMD
SCK Pin 18 CLK
CS Pin 5 Chip Select
Click Save

Field	Value	Description
Peripheral ID	`sd_spi_01`	Unique identifier
Name	`SD Card-SPI`	Display name
Peripheral Type	SDIO (type: 37)	SD card storage
MISO Pin	`19`	DO/DAT0
MOSI Pin	`23`	DI/CMD
SCK Pin	`18`	CLK
CS Pin	`5`	Chip Select

💡 Tip: SD card functionality is recommended to be extended in the esp32s3-F16R8 firmware

Method 2: JSON Configuration File Import

SPI Mode

{
  "id": "sd_spi_01",
  "name": "SD Card-SPI",
  "type": 37,
  "enabled": false,
  "pinCount": 4,
  "pins": [19, 23, 18, 5, 255, 255, 255, 255],
  "params": {
    "frequency": 10000000,
    "mode": 0,
    "msbFirst": true
  }
}

SDIO Mode

{
  "id": "sd_sdio_01",
  "name": "SD Card-SDIO",
  "type": 37,
  "enabled": false,
  "pinCount": 6,
  "pins": [14, 15, 2, 4, 12, 13, 255, 255],
  "params": {}
}

Recommended Execution Action Extensions

The peripheral execution currently has no file write actions. Future additions could include:

Action	Suggested Parameters	Description
`file_append`	`path`, `data`	Append sensor CSV data
`file_write`	`path`, `data`	Overwrite write
`file_read`	`path`	Read and report
`file_delete`	`path`	Delete old files

Example target:

{
  "id": "exec_sd_log_future",
  "name": "SD Card Temp/Humidity Logging - Extension Example",
  "enabled": false,
  "triggers": [
    { "triggerType": 1, "timerMode": 0, "intervalSec": 60 }
  ],
  "actions": [
    { "targetPeriphId": "dht_01", "actionType": 19, "actionValue": "{\"periphId\":\"dht_01\",\"sensorCategory\":\"dht11\",\"dataField\":\"temperature\"}" },
    { "targetPeriphId": "sd_spi_01", "actionType": 0, "actionValue": "TODO:file_append:/sd/dht.csv" }
  ],
  "reportAfterExec": false
}

The actions above are not currently executable by the firmware and are only used to illustrate the data structure direction for future extensions.

Notes

SD cards are recommended to use FAT32 format.
Do not write too frequently; prefer batch caching before writing.
SD cards have high operating current; ensure sufficient power margin.
Hot-swapping is not recommended.

Implementation Status (v2.1)

Current Implementation: Complete driver implemented

Implemented Features

SPI mode (4 pins: CLK/MOSI/MISO/CS)
SDMMC mode (6 pins: CMD/CLK/D0-D3)
Lazy Mount strategy, saving 5-10KB RAM
Parameter validation (interface mode, pin count, frequency)
File system operations (LittleFS Mock test verification)

Lazy Mount Strategy

To optimize memory usage, SD card uses lazy mounting:

Initialization Phase: Only configure GPIO, do not immediately mount file system
First Access: Trigger actual mount operation
Memory Savings: No PSRAM/DRAM resources consumed when not in use

// Only configure GPIO during initialization
pinMode(clk, OUTPUT);
pinMode(mosi, OUTPUT);
pinMode(miso, INPUT);
pinMode(cs, OUTPUT);
digitalWrite(cs, HIGH);  // CS defaults high (not selected)

// Actual mount is performed on first read/write
// esp_vfs_fat_sdspi_mount() or esp_vfs_fat_sdmmc_mount()

Memory Considerations

FATFS mount occupies approximately 5-10KB RAM
Low-memory devices (ESP32-C3 without PSRAM) should use cautiously
Recommended to unmount file system when not in use

Test Coverage

Unit test: test_sdio_config_validation_spi_mode
E2E test: test_e2e_sdcard_spi_peripheral_workflow
Integration test: SPI/SDMMC mode configuration verification, file read/write operations