常见问题

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

在当前 ESP-IDF 终端执行 idf.py --preview --list-targets，确认列表包含 esp32s31。如果没有，检查 VS Code 选择的 SDK 路径与版本，按 开发环境 配置支持预览目标的 SDK。不要改选 esp32s3。

能列出目标只说明 SDK 识别该芯片，还需验证工程依赖、编译和运行。

问：为什么我的工程提示缺少板级配置或无法初始化设备？

在当前示例根目录执行 idf.py --preview bmgr -b esp32_s31_touch_lcd_4_3c，确认生成 components/gen_bmgr_codes，再编译。保留工程自带的 components/esp_boards 和所需适配组件，不从其他示例复制生成目录。

如修改过 YAML，重新生成并核对设备名称、总线和依赖配置。深层目录报路径过长时，使用较短的解压路径和支持长路径的工具。

问：为什么我的电脑没有串口，或者无法下载程序？

本板 Type-C 经 CH343P 连接 UART0。检查数据线、供电开关和 CH343 驱动，并确认没有其他程序占用串口。不要通过 J3 USB Host 接口下载。

自动连接失败时按 手动进入下载模式 操作。若能下载但看不到日志，核对应用使用的控制台类型与波特率；选择 USB Serial/JTAG 控制台不等于日志会出现在 CH343P 串口。

LCD 使用 GPIO33/34 不会接管 CH343P 的 UART0 下载通道，不能照搬 S31-Zero 的显示与原生 USB 复用结论。

问：我能沿用 S3 版的隔离 IO 接线吗？

不能。H4 的 GPIO48～53 是 ESP32-S31 原生 GPIO，没有原隔离 IO 的电气隔离和电平转换。使用 3.3 V 逻辑并与外设共地，不接高电压输入或功率负载。

H4 的 SDA、SCL 则经过单独的 I2C 电平转换电路，不要将其条件应用到其他 GPIO。针序见 扩展连接器。

问：为什么我的屏幕黑屏、花屏或触摸异常？

先确认使用本产品 esp32_s31_touch_lcd_4_3c 板级定义，再分别运行 11_rgb_lcd、12_touch，区分显示和触摸问题。

显示检查电源、PSRAM 初始化、RGB 引脚、800 × 480 时序和 GPIO47 背光。触摸检查 GPIO0/1 I2C、GPIO46 复位、GPIO2 中断和 GT911 复位选址。GPIO60 到 LCD 复位网络的 R78 标为 NC，不作为已接通的复位引脚。

01_i2c_scan 会先执行触摸唤醒流程，再报告 7 位地址；仅扫描成功不代表坐标方向、连续跟踪和全部触摸区域都正常。

问：为什么我的电量计没有应答，或显示容量与电池不同？

BQ27220 由电池侧供电。断电后核对 J1 极性与电池连接，再用 I2C 扫描确认 0x55 是否应答。04_bat_bq27220 初始化失败后会重试。

板级配置中的 650 mAh 是设计容量参数，不能当作实际电池容量。测量结果还需结合电池配置、状态和校准条件判断。

问：为什么我的 TF 卡挂载失败？

检查卡片是否插好、文件系统是否为示例支持的 FAT 格式，以及 GPIO56 是否以低电平使能卡电源。

先备份数据，不用反复格式化代替供电与接线检查。测试文件 s31_tf_card_demo.txt 会被示例覆盖。

问：为什么我的扬声器无声、有噪声或 WAV 无法播放？

本板使用 ES8389，确认没有沿用 ES8311 / ES7210 配置。检查扬声器连接、GPIO57 高有效功放控制、ES8389 的 DAC 参考使能、I2S 引脚与数据格式。

运行 07_codec_sd_wav_player 时，将包内 test.wav 放在 TF 卡根目录，先确认挂载成功。程序解析 16 位 PCM 单声道或双声道 WAV，不直接播放 MP3。原理图中的扬声器功放只接 ES8389 左声道，纯右声道测试片段不能作为该扬声器必须发声的判断条件。I2S 写入成功不等于实际音频输出正常，需检查测试音与噪声。

问：为什么我的 USB Host 设备无法识别？

断电检查 J3 转接线：1 脚 GND、2 脚 D+、3 脚 D−、4 脚 5 V。VBUS 接板载 5 V，没有可配置的 GPIO 使能，不能通过设置其他 GPIO 给设备供电。

先运行 10_usb_host 检查枚举。摄像头再核对 UVC 描述符及 MJPEG 分辨率、帧率，不能由“支持 UVC”推断任意模式兼容。枚举成功也不代表示例具备该设备类的全部驱动功能。

问：为什么我的 RS485 或 CAN-FD 测试失败？

分别检查极性、参考地、对端设置和接线。RS485 示例为 115200、8N1，方向控制使用 GPIO61，运行时不要按 BOOT。CAN-FD 对端需匹配 500 kbit/s 仲裁速率、2 Mbit/s 数据速率与 BRS，并正确设置终端电阻。

综合测试中的联合项目依赖匹配协议配置的外部 RS485 / CAN-FD 转换器，不能将两类电气接口互相短接。未接该对端时，联合测试超时不能单独证明板卡损坏。

问：我可以使用 Arduino 或 S3 版固件吗？

当前资料没有 Arduino 示例或已确认的 S31 板卡配置。ESP32-S3 与 ESP32-S31 的 CPU 架构、外设和引脚不同，不能使用 S3 开发板选项或固件替代。使用本产品 ESP-IDF 工程，并检查所选 SDK 的 ESP32-S31 支持状态。