Skip to main content

Enphase IQ Gateway integration for Gladys Assistant

Enphase IQ Gateway integration for Gladys Assistant

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

View on GitHubAll external integrations

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.

Configuration settings​

These are the settings Enphase IQ Gateway asks for in its configuration screen in Gladys.

SettingTypeRequiredDescription
Getting startedsectionNoGenerate 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 addressstringYesThe 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 tokensecretYesThe 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)numberNoHow 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-inverterbooleanNoPublish one device per micro-inverter with its current production, to spot a failing unit (a dead inverter reports 0 W).
Gateway certificate fingerprint (optional)stringNoOptional 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.

How to install Enphase IQ Gateway in Gladys​

  1. In Gladys, open Integrations: Enphase IQ Gateway appears in the catalog, next to the native integrations, with a community badge.
  2. Click Install. Gladys pulls the Docker image (ghcr.io/echopouet/gladys-enphase:1.0.2), starts it in a sandbox isolated from the core, and generates the integration's interface (devices, discovery and configuration).
  3. Open the Configuration screen of the integration, fill in the settings, and save.
  4. You can also install it directly from its repository URL: https://github.com/EchoPouet/gladys-enphase.

Enphase IQ Gateway requires Gladys >=4.86.0. The catalog inside Gladys refreshes every hour, so a new version becomes available at most one hour after its release.

Not running Gladys yet? It is free and open source: follow the installation guide to get started.

About external integrations​

Enphase IQ Gateway is an external integration: a community integration packaged as a Docker container and published on GitHub, that Gladys installs in one click and runs in a sandbox isolated from its core. It is published and maintained by EchoPouet, not by the Gladys core team.

Subscribe to the Gladys Assistant newsletter

A few emails per month about new releases and project news. Sent by Pierre-Gilles Leymarie, founder of the project. Unsubscribe anytime 🙂
Last updated on