Current Transformer Data
This section documents CT data for Envoy‑metered systems via EnvoyMeterData.
Depending on how many and which CT are installed, data is available in:
Legacy per‑type attributes remain for compatibility:
These map to their counterparts pyenphase.EnvoyData.ctmeters[CtType]. In some future version these may be deprecated.
There are multiple CT types that can be installed. The CT meter types are enumerated as production, storage, net-consumption, total-consumption, backfeed, load, evse and pv3p by pyenphase.models.meters.CtType. One or more of these can be installed and enabled. For multi-phase configurations, there will be one per phase.
data: EnvoyData = await envoy.update()
production_ct = data.ctmeters[CtType.PRODUCTION]
print(f'eid: {production_ct.eid}')
print(f'timestamp: {production_ct.timestamp}')
print(f'energy_delivered: {production_ct.energy_delivered}')
print(f'energy_received: {production_ct.energy_received}')
print(f'power_factor: {production_ct.power_factor}')
print(f'active_power: {production_ct.active_power}')
print(f'voltage: {production_ct.voltage}')
print(f'current: {production_ct.current}')
print(f'frequency: {production_ct.frequency}')
print(f'state: {production_ct.state}')
print(f'measurement_type: {production_ct.measurement_type}')
print(f'metering_status: {production_ct.metering_status}')
print(f'status_flags: {production_ct.status_flags}')
To detect how many CTs are installed, use the Envoy property ct_meter_count. You can identify which CT meters are available via pyenphase.Envoy.ct_meter_list. To test presence of individual CT meters use pyenphase.Envoy.meter_type() with a CtType argument.
The consumption CT can be either net-consumption (installed at the grid boundary) or total-consumption (measuring house load); see ct-model below. Which one is installed, is available in pyenphase.Envoy.consumption_meter_type. The IQ Metered collar includes an embedded net-consumption CT.
how_many_ct = envoy.ct_meter_count
meter_list = envoy.ct_meter_list
consumption_ct = 'installed' if envoy.consumption_meter_type else 'not installed'
production_ct = 'installed' if envoy.meter_type(CtType.PRODUCTION) else 'not installed'
storage_ct = 'installed' if CtType.STORAGE in meter_list else 'not installed'
print(f'This Envoy has Production CT {production_ct}, Consumption CT {consumption_ct}, and Storage CT {storage_ct}')
Consumption CT options
The consumption CT can be installed in two configurations: Solar + Load or Load only. The attribute consumption_meter_type indicates whether the CT is operating in net-consumption or total-consumption mode.
In net-consumption mode, energy_delivered reports cumulative site import (energy received from the grid), while energy_received reports cumulative site export (energy sent to the grid).[1][2] In total-consumption mode, the CT reports only the house load.
active_power is the instantaneous power; its sign reflects the direction of energy flow.
if (cttype := data.consumption_meter_type) == CtType.NET_CONSUMPTION:
grid_import = data.ctmeters[cttype].energy_delivered
grid_export = data.ctmeters[cttype].energy_received
grid_power = data.ctmeters[cttype].active_power
else:
print("No net consumption CT installed")
Production CT Options
The production CT measures solar production. energy_delivered reports the energy generated by the solar array, while energy_received reports energy consumed by the solar hardware. The latter is typically minimal (e.g., inverter consumption during dawn and dusk).[2]
Storage CT Options
The storage CT measures battery charge and discharge. energy_delivered reports energy discharged from the battery, while energy_received reports energy charged to the battery.[2]
Backfeed CT Options
The backfeed CT measures energy fed back from the Combiner to the switchboard. energy_delivered reports energy fed back, while energy_received reports received from the switchboard.[2]
Load CT Options
The load CT measures energy flow between the combiner and backup loads (installations may vary with backup and non‑backup loads). Per the CT Model, energy_delivered is energy towards the switchboard, and energy_received is energy from the switchboard.[2]
EVSE CT Options
The EVSE CT measures energy flow between the combiner and the EV charger. Per the CT Model, energy_delivered is energy towards the switchboard, and energy_received is energy from the switchboard.[2]
PV3P CT Options
The PV3P CT measures solar production by third party PV. energy_delivered reports the energy generated by the solar array, while energy_received reports energy consumed by the solar hardware. The latter is typically minimal (e.g., consumption during dawn and dusk).[2]
CT Model
Below is a generic model for installed CTs. Each CT can be considered as facing the switchboard and reporting energy delivered to the switchboard in its energy_delivered property and energy received from the switchboard in energy_received. Power is positive towards the switchboard and negative from the switchboard.
These properties have different meaning for each specific CT. For a net-consumption CT, delivered is import from the grid, for Solar production CT, it is solar production and for a battery CT it is battery discharge. A total-consumption CT typically has no delivery but only receives what is consumed by the house.
When a combiner is used, several other CT types may be available.
NOTE
This in no way represents a configuration direction, as actual configuration is driven by local rules, installer designs and Enphase installation guidelines. Variations may exist, based on specific needs or rules. This merely describes a simplified view and naming conventions used in this documentation to clarify integration operation. Refer to Enphase documentation for more information.
Some element positions, including PV3P, are assumed positions and still need confirmation.
This is an independent publication and has not been authorized, sponsored, or otherwise approved by Enphase Energy, Inc. It is loosely based on Enphase technical brief “PCS integration in 4th-generation Enphase Energy Systems”.
Dual CT attributes, single production report attribute
An Envoy metered with CTs installed, sources production and consumption data from the CT meters. The system_production data is collected from the production CT. The system_consumption data represents total house load and is either collected from the consumption CT in total-consumption mode or calculated by the Envoy from both production and consumption CTs when the consumption CT is in net-consumption mode.
A single increasing/decreasing total of import and export is reported by the /production.json?details=1 in net-consumption as whLifetime for energy and wNow for power. CT readings provide two monotonically increasing energy properties, actEnergyDlvd and actEnergyRcvd; power is reported in a single value activePower.
Multi-phase CT
For metered Envoy with multi‑phase installations, CT phase data is available in:
Legacy per‑type attributes remain for compatibility:
Phase data is only populated if CTs are installed on more than 1 phase for production and/or consumption phases.
To detect if multiple phases are reporting, use the Envoy property phase_count.
data: EnvoyData = await envoy.update()
if envoy.phase_count > 1:
for phase, phase_data in data.ctmeters_phases.get(CtType.PRODUCTION, {}).items():
for key, value in vars(phase_data).items():
print(f'{phase} {key}: {value}')
Data sources
The data is provided by the updaters below.
This data set is identified by the pyenphase.const.SupportedFeatures flag CTMETERS. In addition it returns THREEPHASE or DUALPHASE to signal if a multi-phase mode is active.
EnvoyMetersUpdater
This is the default updater for CT data. It provides data for aggregated phases and individual phases. Data is measured/calculated by the Envoy.
endpoint config |
||
endpoint data |
||
json path config |
|
|
eid of production |
|
|
eid of consumption |
|
|
|
||
eid of storage |
|
|
json path aggregated |
|
|
json path phases |
|
|
class data |
json node |
uom |
eid |
||
timestamp |
||
actEnergyDlvd |
Wh |
|
actEnergyRcvd |
Wh |
|
activePower |
W |
|
pwrFactor |
||
voltage |
V |
|
current |
A |
|
freq |
Hz |
|
state |
||
measurementType |
||
meteringStatus |
||
statusFlags |