常见问题

问：为什么我的 ESP-IDF 无法识别 ESP32-S31？

在 VS Code 中运行 "ESP-IDF: Select Current ESP-IDF Version"，确认选择的是本产品指定的 esp-idf-s31 环境。再运行 "ESP-IDF: Set Espressif Device Target"，选择 esp32s31（Preview），不要选择 esp32s3。扩展会自动添加预览目标参数。

如果目标列表中没有 esp32s31，检查是否仍在使用其他版本的 SDK。当前示例使用 ESP-IDF 提交 08e0d30a74ad0bfd5a34933142b80f45619ee410，安装步骤见 配置开发环境。

问：为什么我看到的 Flash 配置只有 16 MiB？

本产品提供 16 MB 和 32 MB Flash 版本，当前工程的镜像头和分区表保留 16 MiB 配置。原理图 U3 标注的 GD25Q256EYIGR 对应 32 MiB，仅表示该图纸中的器件选型，不代表所有产品型号。

运行 03_chip_info，分别查看 Physical Flash 和 Configured flash size。前者用于确认实际读取的物理容量，后者是工程设置；即使检测到更大容量，16 MiB 分区边界之外的空间也不会自动分配给应用。

修改配置前先确认实装器件、镜像头与分区表，不能只修改一个容量选项就认定全部空间可用。

问：为什么我的 PSRAM 测试失败？

本产品提供 16 MB 和 32 MB PSRAM 版本，按所购型号核对容量。示例 11 请求 Octal、200 MHz 和 PSRAM XIP，这些是该工程的配置，不能代替实际芯片订货后缀、运行频率和稳定性检查。

先确认实装芯片及存储配置，再检查对应设置。初次使用建议运行不依赖转接板和外接设备的 RGB LED、按键或芯片信息示例。

问：为什么我运行综合测试后 USB 串口断开？

Type-C 的 USB Serial/JTAG 使用 GPIO33、GPIO34，J2 的 RGB 显示数据也使用这两个引脚。示例 11 在显示初始化成功后接管这些引脚，USB 控制台因此不可继续使用。

需要持续使用 USB 控制台时，使用未占用这两个引脚的基础示例。恢复下载可按 手动进入下载模式 操作。

问：为什么我的 RGB LED 没有随 GPIO 电平翻转而变色？

板载 LED 是 WS2812B-1010，通过 GPIO60 接收串行颜色数据。使用 02_blink_rgb 的 RMT 驱动流程，检查数据格式及实际颜色。不要套用其他 Zero 开发板的 LED 引脚。

问：为什么我没有扫描到 I2C 设备？

GPIO52、GPIO53 是外接 I2C 总线，当前原理图没有确定的板载从设备。未接设备时，0 个应答设备可以是正常结果。

接入外设后，检查 J2 第 19 脚 SDA、第 21 脚 SCL、共地、3.3 V 逻辑电平及上拉条件。持续出现 UU 表示探测超时，应检查总线状态。

问：为什么我的 UART 回环一直失败？

断电后确认 GPIO58（TX）与 GPIO59（RX）已短接，对应 H2 第 2、1 脚。断开占用这两个引脚的其他外接设备，再检查串口日志。该示例使用 UART1，电脑上的 USB 控制台只负责查看日志。

问：为什么我的 Wi-Fi 或 BLE 搜索结果异常？

先检查天线选择电阻对应的射频通路。使用板载陶瓷天线时保留天线区域净空；切换至 IPEX 一代接口后，连接适用的 2.4 GHz 外接天线。Wi-Fi STA 示例需要匹配的热点名称和密码；BLE 示例广播名称为 ESP32-S31-Zero，需要使用支持 BLE 的扫描工具。

若基础配置正确，再记录供电、距离、信道和日志进行定位，不根据单次搜索结果判断无线硬件性能。

问：为什么我的综合测试提示显示、触摸或 SD 失败？

示例 11 的显示、触摸和 SD 卡测试需要匹配的触摸屏转接板、SD 卡转接板及外接设备。J2 上引出 LCD、触摸和 SD 信号，不代表裸板已经安装这些设备。

先检查外部硬件是否具备并与工程参数匹配。触摸连续跟踪默认关闭，启动检测结果不代表触摸跟踪可靠性。SD 初始化失败时检查 GPIO20～25、CMD 和数据线的上拉及供电，不能通过格式化卡片修复接线问题。

问：我可以使用 Arduino 开发吗？

当前配套资料没有 Arduino 工程，也没有经确认的 ESP32-S31-Zero 板卡配置。暂不提供 Arduino 操作步骤；不能用 ESP32-S3 的板卡选项替代。

问：为什么我无法使用资料中的测试 BIN 文件？

保留的 ESP32-S31-Zero-Test.bin 尚缺来源版本、烧录地址及配套转接板和外接设备说明。先使用源码编译方式，不根据文件名或其他型号的烧录教程填写地址。详见 保留测试镜像的使用条件。