ESPHome 预编译固件一键烧录

部分 M5Stack 主控、整机和应用方案提供了可直接体验的 ESPHome 预编译固件。通过对应产品页面中的一键烧录按钮，可以将固件写入设备，并根据固件支持的方式完成网络配置和 Home Assistant 接入，无需自行创建 YAML 或编译固件。

1. 准备工作

• 与固件型号匹配的 M5Stack 设备
• 与设备接口匹配、支持数据传输的 USB 数据线
• 支持 WebSerial API 的桌面浏览器，推荐使用 Google Chrome 或 Microsoft Edge
• 对应的 USB 串口驱动；仅在浏览器无法识别串口时需要检查或安装

一键烧录依赖浏览器的串口访问能力，建议直接在电脑端打开产品页面。手机浏览器以及不支持 WebSerial 的浏览器无法完成 USB 烧录。

2. 烧录固件

1. 使用 USB 数据线将设备连接至电脑。如产品页面要求设备进入下载模式，请先按照对应产品说明完成操作。
2. 点击当前产品页面中的在线烧录按钮，在浏览器弹出的串口列表中选择目标设备。如果同时连接了多个串口设备，请根据端口名称确认选择无误。

3. 串口连接成功后，点击安装选项。

4. 核对固件名称和目标设备，确认无误后点击 Install 开始烧录。

5. 等待固件下载、写入和校验完成。在页面提示安装完成前，请勿关闭页面或断开 USB 连接。

6. 烧录完成后，设备通常会自动重启。如果设备没有自动启动，请按下复位键或重新上电。

3. 配置网络

设备需要接入与 Home Assistant 可互相访问的网络。预编译固件可能支持串口、蓝牙或备用热点配网，请选择固件实际提供的一种方式完成配置。

3.1 通过串口配置 Wi-Fi

当固件支持串口配网时，烧录完成页面会显示 Connect to Wi-Fi，也可以重新点击产品页面中的在线烧录按钮并连接同一串口。

1. 选择 Connect to Wi-Fi 进入网络配置界面。

2. 选择目标网络名称（SSID），输入 Wi-Fi 密码，然后点击 Connect。

3. 等待页面提示网络连接成功。

3.2 通过 BLE 配置 Wi-Fi

如果固件支持 BLE 配网，可以通过 Home Assistant Companion App 向设备发送 Wi-Fi 信息。未在 App 中发现设备时，请改用串口或备用热点配网，不代表烧录失败。

1. 开启手机蓝牙并打开 Home Assistant Companion App。
2. 进入 Settings -> Devices & services。

3. 在 Discovered 区域找到待配置的设备，点击 Add，并按照提示输入 Wi-Fi 信息。

4. 等待设备完成网络连接。

3.3 通过备用热点配置 Wi-Fi

如果固件启用了备用热点，设备在无法连接已配置网络时会创建临时 Wi-Fi 热点。热点名称以设备实际显示为准。

1. 使用手机或电脑连接设备创建的热点。

2. 系统通常会自动打开配网页面。如果页面没有弹出，请在浏览器中访问 http://192.168.4.1。

3. 选择目标网络名称（SSID），输入 Wi-Fi 密码，然后点击 Save。

4. 等待设备连接目标网络。连接成功后，临时热点通常会自动关闭。

4. 添加到 Home Assistant

固件启动并连接网络后，Home Assistant 通常会自动发现已启用原生 API 的 ESPHome 设备。

1. 打开 Home Assistant，进入 Settings -> Devices & services。
2. 在 Discovered 区域找到对应设备，点击 Add，并按页面提示完成添加。

3. 添加完成后，在 ESPHome 集成页面中打开设备，检查实体状态和数据是否正常。

如果 Home Assistant 没有自动发现设备：

1. 点击 Add integration，搜索并选择 ESPHome。
2. 输入设备的主机名或 IP 地址。设备 IP 可以从路由器的 DHCP 客户端列表中查询；部分固件也可以通过 USB 串口日志查看启动信息。
3. 如果页面要求输入 API 加密密钥，请使用对应产品页面或固件说明提供的密钥。

5. 常见问题

浏览器未显示串口设备

• 确认 USB 线支持数据传输，并尝试更换 USB 接口。
• 关闭可能占用串口的其他程序。
• 根据设备使用的 USB 串口芯片检查驱动是否安装。
• 按产品说明重新进入下载模式，然后再次连接。

烧录后没有配网入口

不同预编译固件支持的配网方式不同。先重新连接串口检查是否显示 Connect to Wi-Fi；如果没有，请检查设备是否创建了备用热点，或参考对应产品页面确认是否支持 BLE 配网。

设备已联网但无法添加

• 确认设备和 Home Assistant 位于可互相访问的网络中。
• 使用 IP 地址手动添加 ESPHome 集成。
• 通过路由器或串口日志确认设备获得的 IP 地址。
• 检查网络是否阻止 ESPHome 原生 API 端口通信。

6. 后续修改

预编译固件用于快速体验对应产品或应用方案。如果需要修改实体、功能、网络凭据或 API 加密配置，请参考 ESPHome 使用教程 创建或编辑 YAML，并重新编译、烧录与设备匹配的固件。