Classes, methods and properties

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

Bases: object

Class for communicating with an envoy.

async setup()

Obtain the firmware version for later Envoy authentication.

Return type:: None

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

Authenticate to the Envoy based on firmware version.

Return type:: None

async probe_request(endpoint)

Make a probe request.

Probe requests are not retried on bad JSON responses.

Return type:: Response

async request(endpoint, data=None)

Make a request to the Envoy.

Request retries on bad JSON responses which the Envoy sometimes returns.

Return type:: Response

property host: str: Return the Envoy host.

property firmware: AwesomeVersion: Return the Envoy firmware version.

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

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

property supported_features: SupportedFeatures: Return the supported features.

property phase_count: int: Return the number of configured phases for CT meters.

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

property ct_meter_count: int: Return the number of configured current transformers (CT)

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

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

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

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

property envoy_model: str: Return Envoy model description.

async probe()

Probe for model and supported features.

Return type:: None

async update()

Update data.

Return type:: EnvoyData

async go_on_grid()

Make a request to the Envoy to go on grid.

Return type:: dict[str, Any]

async go_off_grid()

Make a request to the Envoy to go off grid.

Return type:: dict[str, Any]

async update_dry_contact(new_data)

Update settings for an Enpower dry contact relay.

Return type:: dict[str, Any]

async open_dry_contact(id)

Open a dry contact relay.

Return type:: dict[str, Any]

async close_dry_contact(id)

Open a dry contact relay.

Return type:: dict[str, Any]

async enable_charge_from_grid()

Enable charge from grid for Encharge batteries.

Return type:: dict[str, Any]

async disable_charge_from_grid()

Disable charge from grid for Encharge batteries.

Return type:: dict[str, Any]

async set_storage_mode(mode)

Set the Encharge storage mode.

Return type:: dict[str, Any]

async set_reserve_soc(value)

Set the Encharge reserve state of charge.

Return type:: dict[str, Any]

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

Bases: EnvoyAuth

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

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

async setup(client)

Obtain the token for Envoy authentication.

Return type:: None

async refresh()

Refresh the token for Envoy authentication.

Return type:: None

property expire_timestamp: int: Return the remaining seconds for the token.

property token: str: Return token retrieved from enligthen

property manager_token: str: Return manager token returned in enligthen login json

property cookies: dict[str, str]: return cookies returned from local jwt check

property is_consumer: bool: Return is_consumer state returned in enligthen login json

property auth: None: No auth required for token authentication.

property headers: dict[str, str]: Return the headers for Envoy authentication.

get_endpoint_url(endpoint)

Return the URL for the endpoint.

Return type:: str

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

Bases: object

Class for querying and determining the Envoy firmware version.

async setup()

Obtain the firmware version for Envoy authentication.

Return type:: None

property version: AwesomeVersion

property serial: str | None

property part_number: str | None

class pyenphase.EnvoyData(encharge_inventory=None, encharge_power=None, encharge_aggregate=None, enpower=None, system_consumption=None, system_production=None, system_consumption_phases=None, system_production_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

Model for an envoy.

encharge_inventory: dict[str, EnvoyEncharge] | None

encharge_power: dict[str, EnvoyEnchargePower] | None

encharge_aggregate: EnvoyEnchargeAggregate | None

enpower: EnvoyEnpower | None

system_consumption: EnvoySystemConsumption | None

system_production: EnvoySystemProduction | None

system_consumption_phases: dict[str, EnvoySystemConsumption | None] | None

system_production_phases: dict[str, EnvoySystemProduction | None] | None

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

ctmeter_consumption_phases: dict[str, EnvoyMeterData] | None

ctmeter_storage_phases: dict[str, EnvoyMeterData] | None

dry_contact_status: dict[str, EnvoyDryContactStatus]

dry_contact_settings: dict[str, EnvoyDryContactSettings]

inverters: dict[str, EnvoyInverter]

tariff: EnvoyTariff | None

raw: dict[str, Any]

class pyenphase.const.SupportedFeatures(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: IntFlag

Features available from Envoy

INVERTERS = 1: Envoy reports 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 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

class pyenphase.const.PhaseNames(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: StrEnum

PHASE_1 = 'L1'

PHASE_2 = 'L2'

PHASE_3 = 'L3'

Model for common properties of an envoy.

class pyenphase.models.common.CommonProperties(production_fallback_list=<factory>, 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

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()

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: :rtype: None

production_fallback_list shared amongst production updaters

Updaters

Base class

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

Bases: object

Base class for Envoy updaters.

abstract async probe(discovered_features)

Probe the Envoy for this updater and return SupportedFeatures.

Return type:: SupportedFeatures | None

abstract 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

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

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

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

Bases: object

Model for an Enphase microinverter.

serial_number: str

last_report_date: int

last_report_watts: int

max_report_watts: int

classmethod from_v1_api(data)

Initialize from the V1 API.

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

EnvoyDryContactSettings

Model for the Enpower dry contact relays.

class pyenphase.models.dry_contacts.DryContactStatus(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: StrEnum

OPEN = 'open'

CLOSED = 'closed'

class pyenphase.models.dry_contacts.DryContactAction(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: StrEnum

APPLY = 'apply'

SHED = 'shed'

SCHEDULE = 'schedule'

NONE = 'none'

class pyenphase.models.dry_contacts.DryContactType(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: StrEnum

NONE = 'NONE'

PV = 'PV'

LOAD = 'LOAD'

class pyenphase.models.dry_contacts.DryContactMode(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

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]

CT Meters

Model for the Envoy’s CT Meters.

class pyenphase.models.meters.EnvoyPhaseMode(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: StrEnum

SPLIT = 'split'

THREE = 'three'

SINGLE = 'single'

class pyenphase.models.meters.CtType(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: StrEnum

PRODUCTION = 'production'

NET_CONSUMPTION = 'net-consumption'

TOTAL_CONSUMPTION = 'total-consumption'

STORAGE = 'storage'

class pyenphase.models.meters.CtState(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: StrEnum

ENABLED = 'enabled'

DISABLED = 'disabled'

class pyenphase.models.meters.CtMeterStatus(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: StrEnum

NORMAL = 'normal'

NOT_METERING = 'not-metering'

CHECK_WIRING = 'check-wiring'

class pyenphase.models.meters.CtStatusFlags(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

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

Utilities

Json

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

Bases:

Return type:: Any

SSL

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