Flow rate unit conversions and device class

homeassistant/components/number/const.py

@@ -34,6 +34,7 @@
     UnitOfTemperature,
     UnitOfTime,
     UnitOfVolume,
+    UnitOfVolumeFlowRate,
     UnitOfVolumetricFlux,
 )
 from homeassistant.helpers.deprecation import (
@@ -42,7 +43,11 @@
     check_if_deprecated_constant,
     dir_with_deprecated_constants,
 )
-from homeassistant.util.unit_conversion import BaseUnitConverter, TemperatureConverter
+from homeassistant.util.unit_conversion import (
+    BaseUnitConverter,
+    TemperatureConverter,
+    VolumeFlowRateConverter,
+)
 
 ATTR_VALUE = "value"
 ATTR_MIN = "min"
@@ -372,6 +377,14 @@ class NumberDeviceClass(StrEnum):
     USCS/imperial units are currently assumed to be US volumes)
     """
 
+    VOLUME_FLOW_RATE = "volume_flow_rate"
+    """Generic flow rate
+
+    Unit of measurement: UnitOfVolumeFlowRate
+    - SI / metric: `m³/h`, `L/min`
+    - USCS / imperial: `ft³/min`, `gal/min`
+    """
+
     WATER = "water"
     """Water.
 
@@ -464,6 +477,7 @@ class NumberDeviceClass(StrEnum):
     NumberDeviceClass.VOLTAGE: set(UnitOfElectricPotential),
     NumberDeviceClass.VOLUME: set(UnitOfVolume),
     NumberDeviceClass.VOLUME_STORAGE: set(UnitOfVolume),
+    NumberDeviceClass.VOLUME_FLOW_RATE: set(UnitOfVolumeFlowRate),
     NumberDeviceClass.WATER: {
         UnitOfVolume.CENTUM_CUBIC_FEET,
         UnitOfVolume.CUBIC_FEET,
@@ -477,6 +491,7 @@ class NumberDeviceClass(StrEnum):
 
 UNIT_CONVERTERS: dict[str, type[BaseUnitConverter]] = {
     NumberDeviceClass.TEMPERATURE: TemperatureConverter,
+    NumberDeviceClass.VOLUME_FLOW_RATE: VolumeFlowRateConverter,
 }
 
 # These can be removed if no deprecated constant are in this module anymore

homeassistant/components/number/strings.json

@@ -148,6 +148,9 @@
     "volume_storage": {
       "name": "[%key:component::sensor::entity_component::volume_storage::name%]"
     },
+    "volume_flow_rate": {
+      "name": "[%key:component::sensor::entity_component::volume_flow_rate::name%]"
+    },
     "water": {
       "name": "[%key:component::sensor::entity_component::water::name%]"
     },

homeassistant/components/recorder/statistics.py

@@ -41,6 +41,7 @@
     TemperatureConverter,
     UnitlessRatioConverter,
     VolumeConverter,
+    VolumeFlowRateConverter,
 )
 
 from .const import (
@@ -139,6 +140,7 @@
     **{unit: TemperatureConverter for unit in TemperatureConverter.VALID_UNITS},
     **{unit: UnitlessRatioConverter for unit in UnitlessRatioConverter.VALID_UNITS},
     **{unit: VolumeConverter for unit in VolumeConverter.VALID_UNITS},
+    **{unit: VolumeFlowRateConverter for unit in VolumeFlowRateConverter.VALID_UNITS},
 }
 
 DATA_SHORT_TERM_STATISTICS_RUN_CACHE = "recorder_short_term_statistics_run_cache"

homeassistant/components/recorder/websocket_api.py

@@ -28,6 +28,7 @@
     TemperatureConverter,
     UnitlessRatioConverter,
     VolumeConverter,
+    VolumeFlowRateConverter,
 )
 
 from .models import StatisticPeriod
@@ -67,6 +68,7 @@
         vol.Optional("temperature"): vol.In(TemperatureConverter.VALID_UNITS),
         vol.Optional("unitless"): vol.In(UnitlessRatioConverter.VALID_UNITS),
         vol.Optional("volume"): vol.In(VolumeConverter.VALID_UNITS),
+        vol.Optional("volume_flow_rate"): vol.In(VolumeFlowRateConverter.VALID_UNITS),
     }
 )
 

homeassistant/components/sensor/const.py

@@ -34,6 +34,7 @@
     UnitOfTemperature,
     UnitOfTime,
     UnitOfVolume,
+    UnitOfVolumeFlowRate,
     UnitOfVolumetricFlux,
 )
 from homeassistant.helpers.deprecation import (
@@ -57,6 +58,7 @@
     TemperatureConverter,
     UnitlessRatioConverter,
     VolumeConverter,
+    VolumeFlowRateConverter,
 )
 
 DOMAIN: Final = "sensor"
@@ -394,6 +396,14 @@ class SensorDeviceClass(StrEnum):
     USCS/imperial units are currently assumed to be US volumes)
     """
 
+    VOLUME_FLOW_RATE = "volume_flow_rate"
+    """Generic flow rate
+
+    Unit of measurement: UnitOfVolumeFlowRate
+    - SI / metric: `m³/h`, `L/min`
+    - USCS / imperial: `ft³/min`, `gal/min`
+    """
+
     WATER = "water"
     """Water.
 
@@ -489,6 +499,7 @@ class SensorStateClass(StrEnum):
     SensorDeviceClass.VOLTAGE: ElectricPotentialConverter,
     SensorDeviceClass.VOLUME: VolumeConverter,
     SensorDeviceClass.VOLUME_STORAGE: VolumeConverter,
+    SensorDeviceClass.VOLUME_FLOW_RATE: VolumeFlowRateConverter,
     SensorDeviceClass.WATER: VolumeConverter,
     SensorDeviceClass.WEIGHT: MassConverter,
     SensorDeviceClass.WIND_SPEED: SpeedConverter,
@@ -555,6 +566,7 @@ class SensorStateClass(StrEnum):
     },
     SensorDeviceClass.VOLTAGE: set(UnitOfElectricPotential),
     SensorDeviceClass.VOLUME: set(UnitOfVolume),
+    SensorDeviceClass.VOLUME_FLOW_RATE: set(UnitOfVolumeFlowRate),
     SensorDeviceClass.VOLUME_STORAGE: set(UnitOfVolume),
     SensorDeviceClass.WATER: {
         UnitOfVolume.CENTUM_CUBIC_FEET,
@@ -621,6 +633,7 @@ class SensorStateClass(StrEnum):
         SensorStateClass.TOTAL_INCREASING,
     },
     SensorDeviceClass.VOLUME_STORAGE: {SensorStateClass.MEASUREMENT},
+    SensorDeviceClass.VOLUME_FLOW_RATE: {SensorStateClass.MEASUREMENT},
     SensorDeviceClass.WATER: {
         SensorStateClass.TOTAL,
         SensorStateClass.TOTAL_INCREASING,

homeassistant/components/sensor/device_condition.py

@@ -77,6 +77,7 @@
 CONF_IS_VOLATILE_ORGANIC_COMPOUNDS_PARTS = "is_volatile_organic_compounds_parts"
 CONF_IS_VOLTAGE = "is_voltage"
 CONF_IS_VOLUME = "is_volume"
+CONF_IS_VOLUME_FLOW_RATE = "is_volume_flow_rate"
 CONF_IS_WATER = "is_water"
 CONF_IS_WEIGHT = "is_weight"
 CONF_IS_WIND_SPEED = "is_wind_speed"
@@ -132,6 +133,7 @@
     SensorDeviceClass.VOLTAGE: [{CONF_TYPE: CONF_IS_VOLTAGE}],
     SensorDeviceClass.VOLUME: [{CONF_TYPE: CONF_IS_VOLUME}],
     SensorDeviceClass.VOLUME_STORAGE: [{CONF_TYPE: CONF_IS_VOLUME}],
+    SensorDeviceClass.VOLUME_FLOW_RATE: [{CONF_TYPE: CONF_IS_VOLUME_FLOW_RATE}],
     SensorDeviceClass.WATER: [{CONF_TYPE: CONF_IS_WATER}],
     SensorDeviceClass.WEIGHT: [{CONF_TYPE: CONF_IS_WEIGHT}],
     SensorDeviceClass.WIND_SPEED: [{CONF_TYPE: CONF_IS_WIND_SPEED}],
@@ -186,6 +188,7 @@
                     CONF_IS_VOLATILE_ORGANIC_COMPOUNDS_PARTS,
                     CONF_IS_VOLTAGE,
                     CONF_IS_VOLUME,
+                    CONF_IS_VOLUME_FLOW_RATE,
                     CONF_IS_WATER,
                     CONF_IS_WEIGHT,
                     CONF_IS_WIND_SPEED,

homeassistant/components/sensor/device_trigger.py

@@ -76,6 +76,7 @@
 CONF_VOLATILE_ORGANIC_COMPOUNDS_PARTS = "volatile_organic_compounds_parts"
 CONF_VOLTAGE = "voltage"
 CONF_VOLUME = "volume"
+CONF_VOLUME_FLOW_RATE = "volume_flow_rate"
 CONF_WATER = "water"
 CONF_WEIGHT = "weight"
 CONF_WIND_SPEED = "wind_speed"
@@ -131,6 +132,7 @@
     SensorDeviceClass.VOLTAGE: [{CONF_TYPE: CONF_VOLTAGE}],
     SensorDeviceClass.VOLUME: [{CONF_TYPE: CONF_VOLUME}],
     SensorDeviceClass.VOLUME_STORAGE: [{CONF_TYPE: CONF_VOLUME}],
+    SensorDeviceClass.VOLUME_FLOW_RATE: [{CONF_TYPE: CONF_VOLUME_FLOW_RATE}],
     SensorDeviceClass.WATER: [{CONF_TYPE: CONF_WATER}],
     SensorDeviceClass.WEIGHT: [{CONF_TYPE: CONF_WEIGHT}],
     SensorDeviceClass.WIND_SPEED: [{CONF_TYPE: CONF_WIND_SPEED}],
@@ -186,6 +188,7 @@
                     CONF_VOLATILE_ORGANIC_COMPOUNDS_PARTS,
                     CONF_VOLTAGE,
                     CONF_VOLUME,
+                    CONF_VOLUME_FLOW_RATE,
                     CONF_WATER,
                     CONF_WEIGHT,
                     CONF_WIND_SPEED,

homeassistant/components/sensor/strings.json

@@ -45,6 +45,7 @@
       "is_volatile_organic_compounds_parts": "[%key:component::sensor::device_automation::condition_type::is_volatile_organic_compounds%]",
       "is_voltage": "Current {entity_name} voltage",
       "is_volume": "Current {entity_name} volume",
+      "is_volume_flow_rate": "Current {entity_name} volume flow rate",
       "is_water": "Current {entity_name} water",
       "is_weight": "Current {entity_name} weight",
       "is_wind_speed": "Current {entity_name} wind speed"
@@ -93,6 +94,7 @@
       "volatile_organic_compounds_parts": "[%key:component::sensor::device_automation::trigger_type::volatile_organic_compounds%]",
       "voltage": "{entity_name} voltage changes",
       "volume": "{entity_name} volume changes",
+      "volume_flow_rate": "{entity_name} volume flow rate changes",
       "water": "{entity_name} water changes",
       "weight": "{entity_name} weight changes",
       "wind_speed": "{entity_name} wind speed changes"
@@ -260,6 +262,9 @@
     "volume": {
       "name": "Volume"
     },
+    "volume_flow_rate": {
+      "name": "Volume flow rate"
+    },
     "volume_storage": {
       "name": "Stored volume"
     },

homeassistant/const.py

@@ -1040,7 +1040,9 @@ class UnitOfVolumeFlowRate(StrEnum):
     """Volume flow rate units."""
 
     CUBIC_METERS_PER_HOUR = "m³/h"
-    CUBIC_FEET_PER_MINUTE = "ft³/m"
+    CUBIC_FEET_PER_MINUTE = "ft³/min"
+    LITERS_PER_MINUTE = "L/min"
+    GALLONS_PER_MINUTE = "gal/min"
 
 
 _DEPRECATED_VOLUME_FLOW_RATE_CUBIC_METERS_PER_HOUR: Final = DeprecatedConstantEnum(
@@ -1053,7 +1055,16 @@ class UnitOfVolumeFlowRate(StrEnum):
     "2025.1",
 )
 """Deprecated: please use UnitOfVolumeFlowRate.CUBIC_FEET_PER_MINUTE"""
-
+_DEPRECATED_VOLUME_FLOW_RATE_LITERS_PER_MINUTE: Final = DeprecatedConstantEnum(
+    UnitOfVolumeFlowRate.LITERS_PER_MINUTE,
+    "2025.1",
+)
+"""Deprecated: please use UnitOfVolumeFlowRate.LITERS_PER_MINUTE"""
+_DEPRECATED_VOLUME_FLOW_RATE_GALLONS_PER_MINUTE: Final = DeprecatedConstantEnum(
+    UnitOfVolumeFlowRate.GALLONS_PER_MINUTE,
+    "2025.1",
+)
+"""Deprecated: please use UnitOfVolumeFlowRate.GALLONS_PER_MINUTE"""
 # Area units
 AREA_SQUARE_METERS: Final = "m²"
 

homeassistant/util/unit_conversion.py

@@ -21,6 +21,7 @@
     UnitOfSpeed,
     UnitOfTemperature,
     UnitOfVolume,
+    UnitOfVolumeFlowRate,
     UnitOfVolumetricFlux,
 )
 from homeassistant.exceptions import HomeAssistantError
@@ -39,6 +40,7 @@
 
 # Duration conversion constants
 _HRS_TO_SECS = 60 * 60  # 1 hr = 3600 seconds
+_HRS_TO_MINUTES = 60  # 1 hr = 60 minutes
 _DAYS_TO_SECS = 24 * _HRS_TO_SECS  # 1 day = 24 hours = 86400 seconds
 
 # Mass conversion constants
@@ -516,3 +518,26 @@ class VolumeConverter(BaseUnitConverter):
         UnitOfVolume.CUBIC_FEET,
         UnitOfVolume.CENTUM_CUBIC_FEET,
     }
+
+
+class VolumeFlowRateConverter(BaseUnitConverter):
+    """Utility to convert volume values."""
+
+    UNIT_CLASS = "volume_flow_rate"
+    NORMALIZED_UNIT = UnitOfVolumeFlowRate.CUBIC_METERS_PER_HOUR
+    # Units in terms of m³/h
+    _UNIT_CONVERSION: dict[str | None, float] = {
+        UnitOfVolumeFlowRate.CUBIC_METERS_PER_HOUR: 1,
+        UnitOfVolumeFlowRate.CUBIC_FEET_PER_MINUTE: 1
+        / (_HRS_TO_MINUTES * _CUBIC_FOOT_TO_CUBIC_METER),
+        UnitOfVolumeFlowRate.LITERS_PER_MINUTE: 1
+        / (_HRS_TO_MINUTES * _L_TO_CUBIC_METER),
+        UnitOfVolumeFlowRate.GALLONS_PER_MINUTE: 1
+        / (_HRS_TO_MINUTES * _GALLON_TO_CUBIC_METER),
+    }
+    VALID_UNITS = {
+        UnitOfVolumeFlowRate.CUBIC_FEET_PER_MINUTE,
+        UnitOfVolumeFlowRate.CUBIC_METERS_PER_HOUR,
+        UnitOfVolumeFlowRate.LITERS_PER_MINUTE,
+        UnitOfVolumeFlowRate.GALLONS_PER_MINUTE,
+    }

tests/components/number/test_init.py

@@ -32,6 +32,7 @@
     ATTR_UNIT_OF_MEASUREMENT,
     CONF_PLATFORM,
     UnitOfTemperature,
+    UnitOfVolumeFlowRate,
 )
 from homeassistant.core import HomeAssistant, State
 from homeassistant.helpers import entity_registry as er
@@ -686,6 +687,22 @@ async def test_restore_number_restore_state(
             100,
             38.0,
         ),
+        (
+            SensorDeviceClass.VOLUME_FLOW_RATE,
+            UnitOfVolumeFlowRate.LITERS_PER_MINUTE,
+            UnitOfVolumeFlowRate.GALLONS_PER_MINUTE,
+            UnitOfVolumeFlowRate.GALLONS_PER_MINUTE,
+            50.0,
+            "13.2",
+        ),
+        (
+            SensorDeviceClass.VOLUME_FLOW_RATE,
+            UnitOfVolumeFlowRate.GALLONS_PER_MINUTE,
+            UnitOfVolumeFlowRate.LITERS_PER_MINUTE,
+            UnitOfVolumeFlowRate.LITERS_PER_MINUTE,
+            13.0,
+            "49.2",
+        ),
     ],
 )
 async def test_custom_unit(

tests/components/sensor/test_init.py

@@ -36,6 +36,7 @@
     UnitOfSpeed,
     UnitOfTemperature,
     UnitOfVolume,
+    UnitOfVolumeFlowRate,
     UnitOfVolumetricFlux,
 )
 from homeassistant.core import HomeAssistant, State
@@ -581,6 +582,22 @@ async def test_restore_sensor_restore_state(
             -0.00001,
             "0",
         ),
+        (
+            SensorDeviceClass.VOLUME_FLOW_RATE,
+            UnitOfVolumeFlowRate.LITERS_PER_MINUTE,
+            UnitOfVolumeFlowRate.GALLONS_PER_MINUTE,
+            UnitOfVolumeFlowRate.GALLONS_PER_MINUTE,
+            50.0,
+            "13.2",
+        ),
+        (
+            SensorDeviceClass.VOLUME_FLOW_RATE,
+            UnitOfVolumeFlowRate.GALLONS_PER_MINUTE,
+            UnitOfVolumeFlowRate.LITERS_PER_MINUTE,
+            UnitOfVolumeFlowRate.LITERS_PER_MINUTE,
+            13.0,
+            "49.2",
+        ),
     ],
 )
 async def test_custom_unit(