Add sensor device class for apparent energy

[balloob]

Context

Home Assistant has device classes for three of the four quantities an electricity meter reports:

Quantity	Device class	Units	Added by
Real power	power	W, kW, …	—
Apparent power	apparent_power	mVA, VA, kVA	#688
Reactive power	reactive_power	mvar, var, kvar	#688, #729
Real energy	energy	Wh, kWh, …	—
Reactive energy	reactive_energy	varh, kvarh	#724
Apparent energy	missing	VAh, kVAh	—

Reactive energy was accepted in #724 in the architecture meeting of 2025-05-08 and merged on 2025-05-16. Apparent energy was not part of that proposal, and it is the only cell of the table still empty. @Breina noted the gap in #724 on 2026-01-01, but it was never raised on its own.

AI slop hidden, expand to view

## Why this matters

Millions of people are billed on it. Many Indian state utilities bill energy in kVAh rather than kWh for commercial and industrial consumers, including Delhi, Uttar Pradesh, Punjab, Haryana, Andhra Pradesh, Bihar and Himachal Pradesh. For those users the meter's kVAh register is the bill. Home Assistant can show them a kWh counter that does not match what they pay for, while the counter that does match cannot be exposed.

It is the only way to see a power-factor penalty coming. Utilities compute average power factor over the billing period as kWh ÷ kVAh. The instantaneous power factor Home Assistant already shows does not answer that: a meter can read 0.98 whenever you look and still average 0.85 across the month. Two counters give the same figure the utility uses, before the penalty lands.

It cannot be computed from what we have. ∫√(P²+Q²)dt ≥ √((∫P dt)² + (∫Q dt)²), with equality only if the power factor never changes, so real energy and reactive energy do not yield it. Neither does kWh with power factor, for the same reason. Integrating apparent power in a helper is an approximation whose error depends on the polling interval, and it misses distortion: with non-linear loads S² = P² + Q² + D². The meter already counted this exactly, over exactly the period the utility bills. Either we carry the register or the number is lost.

It is not useful for capacity planning. Transformers and inverters are rated in VA, but that is a question about peak apparent power, which already has a device class.

Proposal

Add SensorDeviceClass.APPARENT_ENERGY, mirroring reactive_energy:

• UnitOfApparentEnergy with VAh and kVAh. Both are needed: Z-Wave reports kVAh, Iskra meters report VAh, KNX has a datapoint type for each.
• ApparentEnergyConverter in homeassistant/util/unit_conversion.py.
• State classes TOTAL and TOTAL_INCREASING.

Apparent energy is not billable consumption everywhere, and the energy dashboard assumes kWh, so it stays out of the dashboard, the same as reactive energy.

One open question: Matter reports apparent energy in mVAh, so an mVAh member would let Matter use the device class natively, as mVA already does for apparent power. UnitOfReactiveEnergy has no mvarh, which is why Matter's reactive energy cannot be expressed natively either. Adding mVAh now avoids repeating that.

Who needs it

Five integrations in core have a source of apparent energy they cannot express: iskra, knx, matter, solaredge_modbus, zwave_js

Details about integration use and the investigation

Each was verified against the upstream library or protocol definition, not inferred:

• zwave_js — The Z-Wave Electric meter command class defines scale 1 as kVAh, named ElectricScale.KILOVOLT_AMPERE_HOUR upstream. In discovery_data_template.py it sits in a carve-out beside PULSE_COUNT, commented "even though these are energy scales, they don't meet the unit requirements for the energy device class". METER_UNIT_MAP has no entry for it, so the sensor gets no unit and no device class: a bare number in the UI.
• iskra — pyiskra maps a counter whose device-reported unit is VAh to CounterType.APPARENT_IMPORT or APPARENT_EXPORT. get_counter_entity_description assigns a device class only to the active counters, commented "HA's Energy device class supports only active energy". Apparent counters reach the state machine with the raw string VAh and no device class.
• solaredge_modbus — SunSpec meter models 201–204 hold apparent energy beside the reactive registers. solaredged models both totals (registers 40243 and 40251, unit VAh); the spec also defines per-phase points. Meter support landed in Add meter support to SolarEdge Modbus core#180572, and these are the registers it reads but cannot expose.
• knx — xknx defines DPTApparantEnergy (13.011, VAh) and DPTApparantEnergykVAh (13.014, kVAh). Neither is in the DPT map in knx/dpt.py, because there is nothing to map them to. Their reactive counterparts 13.012 and 13.015 were added when reactive_energy landed.
• matter — The ElectricalEnergyMeasurement cluster has an apparent energy feature bit (APEG, 0x10) and an optional apparentEnergy field in EnergyMeasurementStruct, in mVAh. Home Assistant reads only .energy.

mqtt and template sensors would take the device class as they take any other.

What was checked and does not need it

Every integration in core setting apparent_power or a reactive device class was checked against its library or protocol. Measuring VA does not imply counting VAh, and most of these do not:

• Apparent power only: apcupsd, nut, blebox, enphase_envoy, fronius, goodwe, homewizard, mysensors, nrgkick, sma, sofar, solarman, teleinfo, victron_ble, victron_gx, isy994.
• Reactive energy but not apparent: tasmota, shelly.
• Device-configured units that exclude VAh: iotawatt (the query API accepts Volts, Hz, Watts, Amps, Wh, VA, VAR, VARh, PF), emoncms.

Consequences

The change is small and symmetric with one already in core, so recorder statistics, unit conversion and the frontend need nothing new. Two of the five integrations above already ship the workaround in tree: a sensor with a hand-written unit string or none at all, and no device class, neither convertible nor stateable.

[Breina]

Thanks for raising the issue! My integration also needs this: https://github.com/Breina/PowerTagGateway

[balloob]

Oh, another modbus integration! Have you seen our recent work on standardizing Modbus in Home Assistant? https://developers.home-assistant.io/blog/2026/07/05/modernizing-modbus

[balloob]

With modbus-connection, the models could look like this https://github.com/balloobbot/PowerTagGateway/blob/modbus-connection-migration/custom_components/powertag_gateway/schneider_model.py#L107

[emontnemery]

Approved by the core architecture meeting 2026-09-03