This is a HACS custom integration for enphase envoys/IQ Gateways with firmware version 7.X. This integration is based off work done by @jesserizzo, @gtdiehl and @DanBeard, with some changes to report individual battery status.
It still supports Envoys with firmware versions before 7.x including R3 versions for legacy models.
Works with older models that only have (some) production metrics (ie. Envoy-C R or LCD), newer models with only production metrics (IQ Gateway / ENVOY-S Standard) and models that offer both production and consumption metrics (ie. Envoy-S metered).
The initial configuration window requires you to enter the details how to access the Envoy. Following fields have to be filled.
Enter the IP address of the Envoy. If the Envoy is auto-discovered it will be pre-filled. The IP address may be an ipv4 or ipv6 address.
Specify the username and password to access the envoy data. What username and password to use depends on the ENVOY type and/or it's firmware version:
If your IQ Gateway / Envoy-S is on Firmware 7.x or later, use your Enphase Enlighten username and password. Make sure to enable the 'Use Enlighten' option at the bottom of the form.
For older models and ENVOY-S with firmware before 7.x use envoy
without a password, installer
without a password or a valid username and password for the type.
For older models that require username installer
with a password, this can be obtained with this: tool.
In some cases, you need to use the username envoy
with the last 6 digits of the unit's serial number as password.
See the Enphase documentation for more details on various units.
Note This integration does not provide the additional data accessible by Enphase Installer or DIY accounts, only data accessible by Home owner accounts is provided. Using an Installer or DIY account may or may not work work, but currently just the Home owner data is retrieved.
Specify the Envoy serial number. If the Envoy is auto-discovered it will be pre-filled.
Enable this option with IQ Gateway/ENVOY-S Firmware 7.x or later that require Enphase tokens for authentication. It will use the username and password to retrieve the authentication token from the Enphase website, cache it and use it to access the Envoy.
Once the Envoy has been running and is operational, the following configuration items are available:
By default the Envoy data is collected every 60 seconds. One can change the setting to what is desired with a minimum of every 5 seconds. Upon changing the value, reload the integration (or restart Home Assistant).
What the optimal scan frequency is depends on the Envoy model. Models without meters typically update the inverter data every 5 minutes. Models using meters update measurements way more frequent, probably every second or so. Hence the default of 60 seconds as starting point. Some models may have capacity issues running at high refresh rates, so no single recipe is available.
Note Envoy Metered has a data streaming option to bring in data as it comes available which is not currently supported by this integration.
Specifies the timeout for each single data get to the Envoy. Defaults to 30 seconds. Shortening this time does not make the Envoy response faster, lengthening it will allow a slow Envoy more time to respond before time-out occurs.
Specifies how many times a retry should be attempted after the first one failed. Must be at least 1 to allow for automatic token updates. Typically do not change this setting. Increasing may help in poor network conditions.
Optionally a wait time can be inserted between 2 retries. Only change this in special circumstances.
When getting data from the Envoy, an overall timer is started. If not all data is returned when the timer expires, the data collection is considered timed-out and all data is set to unavailable. Intent is catch all if data collection is never returning. Do not change this setting, unless Timeout for single envoy page or number of retries needs to be increased. In that case increase this overall timer value as well to prevent it to timeout the data collection. To get a feel for needed time, enable the debug mode on the envoy and inspect timing of a full collection cycle.
This switch, intended for use with the Envoy-s Metered only, will tell the integration not to use production endpoint on the Envoy. The production endpoint is a relatively slow endpoint on the Envoy and reportedly crashes or restarts at times resulting in timeouts.
The Envoy-s Metered (only) has other, faster endpoints that provide a subset of what production endpoint offers. This subset is lacking the daily total and last 7 day total values which are only provided by the production endpoint. If you are more interested in faster updates from the CT clamps and have less interest in the Daily total or last 7 day total then this may be an option to consider. The values for today total and last 7 day total will show as unavailable. The values for production and consumption CT clamps will update with every collection cycle. The values for the inverters will continue to update every 5 minutes as before.
The integration comes with some entities disabled by default. These only apply when using metered Envoy with CT clamps. If desired enable these by opening the HA entities window in the settings menu. Remove the filter for not shown entities by pushing the clear
button. Then enter disabled or enphase in the search filter to find the disabled entities. Use the selector box to select the ones to enable and use the enable selected
button to enable them.
Enphase model offering differs in various countries as does firmware versions and releases. Not all firmware is released in all countries and as a result firmware versions may differ largely in time. Enphase does push new firmware to the IQ Gateway / Envoy, 'not necessarily letting the home owner know'. In the past this has broken this integration as API details and change information is limited available. See the Enphase documentation website for information available.
This integration supports various models but as models have different features they will not all provide the same data. Brief list of reported data below.
What data is available depends on how many current transformer clamps (CT) are installed and what currents they measure. Both production and consumption clamps can be installed, each for up to 3 phases or multiple circuits on their own breaker in single phase setup. The consumption clamps can be installed in 2 modes, 'Load with Solar'or 'Load only'. To measure net-consumption (energy import/export to the grid) it should be installedin Load with Solar mode. If in 'Load only' mode only total-consumption (to the house) can be reported.
Note If you have CT clamps on a single phase / breaker circuit only, the L1 production and consumption phase sensors will show same data as the over all phases sensors.
The current firmware (D7.6.175 and probably some other right before and after it) without CT clamps connected and configured does obviously not report these measurements. But for some reason it is only reporting:
Note - When adding (or removing) CT clamps after use witouth CT clamps this will cause (huge) step changes/spikes in life time values when CT readings are now from the CT clamps (or longer available) and the wrapping value is no longer/now used.
The naming scheme used is based on the Envoy and inverter Serial numbers.
A device Envoy <serialnumber>
is created with sensor entities for accessible data.
Sensor name | Sensor ID | Units | remarks |
---|---|---|---|
Envoy \<sn> Current Power Production | sensor.Envoy_\<sn>_current_power_production | W | |
Envoy \<sn> Today's Energy production | sensor.Envoy_\<sn>_todays_energy_production | Wh | 1 |
Envoy \<sn> Last Seven Days Energy Production | sensor.Envoy_\<sn>_last_seven_days_energy_production | Wh | 1 |
Envoy \<sn> Lifetime Energy Production | sensor.Envoy_\<sn>_lifetime_energy_production | Wh | 2 |
Envoy \<sn> Lifetime Net Energy Production | sensor.Envoy_\<sn>_lifetime_net_energy_production | Wh | 4 |
Envoy \<sn> Current Power Consumption | sensor.Envoy_\<sn>_current_power_consumption | W | |
Envoy \<sn> Current Net Power Consumption | sensor.Envoy_\<sn>_current_net_power_consumption | W | 4 |
Envoy \<sn> Today's Energy Consumption | sensor.Envoy_\<sn>_todays_energy_consumption | Wh | 4,5 |
Envoy \<sn> Last Seven Days Energy Consumption | sensor.Envoy_\<sn>_last_seven_days_energy_consumption | Wh | 4 |
Envoy \<sn> Lifetime Energy Consumption | sensor.Envoy_\<sn>_lifetime_energy_consumption | Wh | 4 |
Envoy \<sn> Lifetime Net Energy Consumption | sensor.Envoy_\<sn>_lifetime_net_energy_consumption | Wh | 4,7,8 |
Envoy \<sn> Power Factor | sensor.Envoy_\<sn>_pf | 4,9 | |
Envoy \<sn> Voltage | sensor.Envoy_\<sn>_voltage | V | 4,9 |
Envoy \<sn> Frequency | sensor.Envoy_\<sn>_frequency | Wh | 4,9 |
Envoy \<sn> Consumption Current | sensor.Envoy_\<sn>_consumption_Current | A | 4,9 |
Envoy \<sn> Production Current | sensor.Envoy_\<sn>_production_Current | A | 4,9 |
Envoy \<sn> Active Inverter Count | sensor.Envoy_\<sn>_active_inverter_count | 9,10 | |
Grid Status | binary_sensor.grid_status | On/Off | 3 |
Envoy \<sn> Current Power Production L\<n> | sensor.Envoy_\<sn>_current_power_production_l\<n> | W | 4,5 |
Envoy \<sn> Today's Energy production L\<n> | sensor.Envoy_\<sn>_todays_energy_production_l\<n> | Wh | 4,5 |
Envoy \<sn> Last Seven Days Energy Production L\<n> | sensor.Envoy_\<sn>_last_seven_days_energy_production_l\<n> | Wh | 4,5 |
Envoy \<sn> Lifetime Energy Production L\<n> | sensor.Envoy_\<sn>_lifetime_energy_consumption_l\<n> | Wh | 4,5 |
Envoy \<sn> Lifetime Net Energy Production L\<n> | sensor.Envoy_\<sn>_lifetime_net_energy_production_l\<n> | Wh | 4,5,7,8 |
Envoy \<sn> Current Power Consumption L\<n> | sensor.Envoy_\<sn>_current_power_consumption_l\<n> | W | 4,5 |
Envoy \<sn> Current Net Power Consumption L\<n> | sensor.Envoy_\<sn>_current_net_power_consumption_l\<n> | W | 4,5 |
Envoy \<sn> Today's Energy Consumption L\<n> | sensor.Envoy_\<sn>_todays_energy_consumption_l\<n> | Wh | 4,5,6 |
Envoy \<sn> Last Seven Days Energy Consumption L\<n> | sensor.Envoy_\<sn>_last_seven_days_energy_consumption L\<n> | Wh | 4,5,6 |
Envoy \<sn> Lifetime Energy Consumption L\<n> | sensor.Envoy_\<sn>_lifetime_energy_consumption_l\<n> | Wh | 4,5,6 |
Envoy \<sn> Lifetime Net Energy Consumption L\<n> | sensor.Envoy_\<sn>_lifetime_net_energy_consumption_l\<n> | Wh | 4,5,6,7,8 |
Envoy \<sn> Power Factor L\<n> | sensor.Envoy_\<sn>_pf | 4,5,9 | |
Envoy \<sn> Voltage L\<n> | sensor.Envoy_\<sn>_voltage | V | 4,5,9 |
Envoy \<sn> Frequency L\<n> | sensor.Envoy_\<sn>_frequency | Wh | 4,5,9 |
Envoy \<sn> Consumption Current L\<n> | sensor.Envoy_\<sn>_consumption_Current | A | 4,5,9 |
Envoy \<sn> Production Current L\<n> | sensor.Envoy_\<sn>_production_Current | A | 4,5,9 |
Envoy \<sn> | sensor.Envoy\<sn> | Wh | 4,5 |
1 Always zero for Envoy Metered without meters.
2 Reportedly resets to zero when reaching ~1.92MWh for Envoy Metered without meters.
3 Not available on Legacy models and ENVOY Standard with recent firmware.
4 Only on Envoy metered with configured and connected meters.
5 L\<n> L1,L2,L3, availability depends on which and how many phases are connected and configured.
6 Reportedly always zero on Envoy metered with Firmware D8.
7 In V0.0.18 renamed to Lifetime Net Energy Consumption /Production from Export Index/Import Import in v0.0.17. Old Entities will show as unavailable.
8 Only when consumption CT is installed in 'Load with Solar' mode. In 'Load only' mode values have no meaning.
9 Disabled by default and must be enabled in the entities configuration screen. These are values from the consumption CT.
10 Only available on legacy Envoy.
For each inverter a sensor for current power production is created.
Sensor name | Sensor ID | UNits | remarks |
---|---|---|---|
Envoy \<sn> Inverter \<sn> | sensor.Envoy\<sn>_Inverter\<sn> | W | 1 |
1: Not available on Legacy models
Note the entity 'Last Updated' for each inverter is currently not provided.
Note As can be noted the Envoy serial number is part of the inverter sensor id and name. Internally the unique_id for it is the inverter serial number. When changing your setup by moving inverters to a new/different Envoy it will require some preparation/research how this will work out. (Statistics (history) is stored by sensor id)
For each battery a sensor for percent full is created as well as sensors for overall battery percentage, overall battery capacity, overall energy charged and discharged are created.
Sensor name | Sensor ID | Units | remarks |
---|---|---|---|
Envoy \<sn> Battery \<sn> | sensor.Envoy\<sn>_Battery\<sn> | % | 1 |
Envoy \<sn> Total Battery Percentage | sensor.Envoy_\<sn>_total_battery_percentage | % | 1 |
Envoy \<sn> Current Battery Capacity | sensor.Envoy_\<sn>_current_battery_capacity | Wh | 1 |
Envoy \<sn> Battery Energy Charged | sensor.Envoy_\<sn>_battery_energy_charged | Wh | 1 |
Envoy \<sn> Battery Energy Discharged | sensor.Envoy_\<sn>_battery_energy_charged | Wh | 1 |
1: Not available on Legacy models and ENVOYS-S Standard
Once the envoy received the new firmware that requires token authorization, data collection will fail. To switch to the token usage execute next steps:
When issues occur with this integration some items to check are:
Download Diagnostics
button in the Envoy Device page or the Enphase Integration page menu. It will download settings and recent data of the Envoy and provide some key information.Fetched from https://192.168.01.10/some_url: <Response [200 OK]>:
. Inspecting these provides insight in what and how successful data is collected.Using Model: P (HTTPs, Metering enabled: False, Get Inverters: True)
. (Model PC is envoy metered, P is Standard and R/LCD with FW >= R3.9 and P0 is Legacy/C/R/LCD with FW < R3.9>)