SD 卡/TF 卡存储

SD 卡可用于日志、离线数据缓存和大文件存储。普中资料中的 SD 卡示例使用 SPI 方式挂载 FAT 文件系统。

当前支持状态

当前开发源码已有 SDIO 外设类型（type 37）的 SPI 模式挂载、Web 文件操作与规则只读状态动作38；动作40增加默认禁用的单来源持续记录链路，统一候选、设备与长稳验收仍待完成。类型名不表示已支持 SDMMC：运行时拒绝 SDMMC 接口。LittleFS 仍是 Web 静态资源和配置文件的主文件系统，SD 卡不自动接管系统日志或离线报告队列。

以下 SPI 示例默认禁用；启用前须核对板卡能力、引脚占用、供电和固件版本。新配置的开发者模式默认关闭，文件写入、删除和恢复前按页面要求用当前密码启用。2026-10-03 22:08验证更新：SD准入/目录/文件/页面/恢复/快照108项已在r16 Host中局部通过，动作38夹具修正后主仓18/18通过；原Host整组仍失败，完整新冻结候选、实物及长稳待验，不是发布或实物通过声明。规则没有接受任意路径/内容的通用 file_append/file_write 动作；持续记录使用受管动作40。

2026-10-03 20:33 开发增量（已有局部Host回归，完整候选待验）：列目录不再刷新历史容量或清除已有恢复建议。列表最多显示32项，只有实际发现第33项才提示还有更多；恰好32项不是截断。缺少数量/截断标志、非法路径或矛盾响应会保留原列表并显示未确认，不把未知数据当空目录。底层卡读取失败仍可能与目录结束无法区分，因此列表成功不证明介质健康、全部文件完整或写入已落盘。没有执行现场挂载、读写或实物测试。

SPI 接线

SD 卡引脚	ESP32 引脚	说明
DI/CMD	GPIO23	MOSI
DO/DAT0	GPIO19	MISO
CLK	GPIO18	SCK
CS/DAT3	GPIO5	片选
VCC	3.3V	不建议直接接 5V 到裸卡
GND	GND	共地

配置方式

方式1：Web界面配置（推荐）

当前开发版本仅选择 SPI 接口；已有设备应先核对候选固件及验收状态，不能仅凭此文启用输出或挂载现场卡。

SD 卡配置保存前重点核对 SPI 引脚、片选引脚和资源预检结果。GPIO18/23/19/5 仅是 classic ESP32 的接线示例，不适用于所有板卡。

步骤1：进入外设管理页面

打开浏览器访问 ESP32 IP 地址
登录后点击左侧菜单 外设配置

步骤2：添加SD卡外设（SPI）

点击 新增外设 按钮

填写配置：

字段	填写内容	说明
外设ID	`sd_spi_01`	唯一标识符
名称	`SD卡-SPI`	显示名称
外设类型	SDIO (type: 37)	SD卡存储
接口	SPI	JSON 中为 `interface: 1`
MISO引脚	`19`	DO/DAT0
MOSI引脚	`23`	DI/CMD
SCK引脚	`18`	CLK
CS引脚	`5`	片选

点击保存

内存占用、启停释放和恢复时长仍需在目标板实测；PSRAM 容量或驱动存在不能代替验收。

方式2：JSON配置文件导入

SPI 模式

json

{
  "id": "sd_spi_01",
  "name": "SD卡-SPI",
  "type": 37,
  "enabled": false,
  "pinCount": 4,
  "pins": [18, 23, 19, 5, 255, 255, 255, 255],
  "params": {
    "interface": 1,
    "frequency": 10000000
  }
}

引脚数组顺序固定为 SCK、MOSI、MISO、CS。此处为单个外设配置片段，导入应使用相应外设配置流程，不代表完整备份文件。

状态、文件操作与恢复

开发版本的 Web SD 诊断可显式挂载/卸载，并在 /fastbee 沙箱内列出、读取、写入或删除文件。文件读写上限为16 KiB，Web文本读取上限4096字节，列表最多32项。文本编辑器不保证任意二进制/非法UTF-8文件无损往返。挂载不自动格式化，必要时创建沙箱目录。

卸载或挂载失败后，刷新状态、列目录或读文件不会自动重新挂载。确认接线及卡状态后，可在开发模式下确认“恢复/重新挂载”；恢复只尝试本次挂载，不重放失败写入/删除。未知结果不要自动重试，部分写入可能已经改变文件。

状态是生命周期与上次成功挂载/写入/删除的容量快照，不证明卡仍在线或文件已经耐久落盘。容量年龄使用本次启动的64位单调毫秒，不是UTC，不因刷新归零；时钟不可确认、锁忙或失去总线租约时显示未确认。故障/恢复计数在本配置会话内保留，重新配置/重启不保证保留。

规则动作38“SD 状态快照（只读）”可产生带质量和年龄的JSON文本，适用于文本上报，不作为数值历史或实时容量条件；不会挂载、查卡或读写文件。其可用性须与固件版本对应。年龄/恢复/规则已有上文列出的局部Host验证记录，不能替代统一候选门禁；拔卡、满盘、断电、真实内存和长稳仍为 NOT_RUN。

持续记录规则（动作40，开发候选待统一验证）

动作40独立管理“已有采样缓存 → 八条有界队列 → 不超过2 KiB批量追加 → 有限轮转”。它不主动读取传感器、消费UART接收或校时。动作38仍只读卡状态，39仍为温控；点击动作40“执行一次”只读取记录器状态，不启动、刷队列或恢复记录。

先配置现有SDSPI外设和一个已启用、勾选数值历史的动作19采集规则，再创建独立SD记录规则。sourceRef必须精确对应一个采样缓存来源；第二条规则写同一来源会被判为歧义，禁用的重复采集规则也会被计入。远程、Modbus、原始UART与自由文本不是本入口的来源。启动后等待新样本，不把启动前旧缓存当新采样。

参数	单位、范围	默认值
`sourceRef`	1–96字节，字母/数字/`_.:-`，精确来源ID	必须选择
`sampleSec`	采样检查间隔，1–3600秒	5
`maxAgeSec`	来源允许年龄，1–3600秒；仍受来源自身新鲜度限制	30
`flushSec`	批量落盘检查间隔，1–300秒；队列满时提前处理	10
`fileKiB`	每个记录文件，4–16 KiB	16
`fileCount`	当前记录会话保留2–8个文件	4

以下仅为默认禁用的单规则片段，目标与来源须替换为已保存的真实配置：

json

{
  "id": "sd_record_room",
  "name": "SD持续记录",
  "enabled": false,
  "allowPanelControl": false,
  "recordHistory": false,
  "scriptContent": "",
  "triggers": [{"triggerType": 1, "timerMode": 0, "intervalSec": 1}],
  "actions": [{
    "actionType": 40,
    "targetPeriphId": "sd_spi_01",
    "useReceivedValue": false,
    "syncDelayMs": 0,
    "actionValue": "{\"sourceRef\":\"room_temperature\",\"sampleSec\":5,\"maxAgeSec\":30,\"flushSec\":10,\"fileKiB\":16,\"fileCount\":4}"
  }]
}

必须单动作、单1秒间隔触发器，记录间隔由sampleSec决定。规则普通配置持久化；导入必须保持禁用，之后重新核对来源及卡归属才能启用。全局最多一个启用记录器。关闭/删除规则或关闭执行引擎时丢弃尚未落盘队列并释放记录器内存，文件每批均关闭，不在关闭过程中重放旧数据。

仅接纳绑定有效、数值有限、GOOD且新鲜的样本；重复身份/采样时刻不重复写入。来源规则配置、ROM/校准、单位、修订或外设配置代次发生变化会停止记录，须重新确认并禁用/启用规则。队列满时拒绝最新样本并累计dropped，不会无限占用内存。

文件为/fastbee/rec-<owner摘要>-<随机会话>-<槽位>.jsonl，每行含来源、修订、单位、数值、原始单调采样时刻、记录时刻和系统时间质量。wallEpochMs表示记录时的系统时间，不能倒推为传感器测量时刻；仅来源已同步且时间有效时填写，否则为null。未经认证的同步明确标为timeAuthenticated=false，不把RTC/网络可达等同可信时间。

轮转仅替换当前运行会话已经创建并确认大小的文件，不扫描删除旧会话、不格式化卡。历史会话保留，累计空间需要另行人工管理；普通Web写入/删除不允许修改/fastbee/rec-保留命名，仍可读取。重启或恢复产生新会话，不追加或清理不明历史；随机名称发生碰撞也停止，不覆盖旧文件。

短写、满盘、文件变化、卸载、租约变化或未知写入结果会锁存故障，放弃失败批及队列，不自动重放。开发模式下显式“恢复/重新挂载”成功后只接纳恢复之后的新样本；永久来源/配置故障需重新启用规则。原故障文字和累计丢弃数在运行会话内保留，不将恢复后的成功改写为原批成功。

规则列表响应sdRecorder展示phase/pending/accepted/written/dropped/lastError，其中written仅是SDK完整写入、flush和文件长度检查已接受的行数，writeQuality=sdk_write_flush_only不代表断电耐久保证。批量写入不实时扫描FAT容量；容量可能保持未知。无实例或状态锁不可用返回null，不能推断卡健康。

历史候选及已准备的生产回归不作为本次验证结果；本段不声明本次Host、固件、设备或长期测试通过。卡拔插、满盘、断电恢复、真实RAM/耗时、共享SPI并发、24h/7d记录和V14仍需逐项验收，当前设备操作为NOT_RUN。

注意事项

SD 卡建议使用 FAT32。
写入频率不要过高，优先批量缓存后写入。
SD 卡工作电流较高，电源要留余量。
不建议热插拔。

SD 卡/TF 卡存储 ​

当前支持状态 ​

SPI 接线 ​

配置方式 ​

方式1：Web界面配置（推荐） ​

步骤1：进入外设管理页面 ​

步骤2：添加SD卡外设（SPI） ​

方式2：JSON配置文件导入 ​

SPI 模式 ​

状态、文件操作与恢复 ​

持续记录规则（动作40，开发候选待统一验证） ​

注意事项 ​