xiaozhi-esphome设备YAML配置详解：从EchoEar到Guition P4 7.0的25+硬件适配解析

xiaozhi-esphome项目为 ESPHome / Home Assistant 提供了 25+ 套现成的 YAML 设备配置，让你手中的 Xiaozhi AI 语音设备（如 EchoEar、Guition P4 7.0、Spotpear Ball 等）直接变身 Home Assistant 的语音助手卫星。本文以通俗的方式拆解这些设备 YAML 的通用结构、Modular 模块化架构，以及从 ESP32-S3 到 ESP32-P4 的硬件适配差异，帮助新手快速为自己的设备找到并读懂对应配置。

一、项目是做什么的：Xiaozhi AI 设备接入 Home Assistant

xiaozhi-esphome 的核心理念很简单：把市面上便宜的 Xiaozhi AI 硬件（通常只要几十美元）刷成 ESPHome 固件，让它作为 Home Assistant 的语音助手，而不需要单独部署一套 Xiaozhi 服务端。

官方 Quick Start 只有 4 步（见 README.md）：

1. USB 连接设备，在 ESPHome Web 中完成"+ NEW DEVICE"初始化并配网；
2. 在 ESPHome Builder 中接管设备，粘贴对应设备的 YAML（保留原来的name:）；
3. 无线保存并安装（首次可能需要 USB 刷写以更新分区表）；
4. 在 Home Assistant 的Devices页面接受新设备，语音助手自动完成设置。

项目内置了 20 多个 AI 角色形象、9 种待机时钟壁纸和多种开机提示音（见 sounds/ 与 images/README.md），刷完后设备会自动下载对应素材，开箱即用。

二、25+ 设备 YAML 文件都在哪里：devices/ 目录结构

所有设备配置集中在devices/目录，按厂商/系列分子目录组织，每个子目录还附带 README 说明状态与识别方法：

📌选配置的小技巧：

• devices/<厂商>/下的 YAML 是"单文件完整版"，自包含全部内容，最适合作为起点；
• Under_Development/Modular/是持续更新的模块化版本，新设备会先在这里以 alpha/beta 状态出现（见 Modular/README.md）；
• 各子目录 README 会标注工作状态。例如 Waveshare/README.md 用绿/黄/红点标出 1.85C、2.06 手表"Working"、3.5 寸"Partly Working"；Spotpear Balls/README.md 则提醒Ball V1/V2 底部贴纸无法区分版本，需对照外观图识别；
• Guition/README.md 特别提醒 Taichi Pi 分 V1/V2 两版硬件，且没有内置喇叭，需走 3.5mm 小孔外接音箱。

↑ 刷入 YAML 后，设备会自动下载imagemodel指定的角色图（默认 Gwen），待机、聆听、思考、回复各有对应表情

三、逐段读懂设备 YAML：从 SETTINGS 到 hardware pack

以最典型的 Guition_P4_7.0.yaml 为例，一份完整的设备 YAML 由 4 大块组成：

1. SETTINGS 配置区：新手只需改这里

所有设备 YAML 开头都是substitutions:变量区，官方用大段注释框出## SETTINGS ##（Guition_P4_7.0.yaml）。常用变量：

⚠️ 注意注释里的提醒：Presence 传感器变量即使不用也不要删，删除会导致脚本报错（IF NOT USING THESE LEAVE THEM ALONE）。

2. 微唤醒词：micro_wake_word 决定"如何叫醒它"

Guition_P4_7.0.yaml 中默认启用okay_nabu和hey_jarvis两个唤醒词，后面用注释列出了大量可取消注释的选项（alexa、hey_mycroft、自定义hey_sarah等）。项目还在 MicroWakeWords/README.md 托管了.tflite模型文件，内存紧张时可以减配唤醒词数量——官方已贴心地写好了注释。

↑ 说出口令后，micro_wake_word组件在本地触发，屏幕切换到listening.png表情

3. packages：Modular 版本的核心架构

单文件版 YAML 把 3000+ 行代码写在一起，而 Modular 版通过packages:把配置拆成公共核心 + 硬件包（Guition_P4_7.0.yaml）：

packages: core: # 所有设备共享：时钟、页面、语音助手逻辑 url: https://github.com/RealDeco/xiaozhi-esphome.git ref: main files: - devices/Under_Development/Modular/core.yaml hw: # 本设备独有：GPIO、屏幕、音频编解码器 files: - devices/Under_Development/Modular/HW/guition_7.0_hw.yaml

• core.yaml：共享逻辑，包含draw_display脚本、时钟屏保、API 全屏图片服务、虚拟触摸按钮、电池电量线性校准等；
• HW/：48 个硬件包，每个设备的 GPIO 接线只改这里。比如 guition_7.0_hw.yaml 里定义了 I2C 总线（GPIO7/8）、ES8311 音频 DAC、ES7210 麦克风 ADC、GT911 触摸控制器及手势滑动的 lambda 逻辑。

这套架构的好处：上游更新一次 core.yaml，你只需重新编译，所有设备同步升级（"After this, if there is an update, all you need to do is compile again"）。

4. 时钟与壁纸：闲置屏保的两种玩法

Modular v1.00 之后，设备闲置超时会显示时钟屏保，壁纸直接从images/Other/<尺寸>/下载。横屏大尺寸（如 P4 7.0 的 1024×600）提供chip、Rolex、neonwaves等专属壁纸：

↑ Guition P4 7.0 默认壁纸chip（clock_background_image: "chip"）

↑ 另一款科技风clock壁纸，可在 Home Assistant 中通过clock_background_image变量直接切换

四、硬件适配对比：EchoEar、Taichi Pi 与 Guition P4 7.0

同样是"小智设备"，三代硬件在芯片、屏幕、音频链路上差异明显，YAML 也随之适配：

几个值得新手注意的适配细节：

1. ESP32-P4 家族（Guition 4.3 / 7.0、Waveshare ESP32-P4-86-ETH）在 guition_7.0_hw.yaml 中还声明了esp32_hosted（挂载 ESP32-C6 跑 WiFi）和esp_ldo调压，单文件旧版里看不到这些——这也是"新设备先出现在 Modular 目录"的原因；
2. 触摸屏才有手势逻辑：hw包里的on_touch/on_releaselambda 把滑动手势转换成"左右换时钟、上下换壁纸/电量"动作，非触摸设备（如 Taichi Pi）则依赖按键；
3. 分辨率变量决定素材下载路径：角色图路径由${imagemodel}/${imagewidth}x${imageheight}/拼出，所以400x600、600x600、1024x600各尺寸目录都有对应 PNG（见 images/ 目录），小屏用imagesize，大屏则screensize与imagesize分开设置。

↑ 把imagemodel改成Alfred即可获得这位"管家"形象，全部 20+ 角色见 echoear1.2.yaml 的选项注释

五、新手避坑清单：版本、刷机与本地调试

• 版本要求：单文件版（如 echoear1.2.yaml）要求 ESPHome2025.9.0+；Modular 版要求2026.4.0+；带 Sendspin 音乐功能的变体（Modular/SENDSPIN/）要求2026.9.0+。
• 首次刷写走 USB：第一次安装会更新分区表，无线 OTA 可能失败，按提示"Plug into this computer"用 USB 刷即可，之后即可无线升级。
• 遇到问题回退：Modular 目录明确建议——"If you run into problems, please return to the known-working non-modular YAMLs"（见 Modular/README.md）。
• 本地调试：想脱离 Git 远程引用本地编辑，可照 README 步骤把core.yaml+display_pages.yaml+ 设备hw文件拷到localtest/，并把packages:改成!include本地路径。
• DIY 玩家：devices/Breadboard/README.md 给出了 INMP441 麦克风、MAX98357 功放、GC9A01/ILI9341 屏幕的完整 GPIO 接线表，与官方面包板版引脚兼容，甚至可刷回 Xiaozhi 官方固件。
• 进阶玩法：Modular v1.10 起暴露了EVENTS（phase id、请求/回复文本）和show_fullscreen_imageAPI 动作，可配合 Home_Assistant_Automations/ 里的现成自动化 YAML，实现"回复时联动灯光"、"从语音阶段改灯色"等玩法。

总结

xiaozhi-esphome 用"一份 YAML 对应一块硬件"的清晰组织，把 25+ 款 Xiaozhi 系设备的接线差异封装进了HW/硬件包，新手真正要动的只有 SETTINGS 区的imagemodel、startup_sound、clock_background_image几个变量。无论你的设备是入门的 EchoEar、圆屏的 Taichi Pi，还是旗舰级的 Guition P4 7.0，都能在devices/目录按厂商找到对应配置，编译刷机后即可作为 Home Assistant 的语音助手卫星使用。