briancmpbll / home_assistant_custom_envoy

178 stars 76 forks source link

hacs_badge

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).

Installation

  1. Install HACS if you haven't already
  2. Add this repository as a custom integration repository in HACS
  3. Restart home assistant
  4. Add the integration through the home assistant configuration flow, specify settings as needed
  5. The integration has some run-time configuration options, set these as desired after startup.
  6. The integration has some hidden entities, enable these to use these.

Usage

Initial Configuration details

The initial configuration window requires you to enter the details how to access the Envoy. Following fields have to be filled.

Host

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.

Username and Password

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:

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.

Serial number

Specify the Envoy serial number. If the Envoy is auto-discovered it will be pre-filled.

Use Enlighten

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.

Runtime configuration

Once the Envoy has been running and is operational, the following configuration items are available:

Scan Interval - Time between Entity updates

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.

Timeout for single Envoy Page

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.

How many retries in getting an Envoy response

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.

Time between 2 retries

Optionally a wait time can be inserted between 2 retries. Only change this in special circumstances.

Overall Timeout

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.

Do not use production json

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.

Disabled entities

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.

Firmware and its impact

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.

Different models have different features

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.

ENVOY C / R / LCD

IQ Gateway / ENVOY S standard (non metered)

IQ Gateway / ENVOY S standard metered

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.

with connected current transformer clamps

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.

without connected current transformer clamps

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.

Device and Entities

The naming scheme used is based on the Envoy and inverter Serial numbers.

Device

A device Envoy <serialnumber> is created with sensor entities for accessible data.

Envoy Sensors

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.

Inverter Sensors

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)

Battery Sensors

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

How to switch to Enphase token authorization

Once the envoy received the new firmware that requires token authorization, data collection will fail. To switch to the token usage execute next steps:

Troubleshooting

When issues occur with this integration some items to check are: