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.

Examples are disabled and serve only as wiring records and extension templates. For real data logging, add and test the SD/SPI driver and file actions in a custom environment with enough Flash and runtime memory.

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

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

Step 2: Add SD Card Peripheral (Placeholder)

1. Click the Add Peripheral button

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

3. Click Save

💡 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:

1. Initialization Phase: Only configure GPIO, do not immediately mount file system
2. First Access: Trigger actual mount operation
3. 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