ESPHome Home Assistant en Contenedores Docker en Raspberry Pi

Configuración y ejecución de Home Assistant dentro de contenedores Docker en Raspberry Pi y la integración de ESPHome para controlar tus placas de desarrollo ESP32 de manera fluida

Si quieres convertir tu humilde Raspberry Pi 4 en un poderoso centro de comando para el hogar inteligente, estás en el lugar correcto. En este tutorial, recorreremos todo el proceso, desde poner en funcionamiento Home Assistant dentro de contenedores Docker hasta aprovechar el potencial de ESPHome para conectar y controlar sin problemas tu ESP32 y otros dispositivos inteligentes.

En este tutorial, pasaremos por varios pasos para ejecutar ESPHome con Home Assistant en un contenedor Docker en Raspberry Pi:

¿Qué es Home Assistant y ESPHome? #

Home Assistant es una plataforma de automatización del hogar versátil y fácil de usar, de código abierto, que admite una amplia gama de dispositivos de varios fabricantes. Home Assistant te ayuda a conectar diferentes marcas de dispositivos inteligentes en un solo ecosistema, eliminando la necesidad de múltiples aplicaciones móviles para controlar tu hogar.

Además de los dispositivos inteligentes listos para el mercado, Home Assistant tiene muchas integraciones con otros sistemas, incluida la placa ESP32/ESP8266, a través de ESPHome Raspberry Pi. "ESPHome es un sistema para controlar tus ESP8266/ESP32 y RP2040 mediante archivos de configuración simples pero potentes y controlarlos de forma remota a través de sistemas de automatización del hogar". - esphome.io

Una de las mejores partes de Home Assistant es que está disponible para la mayoría de los sistemas operativos modernos, incluidos Raspberry Pi OS y Docker.

El sitio web de Home Assistant sugiere usar un sistema dedicado para ejecutar Home Assistant, por lo tanto, utilizaremos Raspberry Pi 4 8Gb, pero como ejecutaremos múltiples servicios en el Raspberry, lo ejecutaremos dentro de un contenedor Docker.

¿Por qué Docker? #

Primero, Docker es un proyecto de código abierto, puedes imaginarlo como una herramienta gratuita que ayuda a poner aplicaciones en estos pequeños contenedores ordenados, piénsalo como mini paquetes de aplicaciones. Home Assistant lo respalda totalmente, y hay un montón de guías para ayudar. Los contenedores son increíbles porque son fáciles de mover, copiar y probar cosas diferentes sin mucha preocupación. ¿Ya no necesitas uno de los servicios? Simplemente detén el contenedor Docker y eso es todo. No hay frustración al eliminar el desorden que algunos servicios hacen al instalarse.

Añádele el hecho de que Docker es realmente bueno para asegurarse de que las cosas permanezcan igual cada vez que lo usas. Cuando colocas una aplicación dentro de un contenedor Docker, empaquetas todo lo que la aplicación necesita para funcionar. Esto incluye el código, las bibliotecas y las configuraciones. Por lo tanto, no importa dónde ejecutes ese contenedor, ya sea en tu portátil, un servidor o en la nube, siempre funcionará de la misma manera. Esta consistencia es lo que le da a Docker su toque mágico de reproducibilidad.

Instalación del Sistema Operativo Raspberry Pi y Acceso SSH #

Como ya se mencionó, planeamos ejecutar múltiples servicios en Raspberry Pi, por lo tanto, ejecutaremos el contenedor docker de homeassistant. Podríamos simplemente elegir la opción predeterminada del sistema operativo Raspberry Pi, pero como no planeamos ejecutar ningún servicio que requiera acceso a escritorio, no necesitamos un entorno de escritorio y otras cosas que vienen con la opción predeterminada del sistema operativo Raspberry Pi. En su lugar, utilizaremos "Raspberry Pi OS Lite", que como su nombre lo indica es una versión más ligera del sistema operativo Raspberry Pi.

Requisitos Previos #

Antes de comenzar, asegúrate de tener todo listo, necesario para este proyecto, para evitar decepciones en medio de las instrucciones.

Parte	Notas
Raspberry Pi 4	Raspberry Pi 4 8Gb recomendado. Podrías usar una versión anterior, pero por ejemplo, el Rpi3b+ tiene solo 1Gb de RAM, lo que podría no ser suficiente para ejecutar la integración ESPHome Consultar precio en Amazon.com Consultar precio en Amazon.de
Tarjeta microSD	Cualquier tarjeta microSD compatible con Raspberry Pi. Estamos usando SanDisk 64GB Extreme microSD Consultar precio en Amazon.com Consultar precio en Amazon.de
Cable microHDMI (opcional)	En caso de que no quieras habilitar el acceso ssh y prefieras configurar el Raspberry físicamente. Cable Amazon Basics microHDMI a HDMI Consultar precio en Amazon.com Consultar precio en Amazon.de
Computadora	Con sistema operativo compatible con "Raspberry Pi Imager" u otro software de escritura de imágenes similar Consultar precio en Amazon.com Consultar precio en Amazon.de
Lector de tarjetas microSD	Si tu computadora no tiene lector de tarjetas microSD/SD, asegúrate de tener uno externo Consultar precio en Amazon.com Consultar precio en Amazon.de

Hay una pregunta común: ¿Puedes ejecutar Home Assistant en Raspberry Pi 3b+ 1Gb? Y la respuesta es sí, puedes, sin embargo, en nuestra experiencia, suele consumir la mayor parte de la RAM disponible y, por lo tanto, es demasiado lento, especialmente para las integraciones con ESPHome. Aunque funciona, a veces puede ser inestable y compilar programas ESPHome a través de Home Assistant lleva una eternidad. Y eso es sin Docker. Por lo tanto, recomendamos elegir un Raspberry Pi 4 con al menos 4 Gb de RAM.

Si tienes todo listo, podemos comenzar.

Descargar Raspberry Pi Imager En caso de que estés en MacOS y uses HomeBrew, puedes instalar el Raspberry Pi Imager ejecutando brew install --cask raspberry-pi-imager. De lo contrario, descarga el Raspberry Pi Imager y sigue las instrucciones en el sitio web de Raspberry Pi.
Seleccionar Opciones de Raspberry Pi Imager Como se discutió anteriormente, debido a que vamos a usar Raspberry Pi principalmente para ejecutar Docker, que ejecutará Home Assistant y otros servicios, seleccionamos "Raspberry Pi OS Lite (64-bit)". Para Almacenamiento, selecciona la tarjeta microSD insertada.

Ten en cuenta que los pasos 3 y 4 son opcionales si vas a usar un cable microHDMI para conectar tu Raspberry Pi a una pantalla y programarlo físicamente.

Generar Claves SSH Para acceder a nuestro Raspberry Pi de forma remota, después de haber instalado el sistema operativo, necesitamos habilitar la conexión SSH. Podrías usar autenticación por contraseña, pero eso no es muy recomendable, ya que podría ser una amenaza potencial para la seguridad de todo el Raspberry Pi porque cualquier persona que conozca la contraseña podría acceder al Raspberry Pi como administrador. Por lo tanto, generaremos un par de claves SSH para que solo nuestra computadora pueda acceder al Raspberry Pi.
1. Abre la Terminal y escribe 'ssh-keygen -t rsa'. Haz clic en "enter" para confirmar la ubicación predeterminada en '~/.ssh/id_rsa.pub';
2. Escribe 'cat ~/.ssh/id_rsa.pub' y copia la salida impresa en la terminal.
Opciones Avanzadas En Raspberry Pi Imager, haz clic en el ícono de configuración en la esquina inferior derecha.
1. Marca la casilla de verificación "Enable SSH"
2. Selecciona "Allow public-key authentication" solo
3. En el campo "Set authorized_keys for 'x':", pega el contenido de tu clave pública que copiaste en el paso anterior
4. También marcamos la casilla "Set username and password" y rellenamos las credenciales de usuario predeterminadas para nuestro Raspberry Pi Lite OS.
5. Haz clic en "Guardar"

Escribir la Imagen Haz clic en "Write" y espera a que la imagen se escriba en tu tarjeta microSD.
Instalar Raspberry Pi OS Lite Después de escribir con éxito la imagen en una tarjeta micro SD, insértala en tu Raspberry Pi y espera unos minutos. Si tienes un cable microHDMI conectado a la pantalla, espera hasta que el Raspberry Pi te pida que inicies sesión. Si no tienes la pantalla conectada, te recomendamos esperar unos 5 minutos.
SSH en Raspberry Pi Primero, necesitamos saber la dirección IP local de nuestro Raspberry Pi. Hay varias formas de hacerlo...
1. Si tienes la pantalla y el teclado conectados a tu Raspberry Pi, simplemente escribe 'ifconfig eth0' en la consola de Raspberry Pi y busca la dirección IP. Debería verse similar a "192.168.129.13".
2. Si no tienes la pantalla conectada al Raspberry Pi, puedes verificar la dirección IP de Raspberry Pi en la interfaz web de tu router. Las instrucciones variarán de un router a otro, por lo tanto, consulta el manual de tu router.
3. Si no tienes acceso al router, puedes escanear tu red escribiendo 'arp -a' en la terminal de tu computadora. Listará todos los dispositivos conectados a la misma red que tu computadora. Probablemente tendrás varias IPs que se vean similares a "192.168.129.13". Si no estás seguro de cuál es el Raspberry Pi, puedes intentar desconectar el Raspberry de internet o apagarlo, y ejecutar el escaneo arp nuevamente. Es posible que necesites repetirlo varias veces para notar cuál dirección IP aparece o desaparece, lo que significa que pertenece al Raspberry Pi.

Ahora que tenemos la dirección IP local del Raspberry Pi, que en nuestro caso encontramos que es 192.168.129.13, podemos SSH a nuestro Raspberry Pi, escribiendo 'ssh rpi@192.168.129.13'. Asegúrate de reemplazar la dirección IP con la tuya y también, si usaste un nombre de usuario diferente a 'rpi' en Opciones Avanzadas, antes de escribir la imagen en la tarjeta microSD, asegúrate de cambiar eso también.

Es posible que necesites confirmar para agregar el host a la lista de hosts conocidos haciendo clic en enter y deberías ver una pantalla similar a la siguiente, mostrando 'rpi@raspberrypi:~ $'.

Escribe 'sudo su' para obtener privilegios de superusuario.

¡Felicidades! Ahora estás dentro de un terminal de Raspberry Pi.

Instalación de Docker en Raspberry Pi #

Como se mencionó anteriormente, ejecutaremos nuestros servicios dentro de contenedores Docker. Para comenzar con esto, necesitamos instalar el Docker Host en nuestro Raspberry Pi.

Descargar e instalar Docker

Dentro del Terminal, donde tienes la conexión SSH al Raspberry Pi, escribe:

curl -fsSL https://get.docker.com -o get-docker.sh
sh get-docker.sh

Esto descargará el script "get-docker.sh" y lo ejecutará, lo que a su vez descargará e instalará el Docker Host. Ejecutar scripts de shell de esa manera es controvertido, por lo tanto, si lo prefieres, puedes seguir las instrucciones manuales en Docker Docs.

Probar la Instalación de Docker

Para probar si la instalación de Docker fue exitosa y si Docker está funcionando correctamente, hay un contenedor "hello-world" preparado en Docker Hub. Ejecuta lo siguiente:

docker run --name helloworld hello-world

Esto descargará la imagen del contenedor "hello-world" y la ejecutará dentro de un contenedor Docker, lo que ejecutará el programa e imprimirá el mensaje "Hello From Docker" en la pantalla.

Eliminar el Contenedor de Prueba

Ahora hemos confirmado que nuestra instalación de Docker fue exitosa y no necesitamos más el contenedor "hello-world". Mantengamos todo limpio y eliminémoslo de inmediato escribiendo:

docker rm helloworld

Hemos instalado y probado Docker en nuestro Raspberry Pi y está funcionando perfectamente. ¡Felicidades!

Instalación de Home Assistant en Docker ejecutándose en Raspberry Pi #

Finalmente, tenemos todo listo para instalar Home Assistant. Así que, sin más preámbulos, vamos a ello.

Crear un Directorio para Home Assistant

En el directorio raíz de tu usuario en Raspberry Pi, crea un nuevo directorio y cámbiate a él escribiendo:

mkdir homeassistant && cd homeassistant

Ejecutar Imagen de Docker

Vamos a utilizar una imagen oficial de Home Assistant para Docker ejecutando el siguiente comando. ¡No olvides cambiar la variable TZ a tu zona horaria!

docker run -d \
  --name homeassistant \
  --privileged \
  --restart=unless-stopped \
  -e TZ=Europe/Brussels \
  -v ~/homeassistant:/config \
  --network=host \
  ghcr.io/home-assistant/home-assistant:stable

Asegúrate de que el Contenedor esté Ejecutándose

Después de esperar unos minutos, deberíamos tener Home Assistant ejecutándose dentro de un contenedor Docker en nuestro Raspberry Pi. Para verificar el estado, escribe:

docker ps

Busca el contenedor "homeassistant". Bajo ESTADO (STATUS) deberías ver "Up x seconds/minutes". ¡Parece que nuestro contenedor está en funcionamiento!

Abrir la interfaz web de Home Assistant

Abre el navegador web en tu computadora anfitriona e ingresa la misma dirección IP que usaste para hacer ssh en Raspberry, agregando “:8123” al final. En nuestro caso, sería “http://192.168.129.13:8123”.

Configuración Inicial de Home Assistant

Sigue los pasos de configuración inicial, hasta que llegues al panel de control de Home Assistant. Si necesitas ayuda, puedes seguir la documentación oficial de Home Assistant Onboarding.

¡Felicidades! Ahora tienes Home Assistant funcionando completamente dentro de un contenedor Docker en Raspberry Pi.

Configuración de ESPHome #

Finalmente, vamos a integrar el dispositivo ESP32 con Home Assistant, utilizando ESPHome. Para este paso, necesitaremos una placa ESP32 y un cable USB para conectarla a Raspberry Pi.

Requisitos Previos #

Placa de desarrollo ESP32
Cable USB

Si tienes el ESP32 a tu lado, comencemos. Ah, ¿dónde está ese cable USB...?

Obtener Imagen Docker de ESPHome

Para obtener la imagen Docker de ESPHome, ejecuta el siguiente comando en Raspberry Pi:

docker pull ghcr.io/esphome/esphome

Ejecutar el Asistente de Configuración de ESPHome

Para ayudarte a configurar tu primer proyecto ESP32/ESP8266, ESPHome tiene un asistente de configuración. Para ejecutarlo, escribe el siguiente comando en tu Raspberry Pi:

docker run --rm -v "${PWD}":/config -it ghcr.io/esphome/esphome wizard livingroom.yaml

Sigue el Asistente de Configuración de ESPHome
1. Ingresa el nombre de tu ESP32. Nombraremos nuestro dispositivo 'office'. Ten en cuenta que debe ser un nombre en minúsculas.
2. Ingresa 'ESP32' o 'ESP8266', según la plataforma que estés utilizando. En este caso, estamos usando 'ESP32'.
3. Ingresa el tipo de placa que estás utilizando de la lista proporcionada. Dado que estamos utilizando Wemos D1 mini ESP32, 'esp32dev' funcionará.
4. Ingresa el SSID de WiFi (el nombre) de tu red, donde está conectado el Raspberry Pi.
5. Ingresa la contraseña de WiFi.

Eso es todo. Has completado el asistente de configuración de ESPHome. Deberías ver un nuevo archivo llamado 'office.yaml' creado en Raspberry Pi.

Agregar Entidad LED Incorporada Abre el archivo recién creado 'office.yaml' y agrega lo siguiente al final:

switch:
  - platform: gpio
    name: "Builtin LED"
    pin: 2

La versión final de tu archivo 'office.yaml' debería verse así:

esphome:
  name: office

esp32:
  board: esp32dev
  framework:
    type: arduino

# Enable logging
logger:

# Enable Home Assistant API
api:
  password: ""

ota:
  password: ""

wifi:
  ssid: "<YOUR_WIFI_SSID>"
  password: "<YOUR_WIFI_PASSWORD>"

  # Enable fallback hotspot (captive portal) in case wifi connection fails
  ap:
    ssid: "Office Fallback Hotspot"
    password: "AvQ6HE0YfWw8"

captive_portal:

switch:
  - platform: gpio
    name: "Builtin LED"
    pin: 2

Subir la Configuración a la Placa ESP32

Ejecuta el siguiente comando para verificar tu configuración y, si todo está bien, súbela a tu placa ESP32:

docker run --rm --privileged -v "${PWD}":/config --device=/dev/ttyUSB0 -it ghcr.io/esphome/esphome run office.yaml

Agregar la Integración de ESPHome a Home Assistant

Abre la interfaz web de Home Assistant y ve a Configuración -> Dispositivos y Servicios.

Deberías ver un nuevo dispositivo ESPHome, llamado 'office' en la sección Descubierto. Para que aparezca el nuevo dispositivo ESP32, puede tardar unos minutos. Si no aparece, haz clic en "Agregar Integración", selecciona "ESPHome", ingresa 'office.local' en el campo de host, mantén el puerto '6053' y haz clic en "Enviar".

El dispositivo ESP32, ejecutando ESPHome, ahora está integrado con Home Assistant.

Probar la Integración de la Placa ESP32 con Home Assistant

En la interfaz web de Home Assistant, Configuración -> Dispositivos y Servicios, ahora deberías ver ESPHome en la sección "Configurado". Haz clic en el texto "1 Dispositivo". Bajo Controles deberías ver "LED incorporado", intenta encenderlo y apagarlo. Deberías ver el LED incorporado en tu placa ESP32 parpadeando.

También puedes hacer clic en "Agregar al Tablero" para que el control del LED incorporado esté disponible desde el Resumen en el menú.

¡Felicidades! Hemos terminado nuestro viaje de integración de la placa ESP32, ejecutando ESPHome, con Home Assistant, ejecutándose en un contenedor Docker, que se ejecuta en un Raspberry Pi. ¡¿No es emocionante?!

¿Qué sigue? #

Ahora que tenemos nuestra configuración funcionando, el siguiente paso lógico sería agregar algunos sensores y actuadores a tu placa ESP32 y configurarlos con ESPHome. Eso es exactamente lo que te recomendamos hacer. Tendremos algunas publicaciones sobre eso en el futuro.

Además, es posible que quieras acceder a las funciones de tu hogar inteligente desde fuera de tu red, cuando no estés en casa. Consulta la publicación sobre "Acceso a Home Assistant desde Internet con Cloudflare Tunnel".

O integra un broker MQTT local seguro a Home Assistant con Mosquitto. Consulta la publicación sobre "Broker MQTT Seguro en Contenedores Docker de Raspberry con HASS".

Conclusión #

Después de todo este trabajo, hemos aprendido qué son Home Assistant y ESPHome y por qué deberíamos ejecutarlos en contenedores Docker.

También hemos tenido experiencia práctica e integrado la placa ESP32, ejecutando ESPHome, con Home Assistant, ejecutándose en un contenedor Docker, que se ejecuta en un Raspberry Pi.

La infraestructura que hemos construido en nuestro Raspberry Pi nos ayudará a largo plazo. El contenedor Docker de Home Assistant nos ayudará a administrar nuestro Raspberry Pi. Si tenemos algunos recursos libres, ahora podemos ejecutar fácilmente servicios adicionales, sin temor a romper la configuración de Home Assistant.