硬件配置与部署

本文用于源码部署和现场核对。普通用户可直接使用 在线烧录工具。

环境与分区

环境	芯片	Flash/PSRAM	分区表	OTA
esp32-F4R0	ESP32	4MB/无	partitions/4MB.csv	否
esp32-F8R0	ESP32	8MB/无	partitions/8MB.csv	是
esp32-F8R8	ESP32	8MB/8MB	partitions/8MB.csv	是
esp32c3-F4R0	ESP32-C3	4MB/无	partitions/4MB.csv	否
esp32c6-F4R0	ESP32-C6	4MB/无	partitions/4MB.csv	否
esp32c6-F8R0	ESP32-C6	8MB/无	partitions/8MB.csv	是
esp32s3-F8R0	ESP32-S3	8MB/无	partitions/8MB.csv	是
esp32s3-F8R8	ESP32-S3	8MB/8MB	partitions/8MB.csv	是
esp32s3-F16R8	ESP32-S3	16MB/8MB	partitions/16MB.csv	是

以上 9 个环境均为正式发布矩阵。环境名称中的 F/R 分别表示 Flash/PSRAM 容量；部署前仍需确认实际硬件，4MB 环境不支持 OTA。

推荐部署

以下是获准部署后的命令示例；先核对目标MAC/芯片、端口、Flash/PSRAM和分区，备份现场配置。普通文件系统上传可能覆盖配置，不能默认视为保全升级。在源码根目录执行：

powershell -ExecutionPolicy Bypass -File scripts\deploy.ps1 `
  -Env esp32s3-F8R8 -Port COM6 -Monitor

只构建不烧录：

powershell -ExecutionPolicy Bypass -File scripts\deploy.ps1 -Env esp32s3-F8R8 -BuildOnly

手动分步时必须外层获取固件构建锁，使用同一环境和经核验保全配置的同一份staging；下面 run-xxxx 是占位，不能直接运行：

node scripts/gzip-www.js --no-upload --no-monitor --env=esp32s3-F8R8
$env:PLATFORMIO_DATA_DIR='D:\project\gitee\FastBee-Arduino\.pio\fs-staging\run-xxxx'
pio run -e esp32s3-F8R8 --target uploadfs
pio run -e esp32s3-F8R8 --target upload

不要把 data/www 直接当发布镜像；它可能包含未压缩或旧版本资源。

引脚约束

引脚规则集中在源码 include/core/ChipConfig.h，Web 的“引脚校验”只覆盖固件已知限制：

• 避开 Flash/PSRAM、USB/JTAG、BOOT 和串口下载占用的引脚。
• ESP32 classic 的 GPIO34-39 仅输入；ADC2 在 WiFi 工作时受限。
• ESP32-C6 的 GPIO12-17 为控制台/保留区，GPIO24-30 通常不可用于外设；以具体板卡原理图为准。
• I2C、SPI、UART 可以改脚，但同一引脚不能分配给多个已启用外设。
• 4G、舵机、继电器等模块要单独核对电流、电平和共地。

部署后检查

1. 访问 http://<设备IP>/api/health，确认返回 JSON。
2. 登录后读取 /api/system/info，核对芯片、Flash、PSRAM 和固件版本。
3. 读取 /api/features/status，确认需要的功能 compiled 且 active。
4. 逐个启用外设，查看初始化日志和读写结果。
5. 需要联网时，再检查 /api/wifi/status、/api/network/status 和 /api/mqtt/status。

擦除与恢复

切换分区或从其它项目迁移时，先核对布局及恢复方案，保全身份、网络、认证、协议与非Web文件。只有确认需要且获准时才整片擦除并重建镜像。擦除会清空网络、外设、协议、用户和规则配置。

相关文档：硬件选型、分区布局、在线烧录、故障排查。