ESPHome · Troubleshooting
ESPHome Bluetooth Proxy: fallos comunes y cómo arreglarlos
Si tu proxy Bluetooth de ESPHome no detecta dispositivos o se queda sin conexión, aquí están las causas que se repiten en los hilos de Reddit, en GitHub y en el foro de Home Assistant, y cómo las arreglo. No es un tutorial de montaje: para eso tienes la guía de configuración del Bluetooth Proxy. Esto es lo que haces cuando ya está montado y no funciona.
Antes de tocar nada: comprueba lo básico
- La integración Bluetooth de Home Assistant tiene que estar activa. El proxy ESP32 anuncia los dispositivos que ve, pero es la integración de HA la que los recoge y los convierte en entidades. En algunos hilos el fallo era solo que no estaba cargada.
- El proxy debe aparecer como dispositivo en la integración ESPHome. Si no sale, revisa que el ESP32 está en la misma red y que el `api:` de ESPHome acepta la conexión.
- La alimentación importa. Un ESP32 que se reinicia solo al empezar a escanear suele estar pidiendo más corriente de la que le da el puerto o la fuente. Prueba con otro cable y otro puerto antes de culpar al firmware.
Los fallos más repetidos y su solución
| Síntoma | Causa probable | Solución |
|---|---|---|
| No aparece ningún dispositivo BLE | Integración Bluetooth de HA no cargada, o proxy no descubierto | Activa la integración Bluetooth en HA y comprueba que el ESP32 aparece en la integración ESPHome. Reinicia HA si el proxy se descubrió a medias. |
| Equipos detectados al arrancar y luego unavailable a los pocos minutos | Bug de versiones viejas de ESPHome/HA, o conflicto de conexiones activas | Actualiza ESPHome a la última estable (la 2026.10.1 corrige el release de conexiones retenidas) y HA a 2026.11. Si persiste, usa un adaptador Ethernet en vez de WiFi. |
| El proxy va lento o se calienta | Parámetros de escaneo agresivos o CPU saturada | Deja los parámetros de escaneo por defecto; cambiarlos no suele aportar nada y sí sobrecalienta el ESP32. |
| Error de API: “Can’t connect to ESPHome API” | mDNS fallando, IP cambiada o firewall local | Usa una IP fija para el ESP32, revisa que el hostname se resuelve y que el puerto 6053 está abierto en la LAN. Prueba a conectarte desde el Device Builder de ESPHome. |
| No detecta dispositivos lejanos o tras una pared | Antena integrada del ESP32 insuficiente | Usa una placa con antena externa (como Olimex ESP32-PoE-ISO-EA) o coloca el proxy más cerca del dispositivo BLE. |
Memoria: Arduino vs ESP-IDF
La pila Bluetooth consume mucha memoria. En los hilos de Reddit sobre proxies BLE se repite que la implementación de Arduino consume más memoria que ESP-IDF en el ESP32. Si compilaste tu proxy con el framework de Arduino y ves reinicios o el dispositivo no arranca, prueba a cambiar la plataforma del ESP32 de `arduino` a `esp-idf` en la configuración de ESPHome. No es un ajuste mágico, pero en placas con poca RAM libre marca la diferencia.
Parámetros de escaneo: no los toques salvo que sepas lo que haces
La documentación oficial de ESPHome lo dice claro: los parámetros por defecto de escaneo son los recomendados para la mayoría de usuarios. Cambiar `interval` o `window` normalmente no aporta beneficio y sí aumenta el uso de CPU y el tráfico. Un escaneo demasiado agresivo puede sobrecalentar proxies PoE y desestabilizar el WiFi de los que van por red inalámbrica. Si no estás diagnosticando un problema muy concreto, deja esos valores como vienen.
Red y antena: Ethernet y antena externa
El propio manual de ESPHome recomienda, para mejores resultados, usar una placa con Ethernet para descargar el módulo de radio del ESP32 del tráfico WiFi. Si tu proxy va por WiFi y notas cortes, pasar a una placa PoE con antena externa (por ejemplo, Olimex ESP32-PoE-ISO-EA en lugar de una Olimex ESP32-PoE-ISO) suele resolver los problemas de alcance y estabilidad. El cable no es solo comodidad: es una radio menos compitiendo por el aire.
El error de API y la conexión a Home Assistant
Uno de los hilos más recientes del foro (febrero de 2026) muestra un patrón: el proxy había funcionado sin problemas y, de repente, dejó de conectar con el error Can't connect to ESPHome API. Cuando eso pasa, la causa casi nunca está en el YAML del proxy, sino en la red: la IP del ESP32 cambió por DHCP, mDNS dejó de resolver, o el firewall de la LAN bloquea el puerto 6053. Asigna una IP fija o reserva DHCP, verifica con ping y con el Device Builder antes de reflashear.
Si el proxy sigue sin ir después de pasar por todo esto, vuelve a la guía de configuración y revisa el YAML pieza por pieza. A veces un `board:` mal escrito o un `framework:` que no corresponde deja el dispositivo sin pila BLE y sin un error claro en el log.
Suscríbete
Cada domingo un YAML nuevo ya probado y el aviso cuando una integración local se rompe tras actualizar. Lo prometido existe: mira las plantillas YAML.