Empezar HomeKit con ESP32 cuando no sabes ni qué es Docker

¿Quieres probar HomeKit en un ESP32 pero te abandonan los tutoriales en cuanto mencionan "toolchain" o "container"? Esta guía resuelve exactamente ese problema. No vas a aprender qué es "flashear" porque ya lo sabes: vas a aprender empezando del nivel anterior, qué es un microcontrolador, por qué Docker simplifica todo y qué hace exactamente cada comando que escribes.

Al final de este tutorial vas a tener un LED controlado desde la app Casa de tu iPhone, comprendiendo cada paso. Si nunca usaste Docker, si nunca programaste un ESP32, si la palabra "compilar" te suena vaga, eres exactamente la persona para la que está escrita esta guía.

El cuadro general: qué vas a hacer

En orden, los pasos son:

  1. Instalar Docker Desktop (una "computadora dentro de tu computadora" donde viven las herramientas del ESP32)
  2. Descargar el código HomeKit ya hecho (esp32-homekit-demo)
  3. Configurar tus credenciales WiFi en el código
  4. Compilar el firmware desde dentro de Docker
  5. Flashear el binario al ESP32 con esptool.py
  6. Parear el accesorio en la app Casa

Nada de "tienes que saber esto primero". Cada paso lo explicamos cuando llega.

Qué necesitas

Hardware:

  • ESP32-WROOM-32D (placa de desarrollo con USB y botones, recomendada para principiantes)
  • Cable USB de datos (no de solo carga, esa diferencia es crítica)
  • 1 LED de cualquier color
  • 1 resistencia de 220 Ω a 1 kΩ (cualquiera del rango sirve)
  • 2 jumpers macho a macho
  • Protoboard (recomendado para no soldar)
  • Red WiFi de 2.4 GHz (HomeKit ESP32 no soporta 5 GHz)
  • iPhone o iPad con app Casa

Software:

  • Docker Desktop
  • Git
  • Python 3 + esptool.py

No vas a instalar ESP-IDF manualmente. Docker hace ese trabajo por ti.

Docker explicado en 30 segundos

Docker es como una computadora prearmada que vive dentro de tu computadora. Dentro de esa "minicomputadora" están todas las herramientas del ESP32 ya instaladas y con las versiones correctas. Esto evita el dolor clásico de instalar ESP-IDF: rutas mal configuradas, versiones incompatibles, dependencias rotas.

Diagrama del flujo de Docker: Dockerfile genera una imagen y la imagen corre como contenedor

Instalar Docker Desktop

  1. Descarga desde docker.com/products/docker-desktop
  2. Elige tu sistema operativo: Windows, macOS (Intel o Apple Silicon), Linux
  3. Acepta defaults durante la instalación
  4. Reinicia el computador
  5. Abre Docker Desktop, crea una cuenta gratis y espera el mensaje "Docker is running"

Verifica que funciona abriendo una terminal y corriendo:

Bash 
docker --version

Salida esperada: Docker version 29.x.x. Si dice "command not found", Docker Desktop no está corriendo.

ESP-IDF dentro de Docker

ESP-IDF es el entorno oficial de Espressif (compilador, librerías, herramientas de flasheo). Instalar ESP-IDF a mano es notoriamente frágil: la versión cambia entre tutoriales, los toolchains difieren por sistema operativo y un paso mal hecho rompe todo el flujo.

Por eso usamos la imagen Docker oficial espressif/idf:v5.4. Desglosando el nombre:

  • espressif → la empresa que fabrica el ESP32
  • idf → ESP IoT Development Framework
  • v5.4 → versión exacta congelada (importante para que el tutorial funcione tal como está)

Descarga la imagen:

Bash 
docker pull espressif/idf:v5.4

Terminal ejecutando docker pull espressif/idf v5.4 para descargar la imagen oficial

Verifica:

Bash 
docker images

Deberías ver una línea con espressif/idf v5.4 ~4GB. Eso significa que ESP-IDF está disponible para usar.

Importante: nada se instaló permanentemente en tu sistema. Si algo sale mal, docker rmi espressif/idf:v5.4 lo borra completo, sin daño.

Git y Python

Bash 
git --version
python3 --version

Si Python no está instalado, descarga de python.org/downloads y durante el setup marca Add Python to PATH.

Instala esptool.py:

Bash 
pip3 install esptool

Verifica:

Bash 
esptool.py version

Salida esperada: esptool.py v4.x.

Por qué usamos Python aparte si Docker tiene todo

Buena pregunta. Docker compila el firmware (es ahí donde vive ESP-IDF), pero flashear el firmware requiere acceso al puerto USB del computador, y Docker no expone USB de forma confiable en todos los sistemas operativos. Solución pragmática: build dentro de Docker, flash con esptool.py desde tu computador.

Descargar el código HomeKit

Bash 
git clone --recursive https://github.com/AchimPieters/esp32-homekit-demo.git
cd esp32-homekit-demo

Terminal tras clonar el repositorio esp32-homekit-demo con git clone recursive

Adentro vas a ver carpetas examples/, components/ y un CMakeLists.txt. Eso confirma que estás en el lugar correcto.

Entrar al "taller ESP32" (contenedor Docker)

macOS / Linux:

Bash 
docker run -it -v ~/esp32-homekit-demo:/project -w /project espressif/idf:v5.4

Windows (ajusta la ruta a tu usuario):

Bash 
docker run -it -v C:/Users/TU_USUARIO/esp32-homekit-demo:/project -w /project espressif/idf:v5.4

Qué significa el comando:

  • docker run -it → corre un contenedor interactivo
  • -v ~/esp32-homekit-demo:/project → comparte tu carpeta local con la carpeta /project dentro del contenedor
  • -w /project → define /project como directorio de trabajo
  • espressif/idf:v5.4 → la imagen que vas a usar

Cuando tu prompt cambie, estás dentro del contenedor: ESP-IDF disponible.

Tu primer proyecto: el LED

Bash 
cd examples/led

Define el chip target (esto se hace una vez por proyecto):

Bash 
idf.py set-target esp32

Configura WiFi:

Bash 
idf.py menuconfig

Aparece un menú azul. Navega con flechas + Enter:

  • Entra en StudioPieters
  • Define el SSID WiFi
  • Define la contraseña WiFi
  • Guarda y sale

Compila:

Bash 
idf.py build

Si todo está bien, en build/ aparecen bootloader.bin, partition-table.bin y main.bin.

Conectar el LED al ESP32

El ejemplo está configurado para usar GPIO2. En muchas placas ESP32-WROOM-32D este pin está conectado al LED integrado, pero conviene usar un LED externo para tener claridad visual y poder cambiar de pin después.

Placa programadora StudioPieters con los pines GPIO rotulados, incluido el pin del LED

Recordatorio LED:

  • Pata larga = positivo (+)
  • Pata corta = negativo

Si lo conectas al revés, no pasa nada: simplemente no enciende.

Cableado:

Código 
GPIO2 -> [resistencia 220 a 1k] -> LED (pata larga) -> LED (pata corta) -> GND

Sin la resistencia, el LED se quema. Esto es porque el GPIO entrega ~3.3 V y el LED tolera ~2 V: el exceso lo absorbe la resistencia.

Erase + flash

Sale de Docker (Ctrl+D) para usar esptool.py desde tu sistema.

Borra la flash del ESP32:

Bash 
esptool.py erase_flash

Salida típica:

Código 
Connecting....
Chip is ESP32
Erasing flash...
Serial port /dev/cu.usbserial-01FD1166

Anota el nombre del puerto serial que aparece: lo necesitas para el flasheo y para el monitor.

Ejemplos por sistema operativo:

  • macOS: /dev/cu.usbserial-XXXX o /dev/cu.SLAB_USBtoUART
  • Linux: /dev/ttyUSB0 o /dev/ttyACM0
  • Windows: COM3, COM4, etc.

Si no conecta a la primera (muy común): mantén presionado BOOT, presiona y suelta RESET, suelta BOOT, y vuelve a correr el comando.

Flashea el firmware (ajusta la ruta a build/):

Bash 
python -m esptool --chip esp32 -b 460800 \
  --before default_reset --after hard_reset write_flash \
  --flash_mode dio --flash_size 2MB --flash_freq 40m \
  0x1000 build/bootloader/bootloader.bin \
  0x8000 build/partition_table/partition-table.bin \
  0x10000 build/main.bin

Cuando termina sin errores, el firmware ya está corriendo.

Ver al ESP32 hablar: el monitor serial

Abre una nueva terminal (cierra cualquier sesión que use el mismo puerto). Solo un programa puede usar el puerto serial a la vez.

macOS:

Bash 
screen /dev/cu.usbserial-XXXX 115200

115200 es la velocidad baud rate estándar de ESP-IDF.

Si la terminal queda en negro, presiona RESET en el ESP32. Deberías ver:

  1. Info de boot: chip, memoria, sistema arrancando, prueba que el firmware corre
  2. Conexión WiFi: SSID, IP asignada, prueba que las credenciales son correctas
  3. Logs HomeKit:
Código 
>>> HomeKit: Starting server
>>> HomeKit: Using existing accessory ID: 1F:01:DB:62:5F:6A
>>> HomeKit: Configuring mDNS
>>> homekit_setup_mdns: Accessory Setup ID = 1QJ8
>>> homekit_run_server: Starting HTTP server

En este punto el ESP32 está esperando a que la app Casa lo descubra.

Si WiFi falla: revisa que tu red sea 2.4 GHz, que SSID y password estén exactos (sensible a mayúsculas y tildes) y que el router no tenga aislamiento de clientes activado.

Salir del monitor screen:

  1. Ctrl + A
  2. Tecla K
  3. Tecla Y

Parear el accesorio en Apple Home

Icono de Apple Home sobre fondo azul, la app Casa donde aparecerá tu accesorio ESP32

Confirma:

  • ESP32 prendido y conectado a WiFi (logs OK)
  • iPhone/iPad en la misma red WiFi (HomeKit usa mDNS, no funciona entre VLANs sin bonjour proxy)

Pasos en iPhone:

  1. Abre la app Casa
  2. Toca el botón + arriba a la derecha
  3. Añadir accesorio
  4. Selecciona "Más opciones" → "ESP32 LED" (o como aparezca)
  5. Cuando salga el aviso "Accesorio no certificado", toca Añadir igual (es esperado en hardware DIY)
  6. Asigna nombre y habitación

Listo. Toca el accesorio en la app: el LED debe encender. Toca otra vez: apaga.

Variantes y mejoras

Tres extensiones concretas que no vienen en el tutorial original:

  1. Cambiar de LED a relé para controlar 220 V: reemplaza el LED por un módulo relé optoacoplado de 5 V activado por GPIO2 (con transistor + diodo flyback si vas a usar relé crudo). Quedas con un enchufe inteligente DIY desde la primera práctica. ⚠️ Si vas a manipular 220 V, encierra todo en una caja DIN y consulta a un eléctrico.

  2. Múltiples accesorios desde el mismo ESP32: el framework HomeKit permite registrar varios "services" en un mismo accessory. Combina un LED + un sensor de temperatura DHT22 y el ESP32 aparece como termómetro + luz en una sola entrada de la app Casa.

  3. Reset por botón físico: agrega un pulsador en GPIO0 con pull-up interno. En el firmware, si se mantiene presionado 5 segundos, llama a homekit_server_reset() y reinicia. Eso te permite reparear sin tener que reflashear cuando regalas el accesorio o cambias de red.

Personalización para Chile

Componente Producto en MechatronicStore SKU Precio CLP
Placa ESP32-WROOM-32D con USB C ESP32 ESP-WROOM-32 Tipo C X2-10V2 $7.990
LED 5mm (cualquier color) LED 5mm rojo GA1-5 $100
Resistencia 220 Ω Resistencia 1/4W 220 Ω GK1-18 $100
Protoboard 830 puntos Breadboard MB102 830 puntos C-302 $3.790
Cable USB A a Micro USB Cable USB a Micro USB X3-10 $1.290
Jumpers macho a macho 20cm Cables macho macho 40 piezas 20cm C-411 $1.990

Costo total estimado: ~$15.260 CLP.

Si tienes una placa ESP32 con conector USB C en lugar de Micro USB, usa Cable USB Tipo C a USB Tipo A (SKU B-101, $2.190 CLP). El tutorial funciona igual: solo cambia el cable.

Tip Chile: si tu router es Movistar o Entel con plan combo, asegúrate de tener habilitada la red 2.4 GHz separada de la 5 GHz. Por defecto vienen unificadas como "Smart WiFi" y el ESP32 puede no conectarse. En el panel del router puedes separar las dos redes manualmente.

Recursos

Versión chilena con componentes en stock local en MechatronicStore.