跳到主要内容

ESPHome 入门教程

欢迎来到微雪 ESPHome 入门教程。

本教程将帮助你搭建 Home Assistant 环境，并使用 ESPHome 将 ESP32 开发板接入智能家居系统。完成本教程后，你将能够：通过 YAML 配置文件定义 ESP32 设备行为，并在 Home Assistant 中控制该设备。

重要提示：关于硬件与软件版本

硬件：本教程以 微雪 ESP32-S3-Zero（产品文档）作为入门示例板，以 微雪 ESP32-S3-RLCD-4.2（产品文档）作为完整参考示例板。如果你使用其他 ESP32 板，请相应调整板型与引脚配置。

软件：本教程基于 Home Assistant OS 17.3 与 ESPHome 应用 2026.5.1。Home Assistant 与 ESPHome 均迭代频繁，菜单位置、配置语法和 UI 细节可能随版本变化，操作以 Home Assistant 官方文档 和 ESPHome 官方文档 为准。

Home Assistant 与 ESPHome​

Home Assistant（以下简称 HA）是一个开源的家居自动化平台，作为中枢统一管理各品牌智能设备，提供仪表盘、自动化、语音助手等功能。HA 本身不直接控制硬件，而是通过"集成（Integration）"连接各类设备。ESPHome 就是一种集成，它让 HA 能够发现并控制运行 ESPHome 固件的 ESP32 设备。

ESPHome Hero

图片来源：esphome.io

ESPHome 是一个将 ESP32 / ESP8266 等微控制器转换为 HA 设备的固件生成器：开发者用 YAML 文件声明设备上有哪些传感器、开关、灯光等组件，ESPHome 据此编译出对应固件并烧录到设备。烧录完成后，设备会自动被 HA 发现，YAML 中声明的组件会作为实体（Entity）出现在 HA 界面中，无需手写 C/C++ 代码或额外的 HA 集成。

ESPHome 的运行包含两部分：

  • 设备端：编译生成的固件运行在 ESP32 / ESP8266 上，通过 Wi-Fi 与 HA 通信。
  • 编辑与编译端：负责创建、编辑、编译 YAML 配置。可作为 HA 应用运行（本教程采用），也可通过 Docker 或命令行独立运行。

目录​