文档总览
为 ESP32-S3 刷写固件
安装编译工具，通过项目脚本将固件写入板子。
刷写时先把板子接到 Mac。请使用支持数据传输的 USB 线；只能充电的线可能让板子亮灯，却不会出现串口设备。
安装工具与依赖
按照 arduino-cli 官方文档安装命令行工具，再添加 Espressif 开发板索引。项目使用 ESP32 3.3.x 支持包，下面的 3.3.12 与本次核对的上游 CI 一致。
arduino-cli config add board_manager.additional_urls https://espressif.github.io/arduino-esp32/package_esp32_index.json
arduino-cli core update-index
arduino-cli core install esp32:[email protected]
arduino-cli lib install "[email protected]"如果你已配置过这个索引地址，不用重复添加。更新项目时，也请对照上游 README 和构建配置检查依赖版本。
编译并刷入
在克隆仓库的根目录运行：
hardware/flash.sh脚本会编译固件、寻找串口，并尝试将已运行的板子切到 bootloader 后上传。确认上传成功，再拔下板子。
默认编译参数适用于 8 MB Flash、OPI PSRAM 和原生 USB。换用其他板型前，先阅读兼容性说明。
手动指定串口
先查看设备列表，再将你机器上的实际串口传给脚本：
arduino-cli board list
hardware/flash.sh /dev/cu.usbmodemYOUR_PORTYOUR_PORT 是占位符，需要替换。列表中没有设备时，先换数据线、重新连接，必要时按开发板厂商的方法进入 bootloader。
为什么要使用 flash.sh
脚本会强制包含 hardware/hid_bridge/nimble_cfg.h，为蓝牙视频通道设置所需缓冲区。直接用默认 Arduino 参数编译，即使能刷入，也不代表视频链路的配置正确。
项目所在路径不能有空格，因为强制包含文件的编译参数有这个限制；脚本会提前检查。
需要诊断时
hardware/flash.sh --build-only
hardware/flash.sh --debug--build-only 只编译，不上传；--debug 编入 USB 串口诊断信息。正常搭建不需要把这两条都执行一遍。
下一步验证什么
把板子接到 iPhone，在 App 中检查蓝牙、热点与投屏。固件上传成功并不能证明这些连接已经可用，继续设备连接指南逐项确认。