esp32-development

ESP32 开发

将开发板、所连接的电路、固件和主机工具链视为一个整体。只有在硬件端确认观察到预期行为，ESP32 任务才算完成；仅编译或烧录成功并不算完成。

操作约定

1. 确认准确的开发板、SoC 系列、模组、闪存／PSRAM 容量、USB 传输方式、电源和开发板修订版。不要在 ESP32、S2、S3、C2、C3、C5、C6、H2 或 P4 型号之间套用引脚图。
2. 选择引脚或电压等级前，阅读开发板原理图或引脚图、对应的 SoC／模组数据手册，以及所有已连接元件的数据手册。
3. 从只读的主机和 USB 探测开始。打开串口监视器可能会切换 DTR／RTS 并重置目标设备；如果运行状态很重要，请使用不重置选项。
4. 根据产品约束选择一个框架。在编写封装代码之前，优先使用该框架的项目生成器、示例、驱动、构建系统、烧录工具、监视器和调试器。
5. 一次只启动一层：电源和启动、串口日志、一个 GPIO、一个总线、总线扫描或环回、设备身份寄存器、原始读数、校准，然后是应用行为。
6. 操作前确认目标、范围和回滚路径。只读探测无需确认即可进行。首次烧录或修改硬件前，确认目标端口、芯片系列、镜像／分区布局、回滚或重新烧录路径以及电气安全。切勿猜测闪存偏移量。
7. 为真实传感器、时钟、ADC、PWM 设备和执行器保留校准控制。物理差异是预期情况。

回复前证据检查

起草非简单计划或建议前，先完成以下检查：

1. 为每项重要的正面或负面陈述、命令和数值设计选择建立声明台账。source-index.md 中的 URL 只是导航信息，并非证据；请检索对应芯片和当前版本的具体页面，否则将该项标记为 UNKNOWN。
2. 命令帮助只能证明语法。根据当前文档记录所需的目标状态，以及重置、DTR／RTS、下载模式、RAM 存根、端口和修改硬件的影响。如果操作前提未经核实，不要将该命令作为可执行命令提供。
3. 缺失的硬件资料仍然是缺失的。不要用典型情况、示例或“通常”“典型”“某些模组”等说法来替代；应说明已观察到的标记无法证明什么。
4. 不要臆造阈值、余量、间隔、持续时间、点数、百分比或模型形式。应从权威来源或测量标准中推导；否则标记为 UNKNOWN。
5. 根据台账审核最终回复。删除或弱化所有缺少必要证据的重要陈述。

首轮只读探测

python3 scripts/esp32-preflight.py
python3 scripts/esp32-preflight.py --json
pio device list --json-output       # when PlatformIO is installed
mpremote connect list               # when mpremote is installed

预检脚本不会打开串口。USB 描述符可以识别桥接芯片或开发板系列，但不能证明芯片处于下载模式，也不能证明固件专用协议已启用。探测未知开发板前，请阅读决策与预检。

选择路径

需求	优先阅读
确定开发板、主机、端口、传输方式或框架	决策与预检
选择安全的引脚、电源、保护措施、上拉电阻或电平转换	硬件与电气安全
选择 ESP-IDF、Arduino、MicroPython、CircuitPython、ESPHome、Zephyr、Rust 或 NuttX	固件框架
使用原生 CLI 创建、构建、烧录、监控、测试或调试	原生工具工作流
使用 GPIO、ADC、DAC、PWM、触摸、I2C、SPI、UART、I2S、RMT、PCNT、TWAI/CAN 或 USB	外设与总线
集成传感器、显示屏、LED、继电器、电机、伺服机构、电磁阀或其他负载	传感器、执行器与校准
添加 Wi-Fi、BLE、ESP-NOW、Zigbee/Thread、休眠、OTA 或量产电源行为	连接、电源与 OTA
诊断启动、烧录、崩溃、电压骤降、总线、网络或安全状态	调试、恢复与安全
自动化目标测试、调试测试台、注入故障或运行有界反馈循环	硬件测试自动化
更新命令或与版本相关的说明	来源索引

最简启动流程

1. 填写 templates/hardware-bringup.md，并记录每项引脚和电压决策的确切来源。
2. 运行 scripts/esp32-preflight.py；然后使用所选框架自带的开发板列表和项目生成器。
3. 不连接硬件进行构建。解决所有会影响引脚、分区、闪存或安全行为的警告。
4. 仅连接电源和 USB。连接外设前，先捕获启动日志。
5. 使用框架生成的偏移量和映像元数据，通过框架示例或生成的最小项目进行烧录。
6. 验证串口输出、复位行为和芯片身份。然后每次只添加一个外设或负载。
7. 对于总线，先确认电气空闲电平，再运行扫描或回环测试，然后才引入驱动程序。对于执行器，先在不连接负载的情况下测试控制信号，再使用外部驱动器和电源。
8. 通过反复复位和断电再上电测试所需行为。如果涉及 OTA，在依赖 OTA 前，先验证回滚或串口恢复。

自动化硬件反馈循环

如果涉及自动化，请阅读 references/hardware-test-automation.md 并填写 templates/hardware-test-plan.md。将需求与独立观测结果关联，预留共享硬件，调试测试装置，并在更改固件前冻结验收用例。原生测试装置可能会在设置期间烧录或复位设备。请分别记录产品故障、测试装置错误、缺失证据和通过结果；保留每次尝试的记录。如果出现不安全状态、身份或所有权丢失、未确认清理结果，或达到记录的预算上限，请停止。日志显示通过或主机端测试套件通过，都不能证明实际硬件行为。

模板和辅助工具

• templates/hardware-bringup.md — 电路板、电源、引脚、组件和恢复工作表。
• templates/hardware-test-plan.md — 需求与测试映射、调试、故障注入、证据和清理记录。
• templates/component-contract.md — 以数据手册为依据的传感器或执行器集成记录。
• templates/esp-idf-main.c — 包含显式可配置引脚的小型 ESP-IDF GPIO 任务。
• templates/platformio.ini — 最简 PlatformIO 环境，包含显式的板卡、框架和版本固定占位符。
• templates/micropython-i2c-scan.py — 可配置的 I2C 电气特性／身份探测工具。
• templates/esphome-device.yaml 和 templates/esphome-secrets.yaml.example — 使用外部密钥并显式选择框架的安全 ESPHome 调试配置。
• templates/zephyr-esp32.overlay — 最简 devicetree GPIO/I2C 覆盖配置模式。
• scripts/esp32-preflight.py — 无依赖、不会修改系统的主机／工具／端口分类器；运行 --self-test 可执行确定性检查。

严格边界

• ESP32 GPIO 通常不耐受 5 V。请遵循具体数据手册中的限制，并在需要时使用电平转换器或驱动器。
• 不要通过 GPIO 为电机、继电器、电磁阀、伺服器、高电流 LED 或大电容负载供电。请使用额定规格合适的驱动器、外部电源，并在适当情况下共用参考地；对于感性负载，还要提供续流保护。
• 不要认为某个 GPIO 编号普遍安全。引脚绑带、闪存／PSRAM、USB/JTAG、仅输入、ADC 和唤醒限制会因芯片、模块、板卡和启动模式而异。
• 不要把擦除闪存当作通用的首要故障排查步骤。请先保存启动日志、镜像元数据、分区信息、校准／NVS 影响以及恢复文件。
• 安全启动、闪存加密、eFuse 和下载模式限制可能无法撤销。请阅读适用的 SoC 和 ESP-IDF 安全文档，并在一次性硬件上验证恢复路径，然后再进行生产配置。
• 切勿将 Wi-Fi、API、OTA 或签名密钥放入公开模板或源代码管理中。

不适用场景

不要单独使用此技能进行 PCB 布局认证、RF／天线设计、市电电压相关工作、功能安全认证、医疗设备开发，或处理无法获取权威数据手册的组件。请将这些任务交由相应的电气、RF、安全或合规专业人员处理。对于非 ESP32 目标平台，请使用该平台自己的技能和工具链。

退出标准

已记录确切目标和资料来源；已论证电气限制和引脚选择；原生构建和烧录工具运行完成，且没有无法解释的错误；日志表明预期镜像已启动；每条总线或设备都通过了身份级检查；在物理边界处观察到校准后的行为；复位、断电重启和恢复行为均符合请求的部署模式。