This is a Home Assistant custom integration for Enphase Envoy/IQ Gateway. It provides 2 service actions to access Enphase IQ Gateway raw data:
- read_data: GET request to the Envoy
- send_data: PUT/POST/DELETE request to the Envoy
Caution
This integration provides no entities, for entities use the core HA Core integration or another custom integration. It does NOT replace the core integration, both can be used at the same time. The intent is to provide additional specialized and more rarely used service actions which are not present in the core integration. It can run without the core integration, but the core integration would be needed to provide the typical Envoy entities.
Under the hood, this custom integration is a stripped down fork of the HA core integration and it is using the same pyenphase library for communication to the Enphase Envoy/IQ Gateway. Entity creation, scheduled data collection and auto detection are removed. Each Envoy needs to be added manually. Token handling and refresh for firmware version 7.0 and later is retained.
As of Home Assistant version 2025.7, the Enphase Envoy integration switched from using httpx library to using the aiohttp library. This is a breaking change for this custom integration. Starting with Home Assistant 2025.7 you must update to 2.0.0 or newer version.
First production versions. Only use with Home Assistant versions from 2025.3 to 2025.6.3.
Installation
As with all Home Assistant configuration changes, first make appropriate backups of you Home Assistant installation and data.
- Install HACS if you haven't already
- In the future this custom integration will list in the HACS integrations. If not yet, add this GITHUB repository as a custom integration repository to HACS
- Go to the HACS Integrations page in HA, select this custom repository and download the
Enphase Envoy raw datacustom integration - After download restart Home Assistant.
- Configure the custom integration in Home Assistant using the home assistant configuration flow and select the
Enphase Envoy raw dataintegration.
- In Home Assistant create a folder /config/custom_components/enphase_envoy_raw_data
- Copy (only) the files and folders in this repository in folder
custom_components/enphase_envoy_raw_datainto the Home Assistant folder /config/custom_components/enphase_envoy_raw_data. - Restart Home Assistant
- Configure the custom integration in Home Assistant using the home assistant configuration flow and select the
Enphase Envoy raw dataintegration.
Configuration
When first adding the integration or when adding another Envoy instance, enter below configuration information:
| field | Description |
|---|---|
| Host | The name or IP address of the Envoy to configure. |
| Username | For firmware version 7.0 and later, enter your Enlighten cloud username. For firmware before 7.0, enter username installer without a password. |
| Password | For firmware version 7.0 and later, enter your Enlighten cloud password For firmware before 7.0, with username installer, leave blank. |
| I want to enter token manually | If you want to enter a token manually, check this option and select Submit to switch to the token entry form. Use when your Enphase account uses multi-factor authentication or if you don't want to store username/password in the configuration data. |
| token | Enter an Envoy access token when in manual token entry mode. Use the link below the field to open the Enphase token portal. |
The Enlighten cloud username and password for firmware version 7.0 and later will be used to obtain a 1-year-valid token from the enphase web-site when first configured or 1 month before expiry. When in manual token mode you will need to refresh the token manually. A notification will show 1 month before expiry.
Example screenshots
To switch to manual token entry, first enter the host ip address and then check the I want to enter token manually option and select Submit.
To obtain a token from the Enphase token portal, select the Enphase login link below the token field.
Upon successful configuration, the integration can be found in the Home Assistant integrations dashboard.
This service action enables sending a GET request to an Envoy endpoint and receive the reply. For instance, use it in the Home Assistant Developers Tools Actions to inspect raw Envoy data.
Example screenshots of Developer tools actions with Enphase_Envoy_raw_data read_data
| Data attribute | Optional | Description |
|---|---|---|
| Envoy entry | no | The id of the enphase envoy raw data configuration entry. In UI mode use the pulldown to select it. |
| Endpoint | no | The endpoint on the envoy to get data for. Must start with /. For example, to get get inverter data, use /api/v1/production/inverters. |
| From cache | yes | When set, does not send request to envoy, but rather get data from previously cached request results. See cached data. |
Developer tools actions Yaml example reading inverter data
action: enphase_envoy_raw_data.read_data
data:
config_entry_id: 01JP4Q3FHEJQVGKWZ76KJMQ8AH
endpoint: /api/v1/production/inverters
from_cache: false/api/v1/production/inverters:
- serialNumber: "123456789010"
lastReportDate: 1695752919
devType: 1
lastReportWatts: 0
maxReportWatts: 361
- serialNumber: "123456789011"
lastReportDate: 1695752947
devType: 1
lastReportWatts: 0
maxReportWatts: 362Each time a GET request is send, the response is stored or updated in an internal cache. If, for some reason, 2 actions are used requesting for the same data, the second action can request the data from the cache. This can avoid multiple requests for same data send to the Envoy.
Obviously, for an endpoint, there is a balance between request reduction and data age in the cache. For example, use 1 action that regularly sends the request while other related action would use the cached data. For the occasional data inspection using the developer tools action, this is not needed. When creating multiple actions working of the same data it can be an optimization.
If the cache option is used, and the endpoint data is not available in the cache, a request will be send to the envoy.
In general, the use of the HA Core integration to obtain Envoy/IQ Gateway data is recommended. However, cases may exist where there is a need to obtain specific data. Action services can be used in automations and scripts for this purpose. As mentioned, each use of the read_data action service may result in a request send to the Envoy. Some optimization in result data sharing or use of cached data is recommended.
When using the action service with automations and scripts, use the response_variable to receive the returned value. This will be a JSON object with the specified endpoint as key.
Example JSON response data
Response data for endpoint /api/v1/production/inverters
{
"/api/v1/production/inverters": [{
"serialNumber": "123456789013",
"lastReportDate": 1695752919,
"devType": 1,
"lastReportWatts": 0,
"maxReportWatts": 361
}, {
"serialNumber": "123456789045",
"lastReportDate": 1695752947,
"devType": 1,
"lastReportWatts": 0,
"maxReportWatts": 360
},
]
}The response variable can then be used to work with the returned data.
Example automation running daily at 2 am getting inverter data
Automation getting inverter data and writing to notification and input_text.
alias: test_read_data
description: ""
triggers:
- trigger: time_pattern
hours: "2"
conditions: []
actions:
- action: enphase_envoy_raw_data.read_data
metadata: {}
data:
config_entry_id: 01JP4Q3FHEJQVGKWZ76KJMQ8AH
endpoint: /api/v1/production/inverters
response_variable: pv_data
- action: notify.persistent_notification
metadata: {}
data:
title: "First and second Inverter"
message: >
{# show in notifications #}
{% set key = "/api/v1/production/inverters" %}
{{ pv_data[key][0] }}
{{ pv_data[key][1] }}
- action: input_text.set_value
metadata: {}
data:
value: >
{# set value of first_inverter input.text #}
{{ pv_data["/api/v1/production/inverters"][0] }}
target:
entity_id: input_text.first_inverter
mode: singleCaution
This service action enables sending a PUT, POST or DELETE request to an Envoy endpoint and receive the reply.
Example screenshots of Developer tools actions with Enphase_Envoy_raw_data send_data
⚠️ Sending PUT/POST/DELETE requests is at your own risk! Only use this service action if you fully understand the required data format, the effect on the Envoy/IQ Gateway and accept the risk of potential negative impact on the Envoy operation. Also be aware that each new firmware pushed to your Envoy/IQ Gateway may expose different behavior and PUT/POST/DELETE request effects may suddenly change.⚠️
| Data attribute | Optional | Description |
|---|---|---|
| Envoy entry | no | The id of the enphase envoy raw data configuration entry. In UI mode use the pulldown to select it. |
| Endpoint | no | The endpoint on the envoy to send data to. Must start with /. Must be an endpoint that accepts data. |
| Data | no | JSON string or JSON object to send to Envoy. Format must match endpoint requirements. Requires your expertise. |
| Risk acknowledgement | no | This should be set to true as confirmation you are accepting the risk of this operation. If not set, the action will return an error. |
| Send method | no | Specify PUT, POST or DELETE. Which is needed depends on the endpoint and data send. Requires your expertise. |
| Test mode | no | When set, does not send request to envoy, but rather returns the data as JSON so result can be verified. See test mode. |
Building the needed data structure using various methods available in Home Assistant may require some iterations. Before sending any final result, use the test mode to inspect the resulting data. With test mode enabled, the service will not send the data to the envoy, but rather return the JSON object that would have been send. Use the Test mode option until final result is acceptable for sending. As additional safe-guard a non-exiting endpoint can be used for this as no data is actually send.
Developer tools actions Yaml example for send-data with test mode enabled
example to show concept of test mode, no realistic envoy data.
action: enphase_envoy_raw_data.send_data
data:
config_entry_id: 01JP4Q3FHEJQVGKWZ76KJMQ8AH
risk_acknowledged: true
method: POST
test_mode: true
endpoint: /test
data: >
{# Some comment #}
{% set config1 = dict(current = "1.0", voltage = "110", frequency = "50") %}
{% set config2 = {"target": "60", "min": "25", "max": "93"} %}
{% set data = dict( coil1 = config1, target = config2, runtime = "10", alert = false) %}
{{ data }}/test:
coil1:
current: "1.0"
voltage: "110"
frequency: "50"
target:
target: "60"
min: "25"
max: "93"
runtime: "10"
alert: falseBy now you should have realized that sending data may be a risky business. Safe-guards to use are:
- Use a non existing endpoint like
/testuntil certain about sending data. - Enable
test modeuntil certain about sending data.
The response of PUT, POST or DELETE request is returned as JSON with the specified endpoint as key.
- Read-data and send-data return a json object with the endpoint as key. When using the data be aware of this. For example endpoint xyz/abc that returns
{ "a": "1", "b": "2" } will result in
{ "xyz/abc": { "a": "1", "b": "2" } } To use the data be aware to use `actual_value=result["xyz/abc"]`.
- When using the send-data action service, while also using the core (or other custom) integration, consider triggering a data refresh in the core integration as a next step in the automation. This will assure that any changes in effect by the PUT, POST or DELETE will be read back and are reflected in any core entities.
- To enable debug logging, either enable it on the integration or add below to your configuration.yaml
logger:
default: warn
logs:
custom_components.enphase_envoy_raw_data: debugBased on the work of the Enphase Envoy core integration (enphase_envoy) and pyenphase.