Enphase Envoy

An integration for the Enphase Envoy solar energy gateway. This integration works with older models that only have production metrics (ie. Envoy-C) and newer models that offer both production and consumption metrics (ie. Envoy-S).

Prerequisites

• The Envoy must be configured and commissioned.
• The Envoy must be on your local network with IPV4 connectivity from Home Assistant.
• Envoy firmware version 3.9 or newer.
• With Envoy firmware 7 and greater
  • an Enlighten cloud username and password.
  • Home Assistant 2023.9 or newer.

Configuration

To add the Enphase Envoy integration to your Home Assistant instance, use this My button:

Enphase Envoy can be auto-discovered by Home Assistant. If an instance was found, it will be shown as Discovered. You can then set it up right away.

Capabilities

This integration will offer various sensors depending on the configuration of your Enphase system. Sensors are available for the following:

• Current energy production & consumption
• Historical energy production & consumption
• Power production per-inverter

Consumption sensors require your Envoy to be properly configured with consumption CT sensors installed.

With current transformers

For Envoy S Metered / IQ Gateway Metered with installed and configured current transformers (CT), additional features are available:

• Sensors for net production (grid export) and net consumption (grid import) if the consumption CT is a net-consumption CT.

• Disabled sensors for:

  • Balanced net power consumption and lifetime balanced net energy consumption (grid import - grid export) if either a net-consumption or total-consumption CT is installed. The balanced net power consumption value is calculated by the Envoy if a total-consumption CT is used. When a net-consumption CT is installed, it is the same value as the current net power consumption, which is enabled by default if the CT is present.
  • Production and consumption sensors for each phase, if CT are installed on more than 1 phase.
  • Phase net production and net consumption, if CT are installed on more than 1 phase.
  • Frequency for production and net consumption CT (aggregate and phase).
  • Voltage for production and net consumption CT (aggregate and phase).¹
  • Current for production and net consumption CT (aggregate and phase).¹
  • Powerfactor for production and net consumption CT (aggregate and phase).¹
  • Metering status for net consumption and production CT (normal | not-metering | check-wiring) (aggregate and phase).
  • Count of meter status flags active for net consumption and production CT (aggregate and phase).²

With batteries

For Enphase Ensemble systems with the Enpower/IQ System Controller and Encharge/IQ Batteries installed, additional features are available:

• Sensors for battery status and usage
• Sensors for grid status *
• Sensors for the state of the Enpower’s four load-shedding relays *
• A switch allowing you to take your system on-grid and off-grid. Note that the Enpower has a slight delay built-in between receiving these commands and actually switching the system on or off grid. *
• A switch allowing you to enable or disable charging the Encharge/IQ batteries from the power grid. **
• Support for changing the battery storage mode between full backup, self-consumption, and savings mode, and setting the reserve battery level for outages. **
• If a storage CT is installed:
  • Sensors for battery storage energy charged and discharged and current active power discharge/charge
  • Disabled sensors for:
    • Phase battery storage energy charged and discharged and current power discharge/charge
    • Voltage for storage CT (aggregate and phase)
    • Current for storage CT (aggregate and phase)
    • Frequency for storage CT (aggregate and phase)
    • Powerfactor for storage CT (aggregate and phase)
    • Metering status for storage CT (aggregate and phase)
    • Count of meter status flags active storage CT (aggregate and phase)

*: The load shedding and on/off-grid functions are only available with the Enpower/IQ System Controller installed. In battery installations without load-shedding and off-grid functionality, used in many EU countries, these sensors and switches are not available.

**: When used with Enpower/IQ System Controller, the entities to charge from the grid, battery storage mode, and reserve battery level are connected to the Enpower device with the Enpower serial number in their entity and unique IDs. When no Enpower is installed, these are connected to the Envoy itself and the Envoy serial number is used in the IDs.

In multiphase installations with batteries, in countries with phase-balancing grid meters, the battery will export to the grid on one phase the amount it lacks on another phase which pulls the amount from the grid, as if it is using the grid as a ‘transport’ between phases. Since the grid meter will balance the amount imported and exported on the two phases, the net result is zero. The Envoy multiphase consumption CTs, however, will report the amounts on both phases, resulting in too high export on one and too high import on the other. One may consider using the lifetime balanced net energy consumption which is the sum of grid import and export to eliminate this effect. This would require some templating to split these values into import and export values. Alternatively, use the current net power consumption or balanced net power consumption with a Riemann integral sum helper.

Envoy authentication requirements

For newer models running firmware 7 and greater, you will need your Enlighten cloud username and password. The integration will use these credentials to obtain an Envoy access token from the Enlighten cloud.

For models running firmware 5 and older, use installer for the username. No password is required. The integration will automatically detect the installer password.

Enpower load shedding relays

The Enphase Enpower has 4 load shedding relays that can be used to control non-essential loads in your home. These have two main modes of operation:

Standard

When the mode entity is set to standard, you can simply set the state of the relay to be powered or not powered for each mode of operation: on grid, off grid, and on generator.

Battery level

When the relay mode is set to battery level, the relays will turn on and off based on the remaining battery level of your Encharge batteries. Two number entities are available to control the cutoff and restore levels for the relays. When the battery level drops below the cutoff level, the relays will turn off. When the battery level rises above the restore level, the relays will turn back on.

Polling interval

The default polling interval is 60 seconds. To customize the polling interval, refer to defining a custom polling interval. Specify one single entity from the envoy device as target of the action using the + choose entity button. Updating one entity will update all entities of the Envoy and the related devices like the inverters; there is no need to specify multiple or all entities or add (all) inverter entities. When using multiple Envoys, add one entity for each envoy as targets or create separate custom polling intervals with a single entity as needed.

Credentials or device IP address update

This integration supports updating the Envoy configuration through a reconfigure menu option. The reconfiguration allows for changing the Envoy IP address, username, and/or password. Use this menu option if your Enlighten credentials or the device’s IP address has changed and needs to be manually updated. The latter is typically automatically detected and updated.

Use this menu option also when an Envoy firmware upgrade requires a switch from local Envoy username/password to token-based authentication with Enlighten username/password (refer to authentication requirements).

Energy dashboard

This integration provides several values suitable for the energy dashboard:

• For Solar production, use the Envoy Lifetime energy production entity.
• For Grid consumption, use the Envoy Lifetime net energy consumption entity.³
• For Return to grid, use the Envoy Lifetime net energy production entity.³
• For Energy going into the battery, use the the Envoy Lifetime battery energy charged entity.⁴
• For Energy coming out off the battery, use the the Envoy Lifetime battery energy discharged entity.⁴

Configure

The integration provides a configure menu to configure the following options:

• Collect test fixture data in diagnostics report - No/Yes
• Always use a new connection when requesting data from the Envoy - No/Yes
  • Some older Envoy firmware may exhibit connection issues when using the, by default enabled, keep-alive connection and report failures. When set, this option disables the use of keep-alive and builds a new connection at each data request. This makes the communication more reliable for these firmware versions. Reported for the Envoy-R but may apply to other older firmware versions as well.

Debug logs and diagnostics

This integration provides debug logs and diagnostics reports as described in the Home Assistant troubleshooting pages.

Debug log

When experiencing issues during the use of the integration, enable the debug log for the Envoy / IQ Gateway. This will add details on the data collection to the Home Assistant log file. Leave the debug log enabled long enough to capture the occurrence of the issue. If the issue is intermittent, this may take a while and it may grow the log file quite a bit.

If you’re expecting features to show but they are not shown, reload the integration while debug logging is enabled. When this integration is loaded, it will scan the Envoy / IQ Gateway for available features and configure these as needed. Following this initial scan, only data for the found features is collected. Performing a reload with debug enabled results in the debug log containing the initial full scan to assist with analyzing any missing features. Some features are disabled by default, and you need to enable them if you want them to show. Verify this before starting a debug session.

The debug log will show all communication with the Envoy / IQ Gateway. Lines starting with entities are log entries for the integration:

2024-03-07 11:20:11.897 DEBUG (MainThread) [homeassistant.components.enphase_envoy
2024-03-07 11:20:11.898 DEBUG (MainThread) [pyenphase.envoy

Below a typical data request / reply sequence in the log file. These lines will contain the data details received from the Envoy / IQ Gateway.

... [pyenphase.envoy] Requesting https://192.168.1.2/ivp/meters with timeout ...
... [pyenphase.envoy] Request reply from https://192.168.1.2/ivp/meters status 200:...

The end of a collection cycle is marked by:

... [homeassistant.components.enphase_envoy.coordinator] Finished fetching Envoy 123456 data in 1.234 seconds (success: True)

Diagnostics

The diagnostics file is a JSON file and includes a data section with the details for this integration. The file can be viewed with any text editor⁵. The data section has up to 6 major subsections which reflect how the integration is set up and data is used.

When new features are requested or firmware is upgraded, it can happen that existing test fixtures no longer cover all test cases and new ones are needed. It may happen, you are requested to provide data for such test fixtures. The diagnostics report can provide the needed information to build such test fixtures. By default, the diagnostics report does not include this data. To include the test fixture data, enable this option in the integration configure menu. When this option is enabled, the creation of the diagnostic report may take longer as it will perform a scan of the Envoy. When done creating the report, clear the option to prevent this delay the next time a diagnostic report is created. The option has no impact on the integration’s performance, only on the time it takes to create the report.

Below the 6 subsections, each collapsed.

  "data": {
    "config_entry": { ...
    },
    "envoy_properties": { ...
    },
    "raw_data": { ...
    },
    "envoy_model_data": { ...
    },
    "envoy_entities_by_device": [ ...
    ],
    "fixtures" : { ...
    }
  }
}    

Config entry

Shows the integration configuration created when the integration was added.

Envoy properties

Shows the conclusions of the initial data scan and what features were identified, including the detected firmware version in the Envoy.

Raw data

Shows the data collected from the Envoy during the last data scan when the diagnostic report was created. If in doubt about data shown in the dashboards, consult this section to find the raw data sent by the Envoy. The integration is not modifying this data, it’s just providing the data to the entities.

Envoy model data

Shows the data of the Envoy extracted from the raw_data into Envoy class data used by the Home Assistant integration. This is a subset of the full raw dataset.

Envoy entities by device

Shows all entities created by the integration based on the findings of the initial scan, grouped by device. Entity state based on the last data collection cycle is included. State values here come from the Envoy model data and are the values visible in the dashboards.

Fixtures

The data to build test fixtures from. This section is only available when the option to provide this is enabled in the integration configuration. Information is collected from the envoy in a scan for known and needed endpoints. Data is collected to enable the developers to build test fixtures from it.