Integrando Xiaozhi AI con ESPHome para Home Assistant: Arquitectura, retos y aprendizajes

La domótica doméstica avanza a pasos agigantados, pero lograr que distintos dispositivos hablen el mismo “idioma” sigue siendo un desafío para muchos entusiastas y desarrolladores. En el ecosistema Home Assistant, la integración de asistentes de voz satélite personalizados abre la puerta a experiencias realmente adaptadas a cada usuario y espacio del hogar. En este post comparto cómo desarrollé ziaozhi-esphome: una solución para convertir dispositivos Xiaozhi AI en satélites de voz totalmente integrados con Home Assistant, usando ESPHome como puente.

Repositorio en GitHub de ziaozhi-esphome

🧐 Contexto y motivación

En mi experiencia configurando casas inteligentes, noté que si bien existen asistentes de voz comerciales (Alexa, Google Home), sus opciones de personalización y control de datos son limitadas. Además, dispositivos más asequibles o alternativos —como los Xiaozhi AI basados en ESP32— quedaban relegados por falta de integraciones robustas.

La comunidad de Home Assistant y ESPHome ha crecido muchísimo, pero no había una solución sencilla para usar Xiaozhi AI como satélites de voz descentralizados. Algunos de los retos eran:

• Integración directa con Home Assistant sin hacks ni configuraciones manuales excesivas.
• Posibilidad de personalizar el comportamiento y el procesamiento de voz.
• Mantener un flujo de instalación simple y accesible para makers y usuarios intermedios.

Así nació ziaozhi-esphome: un proyecto para “democratizar” el acceso a asistentes de voz personalizados y modulares en el hogar.

🏛️ Arquitectura y enfoque técnico

1. Componentes principales

La solución se apoya en tres pilares tecnológicos:

• ESPHome: Framework que permite definir la lógica de dispositivos ESP32/ESP8266 mediante YAML, facilitando su integración con Home Assistant.
• Dispositivos Xiaozhi AI: Hardware compacto y asequible, basado en ESP32, con micrófono incorporado y capacidad de procesamiento local.
• Home Assistant: Plataforma central de automatización y control del hogar.

Diagrama general

1[Usuario] 
2   ⇅ Voz
3[Xiaozhi AI c/ ESPHome]
4   ⇅ WiFi (MQTT/API)
5[Home Assistant]
6   ⇅
7[Automatizaciones / Control central]

• Xiaozhi AI actúa como punto de captura de voz y comandos.
• ESPHome se encarga de la conexión, gestión de firmware y comunicación.
• Home Assistant recibe eventos y procesa las acciones.

2. Decisiones técnicas clave

a) Uso de ESPHome como “puente universal”

Elegí ESPHome porque:

• Permite actualizaciones OTA (over-the-air).
• Es ampliamente adoptado en la comunidad Home Assistant.
• Admite personalizaciones avanzadas (automatizaciones locales, sensores, triggers, etc.).
• Tiene soporte activo y documentación sólida.

b) Abstracción de configuración

Quise que el usuario final no tuviera que modificar código fuente ni lidiar con configuraciones complejas. Por eso, basé la integración en la edición y despliegue de archivos YAML a través de la interfaz de ESPHome Web, permitiendo cambiar solo lo esencial (nombre del dispositivo, WiFi, opciones extra).

c) Interoperabilidad y modularidad

El proyecto debía ser agnóstico en cuanto a la versión de Home Assistant y compatible con futuras actualizaciones de ESPHome. Por eso, evité dependencias “raras” y me apoyé en los componentes core de ambas plataformas.

🛠️ Componentes del sistema y snippets clave

1. Configuración de ESPHome para Xiaozhi AI

Un punto central es la plantilla YAML personalizada para Xiaozhi. Incluye:

• Configuración WiFi y OTA.
• Sensores de estado (online/offline).
• Integración con el asistente de voz de Home Assistant.
• Comandos personalizados.

Ejemplo de snippet:

1esphome:
2  name: xiaozhi_voice_satellite
3  friendly_name: "Xiaozhi Satélite Salón"
4 
5esp32:
6  board: esp32dev
7 
8wifi:
9  ssid: !secret wifi_ssid
10  password: !secret wifi_password
11 
12api:
13  encryption:
14    key: !secret api_key
15 
16ota:
17  password: !secret ota_pass
18 
19voice_assistant:
20  id: assistant_salon
21  microphone:
22    i2s_adc:
23      id: mic_adc
24      ...
25  tts:
26    platform: google_cloud
27    api_key: !secret google_api_key

Esta configuración permite que el dispositivo capture audio, lo envíe a Home Assistant para su procesamiento (usando Rhasspy, por ejemplo) y reciba respuestas TTS.

2. Integración con Home Assistant

• Una vez encendido y conectado, el Xiaozhi aparece como nuevo dispositivo en Home Assistant.
• Se asocia automáticamente como satélite de voz y puede asignarse a una habitación/zona.
• El flujo de comandos por voz queda centralizado, pero cada dispositivo puede tener automatizaciones locales, por ejemplo:

- Encender una luz si detecta un comando específico.

- Enviar notificaciones si se detecta ruido anómalo.

🧩 Challenges técnicos y cómo los resolví

1. Compatibilidad de hardware (Xiaozhi AI + ESPHome)

No todos los Xiaozhi AI estaban 100% documentados. Algunos modelos traían variantes en el pinout del micrófono o el DAC. Para solucionarlo:

• Mapée manualmente los pines de varios modelos con multímetro y pruebas.
• Definí “profiles” de hardware en la documentación del proyecto, con ejemplos YAML para cada variante.
• Fomenté la colaboración de la comunidad para reportar y validar configuraciones nuevas.

2. Instalación inicial y actualizaciones OTA

El primer “flash” del firmware era complejo para usuarios sin experiencia:

• Documenté paso a paso el uso de ESPHome Web.
• Añadí recordatorios/descripciones sobre la necesidad de flasheo USB la primera vez (por el cambio de tabla de particiones).
• Una vez instalado, todas las actualizaciones se pueden hacer de forma inalámbrica, simplificando la experiencia.

3. Latencia y calidad de audio

Transmitir audio por WiFi puede generar latencia o cortes:

• Ajusté buffers y tasas de muestreo en la configuración I2S.
• Recomiendo redes WiFi estables y routers con buena cobertura.
• Incluí opciones para priorizar comandos críticos localmente en el ESP32 si el enlace se cae.

4. Privacidad y seguridad

Al ser dispositivos que capturan audio, prioricé:

• Uso de API encriptado y contraseñas seguras.
• Opciones para activar/desactivar la captura de audio con botón físico o comando desde Home Assistant.
• Documentación sobre qué datos se transmiten y cómo proteger la red.

📊 Resultados e impacto

Desde la publicación del proyecto:

• Más de 150 descargas del YAML base en la primera semana.
• Feedback positivo de usuarios en Europa y LATAM, agradeciendo la facilidad de integración y la posibilidad de crear asistentes de voz “DIY” realmente funcionales.
• Se han creado variantes para Xiaozhi AI con sensores ambientales y displays, ampliando el ecosistema.

Algunos casos de uso reales:

• Habitación infantil: Comandos de voz para música y luces, sin micrófonos “siempre activos” de grandes empresas.
• Cocina: Timer por voz y control de electrodomésticos inteligentes.
• Espacios de trabajo: Automatización de escenas con mensajes personalizados.

🧠 Aprendizajes y mejoras futuras

Lo que aprendí

• La importancia de documentar bien cada paso y variante de hardware.
• Cómo pequeñas decisiones de UX (como automatizar la detección en Home Assistant) marcan la diferencia.
• El valor de la comunidad: recibí patches y mejoras de usuarios que probaron en modelos que ni conocía.

Próximos pasos

• Añadir integración nativa de wake-word para activación local (sin depender totalmente de Home Assistant).
• Mejorar la gestión de ruido ambiente y calidad de audio con DSP en el firmware.
• Facilitar aún más la configuración, quizás con un asistente gráfico para generar YAMLs personalizados.
• Explorar integraciones con otros asistentes open source como Rhasspy o Wyoming.

🚀 Conclusión

Integrar dispositivos Xiaozhi AI con ESPHome y Home Assistant permite llevar la personalización y el control del hogar inteligente a otro nivel, sin depender de soluciones propietarias ni grandes inversiones. El proyecto ziaozhi-esphome demuestra que, con las herramientas adecuadas y una comunidad activa, es posible construir asistentes de voz distribuidos, privados y adaptados a cada hogar.

¿Te gustaría colaborar, reportar un bug o aportar una nueva variante de hardware? ¡Échale un vistazo al repo en GitHub y súmate a la conversación!

¡Gracias por leer! Si tienes dudas, sugerencias o simplemente te apasiona la domótica, déjame un comentario o contáctame vía GitHub. Seguimos construyendo el futuro del hogar, un YAML a la vez. 😊