CH376T / CH376S 驱动 · ESP32-S3 · 软件模拟 SPI · U盘读写 · FAT16/FAT32 · 纯 C
EN — A CH376T (WCH) driver for ESP32-S3 with ESP-IDF: bit-bang SPI, no external dependencies, full U-disk (USB host) + FAT file API, plus a ready-to-build demo project. 中文 — WCH CH376T 芯片的 ESP32-S3 驱动，用普通 GPIO 模拟 SPI，封装了 U 盘挂载与 FAT 文件读写的全部常用命令，附带可直接
idf.py build的示例工程。
CH376T 是 WCH（南京沁恒）的 U 盘 / SD 卡文件管理控制芯片。芯片内部已经集成了 USB 主机固件、Bulk-Only 传输协议和 FAT12/16/32 文件系统，单片机只要发文件级命令，就能读写 U 盘里的文件，不需要自己实现 USB 协议栈和文件系统。
本驱动把 CH376 手册里的命令逐条封装成 CH376T_xxx() 函数：成功返回 1、失败返回 0，失败时把芯片返回的中断状态码打到串口。每个函数都注明了对应的手册命令码、参数顺序和限制。仓库不含任何业务逻辑，可以直接拿去集成。
- 不依赖 IDF 的 SPI master 驱动（bit-bang，4 根线，引脚可在头文件里任意指定）
- 只用
driver/gpio.h+esp_log.h+ FreeRTOS，纯 C，无第三方库 - 覆盖 CH376 手册 40 条命令中的 31 条：初始化、磁盘挂载、文件新建 / 打开 / 删除 / 关闭、读、写、追加、目录创建、文件枚举、目录信息、文件指针定位、磁盘容量与剩余空间查询
- 可传参的文件名与数据：
CH376T_FILE_OPEN_NAME("/LOG.TXT")、CH376T_BYTE_WRITE_DATA(buf, len)（自动分批，任意长度） - 追加写支持：
CH376T_BYTE_LOCATE(0xFFFFFFFFUL, NULL)定位到文件末尾，不覆盖旧数据 - 头文件里带完整的中文注释与手册命令对照表
- 附带
examples/esp32s3-demo示例工程：连接 → 创建文件 → 写入hello ch376→ 关闭，每一步都有编号日志
CH376T/
├── ch376_spi.c ← 驱动实现
├── ch376_spi.h ← 引脚配置、命令码/状态码宏、函数声明
├── docs/
│ ├── CH376T-driver-guide-zh.md ← 驱动接口说明（含全部 API、状态码、使用流程）
│ └── CH376DS1-CH376T-datasheet-CN.pdf ← 芯片手册
└── examples/
└── esp32s3-demo/ ← 可直接编译的 ESP32-S3 示例工程
├── README.md
├── CMakeLists.txt
├── sdkconfig.defaults
└── main/
├── CMakeLists.txt
└── ch376_demo.c
引脚在 ch376_spi.h 顶部定义，换接线只改这里：
| CH376T | ESP32-S3 | 方向 | 说明 |
|---|---|---|---|
| SCS | GPIO2 | 输出 | SPI 片选，低电平有效 |
| SDI | GPIO41 | 输出 | ESP32 的 MOSI → CH376 的 SDI |
| SDO | GPIO40 | 输入 | CH376 的 SDO → ESP32 的 MISO |
| SCK | GPIO42 | 输出 | SPI 时钟 |
| INT# | GPIO1 | 输入 | 中断请求，低电平有效 |
| VCC / GND | 5V 或 3.3V | 电源 | 按模块要求供电，注意共地 |
两个硬件前提：
- INT# 必须接到单片机。驱动靠轮询 INT 引脚判断命令是否执行完，不接会让每次命令都等到约 1 秒超时。
- CH376T 的 SPI# 引脚在复位期间必须为低电平（芯片靠它选择 SPI 接口而不是异步串口），这是硬件决定的。
git clone https://github.com/TELE-nwj/CH376T.git
cd CH376T/examples/esp32s3-demo
idf.py set-target esp32s3
idf.py build
idf.py -p COMx flash monitor # COM 口按实际修改在串口里看到 [1/8] ~ [8/8] 全部成功，U 盘根目录就会出现 ASD.TXT，内容为 hello ch376。
#include "ch376_spi.h"
CH376_PORT_INIT(); /* ① 配置 GPIO */
CH376T_CheckExist(); /* ② 芯片在线检测（0x06） */
CH376T_SetUsbMode(); /* ③ 进入 USB 主机模式（0x15） */
/* ④ 检测 U 盘 + ⑤ 挂载磁盘（两者都成功才能进行文件操作） */
if (CH376T_CMD_DISK_CONNECT() && CH376T_DISK_MOUNT())
{
CH376T_FILE_CREATE_NAME("/HELLO.TXT"); /* ⑥ 新建文件 */
CH376T_BYTE_WRITE_DATA((const uint8_t *)"hello ch376", 11); /* ⑦ 写入数据 */
CH376T_FILE_CLOSE(); /* ⑧ 关闭并刷新 */
}追加写（保留原内容）：
if (CH376T_FILE_OPEN_NAME("/LOG.TXT"))
{
CH376T_BYTE_LOCATE(0xFFFFFFFFUL, NULL); /* 把指针移到文件末尾，否则从头覆盖 */
CH376T_BYTE_WRITE_DATA((const uint8_t *)line, (uint16_t)strlen(line));
CH376T_FILE_CLOSE();
}| 分类 | 函数 | 说明 |
|---|---|---|
| 初始化 | CH376_PORT_INIT CH376T_CheckExist CH376T_SetUsbMode CH376T_ResetAll CH376T_EnterSleep CH376T_Get_IC_Ver |
GPIO 配置、在线检测、USB 模式、复位、睡眠 |
| 磁盘 | CH376T_CMD_DISK_CONNECT CH376T_DISK_MOUNT CH376T_DISK_CAPACITY CH376T_DISK_QUERY |
检测连接、挂载、物理容量、剩余空间 |
| 文件 | CH376T_FILE_OPEN_NAME CH376T_FILE_CREATE_NAME CH376T_FILE_ERASE CH376T_FILE_CLOSE CH376T_GetFileSize |
打开（按名字）、新建（按名字）、删除、关闭、长度 |
| 读 / 写 | CH376T_BYTE_WRITE_DATA CH376T_BYTE_READ CH376T_BYTE_WRITE CH376T_BYTE_LOCATE CH376T_SEC_LOCATE |
写任意数据、读、定位（追加写） |
| 目录 / 枚举 | CH376T_DIR_CREATE CH376T_DIR_INFO_READ CH376T_DIR_INFO_SAVE CH376T_FILE_ENUM_START CH376T_FILE_ENUM_GO |
建目录、目录信息、通配符枚举文件 |
| 缓冲区 | CH376T_WR_OFS_DATA |
写芯片内部缓冲区（配合修改目录信息） |
完整接口说明（参数、返回值、对应手册命令码、状态码表）见 docs/CH376T-driver-guide-zh.md。
CH376T（SSOP20）、CH376S（SOP28）、CH376F（QFN28）——只要是走 SPI 接口的都适用；CH376S 的 8 位并口模式不适用（本驱动是 SPI 版）。
已验证：驱动已随示例工程在 ESP-IDF v5.5.5 + ESP32-S3 上完整编译通过（idf.py build 退出码 0）；语法检查在 -Wall -Wextra -Werror 下零告警。
尚未验证（重要）：所有需要实际连接 U 盘收发的行为还没有上机测试——包括挂载、建文件、写入、关闭、枚举、删文件、建目录、文件指针定位、磁盘容量查询。这批较新的函数在头文件里都标了 //未验证，请以实测为准。
已知特性与限制：
- 阻塞式、不可重入：所有命令同步阻塞，
wait()忙等最长约 1 秒且不让出 CPU；驱动内部无锁，多任务共用需自行加锁串行化。 - 速度：软件模拟 SPI 约 250kHz（芯片本身支持 24MHz）。写 1KB 数据约 20ms。
CH376T_FILE_CREATE()/CH376T_FILE_CREATE_NAME()是“先删后建”，不要用它们打开已有文件。wait()会打日志：轮询过程中有ESP_LOGI，高频写盘时串口输出较多。- 未实现的 9 条命令：
CMD_SET_FILE_SIZE(0x0D，手册未给命令码)、CMD_WR_HOST_DATA(0x2C)、CMD_SEC_READ/WRITE(0x4B/0x4C)、CMD_DISK_BOC_CMD(0x50)、CMD_DISK_READ/WRITE/RD_GO/WR_GO(0x54~0x57，物理扇区读写)。
关键词 / Keywords：CH376T CH376S CH376 WCH 沁恒 ESP32-S3 ESP32S3 ESP-IDF U盘 U-disk USB-flash USB-Host FAT32 FAT16 SPI bit-bang 软件SPI 驱动 driver 嵌入式 embedded