Integración domótica Enphase IQ Gateway, gratuita y de código abierto

Local monitoring of your Enphase IQ Gateway: production, consumption and micro-inverters.

• Publicado por EchoPouet
• Dispositivos
• Versión 1.0.3
• Requiere Gladys >=4.86.0
• ★ 0

Ver en GitHubTodas las integraciones externas

info

La documentación de esta integración la escribe su autor y, por ahora, solo está disponible en inglés.

This integration monitors your Enphase solar installation locally: production, consumption (when a meter is present), battery (when an IQ Battery is installed), the individual production of every micro-inverter, the IQ System Controller and the CT meters.

Prerequisites

• An IQ Gateway with D8+ firmware (November 2023 or later).
• The gateway reachable from the same local network as your Gladys instance.
• A local access token: on the gateway web UI, go to System > Local Access, sign the Enphase agreement and copy the displayed JWT token.

Configuration

1. Install the integration from the Gladys catalog.
2. Enter the gateway local IP address (or click “Detect gateway”, which finds it over mDNS).
3. Paste your local access token.
4. Choose the refresh interval (15 to 600 seconds, 60 by default).
5. Enable “Monitor each micro-inverter” to get one device per inverter.

The integration makes no cloud calls: everything stays on your local network.

Published devices

Values are published in kW / kWh (power / energy), % (battery level), °C (temperature), V (voltage) and A (current), rounded to 3 decimal places maximum.

• One “gateway” device: production (kW), today / last 7 days / lifetime production (kWh), consumption (kW and kWh/day) when a meter exists, and battery (level %, charge/discharge power, remaining energy) when an IQ Battery is installed.
• One device per micro-inverter (when enabled): instantaneous power (kW) and a text status (“Active”, “Offline…”) to spot a failing inverter.
• One device per IQ Battery (Encharge): level (%), temperature (°C), power (kW) and capacity (kWh).
• One “IQ System Controller” device (Enpower): grid mode, temperature (°C) and admin state.
• One device per CT meter: active power (kW), delivered / received energy (kWh), voltage (V) and current (A).

The Encharge, Enpower and CT meter devices are only published when the gateway reports them (automatic detection).

Security: pin the gateway certificate

The gateway uses a self-signed certificate, so the integration cannot cryptographically prove its identity by default. Anyone able to impersonate the gateway on your local network could in theory capture your access token.

Recommended: fill in the “Gateway certificate fingerprint (optional)” field. The integration then only trusts a gateway that presents exactly that certificate — an impostor is rejected (CERT_PIN_MISMATCH) even though TLS validation stays relaxed.

1. From a trusted machine on the same network, read the real gateway's fingerprint:

   openssl s_client -connect <gateway_ip>:443 \
     < /dev/null 2>/dev/null | \
     openssl x509 -noout -fingerprint -sha256

2. Copy the SHA256 Fingerprint=... value into the Gateway certificate fingerprint field.
3. Save — the pin is applied immediately. Case and separator spacing don't matter (the code normalises them).

If the gateway's certificate ever changes (firmware update, hardware replacement), the integration will refuse to connect: re-read the new fingerprint and update the field.

Note: the pin protects every connection made after it is set. Always read the fingerprint from your own, trusted gateway — never through an intermediate source.

Troubleshooting

• “Token refused”: the token is invalid, expired or revoked. Regenerate it in the gateway menu (System > Local Access).
• “Gateway unreachable”: check that the gateway is powered, on the same network, and that the IP is correct (the “Detect gateway” button finds it over mDNS).
• “Detect gateway” finds nothing: the gateway advertises several addresses over mDNS, including IPv6 ones. The integration only keeps a private address (IPv4 first) and never sends the token to a public address — if no private address is advertised, enter the gateway's LAN IP manually.
• No consumption shown: your installation has no consumption meter connected — the integration only publishes data the gateway actually reports.
• Certificate fingerprint rejected: the gateway certificate changed or a device is trying to impersonate the gateway. Re-read the real fingerprint and update the field.
• The transport badge stays local when all is well, and switches to unreachable when the gateway stops answering.

Parámetros de configuración

Estos son los parámetros que Enphase IQ Gateway te pide en su pantalla de configuración en Gladys.

Parámetro	Tipo	Obligatorio	Descripción
Getting started	section	No	Generate a local access token on your IQ Gateway (firmware D8+): from the gateway web UI, go to System > Local Access, sign the Enphase agreement and copy the token. The integration reads it directly on your local network — no cloud account needed.
Gateway IP address	string	Sí	The local IP address of your IQ Gateway, e.g. 192.168.1.42. Use the "Detect gateway" button to find it on your network.
Local access token	secret	Sí	The JWT token generated in the gateway web UI (System > Local Access). It is stored encrypted by Gladys and never sent to the frontend.
Refresh interval (s)	number	No	How often the gateway is polled, in seconds. Production data updates every 5 seconds on the gateway; a 15-60 s poll is a good balance.
Monitor each micro-inverter	boolean	No	Publish one device per micro-inverter with its current production, to spot a failing unit (a dead inverter reports 0 W).
Gateway certificate fingerprint (optional)	string	No	Optional SHA-256 fingerprint of the gateway's certificate (e.g. AB:CD:12:34:…). When set, the integration only trusts a gateway whose certificate matches it — the recommended defense against a device impersonating your gateway on the local network. Get it from your browser's certificate view, or with: openssl s_client -connect <gateway_ip>:443 < /dev/null 2>/dev/null | openssl x509 -noout -fingerprint -sha256.

Cómo instalar Enphase IQ Gateway en Gladys

1. En Gladys, abre Integraciones: Enphase IQ Gateway aparece en el catálogo junto a las integraciones nativas, con una insignia de comunidad.
2. Haz clic en Instalar. Gladys descarga la imagen Docker (ghcr.io/echopouet/gladys-enphase:1.0.3), la ejecuta en un entorno aislado del núcleo y genera la interfaz de la integración (dispositivos, descubrimiento y configuración).
3. Abre la pantalla de Configuración de la integración, rellena los parámetros y guarda.
4. También puedes instalarla directamente desde la URL de su repositorio: https://github.com/EchoPouet/gladys-enphase.

Enphase IQ Gateway requiere Gladys >=4.86.0. El catálogo de Gladys se actualiza cada hora, así que una nueva versión está disponible como máximo una hora después de publicarse.

¿Todavía no usas Gladys? Es gratuito y de código abierto: sigue la guía de instalación para empezar.

Sobre las integraciones externas

Enphase IQ Gateway es una integración externa: una integración comunitaria empaquetada como contenedor Docker y publicada en GitHub. Gladys la instala con un clic y la ejecuta en un entorno aislado del núcleo. La publica y mantiene EchoPouet, no el equipo principal de Gladys.

• Explorar todas las integraciones externas
• Descubrir las integraciones nativas incluidas en Gladys
• Crear y publicar tu propia integración externa
• Código fuente en GitHub — fuente de esta documentación

Suscríbete a la newsletter de Gladys Assistant

Unos pocos correos al mes sobre nuevas versiones y novedades del proyecto. Enviados por Pierre-Gilles Leymarie, fundador del proyecto. Puedes darte de baja cuando quieras 🙂