本文记录在树莓派 Home Assistant (hass) 环境下，使用 ESPHome 编译、构建并烧录 ESP32 固件的完整流程。包含常见网络超时错误的解决方法及串口烧录命令详解。
一、 前置准备与问题排查
在开始之前，请确保你已经安装了 ESPHome。通常它包含在 Home Assistant 的 Python 虚拟环境中。
1. 检查开发环境
首先进入你的 ESPHome 项目目录（假设为 ~/hass/esphome），并确认配置文件存在。
cd ~/hass/esphome
ls
# 确保看到类似 esp32.yaml 的配置文件2. 解决"Github 连接超时"错误（常见坑）
如果在安装依赖或编译时遇到 ConnectTimeout: Connection to github.com timed out，这是因为网络环境无法连接到 GitHub 下载依赖包。
解决方法：
- 方法A（推荐） ：配置代理或切换网络环境，确保能访问
github.com。 - 方法B（临时）：增加网络超时时间，但这通常治标不治本。
- 方法C ：检查 DNS 设置，尝试将 DNS 修改为
8.8.8.8或114.114.114.114。
二、 核心命令详解
ESPHome 的操作主要分为三个步骤：验证配置 、编译固件 、烧录固件。
1. 验证配置
在编译之前，最好先检查 YAML 语法是否正确。
esphome config esp32.yaml输出 SUCCESS 表示配置无误。
2. 编译固件
此步骤会将你的 YAML 配置编译成 ESP32 可执行的二进制文件。
esphome compile esp32.yaml编译成功标志 ：
看到如下日志表示编译完成：
========================================================================================== [SUCCESS] Took 1127.25 seconds ==========================================================================================
INFO Successfully compiled program.3. 烧录固件
编译完成后，需要将固件上传到 ESP32 芯片。这里有两种方式：OTA (无线) 和 串口 (USB)。
方式 A：OTA 无线烧录（适用于设备已联网）
如果设备之前已经刷过 ESPHome 且连接了 WiFi，直接运行：
esphome run esp32.yaml*此命令会自动编译并尝试通过 WiFi 上传。*
方式 B：串口烧录（适用于首次烧录或 OTA 失败）
这是最稳妥的方式。首先通过 USB 线连接 ESP32 和树莓派。
步骤 1：查找串口设备
在 Linux 下，串口设备通常位于 /dev/ 目录下。使用以下命令查找：
ls /dev/ttyUSB* /dev/ttyACM* /dev/serial/by-id/*/dev/ttyUSB0: 常见的 USB 转串口设备（如 CP2102, CH340）。/dev/serial/by-id/...: 设备的唯一 ID 路径，推荐使用，防止插错设备。
常见输出示例：
/dev/ttyUSB0
/dev/serial/by-id/usb-Silicon_Labs_CP2102_USB_to_UART_Bridge_Controller_0001-if00-port0步骤 2：执行烧录命令
找到设备路径后，使用 upload 命令并指定 --device 参数（注意：ESPHome 使用 --device 而不是 --port）：
# 使用简单设备名
esphome upload esp32.yaml --device /dev/ttyUSB0
# 或者使用唯一 ID（推荐）
esphome upload esp32.yaml --device /dev/serial/by-id/usb-Silicon_Labs_CP2102_USB_to_UART_Bridge_Controller_0001-if00-port0烧录成功标志 ：
看到如下日志表示烧录成功：
Hash of data verified.
Leaving...
Hard resetting via RTS pin...
INFO Successfully uploaded program.