Cómo Integrar un Inversor Solar Enphase con Envoy-S en Home Assistant vía API Local: Guía Paso a Paso

La integración de un inversor solar Enphase con Envoy-S en Home Assistant a través de la API local se ha convertido en una de las prácticas más demandadas por los propietarios de instalaciones fotovoltaicas que buscan un control absoluto sobre su monitorización energética. A diferencia de las soluciones basadas en la nube, la API local ofrece una comunicación directa con el dispositivo, eliminando latencias, dependencias de servidores externos y posibles interrupciones del servicio. En esta guía exhaustiva, exploraremos desde los fundamentos técnicos de la comunicación con el Envoy-S hasta la configuración paso a paso en Home Assistant, incluyendo la instalación del complemento oficial, la autenticación con tokens, la creación de paneles personalizados y la resolución de los errores más comunes. Si deseas llevar tu monitorización solar al siguiente nivel, has llegado al lugar indicado.

Introducción al ecosistema Enphase y la API local

Enphase Energy es uno de los fabricantes de microinversores solares más reconocidos a nivel mundial. Su arquitectura distribuida, en la que cada panel cuenta con su propio microinversor, ofrece ventajas significativas en cuanto a eficiencia, monitorización por panel y tolerancia a sombras. El componente central de comunicación es el Envoy-S, un gateway que recopila los datos de producción de cada microinversor y los envía a la nube de Enphase para su visualización en la aplicación Enlighten. Sin embargo, para los entusiastas de la domótica y la monitorización avanzada, depender exclusivamente de la nube supone una limitación importante. Aquí es donde entra en juego la API local del Envoy-S.

La API local del Envoy-S permite acceder a los datos de producción en tiempo real directamente desde la red local, sin necesidad de conexión a Internet. Esto se traduce en una monitorización más rápida, segura y personalizable. Además, posibilita la integración con sistemas como Home Assistant, lo que abre un abanico de posibilidades: automatizaciones basadas en la producción solar, control de cargas, estadísticas históricas y alertas personalizadas. En los últimos años, la comunidad de Home Assistant ha desarrollado herramientas específicas para facilitar esta integración, destacando el complemento oficial Enphase Envoy, que simplifica enormemente el proceso.

A lo largo de esta guía, asumiremos que ya cuentas con una instalación Enphase operativa y un Envoy-S conectado a tu red local. Si aún no has configurado tu sistema, te recomendamos contactar con tu instalador para asegurarte de que el Envoy-S está correctamente aprovisionado y accesible. Una vez cumplidos los requisitos previos, estarás listo para sumergirte en el mundo de la monitorización local con Home Assistant.

Requisitos previos y preparación del entorno

Antes de comenzar con la integración, es fundamental asegurarse de que se cumplen una serie de requisitos técnicos. En primer lugar, necesitarás tener Home Assistant instalado y funcionando en tu red local. Puede ser una instalación de Home Assistant OS, Supervised, Container o Core, aunque para aprovechar al máximo las funcionalidades, recomendamos Home Assistant OS con el supervisor habilitado, ya que facilita la instalación de complementos. En segundo lugar, tu Envoy-S debe estar conectado a la misma red que Home Assistant, ya sea por Ethernet o Wi-Fi. Es importante verificar que el Envoy-S tenga una dirección IP fija o reservada en tu router para evitar cambios inesperados.

Otro aspecto crítico es la versión de firmware del Envoy-S. Enphase ha ido actualizando el firmware a lo largo del tiempo, y algunas versiones antiguas pueden tener limitaciones en cuanto al acceso local. Las versiones más recientes, como la 7.x o superiores, ofrecen una API local más robusta y documentada. Puedes consultar la versión de firmware en la aplicación Enlighten o accediendo a la interfaz web del Envoy-S. Si tu firmware es anterior a la versión 5.x, es posible que necesites actualizarlo, lo cual se realiza automáticamente si el Envoy-S tiene conexión a Internet.

Además, es recomendable tener a mano el número de serie del Envoy-S, ya que lo necesitarás durante la configuración. También deberás asegurarte de que Home Assistant tiene acceso a la red local y que no hay cortafuegos bloqueando la comunicación entre ambos dispositivos. En entornos empresariales o redes segmentadas, verifica que los puertos necesarios estén abiertos. La API local del Envoy-S utiliza el puerto 80 para HTTP y el 443 para HTTPS, aunque la mayoría de las integraciones funcionan correctamente con HTTP en la red local.

Verificación de la conectividad con el Envoy-S

Para comprobar que el Envoy-S es accesible desde la red local, puedes realizar una prueba sencilla utilizando el comando ping desde una terminal en tu ordenador. Por ejemplo, si la IP del Envoy-S es 192.168.1.100, ejecuta: ping 192.168.1.100. Si recibes respuestas, la conectividad básica está garantizada. A continuación, intenta acceder a la interfaz web del Envoy-S escribiendo http://192.168.1.100 en tu navegador. Deberías ver la página de inicio de sesión del Envoy-S. Si no puedes acceder, revisa la configuración de red o consulta el manual del dispositivo.

Una vez confirmado el acceso, es momento de explorar la API local. La API del Envoy-S expone varios endpoints que devuelven datos en formato JSON. Por ejemplo, el endpoint /api/v1/production proporciona información sobre la producción actual. Puedes probar a acceder a http://192.168.1.100/api/v1/production desde tu navegador. Si el Envoy-S requiere autenticación, es posible que recibas un error 401. En ese caso, necesitarás obtener un token de acceso, que discutiremos más adelante. Por ahora, basta con saber que la API está activa y responde.

Instalación del complemento Enphase Envoy en Home Assistant

Home Assistant cuenta con una integración oficial para Enphase Envoy que facilita enormemente la conexión con la API local. Esta integración se distribuye como un complemento (add-on) que puedes instalar desde la tienda de complementos. Asegúrate de tener habilitado el modo avanzado en tu perfil de usuario para ver todos los complementos disponibles. El complemento se llama "Enphase Envoy" y está mantenido por la comunidad de Home Assistant. Su instalación es sencilla y en pocos minutos tendrás acceso a todos los datos de tu sistema solar.

Para instalar el complemento, sigue estos pasos:

Durante la configuración, el asistente te pedirá que introduzcas la dirección IP del Envoy-S. Si no la conoces, puedes encontrarla en la lista de dispositivos de tu router o utilizando herramientas de escaneo de red como Fing. También te solicitará el número de serie del Envoy-S, que puedes encontrar en una etiqueta en el propio dispositivo o en la aplicación Enlighten. Una vez completados estos pasos, Home Assistant comenzará a recibir datos de producción solar en tiempo real.

Configuración avanzada: autenticación con token y acceso a la API

En algunas versiones de firmware, el Envoy-S requiere un token de autenticación para acceder a la API local. Este token se genera a partir del número de serie del Envoy-S y se utiliza como contraseña en las peticiones HTTP. El complemento de Home Assistant suele gestionar esto automáticamente, pero es útil comprender el proceso por si necesitas realizar ajustes manuales o solucionar problemas. El token se obtiene mediante una llamada a la API de Enphase, pero también puedes generarlo localmente si tienes acceso a la interfaz web del Envoy-S.

Para generar el token manualmente, sigue estos pasos:

• Accede a la interfaz web del Envoy-S: Introduce la IP del Envoy-S en tu navegador y pulsa Enter.
• Inicia sesión: Utiliza las credenciales de instalador. Si no las tienes, prueba con usuario "envoy" y la contraseña que suele ser los últimos seis dígitos del número de serie.
• Navega a la sección de API: Busca la opción "API" o "Local API" en el menú. Allí encontrarás un botón para generar un token.
• Copia el token: Se mostrará una cadena alfanumérica larga. Cópiala y guárdala en un lugar seguro.

Una vez que tengas el token, puedes probar la API local utilizando herramientas como curl. Por ejemplo, para obtener la producción actual, ejecuta: curl -H "Authorization: Bearer TU_TOKEN" http://IP_DEL_ENVOY/api/v1/production. Si todo está correcto, recibirás un JSON con los datos de producción. Este token también se puede introducir en la configuración del complemento de Home Assistant si es necesario.

Creación de paneles y automatizaciones en Home Assistant

Una vez que la integración está configurada, Home Assistant creará automáticamente una serie de entidades relacionadas con tu sistema solar. Estas entidades incluyen sensores de producción actual, energía producida hoy, energía total, potencia por panel (si tienes microinversores individuales), y más. Para aprovechar al máximo estos datos, es recomendable crear un panel de control personalizado. Puedes utilizar la interfaz de Lovelace para arrastrar y soltar tarjetas, o editar el archivo YAML para un control total.

Un panel típico de monitorización solar incluye gráficos de producción a lo largo del día, indicadores de potencia instantánea, y estadísticas históricas. La tarjeta "Gauge" es ideal para mostrar la potencia actual, mientras que la tarjeta "History Graph" permite visualizar la producción de las últimas 24 horas. También puedes utilizar la tarjeta "Energy" para un seguimiento a largo plazo. A continuación, te mostramos un ejemplo de configuración YAML para un panel básico:

type: vertical-stack
cards:
  - type: gauge
    entity: sensor.envoy_current_power_production
    name: Producción actual
    min: 0
    max: 5000
  - type: history-graph
    entities:
      - sensor.envoy_current_power_production
    hours_to_show: 24
  - type: energy
    entity: sensor.envoy_lifetime_energy_production

Además de la visualización, las automatizaciones son otro punto fuerte. Por ejemplo, puedes programar que cuando la producción solar supere un umbral, se encienda un ventilador o se cargue un vehículo eléctrico. O que cuando la producción caiga a cero al atardecer, se activen las luces de la casa. Las posibilidades son infinitas. Para crear una automatización, ve a Configuración > Automatizaciones y escenas > Crear automatización. Selecciona el sensor de producción como disparador y define las acciones deseadas.

Ejemplo práctico: Automatización para aprovechar el excedente solar

Supongamos que tienes un calentador de agua eléctrico y quieres que se active solo cuando haya excedente de producción solar. Puedes crear una automatización que evalúe la diferencia entre la producción solar y el consumo de la casa. Si la producción supera el consumo en más de 500 W durante 5 minutos, se enciende el calentador. Esta automatización no solo ahorra energía, sino que maximiza el autoconsumo. Aquí tienes un ejemplo de código YAML para lograrlo:

alias: Activar calentador con excedente solar
trigger:
  - platform: numeric_state
    entity_id: sensor.envoy_current_power_production
    above: 500
    for: "00:05:00"
condition:
  - condition: numeric_state
    entity_id: sensor.consumo_casa
    below: sensor.envoy_current_power_production
    value_template: "{{ states('sensor.envoy_current_power_production') | float - states('sensor.consumo_casa') | float }}"
action:
  - service: switch.turn_on
    entity_id: switch.calentador

Este es solo un ejemplo; puedes adaptarlo a tus necesidades. La integración con Home Assistant te permite combinar datos solares con cualquier otro dispositivo inteligente de tu hogar, creando un ecosistema verdaderamente inteligente y eficiente.

Errores comunes y solución de problemas

A pesar de que la integración es relativamente sencilla, pueden surgir problemas durante la configuración o el funcionamiento. A continuación, enumeramos los errores más frecuentes y sus soluciones:

Comparativa de métodos de integración: API local vs. nube

Existen varias formas de integrar los datos de Enphase en Home Assistant. La más común es mediante la API local, pero también es posible utilizar la API en la nube de Enphase o incluso servicios de terceros. A continuación, comparamos las características principales de cada método para ayudarte a elegir el más adecuado.