Add power configuration to Energy dashboard (home-assistant#153809)

Co-authored-by: Copilot <[email protected]>

Author: MindFreeze

homeassistant/components/energy/data.py

@@ -5,7 +5,7 @@
 import asyncio
 from collections import Counter
 from collections.abc import Awaitable, Callable
-from typing import Literal, TypedDict
+from typing import Literal, NotRequired, TypedDict
 
 import voluptuous as vol
 
@@ -29,7 +29,7 @@ async def async_get_manager(hass: HomeAssistant) -> EnergyManager:
 class FlowFromGridSourceType(TypedDict):
     """Dictionary describing the 'from' stat for the grid source."""
 
-    # statistic_id of a an energy meter (kWh)
+    # statistic_id of an energy meter (kWh)
     stat_energy_from: str
 
     # statistic_id of costs ($) incurred from the energy meter
@@ -58,13 +58,22 @@ class FlowToGridSourceType(TypedDict):
     number_energy_price: float | None  # Price for energy ($/kWh)
 
 
+class GridPowerSourceType(TypedDict):
+    """Dictionary holding the source of grid power consumption."""
+
+    # statistic_id of a power meter (kW)
+    # negative values indicate grid return
+    stat_rate: str
+
+
 class GridSourceType(TypedDict):
     """Dictionary holding the source of grid energy consumption."""
 
     type: Literal["grid"]
 
     flow_from: list[FlowFromGridSourceType]
     flow_to: list[FlowToGridSourceType]
+    power: NotRequired[list[GridPowerSourceType]]
 
     cost_adjustment_day: float
 
@@ -75,6 +84,7 @@ class SolarSourceType(TypedDict):
     type: Literal["solar"]
 
     stat_energy_from: str
+    stat_rate: NotRequired[str]
     config_entry_solar_forecast: list[str] | None
 
 
@@ -85,6 +95,8 @@ class BatterySourceType(TypedDict):
 
     stat_energy_from: str
     stat_energy_to: str
+    # positive when discharging, negative when charging
+    stat_rate: NotRequired[str]
 
 
 class GasSourceType(TypedDict):
@@ -136,12 +148,15 @@ class DeviceConsumption(TypedDict):
     # This is an ever increasing value
     stat_consumption: str
 
+    # Instantaneous rate of flow: W, L/min or m³/h
+    stat_rate: NotRequired[str]
+
     # An optional custom name for display in energy graphs
     name: str | None
 
     # An optional statistic_id identifying a device
     # that includes this device's consumption in its total
-    included_in_stat: str | None
+    included_in_stat: NotRequired[str]
 
 
 class EnergyPreferences(TypedDict):
@@ -194,6 +209,12 @@ def _flow_from_ensure_single_price(
     }
 )
 
+GRID_POWER_SOURCE_SCHEMA = vol.Schema(
+    {
+        vol.Required("stat_rate"): str,
+    }
+)
+
 
 def _generate_unique_value_validator(key: str) -> Callable[[list[dict]], list[dict]]:
     """Generate a validator that ensures a value is only used once."""
@@ -224,13 +245,18 @@ def validate_uniqueness(
             [FLOW_TO_GRID_SOURCE_SCHEMA],
             _generate_unique_value_validator("stat_energy_to"),
         ),
+        vol.Optional("power"): vol.All(
+            [GRID_POWER_SOURCE_SCHEMA],
+            _generate_unique_value_validator("stat_rate"),
+        ),
         vol.Required("cost_adjustment_day"): vol.Coerce(float),
     }
 )
 SOLAR_SOURCE_SCHEMA = vol.Schema(
     {
         vol.Required("type"): "solar",
         vol.Required("stat_energy_from"): str,
+        vol.Optional("stat_rate"): str,
         vol.Optional("config_entry_solar_forecast"): vol.Any([str], None),
     }
 )
@@ -239,6 +265,7 @@ def validate_uniqueness(
         vol.Required("type"): "battery",
         vol.Required("stat_energy_from"): str,
         vol.Required("stat_energy_to"): str,
+        vol.Optional("stat_rate"): str,
     }
 )
 GAS_SOURCE_SCHEMA = vol.Schema(
@@ -294,6 +321,7 @@ def check_type_limits(value: list[SourceType]) -> list[SourceType]:
 DEVICE_CONSUMPTION_SCHEMA = vol.Schema(
     {
         vol.Required("stat_consumption"): str,
+        vol.Optional("stat_rate"): str,
         vol.Optional("name"): str,
         vol.Optional("included_in_stat"): str,
     }

homeassistant/components/energy/validate.py

@@ -12,6 +12,7 @@
     STATE_UNAVAILABLE,
     STATE_UNKNOWN,
     UnitOfEnergy,
+    UnitOfPower,
     UnitOfVolume,
 )
 from homeassistant.core import HomeAssistant, callback, valid_entity_id
@@ -23,12 +24,17 @@
 ENERGY_USAGE_UNITS: dict[str, tuple[UnitOfEnergy, ...]] = {
     sensor.SensorDeviceClass.ENERGY: tuple(UnitOfEnergy)
 }
+POWER_USAGE_DEVICE_CLASSES = (sensor.SensorDeviceClass.POWER,)
+POWER_USAGE_UNITS: dict[str, tuple[UnitOfPower, ...]] = {
+    sensor.SensorDeviceClass.POWER: tuple(UnitOfPower)
+}
 
 ENERGY_PRICE_UNITS = tuple(
     f"/{unit}" for units in ENERGY_USAGE_UNITS.values() for unit in units
 )
 ENERGY_UNIT_ERROR = "entity_unexpected_unit_energy"
 ENERGY_PRICE_UNIT_ERROR = "entity_unexpected_unit_energy_price"
+POWER_UNIT_ERROR = "entity_unexpected_unit_power"
 GAS_USAGE_DEVICE_CLASSES = (
     sensor.SensorDeviceClass.ENERGY,
     sensor.SensorDeviceClass.GAS,
@@ -82,6 +88,10 @@ def _get_placeholders(hass: HomeAssistant, issue_type: str) -> dict[str, str] |
                 f"{currency}{unit}" for unit in ENERGY_PRICE_UNITS
             ),
         }
+    if issue_type == POWER_UNIT_ERROR:
+        return {
+            "power_units": ", ".join(POWER_USAGE_UNITS[sensor.SensorDeviceClass.POWER]),
+        }
     if issue_type == GAS_UNIT_ERROR:
         return {
             "energy_units": ", ".join(GAS_USAGE_UNITS[sensor.SensorDeviceClass.ENERGY]),
@@ -159,45 +169,49 @@ def as_dict(self) -> dict:
 
 
 @callback
-def _async_validate_usage_stat(
+def _async_validate_stat_common(
     hass: HomeAssistant,
     metadata: dict[str, tuple[int, recorder.models.StatisticMetaData]],
     stat_id: str,
     allowed_device_classes: Sequence[str],
     allowed_units: Mapping[str, Sequence[str]],
     unit_error: str,
     issues: ValidationIssues,
-) -> None:
-    """Validate a statistic."""
+    check_negative: bool = False,
+) -> str | None:
+    """Validate common aspects of a statistic.
+
+    Returns the entity_id if validation succeeds, None otherwise.
+    """
     if stat_id not in metadata:
         issues.add_issue(hass, "statistics_not_defined", stat_id)
 
     has_entity_source = valid_entity_id(stat_id)
 
     if not has_entity_source:
-        return
+        return None
 
     entity_id = stat_id
 
     if not recorder.is_entity_recorded(hass, entity_id):
         issues.add_issue(hass, "recorder_untracked", entity_id)
-        return
+        return None
 
     if (state := hass.states.get(entity_id)) is None:
         issues.add_issue(hass, "entity_not_defined", entity_id)
-        return
+        return None
 
     if state.state in (STATE_UNAVAILABLE, STATE_UNKNOWN):
         issues.add_issue(hass, "entity_unavailable", entity_id, state.state)
-        return
+        return None
 
     try:
         current_value: float | None = float(state.state)
     except ValueError:
         issues.add_issue(hass, "entity_state_non_numeric", entity_id, state.state)
-        return
+        return None
 
-    if current_value is not None and current_value < 0:
+    if check_negative and current_value is not None and current_value < 0:
         issues.add_issue(hass, "entity_negative_state", entity_id, current_value)
 
     device_class = state.attributes.get(ATTR_DEVICE_CLASS)
@@ -211,6 +225,36 @@ def _async_validate_usage_stat(
         if device_class and unit not in allowed_units.get(device_class, []):
             issues.add_issue(hass, unit_error, entity_id, unit)
 
+    return entity_id
+
+
+@callback
+def _async_validate_usage_stat(
+    hass: HomeAssistant,
+    metadata: dict[str, tuple[int, recorder.models.StatisticMetaData]],
+    stat_id: str,
+    allowed_device_classes: Sequence[str],
+    allowed_units: Mapping[str, Sequence[str]],
+    unit_error: str,
+    issues: ValidationIssues,
+) -> None:
+    """Validate a statistic."""
+    entity_id = _async_validate_stat_common(
+        hass,
+        metadata,
+        stat_id,
+        allowed_device_classes,
+        allowed_units,
+        unit_error,
+        issues,
+        check_negative=True,
+    )
+
+    if entity_id is None:
+        return
+
+    state = hass.states.get(entity_id)
+    assert state is not None
     state_class = state.attributes.get(sensor.ATTR_STATE_CLASS)
 
     allowed_state_classes = [
@@ -255,6 +299,39 @@ def _async_validate_price_entity(
         issues.add_issue(hass, unit_error, entity_id, unit)
 
 
+@callback
+def _async_validate_power_stat(
+    hass: HomeAssistant,
+    metadata: dict[str, tuple[int, recorder.models.StatisticMetaData]],
+    stat_id: str,
+    allowed_device_classes: Sequence[str],
+    allowed_units: Mapping[str, Sequence[str]],
+    unit_error: str,
+    issues: ValidationIssues,
+) -> None:
+    """Validate a power statistic."""
+    entity_id = _async_validate_stat_common(
+        hass,
+        metadata,
+        stat_id,
+        allowed_device_classes,
+        allowed_units,
+        unit_error,
+        issues,
+        check_negative=False,
+    )
+
+    if entity_id is None:
+        return
+
+    state = hass.states.get(entity_id)
+    assert state is not None
+    state_class = state.attributes.get(sensor.ATTR_STATE_CLASS)
+
+    if state_class != sensor.SensorStateClass.MEASUREMENT:
+        issues.add_issue(hass, "entity_unexpected_state_class", entity_id, state_class)
+
+
 @callback
 def _async_validate_cost_stat(
     hass: HomeAssistant,
@@ -434,6 +511,21 @@ async def async_validate(hass: HomeAssistant) -> EnergyPreferencesValidation:
                         )
                     )
 
+            for power_stat in source.get("power", []):
+                wanted_statistics_metadata.add(power_stat["stat_rate"])
+                validate_calls.append(
+                    functools.partial(
+                        _async_validate_power_stat,
+                        hass,
+                        statistics_metadata,
+                        power_stat["stat_rate"],
+                        POWER_USAGE_DEVICE_CLASSES,
+                        POWER_USAGE_UNITS,
+                        POWER_UNIT_ERROR,
+                        source_result,
+                    )
+                )
+
         elif source["type"] == "gas":
             wanted_statistics_metadata.add(source["stat_energy_from"])
             validate_calls.append(

tests/components/energy/conftest.py

@@ -0,0 +1,56 @@
+"""Fixtures for energy component tests."""
+
+from unittest.mock import patch
+
+import pytest
+
+from homeassistant.components.energy import async_get_manager
+from homeassistant.components.energy.data import EnergyManager
+from homeassistant.components.recorder import Recorder
+from homeassistant.core import HomeAssistant
+from homeassistant.setup import async_setup_component
+
+
+@pytest.fixture
+def mock_is_entity_recorded():
+    """Mock recorder.is_entity_recorded."""
+    mocks = {}
+
+    with patch(
+        "homeassistant.components.recorder.is_entity_recorded",
+        side_effect=lambda hass, entity_id: mocks.get(entity_id, True),
+    ):
+        yield mocks
+
+
+@pytest.fixture
+def mock_get_metadata():
+    """Mock recorder.statistics.get_metadata."""
+    mocks = {}
+
+    def _get_metadata(_hass, *, statistic_ids):
+        result = {}
+        for statistic_id in statistic_ids:
+            if statistic_id in mocks:
+                if mocks[statistic_id] is not None:
+                    result[statistic_id] = mocks[statistic_id]
+            else:
+                result[statistic_id] = (1, {})
+        return result
+
+    with patch(
+        "homeassistant.components.recorder.statistics.get_metadata",
+        wraps=_get_metadata,
+    ):
+        yield mocks
+
+
+@pytest.fixture
+async def mock_energy_manager(
+    recorder_mock: Recorder, hass: HomeAssistant
+) -> EnergyManager:
+    """Set up energy."""
+    assert await async_setup_component(hass, "energy", {"energy": {}})
+    manager = await async_get_manager(hass)
+    manager.data = manager.default_preferences()
+    return manager