Classes, methods and properties

class pyenphase.Envoy(host, client=None, timeout=None)

Bases: object

Class for communicating with an envoy.

Collects solar production data for all Envoy models as of firmware 3.9. Depending on model and installed components can collect power/energy consumption, battery charge, discharge and settings. Supports communication with both pre- and post V7 Envoy firmware.

envoy = Envoy(host_ip_or_name)
await envoy.setup()
await envoy.authenticate(
    username=username,
    password=password,
    token=token
)
await envoy.update()
# ...
await envoy.close()

Parameters:

host (str) – Envoy DNS name or IP address
client (ClientSession | None) – aiohttp ClientSession not verifying SSL certificates, if not specified one will be created.
timeout (float | ClientTimeout | None) – aiohttp ClientTimeout to use, if not specified 10 sec connection and 45 sec read timeouts will be used.

async setup()

Initiate Envoy communication by obtaining firmware version.

Read /info on Envoy, accessible without authentication. Instantiates EnvoyFirmware class object. Required to decide what authentication to use for sub-sequent Envoy communication. Use this method as first step after class instantiation

Will retry up to 4 times or 50 sec elapsed at next try, which ever comes first.

Raises:

EnvoyFirmwareFatalCheckError – if connection or timeout failure occurs
EnvoyFirmwareCheckError – on http errors or any HTTP status other then 200

Return type:

None

async close()

Close or clean anything opened or created on behalf of the caller.

Should be called when ending application, if:

no aiohttp ClientSession was specified for the Envoy:
- the pyenphase-created ClientSession will be closed.
an aiohttp ClientSession was provided by the caller:
- Envoy will not close the provided session; the caller remains responsible.

Return type:: None
Returns:: None

async authenticate(username=None, password=None, token=None)

Authenticate to the Envoy based on firmware version.

If firmware version retrieved in Envoy.setup is < 7 then create DigestAuth using passed username and password. Use ‘envoy’ or ‘installer’ username and blank password.

If Firmware is >= 7 create JWT Token based authorization. If token is passed, use it for authorization. If no token is passed, username and password should be Enlighten Cloud credentials to obtain a token. Validate the token with the local Envoy.

Parameters:

username (str | None) – Enligthen Cloud username or local Envoy username, defaults to None
password (str | None) – Enligthen Cloud password or local Envoy password, defaults to None
token (str | None) – Token to use with authentication, defaults to None

Raises:

EnvoyAuthenticationRequired – Authentication failed with the local Envoy, provided token is expired or no token could be obtained from Enlighten cloud due to error or missing parameters.

Return type:

None

async probe_request(endpoint)

Make a probe request to the Envoy.

Probe requests are intended for use by updates during initial search of available features in the Envoy. They are not retried on connection errors, timeouts or bad JSON responses. For regular data retrieval, use the request method. Sends GET request to endpoint on Envoy and returns the response.

Parameters:: endpoint (str) – Envoy Endpoint to access, start with leading /.
Raises:: EnvoyAuthenticationRequired – if no prior authentication was completed or HTTP status 401 or 404 is returned.
Return type:: ClientResponse
Returns:: request response.

async request(endpoint, data=None, method=None)

Make a request to the Envoy.

Send GET or POST request to Envoy. Defaults to GET, specify data dictionary to perform a POST. Only specify the endpoint path in the Envoy, HTTP type and Envoy address is prepended to form full URL based on authentication method.

Request retries on client connection issues or timeouts. Will retry up to 4 times or 50 sec elapsed at next try, which ever comes first.

Parameters:

endpoint (str) – Envoy Endpoint to access, start with leading /
data (dict[str, Any] | None) – optional data dictionary to send to the Envoy Defaults to none, if none a GET request is issued.
method (str | None) – HTTP method to use when sending data dictionary, if none and data is specified POST is default

Raises:

EnvoyAuthenticationRequired – if no prior authentication was completed or HTTP status 401 or 404 is returned.

Raises:

Any communication errors when retries are exceeded

Return type:

ClientResponse

Returns:

request response.

async interface_settings()

Returns Envoy active interface information.

Returned data includes interface mac, interface type, software build date, configured timezone and DHCP settings

This data is sourced from the /home endpoint which is a slower responding endpoint with some potential overhead on the Envoy. For this reason, as well as the fact that the data is static, it will only be fetched one time when called first time and cached internally. Subsequent calls will be fulfilled from the cache. A call to envoy.setup() will invalidate the cached data and result in a one-time read from Envoy upon next call.

Return type:: EnvoyInterfaceInformation | None
Returns:: Interface details or None if error

property host: str: Return the Envoy host specified at initialization.

property firmware: AwesomeVersion: Return the Envoy firmware version as read from the Envoy.

property part_number: str | None: Return the Envoy part number as read from the Envoy.

property serial_number: str | None: Return the Envoy serial number as read from the Envoy.

property is_metered: bool: Return the Envoy imetered info as read from the Envoy.

property supported_features: SupportedFeatures: Return the mask of Envoy supported features as established during Probe.

property phase_count: int: Return the number of configured phases for CT meters as read from the Envoy.

property active_phase_count: int: Return the number of actual reported phases in Envoy production/consumption report.

property ct_meter_count: int: Return the number of configured current transformers (CT) as read from the Envoy

property consumption_meter_type: CtType | None: Return the type of consumption ct meter installed (total or net-consumption or None) as read from the Envoy.

property production_meter_type: CtType | None: Return the type of production ct meter installed (Production or None) as read from the Envoy.

property storage_meter_type: CtType | None: Return the type of storage ct meter installed (Storage or None) as read from the Envoy.

property phase_mode: EnvoyPhaseMode | None: Return the phase mode configured for the CT meters (single, split or three) as read from the Envoy.

property acb_count: int: Return the number of reported ACB batteries in Production storage report section.

property envoy_model: str

Return Envoy model description.

Describes the Envoy model based on properties found.

if 2 or more phases found or at least 1 ct is found:
- phase count
- phase mode
if consumption CT found, type of consumption CT
presence of production and/or storage ct

Example: “Envoy, phases: 2, phase mode: split, net-consumption CT, production CT”

Returns:: String describing the Envoy model and features.

async probe()

Probe for Envoy model and supported features.

For each updater in the list of updaters returned by get_updaters, execute the probe() method. Build and store a list of updaters to use, containing updaters for which the probe() method does return at least 1 supported feature. Store the map of all returned supported features.

An updaters probe method should determine if the data for the specific updater scope is available or not. If so, the updaters update() method will be used during data collection.

Probe should be used only once, after setup and authorization at the start of the communication. The update() method will call probe if not done prior.

Raises:: EnvoyProbeFailed – if no solar production data can be found on the Envoy. Solar production data is available in all Envoy models.
Return type:: None

async update()

Read data from Envoy.

For each updater in the list of established updaters during probe(), execute the update() method to collect current data from the Envoy. If probe was never executed, use probe method first.

An updaters update() method should obtain the data for the specific updater scope and save to the Envoy data set.

Raises:

EnvoyCommunicationError – when aiohttp network or communication error occurs.
EnvoyHTTPStatusError – when HTTP status is not 2xx.

Return type:

EnvoyData

Returns:

Collected Envoy data

async go_on_grid()

Make a request to the Envoy to go on grid.

POST {“mains_admin_state”: “closed”} to /ivp/ensemble/relay directing to connect to the grid. Requires ENPOWER installed.

Raises:

EnvoyFeatureNotAvailable – If ENPOWER feature is not available in Envoy
EnvoyCommunicationError – when aiohttp network or communication error occurs.
EnvoyHTTPStatusError – when HTTP status is not 2xx.

Return type:

dict[str, Any]

Returns:

JSON returned by Envoy

async go_off_grid()

Make a request to the Envoy to go off grid.

POST {“mains_admin_state”: “open”} to /ivp/ensemble/relay directing to disconnect from the grid. Requires ENPOWER installed.

Raises:

EnvoyFeatureNotAvailable – If ENPOWER feature is not available in Envoy
EnvoyCommunicationError – when aiohttp network or communication error occurs.
EnvoyHTTPStatusError – when HTTP status is not 2xx.

Return type:

dict[str, Any]

Returns:

JSON returned by Envoy

async update_dry_contact(new_data)

Update settings for an Enpower dry contact relay.

POST updated dry contact settings to /ivp/ss/dry_contact_settings in the Envoy. New_data dict can contain one or more of below items to set. The key/value for “id” is required to identify the relay. Only include key/values to change.

{
    "id": "<relay-id>",
    "grid_action": "value",
    "micro_grid_action": "value",
    "gen_action": "value",
    "override": "value",
    "load_name": "value",
    "mode": "value",
    "soc_low": "value",
    "soc_high": "value",
},

Settings specified in the data dict are updated in the internally stored dry_contact_settings and send as a whole to update the Envoy.

Parameters:

new_data (dict[str, Any]) – dict of settings to change, “id” key/value required

Raises:

EnvoyFeatureNotAvailable – If ENPOWER feature is not available in Envoy
EnvoyCommunicationError – when aiohttp network or communication error occurs.
EnvoyHTTPStatusError – when HTTP status is not 2xx.
ValueError – If update was attempted before first data was requested from Envoy
ValueError – If no “id” key is present in data dict to send.

Return type:

dict[str, Any]

Returns:

dry_contact_settings JSON returned by Envoy

async open_dry_contact(id)

Open a dry contact relay.

POST {“dry_contacts”: {“id”: id, “status”: “open”}} to Envoy to open dry contact with specified id. Upon successful POST, update dry contact status in internal data as Envoy needs some time to implement the change and have status updated.

Parameters:

id (str) – relay id of dry contact relay to open

Raises:

EnvoyFeatureNotAvailable – If ENPOWER feature is not available in Envoy
EnvoyCommunicationError – when aiohttp network or communication error occurs.
EnvoyHTTPStatusError – when HTTP status is not 2xx.

Return type:

dict[str, Any]

Returns:

JSON response of Envoy

async close_dry_contact(id)

Close a dry contact relay.

POST {“dry_contacts”: {“id”: id, “status”: “closed”}} to Envoy to close dry contact with specified id. Upon successful POST, update dry contact status in internal data as Envoy needs some time to implement the change and have status updated.

Parameters:

id (str) – relay id of dry contact relay to open

Raises:

EnvoyFeatureNotAvailable – If ENPOWER feature is not available in Envoy
EnvoyCommunicationError – when aiohttp network or communication error occurs.
EnvoyHTTPStatusError – when HTTP status is not 2xx.

Return type:

dict[str, Any]

Returns:

JSON response of Envoy

async enable_charge_from_grid()

Enable charge from grid for Encharge batteries.

Set charge_from_grid true in internal stored tariff data and send updated tariff data to Envoy using PUT. This will update the charge from grid setting to true in the Envoy.

Raises:

EnvoyFeatureNotAvailable – If no Encharge or IQ batteries are available
EnvoyFeatureNotAvailable – If no TARIFF data is available in Envoy
EnvoyCommunicationError – when aiohttp network or communication error occurs.
EnvoyHTTPStatusError – when HTTP status is not 2xx.
ValueError – If update was attempted before first data was requested from Envoy

Return type:

dict[str, Any]

Returns:

JSON response of Envoy

async disable_charge_from_grid()

Disable charge from grid for Encharge batteries.

Set charge_from_grid false in internal stored tariff data and send updated tariff data to Envoy using PUT. This will update the charge from grid setting to false in the Envoy.

Raises:

EnvoyFeatureNotAvailable – If no Encharge or IQ batteries are available
EnvoyFeatureNotAvailable – If no TARIFF data is available in Envoy
EnvoyCommunicationError – when aiohttp network or communication error occurs.
EnvoyHTTPStatusError – when HTTP status is not 2xx.
ValueError – If update was attempted before first data was requested from Envoy

Return type:

dict[str, Any]

Returns:

JSON response of Envoy

async set_storage_mode(mode)

Set the Encharge storage mode.

Set storage_mode in internal stored tariff data to specified mode and send updated tariff data to /admin/lib/tariff in Envoy using PUT. This will update the storage mode setting in the Envoy.

Parameters:

mode (EnvoyStorageMode) – storage mode to set

Raises:

EnvoyFeatureNotAvailable – If no Encharge or IQ batteries are available
EnvoyFeatureNotAvailable – If no TARIFF data is available in Envoy
EnvoyCommunicationError – when aiohttp network or communication error occurs.
EnvoyHTTPStatusError – when HTTP status is not 2xx.
ValueError – If update was attempted before first data was requested from Envoy

Return type:

dict[str, Any]

Returns:

JSON response of Envoy

async set_reserve_soc(value)

Set the Encharge reserve state of charge.

Set reserved_soc in internal stored tariff data to specified value and send updated tariff data to /admin/lib/tariff in Envoy using PUT. This will update the reserve soc setting in the Envoy.

Parameters:

value (int) – reserve soc to set

Raises:

EnvoyFeatureNotAvailable – If no Encharge or IQ batteries are available
EnvoyFeatureNotAvailable – If no TARIFF data is available in Envoy
EnvoyCommunicationError – when aiohttp network or communication error occurs.
EnvoyHTTPStatusError – when HTTP status is not 2xx.
ValueError – If update was attempted before first data was requested from Envoy

Return type:

dict[str, Any]

Returns:

JSON response of Envoy

class pyenphase.auth.EnvoyAuth(host)

Bases: object

Base class for local Envoy authentication.

Parameters:: host (str) – local Envoy DNS name or IP Address

abstractmethod async setup(client)

Setup token based authentication with the local Envoy.

Required for Envoy firmware >= 7.0

Parameters:: client (ClientSession) – an aiohttp ClientSession to communicate with the local Envoy,
Return type:: None

abstract property cookies: dict[str, str]: Return the Envoy cookie.

abstract property auth: DigestAuthMiddleware | None

Setup Digest authentication for local Envoy.

Required for Envoy firmware < 7.0

abstract property headers: dict[str, str]: Return the auth headers for Envoy communication.

abstractmethod get_endpoint_url(endpoint)

Return the URL for the endpoint.

Parameters:: endpoint (str) – Envoy Endpoint to access, start with leading /
Return type:: str
Returns:: formatted full URL string

class pyenphase.auth.EnvoyTokenAuth(host, cloud_username=None, cloud_password=None, envoy_serial=None, token=None)

Bases: EnvoyAuth

Class to authenticate with Envoy using Tokens.

Use with Envoy firmware 7.x and newer

Parameters:

host (str) – local Envoy DNS name or IP Address
cloud_username (str | None) – Enligthen Cloud username, required to obtain new token when token is not specified or expired, defaults to None
cloud_password (str | None) – Enligthen Cloud password, required to obtain new token when token is not specified or expired, defaults to None
envoy_serial (str | None) – Envoy serial number, required to obtain new token when token is not specified or expired, defaults to None
token (str | None) – Token to use with authentication, if not specified, one will be obtained from Enlighten cloud if username, password and serial are specified, defaults to None

JSON_LOGIN_URL = 'https://enlighten.enphaseenergy.com/login/login.json?'

TOKEN_URL = 'https://entrez.enphaseenergy.com/tokens'

async setup(client)

Setup token based authentication with the local Envoy

If no token is specified, a token is obtained from Enlighten Cloud using specified username, password and serialnumber. With the specified or obtained token, validates the token with the local Envoy. New or updated token can be accessed using the token property. Token is not stored persistent, caller should store and specify token over restarts.

Parameters:: client (ClientSession) – an aiohttp ClientSession to communicate with the local Envoy,
Raises:: EnvoyAuthenticationError – Authentication failed with the local Envoy or no token could be obtained from Enlighten cloud due to error or missing parameters,
Return type:: None

async refresh()

Refresh the token for Envoy authentication.

Retrieves a new token from the Enlighten cloud using specified username, password and Envoy serial number of the class object. Updated token can be accessed using the token property. Token is not stored persistent, caller should store it after refresh and specify token over restarts.

Return type:: None

property expire_timestamp: int

Return the expiration time for the token.

Owner useraccount type tokens are valid for a year while installer tokens are only valid for 12 hours.

Returns:: epoch expiration time

property token_type: str

Return the enphase user type for the token.

Enlighten user accounts can be type ‘owner’ or ‘installer’. Both have access to the envoy base data. Installer has access to more data and configuration setup.

Raises:: EnvoyAuthenticationRequired if no prior authentication was done
Returns:: ‘owner’ or ‘installer’

property token: str

Return token used with the Envoy.

Returns the current token, either the original specified token, or the token obtained from the Enlighten cloud if not specified or the refreshed token at expiration.

Will assert if no token was ever specified or obtained.

Returns:: jwt token string

property manager_token: str

Return manager token returned in enligthen login json.

This property is only available if a token has been requested from the Enlighten cloud. This is only the case if no token was specified, or a token refresh was requested. If a valid token with a future expiration time was specified this method will assert.

Returns:: token string

property cookies: dict[str, str]

Return cookies returned during setup of the envoy.

Cookies received from the local Envoy during setup and local jwt check are stored in the class, this method returns these.

Returns:: cookies dict

property is_consumer: bool

Return is_consumer state returned in enligthen login json

This property is only available if a token has been requested from the Enlighten cloud. This is only the case if no token was specified, or a token refresh was requested. If a valid token with a future expiration time was specified no login was attempted and this method will return the default false. If an installer account was used it will return false as well.

Returns:: true if enlighten login was performed and used credentials are for consumer account, otherwise false

property auth: None

Digest authentication for local Envoy.

Not used with token authentication. Placeholder for EnvoyAuth abstractproperty

Returns:: None

property headers: dict[str, str]

Return the authentication headers for Envoy communication.

Token authorization with Envoy requires an Authorization header in Bearer format with token.

Returns:: token authorization header

get_endpoint_url(endpoint)

Return the URL for the endpoint.

Parameters:: endpoint (str) – Envoy Endpoint to access, start with leading /
Return type:: str
Returns:: formatted https URL string

class pyenphase.auth.EnvoyLegacyAuth(host, username, password)

Bases: EnvoyAuth

Class to authenticate with legacy Envoy using digest.

Use with Envoy firmware before 7.0

Parameters:

host (str) – local Envoy DNS name or IP Address
local_username – Username to access Envoy
local_password – Password to access Envoy

property auth: DigestAuthMiddleware | None

Digest authentication for local Envoy.

Creates DigestAuthMiddleware based on username and password.

Returns:: DigestAuthMiddleware for local Envoy or None if username and/or password are not specified

async setup(client)

Setup authentication with the local Envoy

DigestAuth does not use additional setup, placeholder for EnvoyAuth abstractpropery.

Parameters:: client (ClientSession) – ClientSession to communicate with local Envoy
Return type:: None

property headers: dict[str, str]

Return the headers needed for Envoy authentication.

DigestAuth does not use authorization header. Placeholder for EnvoyAuth abstractproperty.

Returns:: empty dict

get_endpoint_url(endpoint)

Return the URL for the endpoint.

Parameters:: endpoint (str) – Envoy Endpoint to access, start with leading /
Return type:: str
Returns:: formatted http URL string

property cookies: dict[str, str]

Return cookies returned during setup of the envoy.

DigestAuth does not use cookies. Placeholder for EnvoyAuth abstractproperty.

Returns:: empty dict

class pyenphase.firmware.EnvoyFirmware(_client, host)

Bases: object

Class for querying and determining the Envoy firmware version.

Parameters:

client – aiohttp ClientSession not verifying SSL certificates, see pyenphase.ssl.
host (str) – Envoy DNS name or IP address

async setup()

Obtain the firmware version, serial-number and part-number from Envoy.

Read /info on Envoy, accessible without authentication. Store firmware version, serial-number and part-number properties from xml response.

Reads first on HTTPS, if that fails on HTTP for firmware < 7. Will retry up to 4 times or 50 sec elapsed at next try, which ever comes first.

connector = aiohttp.TCPConnector(ssl=create_no_verify_ssl_context())
client = aiohttp.ClientSession(connector=connector)
firmware = EnvoyFirmware(client,host)
await firmware.setup()
print(firmware.version)

Raises:

EnvoyFirmwareFatalCheckError – if connection or timeout failure occurs
EnvoyFirmwareCheckError – on http errors or any HTTP status other then 200

Return type:

None

property version: AwesomeVersion

Return firmware version as read from Envoy.

Returns:: Envoy firmware version or None if pyenphase.firmware.EnvoyFirmware.setup was not used

property serial: str | None

Return serial number as read from Envoy.

Returns:: Envoy serial number or None if pyenphase.firmware.EnvoyFirmware.setup was not used

property part_number: str | None

Return part number as read from Envoy.

Returns:: Envoy part number or None if pyenphase.firmware.EnvoyFirmware.setup was not used

property is_metered: bool

Return imetered setting as read from Envoy.

Returns:: Envoy info imetered setting. Only True if read and set in info

class pyenphase.EnvoyData(encharge_inventory=None, encharge_power=None, encharge_aggregate=None, enpower=None, acb_power=None, battery_aggregate=None, collar=None, c6cc=None, system_consumption=None, system_production=None, system_consumption_phases=None, system_production_phases=None, system_net_consumption=None, system_net_consumption_phases=None, ctmeter_production=None, ctmeter_consumption=None, ctmeter_storage=None, ctmeter_production_phases=None, ctmeter_consumption_phases=None, ctmeter_storage_phases=None, dry_contact_status=<factory>, dry_contact_settings=<factory>, inverters=<factory>, tariff=None, raw=<factory>)

Bases: object

Data Model for an envoy.

Data is extract from raw data requested from Envoy. All raw data is also available as-received in raw. For details on data models refer to the individual model descriptions.

encharge_inventory: dict[str, EnvoyEncharge] | None: dict of found Encharge device information, keyed by Encharge serial number.

encharge_power: dict[str, EnvoyEnchargePower] | None: dict of Enpower device power and charge state, keyed by Enpower serial number.

encharge_aggregate: EnvoyEnchargeAggregate | None: Aggregated data for all Encharge devices

enpower: EnvoyEnpower | None: EnchargePower device information

acb_power: EnvoyACBPower | None: Power and soc for aggregated ACB batteries

battery_aggregate: EnvoyBatteryAggregate | None: aggregated Enphase and ACB battery SOC and total capacity

collar: EnvoyCollar | None: IQ Meter collar, only for Envoy with IQ Meter Collar integrated consumption metering installed

c6cc: EnvoyC6CC | None: Envoy C6 Combiner controller

system_consumption: EnvoySystemConsumption | None: Consumption power & energy values, only for Envoy metered with CT installed

system_production: EnvoySystemProduction | None: Solar Production power & energy values

system_consumption_phases: dict[str, EnvoySystemConsumption | None] | None: Individual phase consumption power & energy values, keyed by PhaseNames, only for Envoy metered with CT installed

system_production_phases: dict[str, EnvoySystemProduction | None] | None: Individual phase solar production power & energy values, keyed by PhaseNames, only for Envoy metered with CT installed

system_net_consumption: EnvoySystemConsumption | None: Net consumption power & energy values, a.k.a. grid import/export, only for Envoy metered with CT installed

system_net_consumption_phases: dict[str, EnvoySystemConsumption | None] | None: Individual phase Net consumption power & energy values, keyed by PhaseNames, only for Envoy metered with CT installed

ctmeter_production: EnvoyMeterData | None: Production CT Meter data

ctmeter_consumption: EnvoyMeterData | None: Consumption CT Meter data

ctmeter_storage: EnvoyMeterData | None: Storage CT Meter data

ctmeter_production_phases: dict[str, EnvoyMeterData] | None: Individual phase production ct power & energy values, keyed by PhaseNames, only for Envoy metered with production CT installed

ctmeter_consumption_phases: dict[str, EnvoyMeterData] | None: Individual phase consumption ct power & energy values, keyed by PhaseNames, only for Envoy metered with consumption installed

ctmeter_storage_phases: dict[str, EnvoyMeterData] | None: Individual phase storage ct power & energy values, keyed by PhaseNames, only for Envoy metered with storage CT installed

dry_contact_status: dict[str, EnvoyDryContactStatus]: dict of Dry contact relay status, keyed by relay ID

dry_contact_settings: dict[str, EnvoyDryContactSettings]: dict of Dry contact relay settings, keyed by relay ID

inverters: dict[str, EnvoyInverter]: dict of Solar inverter data, keyed by inverter serial-number

tariff: EnvoyTariff | None: Tariff information from Envoy

raw: dict[str, Any]: All request responses received from Envoy in last Envoy.update, keyed by endpoint

pyenphase constant definitions

class pyenphase.const.SupportedFeatures(*values)

Bases: IntFlag

Features available from Envoy

Each supported feature maps to a specific data set or information that can be provided by an Envoy. Depending on actual make, firmware and installed components an Envoy may provide 1 or more features. All Envoy should at least report solar production, marked as PRODUCTION.

Class EnvoyUpdater updaters will set these features flags during the Envoy.probe phase. During data collection by Envoy.update each updater with set features will be used to collect the specific data.

from pyenphase.const import SupportedFeatures

# set METERING flag
features |= SupportedFeatures.METERING

# test features
if features.PRODUCTION in supported_features:
    pass

if features & SupportedFeatures.DUALPHASE:
    pass

INVERTERS = 1: Envoy reports solar panel inverters

METERING = 2: Envoy reports active production meter

TOTAL_CONSUMPTION = 4: Envoy reports total consumption

NET_CONSUMPTION = 8: Envoy reports net consumption

ENCHARGE = 16: Envoy reports encharge data

ENPOWER = 32: Envoy reports Enpower data

PRODUCTION = 64: Envoy reports solar production data

TARIFF = 128: Envoy reports tariff information

DUALPHASE = 256: Envoy metered is configured in split phase mode

THREEPHASE = 512: Envoy metered is configured in three phase mode

CTMETERS = 1024: Envoy has enabled CT meter(s)

GENERATOR = 2048: Envoy reports generator data

ACB = 4096: Envoy reports ACB Battery data

DETAILED_INVERTERS = 8192: Detailed inverter data is reported

COLLAR = 16384: Envoy reports a Collar

C6CC = 32768: Envoy reports a C6 Combiner controller

class pyenphase.const.PhaseNames(*values)

Bases: StrEnum

Electricity grid phase names.

PHASE_1 = 'L1': first phase (1, A, ..)

PHASE_2 = 'L2': second phase (2, B, ..)

PHASE_3 = 'L3': third phase (3, C, ..)

pyenphase.const.PHASENAMES: list[str] = [PhaseNames.PHASE_1, PhaseNames.PHASE_2, PhaseNames.PHASE_3]

list to access PhaseNames by numerical index.

phase_count = 2
for phase in range(phase_count):
    print(production[PHASENAMES[phase]])

Model for common properties of an envoy.

class pyenphase.models.common.CommonProperties(production_fallback_list=<factory>, acb_batteries_reported=0, imeter_info=False, phase_count=0, ct_meter_count=0, phase_mode=None, consumption_meter_type=None, production_meter_type=None, storage_meter_type=None, active_phase_count=0)

Bases: object

Model for common properties of an envoy shared amongst all updaters.

One set are properties set during probe to share amongst updaters and with clients. These should be reset at each probe run.

More properties can be added, originators should handle reset as needed by adding to reset_probe_properties to reset at probe or in a different way or leave existing all lifetime.

production_fallback_list: list[str]: Fallback production endpoints for Metered without CT

acb_batteries_reported: int: ACB batteries report current power in production and in ensemble secctl Ensemble updater should only report combined ACB en Encharge if production report has data

imeter_info: bool: imeter flag from /info. If true envoy is metered type used to detect metered without actual CT installed to enable picking correct data

phase_count: int: number of phases configured in envoy

ct_meter_count: int: number of active ct meters

phase_mode: EnvoyPhaseMode | None: phase mode configured in the CT meters

consumption_meter_type: CtType | None

production_meter_type: CtType | None

storage_meter_type: CtType | None

active_phase_count: int: number of phases actually reporting phase data

reset_probe_properties(is_metered=False)

Reset common properties that are initialized during probe.

probe properties are reset at each probe to avoid sticking memories. This should exclude common properties set outside of probe or controlled by a specific updater, these should be reset at different moments by different method by updaters or owner

reset properties:

production_fallback_list shared amongst production updaters ACB_batteries_reported shared between production and Ensemble imeter_info setting from /info indicating envoy is metered type

Return type:: None

Updaters

Base class

class pyenphase.updaters.base.EnvoyUpdater(envoy_version, probe_request, request, common_properties)

Bases: object

Base class for Envoy updaters.

abstractmethod async probe(discovered_features)

Probe the Envoy for this updater and return SupportedFeatures.

Return type:: SupportedFeatures | None

abstractmethod async update(envoy_data)

Update the Envoy for this updater.

Return type:: None

production

Envoy production data updater

class pyenphase.updaters.production.EnvoyProductionUpdater(envoy_version, probe_request, request, common_properties)

Bases: EnvoyUpdater

Class to handle updates for production data.

end_point = '/production'

allow_inverters_fallback = False

async probe(discovered_features)

Probe the Envoy for this endpoint and return SupportedFeatures.

Return type:: SupportedFeatures | None

async update(envoy_data)

Update the Envoy for this endpoint.

Return type:: None

class pyenphase.updaters.production.EnvoyProductionJsonUpdater(envoy_version, probe_request, request, common_properties)

Bases: EnvoyProductionUpdater

Class to handle updates for production data from the production.json endpoint.

end_point = '/production.json?details=1'

class pyenphase.updaters.production.EnvoyProductionJsonFallbackUpdater(envoy_version, probe_request, request, common_properties)

Bases: EnvoyProductionJsonUpdater

Class to handle updates for production data from the production.json endpoint.

This class will accept the production endpoint even if activeCount is 0

allow_inverters_fallback = True

class pyenphase.updaters.api_v1_production.EnvoyApiV1ProductionUpdater(envoy_version, probe_request, request, common_properties)

Bases: EnvoyUpdater

Class to handle updates for production data.

async probe(discovered_features)

Probe the Envoy for this updater and return SupportedFeatures.

Return type:: SupportedFeatures | None

async update(envoy_data)

Update the Envoy for this updater.

Return type:: None

Inverters

class pyenphase.updaters.api_v1_production_inverters.EnvoyApiV1ProductionInvertersUpdater(envoy_version, probe_request, request, common_properties)

Bases: EnvoyUpdater

Class to handle updates for inverter production data.

async probe(discovered_features)

Probe the Envoy for this updater and return SupportedFeatures.

Return type:: SupportedFeatures | None

async update(envoy_data)

Update the Envoy for this updater.

Return type:: None

EnvoyEnsemble

Pyenphase Ensemble updater class.

class pyenphase.updaters.ensemble.EnvoyEnembleUpdater(envoy_version, probe_request, request, common_properties)

Bases: EnvoyUpdater

Class to handle updates for Ensemble devices.

async probe(discovered_features)

Probe the Envoy for this updater and return SupportedFeatures.

Return type:: SupportedFeatures | None

async update(envoy_data)

Update the Envoy for this updater.

Return type:: None

EnvoyTariff

class pyenphase.updaters.tariff.EnvoyTariffUpdater(envoy_version, probe_request, request, common_properties)

Bases: EnvoyUpdater

Class to handle updates for the Envoy tariff data.

async probe(discovered_features)

Probe the Envoy for this updater and return SupportedFeatures.

Return type:: SupportedFeatures | None

async update(envoy_data)

Update the Envoy for this updater.

Return type:: None

Current Transformers

Envoy CT Meter updater

class pyenphase.updaters.meters.EnvoyMetersUpdater(envoy_version, probe_request, request, common_properties)

Bases: EnvoyUpdater

Class to handle updates for Envoy CT Meters.

end_point = '/ivp/meters': endpoint in envoy to read CT meter configuration

data_end_point = '/ivp/meters/readings'

production_meter_type: CtType | None = None: Production CT type

consumption_meter_type: CtType | None = None: Consumpion CT type (net or total)

storage_meter_type: CtType | None = None: Storage CT type

phase_mode: EnvoyPhaseMode | None = None

phase_count: int = 0: Number of phases configured and measured in the Envoy

ct_meters_count: int = 0

production_meter_eid: str | None = None: Production CT identifier

consumption_meter_eid: str | None = None: Consumption CT identifier

storage_meter_eid: str | None = None: Storage CT identifier

async probe(discovered_features)

Probe the Envoy meter setup and return CT and multiphase details in SupportedFeatures.

Get CT configuration info from ivp/meters in the Envoy and determine any multi-phase setup. Set Threephase or Dualphase supported feature if Envoy is in one of these setups. Set common property information in envoy data for phase_count, ct_meter_count, phase_mode and ct_consumption_meter type to default or found values. These 4 are owned by this updater.

Parameters:: discovered_features (SupportedFeatures) – Features discovered by other updaters for this updater to skip
Return type:: SupportedFeatures | None
Returns:: features discovered by this updater

async update(envoy_data)

Update the Envoy data from the meters endpoints.

Get CT configuration from ivp/meters and CT readings from ivp/meters/readings. Store data as EnvoyMeterData in ctmeter_production, ctmeter_consumption if either meter is found enabled during probe. If more then 1 phase is active, store phase data in ctmeter_production_phases and ctmeter_consumption_phases. Match data in ivp/meters and ivp/meters/reading using the eid field in both datasets.

Parameters:: envoy_data (EnvoyData) – EnvoyData structure to store data to
Return type:: None

Models

EnvoySystemProduction

class pyenphase.models.system_production.EnvoySystemProduction(watt_hours_lifetime, watt_hours_last_7_days, watt_hours_today, watts_now)

Bases: object

Model for the Envoy’s production data.

watt_hours_lifetime: int: Lifetime Energy produced

watt_hours_last_7_days: int: Energy produced in previous 7 days (not including today)

watt_hours_today: int: Energy produced since start of day

watts_now: int: Current Power production

classmethod from_v1_api(data)

Initialize from the V1 API.

Parameters:: data (dict[str, Any]) – JSON reply from api/v1/production endpoint
Return type:: EnvoySystemProduction
Returns:: Lifetime, last seven days, todays energy and current power for solar production

classmethod from_production(data)

Initialize from the production API.

Parameters:: data (dict[str, Any]) – JSON reply from /production endpoint
Return type:: EnvoySystemProduction
Returns:: Lifetime, last seven days, todays energy and current power for solar production

classmethod from_production_phase(data, phase)

Initialize from the production API phase data.

Parameters:

data (dict[str, Any]) – JSON reply from /production endpoint
phase (int) – Index (0-2) in [lines] segment for which to return data

Return type:

EnvoySystemProduction | None

Returns:

Lifetime, last seven days, todays energy and current power for production phase

EnvoySystemConsumption

class pyenphase.models.system_consumption.EnvoySystemConsumption(watt_hours_lifetime, watt_hours_last_7_days, watt_hours_today, watts_now)

Bases: object

Model for the Envoy’s (total, house) consumption data.

watt_hours_lifetime: int: Lifetime Energy consumed (total-consumption, house)

watt_hours_last_7_days: int: Energy consumed in previous 7 days (not including today)

watt_hours_today: int: Energy consumption since start of day (total-consumption, house)

watts_now: int: Current Power consumption (total-consumption, house)

classmethod from_production(data, consumption_segment=0)

Initialize from the production API.

Parameters:: data (dict[str, Any]) – JSON reply from /production endpoint
Return type:: EnvoySystemConsumption
Returns:: Lifetime, last 7 days, todays energy and current power for total-consumption

classmethod from_production_phase(data, phase, consumption_segment=0)

Initialize from the production API phase data.

Parameters:

data (dict[str, Any]) – JSON reply from /production endpoint
phase (int) – Index (0-2) in [lines] segment for which to return data

Return type:

EnvoySystemConsumption | None

Returns:

Lifetime, last 7 days, todays energy and current power for total-consumption phase

EnvoyInverter

class pyenphase.models.inverter.EnvoyInverter(serial_number, last_report_date, last_report_watts, max_report_watts, dc_voltage=None, dc_current=None, ac_voltage=None, ac_current=None, ac_frequency=None, temperature=None, lifetime_energy=None, energy_produced=None, energy_today=None, last_report_duration=None)

Bases: object

Model for an Enphase microinverter.

serial_number: str

last_report_date: int

last_report_watts: int

max_report_watts: int

dc_voltage: float | None

dc_current: float | None

ac_voltage: float | None

ac_current: float | None

ac_frequency: float | None

temperature: float | None

lifetime_energy: int | None

energy_produced: float | None

energy_today: int | None

last_report_duration: int | None

classmethod from_v1_api(data)

Initialize from the V1 API.

Return type:: EnvoyInverter

classmethod from_device_data(data)

Initialize from device data.

Return type:: EnvoyInverter

EnvoyEncharge

class pyenphase.models.encharge.EnvoyEncharge(admin_state, admin_state_str, bmu_firmware_version, comm_level_2_4_ghz, comm_level_sub_ghz, communicating, dc_switch_off, encharge_capacity, encharge_revision, firmware_loaded_date, firmware_version, installed_date, last_report_date, led_status, max_cell_temp, operating, part_number, percent_full, serial_number, temperature, temperature_unit, zigbee_dongle_fw_version)

Bases: object

Model for the Encharge/IQ battery.

admin_state: int

admin_state_str: str

bmu_firmware_version: str

comm_level_2_4_ghz: int

comm_level_sub_ghz: int

communicating: bool

dc_switch_off: bool

encharge_capacity: int

encharge_revision: int

firmware_loaded_date: int

firmware_version: str

installed_date: int

last_report_date: int

led_status: int

max_cell_temp: int

operating: bool | None

part_number: str

percent_full: int

serial_number: str

temperature: int

temperature_unit: str

zigbee_dongle_fw_version: str | None

classmethod from_api(inventory)

Initialize from the API.

Return type:: EnvoyEncharge

EnvoyEnchargeAggregate

class pyenphase.models.encharge.EnvoyEnchargeAggregate(available_energy, backup_reserve, state_of_charge, reserve_state_of_charge, configured_reserve_state_of_charge, max_available_capacity)

Bases: object

Model for Encharge aggregate data.

available_energy: int

backup_reserve: int

state_of_charge: int

reserve_state_of_charge: int

configured_reserve_state_of_charge: int

max_available_capacity: int

classmethod from_api(data)

Initialize from the API.

Return type:: EnvoyEnchargeAggregate

EnvoyEnchargePower

class pyenphase.models.encharge.EnvoyEnchargePower(apparent_power_mva, real_power_mw, soc)

Bases: object

Model for the Encharge/IQ battery power.

apparent_power_mva: int

real_power_mw: int

soc: int

classmethod from_api(power)

Initialize from the API.

Return type:: EnvoyEnchargePower

EnvoyEnpower

class pyenphase.models.enpower.EnvoyEnpower(grid_mode, admin_state, admin_state_str, comm_level_2_4_ghz, comm_level_sub_ghz, communicating, firmware_loaded_date, firmware_version, installed_date, last_report_date, mains_admin_state, mains_oper_state, operating, part_number, serial_number, temperature, temperature_unit, zigbee_dongle_fw_version)

Bases: object

Model for the Enpower/IQ System Controller.

grid_mode: str

admin_state: int

admin_state_str: str

comm_level_2_4_ghz: int

comm_level_sub_ghz: int

communicating: bool

firmware_loaded_date: int

firmware_version: str

installed_date: int

last_report_date: int

mains_admin_state: str

mains_oper_state: str

operating: bool | None

part_number: str

serial_number: str

temperature: int

temperature_unit: str

zigbee_dongle_fw_version: str | None

classmethod from_api(enpower)

Initialize from the API.

Return type:: EnvoyEnpower

ACBPower

class pyenphase.models.acb.EnvoyACBPower(power, charge_wh, state_of_charge, state, batteries)

Bases: object

Model for the ACB battery power.

power: int: Current discharge/charge power for ACB batteries from wNow.

charge_wh: int: Current available capacity in Wh for ACB batteries from whNow

state_of_charge: int: Current SOC in percentage for ACB batteries from percentFull

state: str: Current state for ACB batteries (discharging/idle/charging) from state

batteries: int: Number of reported ACB batteries from activeCount

classmethod from_production(data, acb_segment=0)

Fill ACB battery power data from Envoy data format.

Source data URL_PRODUCTION_JSON[“storage”]

"storage": [{
    "type": "acb",
    "activeCount": 3,
    "readingTime": 1731943992,
    "wNow": 260,
    "whNow": 930,
    "state": "discharging",
    "percentFull": 25
}]

Parameters:

data (dict[str, Any]) – JSON returned from URL_PRODUCTION_JSON
acb_segment (int) – segment to process from storage list, default is 0

Returns:

ACB battery current power out/in and energy content and status

Return type:

EnvoyACBPower

Envoy Aggregate Battery SOC

class pyenphase.models.acb.EnvoyBatteryAggregate(available_energy, state_of_charge, max_available_capacity)

Bases: object

Model for combined Encharge and ACB batteries aggregate data.

available_energy: int: Sum of Encharge aggregate and ACB aggregate current battery energy content from ENC_agg_avail_energy and ACB_agg_energy.

state_of_charge: int: Combined State of charge for all Encharge and ACB batteries from agg_soc.

max_available_capacity: int: Combined total maximum capacity for all Encharge and ACB batteries from Max_energy.

classmethod from_api(data)

Fill Aggregated battery data from Envoy data format.

Source data parts of URL_ENSEMBLE_SECCTRL

{

    "agg_soc": 39,
    "Max_energy": 7220,

    "ENC_agg_avail_energy": 350,

    "Enc_max_available_capacity": 3500,
    "ACB_agg_soc": 25,
    "ACB_agg_energy": 930,

}

Parameters:: data (dict[str, Any]) – JSON returned from URL_ENSEMBLE_SECCTRL
Returns:: Aggregated Battery data for all Encharge and ACB batteries
Return type:: EnvoyBatteryAggregate

EnvoyDryContactSettings

Model for the Enpower dry contact relays.

class pyenphase.models.dry_contacts.DryContactStatus(*values)

Bases: StrEnum

OPEN = 'open'

CLOSED = 'closed'

class pyenphase.models.dry_contacts.DryContactAction(*values)

Bases: StrEnum

APPLY = 'apply'

SHED = 'shed'

SCHEDULE = 'schedule'

NONE = 'none'

class pyenphase.models.dry_contacts.DryContactType(*values)

Bases: StrEnum

NONE = 'NONE'

PV = 'PV'

LOAD = 'LOAD'

THIRD_PARTY_PV = '3RD-PV'

class pyenphase.models.dry_contacts.DryContactMode(*values)

Bases: StrEnum

MANUAL = 'manual'

STATE_OF_CHARGE = 'soc'

class pyenphase.models.dry_contacts.EnvoyDryContactStatus(id, status)

Bases: object

Model for the Enpower dry contact relay status.

id: str

status: str

classmethod from_api(relay)

Initialize from the API.

Return type:: EnvoyDryContactStatus

class pyenphase.models.dry_contacts.EnvoyDryContactSettings(id, black_start, essential_end_time, essential_start_time, generator_action, grid_action, load_name, manual_override, micro_grid_action, mode, override, priority, pv_serial_nb, soc_high, soc_low, type)

Bases: object

Model for the Enpower dry contact relay settings.

id: str

black_start: float | None

essential_end_time: float | None

essential_start_time: float | None

generator_action: DryContactAction

grid_action: DryContactAction

load_name: str

manual_override: bool | None

micro_grid_action: DryContactAction

mode: DryContactMode

override: bool

priority: float | None

pv_serial_nb: list[Any]

soc_high: float

soc_low: float

type: DryContactType

classmethod from_api(relay)

Initialize from the API.

Return type:: EnvoyDryContactSettings

to_api()

Convert to API format.

Return type:: dict[str, Any]

EnvoyCollar

Model for the IQ Meter Collar.

class pyenphase.models.collar.EnvoyCollar(admin_state, admin_state_str, firmware_loaded_date, firmware_version, installed_date, last_report_date, communicating, mid_state, grid_state, part_number, serial_number, temperature, temperature_unit, control_error, collar_state)

Bases: object

Model for the Enphase IQ Meter Collar.

admin_state: int

admin_state_str: str

firmware_loaded_date: int

firmware_version: str

installed_date: int

last_report_date: int

communicating: bool

mid_state: str

grid_state: str

part_number: str

serial_number: str

temperature: int

temperature_unit: str

control_error: int

collar_state: str

classmethod from_api(inventory)

Initialize from the API. Returns None if required keys are missing.

Return type:: EnvoyCollar | None

EnvoyC6CC

Model for the Enphase C6 Combiner.

class pyenphase.models.c6combiner.EnvoyC6CC(admin_state, admin_state_str, firmware_loaded_date, firmware_version, installed_date, last_report_date, communicating, part_number, serial_number, dmir_version)

Bases: object

Model for the Enphase C6 Combiner.

admin_state: int

admin_state_str: str

firmware_loaded_date: int

firmware_version: str

installed_date: int

last_report_date: int

communicating: bool

part_number: str

serial_number: str

dmir_version: str

classmethod from_api(inventory)

Initialize from the API. Returns None if required keys are missing.

Return type:: EnvoyC6CC | None

CT Meters

Model for the Envoy’s CT Meters.

class pyenphase.models.meters.EnvoyPhaseMode(*values)

Bases: StrEnum

SPLIT = 'split'

THREE = 'three'

SINGLE = 'single'

class pyenphase.models.meters.CtType(*values)

Bases: StrEnum

PRODUCTION = 'production'

NET_CONSUMPTION = 'net-consumption'

TOTAL_CONSUMPTION = 'total-consumption'

STORAGE = 'storage'

class pyenphase.models.meters.CtState(*values)

Bases: StrEnum

ENABLED = 'enabled'

DISABLED = 'disabled'

class pyenphase.models.meters.CtMeterStatus(*values)

Bases: StrEnum

NORMAL = 'normal'

NOT_METERING = 'not-metering'

CHECK_WIRING = 'check-wiring'

class pyenphase.models.meters.CtStatusFlags(*values)

Bases: StrEnum

PODUCTION_IMBALANCE = 'production-imbalance'

NEGATIVE_PRODUCTION = 'negative-production'

POWER_ON_UNUSED_PHASE = 'power-on-unused-phase'

NEGATIVE_TOTAL_CONSUMPTION = 'negative-total-consumption'

class pyenphase.models.meters.CtMeterData

Bases: TypedDict

eid: str

state: CtState

measurementType: CtType

phaseMode: EnvoyPhaseMode

phaseCount: int

meteringStatus: CtMeterStatus

statusFlags: list[CtStatusFlags]

class pyenphase.models.meters.EnvoyMeterData(eid, timestamp, energy_delivered, energy_received, active_power, power_factor, voltage, current, frequency, state, measurement_type, metering_status, status_flags)

Bases: object

Model for the Envoy’s CT meter data.

eid: str: CT meter identifier

timestamp: int: Time of measurement

energy_delivered: int: Lifetime Energy delivered through CT

energy_received: int: Lifetime Energy received through CT

active_power: int: Current power exchang through CT, positive is delivering, negative is receiving

power_factor: float: Power factor reported for CT measurement

voltage: float: Voltage on circuit, when multiphase sum of voltage of individual phases

current: float: current measured by CT

frequency: float: frequency measured by CT

state: CtState | None: Actual State of CT

measurement_type: CtType | None: Measurement type configured for CT

metering_status: CtMeterStatus | None: CT Measurement status

status_flags: list[CtStatusFlags] | None: CT status flags.

classmethod from_api(data, meter_status)

Return CT meter data from /ivp/meters and ivp/meters/reading json.

Return type:: EnvoyMeterData

classmethod from_phase(data, meter_status, phase)

Return CT meter phase data from /ivp/meters and ivp/meters/reading json.

Return type:: EnvoyMeterData | None

Interface data

class pyenphase.models.home.EnvoyInterfaceInformation(primary_interface, mac, interface_type, dhcp, software_build_epoch, timezone)

Bases: object

Envoy Interface information data model.

primary_interface: str: name of primary (active) interface

mac: str: mac of primary interface, “unknown” if missing

interface_type: str: primary interface type, “unknown” if missing

dhcp: bool: interfaces uses DHCP, False if missing

software_build_epoch: int: envoy software build time, 0 if missing

timezone: str: Timezone set in Envoy, “unknown” if missing

classmethod from_api(data)

Return active interface information configured in Envoy

Parses the received JSON into EnvoyInterfaceInformation model data Source data must be sourced from URL_HOME.

software_build_epoch, timezone are returned as is. network.primary_interface is returned as is, and used to find interface data in network.interfaces from which type, mac and dhcp are returned.

Not all Envoy firmware version may return all data. Defaults for str members is unknown, int 0 and bool False

Example json returned from /home endpoint:

{
"software_build_epoch": 1719503966,
"timezone": "Europe/Amsterdam",
"current_date": "04/24/2025",
"current_time": "14:53",
"network": {
    "web_comm": true,
    "ever_reported_to_enlighten": true,
    "last_enlighten_report_time": 1745499043,
    "primary_interface": "eth0",
    "interfaces": [
    {
        "type": "ethernet",
        "interface": "eth0",
        "mac": "00:1D:C0:7F:B6:3B",
        "dhcp": true,
        "ip": "192.168.3.112",
        "signal_strength": 1,
        "signal_strength_max": 1,
        "carrier": true
    },
    {
        "signal_strength": 0,
        "signal_strength_max": 0,
        "type": "wifi",
        "interface": "wlan0",
        "mac": "60:E8:5B:AB:9D:64",
        "dhcp": true,
        "ip": null,
        "carrier": false,
        "supported": true,
        "present": true,
        "configured": false,
        "status": "connecting"
    }
]

}

Parameters:: data (dict[str, Any]) – json returned by /home endpoint
Return type:: EnvoyInterfaceInformation | None
Returns:: Envoy interface configuration information

Utilities

Json

Helper functions for JSON.

class pyenphase.json.json_loads(end_point, json_source)

Bases:

Deserialize a JSON string into a Python object

Parameters:

end_point (str) – source for json, used for debug log, typically endpoint on Envoy.
json_source (bytes | str) – json string, typically from request response content to Envoy.

Return type:

Any

Returns:

deserialized JSON

SSL

Pyenphase SSL helper

pyenphase.ssl.NO_VERIFY_SSL_CONTEXT = <ssl.SSLContext object>

Alias for create_no_verify_ssl_context

import aiohttp
from pyenphase.ssl import NO_VERIFY_SSL_CONTEXT

connector = aiohttp.TCPConnector(ssl=NO_VERIFY_SSL_CONTEXT)
client = aiohttp.ClientSession(connector=connector)

pyenphase.ssl.SSL_CONTEXT = <ssl.SSLContext object>

Alias for create_default_ssl_context

import aiohttp
from pyenphase.ssl import SSL_CONTEXT

connector = aiohttp.TCPConnector(ssl=SSL_CONTEXT)
async with aiohttp.ClientSession(connector=connector) as client:
    response = await client.post(url, json=json, data=data)

pyenphase.ssl.create_default_ssl_context()

Create aiohttp client with default SSL context.

Return type:: SSLContext

pyenphase.ssl.create_no_verify_ssl_context()

Return an SSL context that does not verify the server certificate.

This is a copy of aiohttp’s create_default_context() function, with the ssl verify turned off and old SSL versions enabled.

https://github.com/aio-libs/aiohttp/blob/33953f110e97eecc707e1402daa8d543f38a189b/aiohttp/connector.py#L911

Return type:: SSLContext
Returns:: SSLcontext with ssl verify turned off.

Exceptions

Enphase Envoy exceptions.

exception pyenphase.exceptions.EnvoyError

Bases: Exception

Base class for Envoy exceptions.

exception pyenphase.exceptions.EnvoyFirmwareCheckError(status_code, status)

Bases: EnvoyError

Exception raised when unable to query the Envoy firmware version.

http error when sending request to Envoy
Any http status code other then 200 received

Parameters:

status_code (int) – http status code
status (str) – Error status description

exception pyenphase.exceptions.EnvoyFirmwareFatalCheckError(status_code, status)

Bases: EnvoyError

Exception raised when we should not retry getting the Envoy firmware version.

aiohttp timeout or connection error when sending request to Envoy

Parameters:

status_code (int) – http status code
status (str) – Error status description

exception pyenphase.exceptions.EnvoyAuthenticationError(status)

Bases: EnvoyError

Exception raised when Envoy Authentication fails.

When a jwt token authentication failure occurs with the local Envoy.
When using token authentication and no cloud credentials or envoy serial are specified
When a failure occurs during obtaining a token from the Enlighten cloud

Parameters:: status (str) – Error status description

exception pyenphase.exceptions.EnvoyAuthenticationRequired(status)

Bases: EnvoyError

Exception raised when authentication hasn’t been setup.

When communication with Envoy was attempted without setting up authentication.
When neither token nor username and/or password are specified during authentication.