# 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：进入外设管理页面

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

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

1. 点击 **<i class="fas fa-plus"></i> 新增外设** 按钮

2. 填写配置：

   | 字段 | 填写内容 | 说明 |
   |------|---------|------|
   | **外设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` | 片选 |

3. 点击 **保存**

> 内存占用、启停释放和恢复时长仍需在目标板实测；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 卡工作电流较高，电源要留余量。
* 不建议热插拔。
