Enphase IQ Gateway Setup

An Enphase system reports through its IQ Gateway, also called the Envoy. The microinverters and IQ Batteries report to the gateway and have no network connection of their own. Home Assistant connects to the gateway through the built-in Enphase Envoy integration and reads it over the local network. The Enphase cloud is only used to get the access token, when the integration is added and when the token is renewed each year.

Before You Start

1. The system is commissioned. The solar installer sets up the gateway and its meters. Home Assistant only reads what the gateway was configured to measure.
2. Check which meters are fitted. Solar production is available on every gateway with microinverters. House consumption and grid import and export need a metered gateway with consumption current transformers (CTs), installed as Load with Solar (net consumption) for grid data. Ask the solar installer, or look for consumption data in the Enphase app.
3. Get the homeowner’s Enphase account. On gateway firmware 7 and later, Home Assistant needs the email and password of the Enphase account the system is registered to. Find out whether the account uses multi-factor authentication: see Accounts With Multi-Factor Authentication .
4. Connect the gateway once. Use Ethernet or Wi-Fi, not both. On both, Home Assistant’s discovery alternates between the two addresses and the connection drops roughly every 30 minutes.
5. Reserve its IP address. Reserve the gateway’s address in the router.

Step 1: Add the Gateway to Home Assistant

1. Go to Settings > Devices & Services. The gateway usually appears under Discovered as Enphase Envoy. Select Add. If it is not there, select Add Integration, search for Enphase Envoy, and enter its IP address.
2. Enter the Enphase account Username (its email) and Password. On firmware before 7, enter installer as the username and leave the password empty.
3. Assign the gateway to an area.

Home Assistant uses the account to get a one-year token from Enphase, and renews it 30 days before it expires. Setup fails if the Enphase website cannot be reached at that moment: retry later.

The gateway appears with its production sensors, one device for each microinverter, and the consumption, grid, and battery sensors its meters support. Home Assistant reads the gateway every 60 seconds. Each microinverter reports to the gateway only every 5 to 15 minutes, so its own sensors change more slowly.

Accounts With Multi-Factor Authentication

Signing in with the username and password fails when the Enphase account uses multi-factor authentication. Enter a token instead:

1. Sign in to the Enphase token portal with the Enphase account, select the system and its gateway, and create a token.
2. In the Home Assistant setup form, check Enter the Envoy access token manually and select Submit.
3. Paste the token and submit.

A manual token is not renewed. Home Assistant raises a repair 30 days before it expires: create a new token, then open the Enphase Envoy entry and select Reconfigure from its menu (⋮) to paste it.

Step 2: Set Up the Energy Dashboard

Go to Settings > Dashboards > Energy and add:

• Solar production: Envoy serial Lifetime energy production. Use the lifetime sensor rather than Energy production today, which some firmware versions reset late or report wrongly.
• Grid consumption and Return to grid, with net-consumption CTs: Envoy serial Lifetime net energy consumption and Envoy serial Lifetime net energy production.
• Home battery storage, with IQ Batteries and a storage CT: Envoy serial Lifetime battery energy charged and Lifetime battery energy discharged.

Compare the grid values with the utility meter for a few days: mismatches have been reported. With Load only consumption CTs, the gateway reports only a balanced grid value, which needs template helpers to split into import and export. A separate energy monitor at the panel is simpler.

Use It With Solar-Surplus EV Charging

The Solar Surplus EV Charging recipe uses these sensors:

• Solar production: Envoy serial Current power production.
• Grid power (optional): Envoy serial Current net power consumption, which is positive when the house imports from the grid. It needs net-consumption CTs.
• Home battery charge (optional): Envoy serial Battery, the charge level of the IQ Batteries.

Home Assistant reads the gateway once a minute, so keep the recipe’s hold time at its default of 3 minutes or more. A shorter hold time can act on a single reading.

IQ Batteries

Home Assistant shows the batteries’ charge level, available energy, and reserve level. Since gateway firmware 8.2.4225, it cannot change the battery mode, the reserve level, or charging from the grid: the local API no longer allows it. Make those changes in the Enphase app.

Network Access

• From Home Assistant to the gateway: HTTPS (TCP 443) on firmware 7 and later, HTTP (TCP 80) before.
• From Home Assistant to the internet: HTTPS to enlighten.enphaseenergy.com and entrez.enphaseenergy.com when the integration is added and when the token is renewed.
• From the gateway to the internet: keep it open. The gateway reports to Enphase, which feeds the Enphase app and the solar installer’s monitoring, and receives its firmware updates that way.

Discovery uses mDNS, which does not cross VLANs on its own. On a separate IoT network, add the gateway by its IP address.

Troubleshooting

1. Setup fails with an authentication error. Check the account email and password in the Enphase app. An error mentioning session_id or multi-factor authentication means the account uses it: enter a token instead.
2. Grid or consumption sensors are missing. The gateway has no consumption CTs, or they are installed as Load only. In that case the gateway still reports house consumption, but only a balanced grid value, disabled by default, that the Energy dashboard cannot use directly.
3. Data stops for a while around 11 PM. The gateway runs maintenance tasks then, and requests can fail. Readings come back on their own, at sunrise for some production sensors.
4. Lifetime production drops by about 1.2 MWh. Some firmware versions do this, reportedly when one microinverter’s internal counter rolls over. The community Correct Envoy lifetime production energy blueprint creates a corrected sensor to use in the Energy dashboard instead.
5. Lots of inverter sensors are missing. With more than 49 microinverters, the gateway only reports power for each one, not voltage, current, or temperature.