Cómo Integrar un Inversor Solar Enphase en Home Assistant con Modbus TCP: Guía Paso a Paso

La integración de un inversor solar Enphase en Home Assistant mediante Modbus TCP se ha convertido en una de las prácticas más demandadas por los entusiastas de la domótica y la eficiencia energética. A diferencia de otras soluciones propietarias, el protocolo Modbus TCP ofrece un acceso directo y local a los datos de generación, consumo y estado del sistema, sin depender de la nube del fabricante. Esto no solo garantiza una privacidad total y una latencia mínima, sino que también abre un abanico infinito de posibilidades para automatizar el consumo de energía en función de la producción solar. En esta guía exhaustiva, te acompañaremos paso a paso desde los conceptos teóricos hasta la implementación práctica, incluyendo la configuración del gateway Enphase IQ Envoy, la instalación de la integración en Home Assistant, la creación de sensores personalizados y la resolución de los errores más comunes. Si buscas llevar tu instalación fotovoltaica al siguiente nivel, has llegado al lugar indicado.

Fundamentos Técnicos de Enphase y Modbus TCP

Antes de sumergirnos en la configuración, es crucial comprender la arquitectura de comunicación que hace posible esta integración. Los sistemas Enphase, especialmente los basados en microinversores de las series IQ7 e IQ8, utilizan un dispositivo central llamado IQ Envoy o IQ Gateway. Este gateway actúa como un puente entre los microinversores instalados en el tejado y la red local. Tradicionalmente, Enphase ofrece una API en la nube para monitorizar la producción, pero esta depende de una conexión a Internet y de los servidores del fabricante. El protocolo Modbus TCP, en cambio, permite consultar los registros internos del gateway directamente a través de la red local, utilizando el puerto 502. Esto significa que los datos fluyen instantáneamente desde el gateway a tu servidor de Home Assistant, sin intermediarios. Los registros Modbus contienen información valiosa como la potencia instantánea de cada panel, la energía total generada, el voltaje de la red, la frecuencia y el estado de los relés de control. La clave está en que Enphase implementa un servidor Modbus TCP en el propio gateway, lo que facilita la lectura de estos registros mediante bibliotecas estándar. Es importante destacar que no todos los modelos de Envoy soportan Modbus TCP de la misma manera; los modelos más antiguos, como el Envoy-S Metered, requieren una configuración específica, mientras que los IQ Gateway más recientes lo incluyen de serie. A lo largo de esta guía, asumiremos que cuentas con un IQ Gateway compatible y con acceso a la red local.

El Papel del Gateway IQ Envoy

El IQ Envoy es el cerebro del sistema Enphase. Se encarga de recopilar los datos de cada microinversor a través de la tecnología Power Line Communication (PLC) y de gestionar la comunicación con la nube. Para nuestra integración, lo configuraremos para que también exponga esos datos a través de Modbus TCP. Es fundamental que el gateway esté conectado a la misma red local que Home Assistant, ya sea por Ethernet o Wi-Fi. Además, necesitaremos conocer su dirección IP, que podemos obtener desde el router o desde la aplicación Enphase Installer Toolkit. Una vez que tengamos la IP, podremos probar la conectividad utilizando herramientas como Modbus Poll o simplemente desde la terminal con el comando `nc -zv 502`. Si el puerto está abierto, estaremos listos para el siguiente paso. Es recomendable asignar una IP estática al gateway para evitar que cambie y rompa la integración. También es importante verificar la versión de firmware del Envoy, ya que Enphase ha ido habilitando Modbus TCP en diferentes versiones. En general, los firmwares superiores a la versión 5.0 lo soportan de forma nativa, pero en algunos casos puede ser necesario habilitarlo mediante la herramienta de instalador.

Ventajas de Modbus TCP frente a la API en la Nube

La principal ventaja de utilizar Modbus TCP es la independencia de la nube. Con la API en la nube, los datos se actualizan cada 5 o 15 minutos, y dependes de la disponibilidad de los servidores de Enphase. Con Modbus TCP, los datos se actualizan cada segundo o incluso más rápido, lo que te permite reaccionar casi en tiempo real a los cambios en la producción solar. Esto es especialmente útil para automatizaciones que requieren un control preciso, como encender un termo eléctrico cuando la producción supera un umbral, o cargar un vehículo eléctrico con excedentes. Además, al ser local, no consumes ancho de banda de Internet ni expones tus datos a terceros. La privacidad es total. Otra ventaja es la fiabilidad: aunque se caiga Internet, la comunicación entre Home Assistant y el Envoy sigue funcionando, por lo que tus automatizaciones críticas no se verán afectadas. Por último, Modbus TCP es un protocolo estándar y ampliamente documentado, lo que facilita la integración con otras herramientas y lenguajes de programación.

Guía Paso a Paso para la Integración en Home Assistant

Una vez que tenemos claro el marco teórico, procedamos a la implementación práctica. Home Assistant ofrece varias vías para integrar dispositivos Modbus: la integración nativa `modbus`, la integración personalizada `enphase_envoy` (disponible a través de HACS) o el uso de Node-RED. En esta guía nos centraremos en la integración nativa `modbus`, que es la más flexible y no requiere dependencias externas, aunque también mencionaremos la integración personalizada por su simplicidad. El proceso se divide en varias etapas: preparación del gateway, configuración en Home Assistant, definición de sensores y creación de automatizaciones.

Paso 1: Preparación del Gateway Enphase

Antes de tocar Home Assistant, debemos asegurarnos de que el gateway Enphase está listo para aceptar conexiones Modbus TCP. Sigue estos pasos:

• Accede al Envoy: Conecta tu ordenador o móvil a la misma red que el Envoy. Abre un navegador y escribe la dirección IP del Envoy (por ejemplo, http://192.168.1.100). Deberías ver la página de inicio de Enphase. Si no la conoces, puedes usar la aplicación Enphase Installer Toolkit para escanear la red.
• Habilita Modbus TCP: En algunos modelos, Modbus TCP viene deshabilitado por defecto. Para habilitarlo, necesitas iniciar sesión como instalador. El usuario por defecto es 'installer' y la contraseña suele ser la última parte del número de serie del Envoy. Una vez dentro, busca la sección de 'Configuración avanzada' o 'Modbus' y activa la opción 'Modbus TCP'. Si no encuentras esta opción, consulta la documentación de Enphase o contacta con soporte.
• Verifica la conectividad: Desde tu ordenador, abre una terminal y ejecuta `telnet 502`. Si la conexión se establece, verás una pantalla en blanco o un mensaje de bienvenida. Si no, revisa el firewall o la configuración de red.

Paso 2: Configuración de la Integración Modbus en Home Assistant

Home Assistant tiene una integración nativa para Modbus que se configura a través del archivo `configuration.yaml`. A diferencia de otras integraciones, no se añade desde la interfaz gráfica, sino que requiere editar el archivo de configuración. A continuación, te mostramos cómo hacerlo:

Abre el archivo `configuration.yaml` (puedes usar el add-on File Editor o Visual Studio Code). Añade el siguiente bloque:

modbus:
  - name: Enphase Envoy
    type: tcp
    host: 192.168.1.100  # Reemplaza con la IP de tu Envoy
    port: 502
    sensors:
      - name: Producción Solar Instantánea
        unique_id: enphase_produccion_instantanea
        slave: 1
        address: 40084
        input_type: holding
        data_type: uint32
        unit_of_measurement: W
        device_class: power
        state_class: measurement
        scale: 1
        precision: 0
      - name: Energía Solar Hoy
        unique_id: enphase_energia_hoy
        slave: 1
        address: 40001
        input_type: holding
        data_type: uint32
        unit_of_measurement: Wh
        device_class: energy
        state_class: total_increasing
        scale: 1
        precision: 0

En este ejemplo, hemos definido dos sensores: uno para la producción instantánea (en vatios) y otro para la energía generada hoy (en vatios-hora). Los registros Modbus utilizados son 40084 y 40001 respectivamente, que son los estándar para los Envoy IQ. Es importante que verifiques las direcciones de registro, ya que pueden variar ligeramente entre modelos. La opción `slave: 1` se refiere al ID del esclavo Modbus, que en Enphase suele ser 1. El `input_type: holding` indica que leemos registros de tipo holding. El `data_type: uint32` especifica que el registro es un entero sin signo de 32 bits. La `scale` se utiliza para convertir unidades si es necesario; en este caso, 1 porque los registros ya están en las unidades deseadas. Una vez guardado el archivo, reinicia Home Assistant para que los cambios surtan efecto. Puedes comprobar que los sensores se han creado yendo a Configuración > Dispositivos y Servicios > Entidades y buscando los nombres que definiste.

Paso 3: Uso de la Integración Personalizada Enphase Envoy (Alternativa)

Si prefieres una solución más sencilla y no quieres lidiar con registros Modbus, existe una integración personalizada llamada `enphase_envoy` que se puede instalar a través de HACS (Home Assistant Community Store). Esta integración detecta automáticamente el Envoy y crea todos los sensores relevantes sin necesidad de especificar direcciones. Para instalarla, sigue estos pasos:

1. Asegúrate de tener HACS instalado en tu Home Assistant.
2. Ve a HACS > Integraciones > Explora y repositorios, y busca 'Enphase Envoy'.
3. Instala la integración y reinicia Home Assistant.
4. Ve a Configuración > Dispositivos y Servicios > Añadir integración y busca 'Enphase Envoy'.
5. Introduce la IP del Envoy y las credenciales (usuario y contraseña). Normalmente, el usuario es 'envoy' y la contraseña es la última parte del número de serie.
6. La integración creará automáticamente sensores para la producción, el consumo, la energía importada/exportada, etc.

Esta integración utiliza la API local del Envoy, que también es local y no depende de la nube. Es una excelente opción si no necesitas un control tan granular sobre los registros Modbus. Sin embargo, para usuarios avanzados que quieran acceder a registros específicos no cubiertos por la integración, Modbus TCP sigue siendo la mejor opción.

Sensores y Automatizaciones Avanzadas

Una vez que los datos fluyen hacia Home Assistant, el verdadero potencial se despliega. Podemos crear sensores personalizados que combinen información de varias fuentes, como el consumo de la casa y la producción solar, para calcular el excedente. También podemos definir automatizaciones que aprovechen ese excedente para alimentar cargas controlables. A continuación, exploramos algunas ideas.

Creación de Sensores de Excedente y Consumo Neto

Para saber cuánta energía estamos exportando a la red o importando de ella, necesitamos un sensor de consumo neto. Si tenemos un medidor de consumo en el Envoy (como el CT opcional), podemos leerlo directamente. Si no, podemos calcularlo restando la producción solar del consumo total de la casa. Para ello, necesitamos un sensor de consumo total, que puede venir de otro dispositivo (por ejemplo, un Shelly EM) o del propio Envoy si está equipado con pinzas de corriente. Supongamos que tenemos un sensor `sensor.consumo_casa` en vatios. Podemos crear un sensor de plantilla que calcule el excedente:

template:
  - sensor:
      - name: 'Excedente Solar'
        unique_id: excedente_solar
        unit_of_measurement: 'W'
        device_class: power
        state_class: measurement
        state: >
          {% set produccion = states('sensor.produccion_solar_instantanea') | float(0) %}
          {% set consumo = states('sensor.consumo_casa') | float(0) %}
          {{ (produccion - consumo) | round(0) }}

Este sensor nos dirá en todo momento si estamos exportando (valor positivo) o importando (valor negativo). Con esta información, podemos activar dispositivos cuando el excedente supere cierto umbral.

Automatizaciones para Aprovechar el Excedente

Imagina que quieres calentar el agua de tu termo eléctrico utilizando solo el excedente solar. Puedes crear una automatización que encienda el termo cuando el excedente sea mayor que la potencia del termo (por ejemplo, 1500 W) durante al menos 5 minutos, y que lo apague cuando el excedente caiga por debajo de 500 W. Aquí tienes un ejemplo de automatización en YAML:

automation:
  - alias: 'Encender termo con excedente solar'
    trigger:
      - platform: numeric_state
        entity_id: sensor.excedente_solar
        above: 1500
        for: '00:05:00'
    action:
      - service: switch.turn_on
        target:
          entity_id: switch.termo_electrico
  - alias: 'Apagar termo si no hay excedente'
    trigger:
      - platform: numeric_state
        entity_id: sensor.excedente_solar
        below: 500
        for: '00:02:00'
    action:
      - service: switch.turn_off
        target:
          entity_id: switch.termo_electrico

Este es solo un ejemplo. Puedes aplicar la misma lógica para cargar un coche eléctrico, encender una bomba de piscina, o incluso regular la velocidad de un ventilador. La integración con Modbus TCP te permite reaccionar en segundos, maximizando el autoconsumo.

Errores Comunes y Soluciones

A pesar de que la integración es relativamente sencilla, los usuarios noveles suelen encontrarse con una serie de problemas recurrentes. A continuación, enumeramos los más habituales y cómo resolverlos.

Otro error frecuente es la incorrecta definición de los registros. Si los valores son absurdos (por ejemplo, 4294967295), probablemente estés leyendo un registro de 32 bits como dos de 16 bits. En ese caso, ajusta el `data_type` a `uint32` o `int32` según corresponda. También es posible que el orden de los bytes esté invertido; Modbus puede utilizar big-endian o little-endian. Home Assistant permite especificar `swap: byte` o `swap: word` para corregirlo. Si los sensores no se actualizan, revisa el intervalo de escaneo (`scan_interval`); por defecto es 30 segundos, pero puedes reducirlo a 5 segundos si necesitas más frecuencia. No obstante, ten cuidado de no sobrecargar el Envoy con demasiadas peticiones.

Por último, si utilizas la integración personalizada, es posible que te encuentres con problemas de autenticación. La contraseña del Envoy suele ser la última parte del número de serie, pero en algunos modelos es necesario generarla a través de la herramienta de instalador. Si no puedes acceder, prueba con el usuario 'envoy' y la contraseña que aparece en la etiqueta del dispositivo.

Comparativa de Métodos de Integración

Para ayudarte a elegir el método más adecuado, hemos preparado la siguiente tabla comparativa:

Como se puede observar, Modbus TCP ofrece el mayor control pero requiere más esfuerzo inicial. La integración personalizada es un buen equilibrio para la mayoría de usuarios. La API en la nube solo se recomienda si no te importa la dependencia externa.

Preguntas Frecuentes

Conclusión y Recomendaciones Finales

La integración de un inversor Enphase en Home Assistant mediante Modbus TCP es una excelente manera de tomar el control de tu instalación solar. Te permite acceder a datos en tiempo real, crear automatizaciones inteligentes y reducir tu dependencia de la nube. A lo largo de esta guía hemos cubierto desde los fundamentos técnicos hasta la implementación práctica, incluyendo la configuración del gateway, la definición de sensores, la creación de automatizaciones y la resolución de errores comunes. Si eres un usuario principiante, te recomendamos empezar con la integración personalizada Enphase Envoy, que es más sencilla y rápida de configurar. Si eres un usuario avanzado y necesitas acceso a registros específic