Example 24: SD card read/write

fastbeeAbout 2 min

Example 24: SD card read/write

Synchronized Device Documentation

This page corresponds to the synchronized Chinese source. Commands, JSON examples, API paths, field names, and screenshots are kept aligned with the Chinese device-side source documentation.

What This Page Covers

Overview
Wiring
JSON Configuration Example
PeriphExec Linkage
Notes

Source Reference

The detailed operational source is preserved below so implementation details stay exact while the English navigation, titles, and reading path remain available.

示例24:SD卡读写

实验概述

通过 SPI 或 SDIO 接口读写 SD 卡/TF 卡，用于数据存储、日志记录和配置文件管理。当前 FastBee 已保留 SDIO 外设类型（type 37）和配置框架，但运行时 SD 卡挂载、文件读写动作尚未内置。

注意：本实验文档提供接线和配置占位。真正启用 SD 卡读写建议放在 ESP32-S3 full 固件中扩展，避免普通 ESP32 slim 固件增加过多资源占用。

硬件接线

SPI 模式

开发板标识	GPIO引脚	SD卡引脚
MOSI	GPIO23	DI（CMD）
MISO	GPIO19	DO（DAT0）
CLK	GPIO18	CLK
CS	GPIO5	CS（DAT3）

SDIO 模式（更快）

开发板标识	GPIO引脚	SD卡引脚
CLK	GPIO14	CLK
CMD	GPIO15	CMD
D0	GPIO2	DAT0
D1	GPIO4	DAT1
D2	GPIO12	DAT2
D3	GPIO13	DAT3

JSON 配置示例

SPI 模式

{
  "peripherals": [
    {
      "id": "sd_spi",
      "name": "SD卡-SPI",
      "type": 37,
      "enabled": false,
      "pins": [23, 19, 18, 5],
      "params": {}
    }
  ]
}

SDIO 模式

{
  "peripherals": [
    {
      "id": "sd_sdio",
      "name": "SD卡-SDIO",
      "type": 37,
      "enabled": false,
      "pins": [14, 15, 2, 4, 12, 13],
      "params": {}
    }
  ]
}

外设执行联动

⚠️ 注意：当前外设执行没有内置 file_append/file_write 文件动作。下面是后续扩展方向。

未来场景：温度数据日志（定时触发）

功能：每60秒读取温度并写入SD卡日志文件

预期配置步骤（待固件支持）：

创建规则，名称：温度数据日志
触发器配置：
- 触发类型：选择 定时触发
- 定时模式：选择 固定间隔
- 间隔时间：60000（60秒）
动作配置：
- 动作1：读取传感器 → dht_01
- 动作2：文件追加 → /sd/temperature_log.csv

预期日志格式：

时间戳,温度(°C),湿度(%)
2024-01-01 08:00:00,25.3,60
2024-01-01 08:01:00,25.4,59

注意事项

格式：SD 卡需格式化为 FAT32（<32GB）或 exFAT（≥32GB）
供电：SD 卡工作电流可达 100mA，确保 3.3V 供电稳定
SPI 共享：SD 卡使用 SPI 总线时，CS 引脚用于选择设备
GPIO12 冲突：SDIO 模式下 GPIO12 为 DAT2，启动时不能为高电平
写入频率：避免过于频繁的写入操作，建议批量写入
文件系统：FastBee 使用 LittleFS 管理内部 Flash，SD 卡使用 FAT 文件系统
热插拔：不支持热插拔，SD 卡需在断电时插拔
当前状态：配置框架就绪，运行时驱动和文件动作待补