Add unit of electric charge as unit of measurement option

Author: Sven ten Raa

homeassistant/components/apcupsd/sensor.py

@@ -13,6 +13,7 @@
 from homeassistant.const import (
     PERCENTAGE,
     UnitOfApparentPower,
+    UnitOfElectricCharge,
     UnitOfElectricCurrent,
     UnitOfElectricPotential,
     UnitOfFrequency,
@@ -434,6 +435,8 @@
     " Volt-Ampere": UnitOfApparentPower.VOLT_AMPERE,
     " VA": UnitOfApparentPower.VOLT_AMPERE,
     " Watts": UnitOfPower.WATT,
+    " Ampere hour": UnitOfElectricCharge.AMPERE_HOUR,
+    " milliampere hour": UnitOfElectricCharge.MILLIAMPERE_HOUR,
     " Hz": UnitOfFrequency.HERTZ,
     " C": UnitOfTemperature.CELSIUS,
     # APCUPSd reports data for "itemp" field (eventually represented by UPS Internal

homeassistant/components/number/const.py

@@ -17,6 +17,7 @@
     SIGNAL_STRENGTH_DECIBELS_MILLIWATT,
     UnitOfApparentPower,
     UnitOfDataRate,
+    UnitOfElectricCharge,
     UnitOfElectricCurrent,
     UnitOfElectricPotential,
     UnitOfEnergy,
@@ -239,6 +240,12 @@ class NumberDeviceClass(StrEnum):
     Unit of measurement: `W`, `kW`
     """
 
+    CHARGE = "charge"
+    """Charge.
+
+    Unit of measurement: `mAh`, `Ah`
+    """
+
     PRECIPITATION = "precipitation"
     """Accumulated precipitation.
 
@@ -413,6 +420,10 @@ class NumberMode(StrEnum):
     NumberDeviceClass.PM25: {CONCENTRATION_MICROGRAMS_PER_CUBIC_METER},
     NumberDeviceClass.POWER_FACTOR: {PERCENTAGE, None},
     NumberDeviceClass.POWER: {UnitOfPower.WATT, UnitOfPower.KILO_WATT},
+    NumberDeviceClass.CHARGE: {
+        UnitOfElectricCharge.MILLIAMPERE_HOUR,
+        UnitOfElectricCharge.AMPERE_HOUR,
+    },
     NumberDeviceClass.PRECIPITATION: set(UnitOfPrecipitationDepth),
     NumberDeviceClass.PRECIPITATION_INTENSITY: set(UnitOfVolumetricFlux),
     NumberDeviceClass.PRESSURE: set(UnitOfPressure),

homeassistant/components/recorder/statistics.py

@@ -28,6 +28,7 @@
 from homeassistant.util import dt as dt_util
 from homeassistant.util.unit_conversion import (
     BaseUnitConverter,
+    ChargeConverter,
     DataRateConverter,
     DistanceConverter,
     ElectricCurrentConverter,
@@ -138,6 +139,7 @@
     **{unit: InformationConverter for unit in InformationConverter.VALID_UNITS},
     **{unit: MassConverter for unit in MassConverter.VALID_UNITS},
     **{unit: PowerConverter for unit in PowerConverter.VALID_UNITS},
+    **{unit: ChargeConverter for unit in ChargeConverter.VALID_UNITS},
     **{unit: PressureConverter for unit in PressureConverter.VALID_UNITS},
     **{unit: SpeedConverter for unit in SpeedConverter.VALID_UNITS},
     **{unit: TemperatureConverter for unit in TemperatureConverter.VALID_UNITS},

homeassistant/components/recorder/websocket_api.py

@@ -15,6 +15,7 @@
 from homeassistant.helpers.json import JSON_DUMP
 from homeassistant.util import dt as dt_util
 from homeassistant.util.unit_conversion import (
+    ChargeConverter,
     DataRateConverter,
     DistanceConverter,
     ElectricCurrentConverter,
@@ -62,6 +63,7 @@
         vol.Optional("information"): vol.In(InformationConverter.VALID_UNITS),
         vol.Optional("mass"): vol.In(MassConverter.VALID_UNITS),
         vol.Optional("power"): vol.In(PowerConverter.VALID_UNITS),
+        vol.Optional("charge"): vol.In(ChargeConverter.VALID_UNITS),
         vol.Optional("pressure"): vol.In(PressureConverter.VALID_UNITS),
         vol.Optional("speed"): vol.In(SpeedConverter.VALID_UNITS),
         vol.Optional("temperature"): vol.In(TemperatureConverter.VALID_UNITS),

homeassistant/components/sensor/const.py

@@ -17,6 +17,7 @@
     SIGNAL_STRENGTH_DECIBELS_MILLIWATT,
     UnitOfApparentPower,
     UnitOfDataRate,
+    UnitOfElectricCharge,
     UnitOfElectricCurrent,
     UnitOfElectricPotential,
     UnitOfEnergy,
@@ -37,6 +38,7 @@
 )
 from homeassistant.util.unit_conversion import (
     BaseUnitConverter,
+    ChargeConverter,
     DataRateConverter,
     DistanceConverter,
     ElectricCurrentConverter,
@@ -277,6 +279,12 @@ class SensorDeviceClass(StrEnum):
     Unit of measurement: `W`, `kW`
     """
 
+    CHARGE = "charge"
+    """Charge.
+
+    Unit of measurement: `mAh`, `Ah`
+    """
+
     PRECIPITATION = "precipitation"
     """Accumulated precipitation.
 
@@ -460,6 +468,7 @@ class SensorStateClass(StrEnum):
     SensorDeviceClass.ENERGY_STORAGE: EnergyConverter,
     SensorDeviceClass.GAS: VolumeConverter,
     SensorDeviceClass.POWER: PowerConverter,
+    SensorDeviceClass.CHARGE: ChargeConverter,
     SensorDeviceClass.POWER_FACTOR: UnitlessRatioConverter,
     SensorDeviceClass.PRECIPITATION: DistanceConverter,
     SensorDeviceClass.PRECIPITATION_INTENSITY: SpeedConverter,
@@ -514,6 +523,10 @@ class SensorStateClass(StrEnum):
     SensorDeviceClass.PM25: {CONCENTRATION_MICROGRAMS_PER_CUBIC_METER},
     SensorDeviceClass.POWER_FACTOR: {PERCENTAGE, None},
     SensorDeviceClass.POWER: {UnitOfPower.WATT, UnitOfPower.KILO_WATT},
+    SensorDeviceClass.CHARGE: {
+        UnitOfElectricCharge.MILLIAMPERE_HOUR,
+        UnitOfElectricCharge.AMPERE_HOUR,
+    },
     SensorDeviceClass.PRECIPITATION: set(UnitOfPrecipitationDepth),
     SensorDeviceClass.PRECIPITATION_INTENSITY: set(UnitOfVolumetricFlux),
     SensorDeviceClass.PRESSURE: set(UnitOfPressure),

homeassistant/const.py

@@ -494,6 +494,13 @@ class UnitOfApparentPower(StrEnum):
 """Deprecated: please use UnitOfApparentPower.VOLT_AMPERE."""
 
 
+class UnitOfElectricCharge(StrEnum):
+    """Charge units."""
+
+    AMPERE_HOUR = "Ah"
+    MILLIAMPERE_HOUR = "mAh"
+
+
 # Power units
 class UnitOfPower(StrEnum):
     """Power units."""

homeassistant/util/unit_conversion.py

@@ -10,6 +10,7 @@
     PERCENTAGE,
     UNIT_NOT_RECOGNIZED_TEMPLATE,
     UnitOfDataRate,
+    UnitOfElectricCharge,
     UnitOfElectricCurrent,
     UnitOfElectricPotential,
     UnitOfEnergy,
@@ -284,6 +285,21 @@ class PowerConverter(BaseUnitConverter):
     }
 
 
+class ChargeConverter(BaseUnitConverter):
+    """Utility to convert charge values."""
+
+    UNIT_CLASS = "charge"
+    NORMALIZED_UNIT = UnitOfElectricCharge.AMPERE_HOUR
+    _UNIT_CONVERSION: dict[str | None, float] = {
+        UnitOfElectricCharge.MILLIAMPERE_HOUR: 1,
+        UnitOfElectricCharge.AMPERE_HOUR: 1 / 1000,
+    }
+    VALID_UNITS = {
+        UnitOfElectricCharge.MILLIAMPERE_HOUR,
+        UnitOfElectricCharge.AMPERE_HOUR,
+    }
+
+
 class PressureConverter(BaseUnitConverter):
     """Utility to convert pressure values."""
 

tests/util/test_unit_conversion.py

@@ -11,6 +11,7 @@
     CONCENTRATION_PARTS_PER_MILLION,
     PERCENTAGE,
     UnitOfDataRate,
+    UnitOfElectricCharge,
     UnitOfElectricCurrent,
     UnitOfElectricPotential,
     UnitOfEnergy,
@@ -28,6 +29,7 @@
 from homeassistant.util import unit_conversion
 from homeassistant.util.unit_conversion import (
     BaseUnitConverter,
+    ChargeConverter,
     DataRateConverter,
     DistanceConverter,
     ElectricCurrentConverter,
@@ -60,6 +62,7 @@
         InformationConverter,
         MassConverter,
         PowerConverter,
+        ChargeConverter,
         PressureConverter,
         SpeedConverter,
         TemperatureConverter,
@@ -90,6 +93,11 @@
     InformationConverter: (UnitOfInformation.BITS, UnitOfInformation.BYTES, 8),
     MassConverter: (UnitOfMass.STONES, UnitOfMass.KILOGRAMS, 0.157473),
     PowerConverter: (UnitOfPower.WATT, UnitOfPower.KILO_WATT, 1000),
+    ChargeConverter: (
+        UnitOfElectricCharge.MILLIAMPERE_HOUR,
+        UnitOfElectricCharge.AMPERE_HOUR,
+        1000,
+    ),
     PressureConverter: (UnitOfPressure.HPA, UnitOfPressure.INHG, 33.86389),
     SpeedConverter: (
         UnitOfSpeed.KILOMETERS_PER_HOUR,
@@ -277,6 +285,20 @@
         (10, UnitOfPower.KILO_WATT, 10000, UnitOfPower.WATT),
         (10, UnitOfPower.WATT, 0.01, UnitOfPower.KILO_WATT),
     ],
+    ChargeConverter: [
+        (
+            10,
+            UnitOfElectricCharge.AMPERE_HOUR,
+            10000,
+            UnitOfElectricCharge.MILLIAMPERE_HOUR,
+        ),
+        (
+            10,
+            UnitOfElectricCharge.MILLIAMPERE_HOUR,
+            0.01,
+            UnitOfElectricCharge.AMPERE_HOUR,
+        ),
+    ],
     PressureConverter: [
         (1000, UnitOfPressure.HPA, 14.5037743897, UnitOfPressure.PSI),
         (1000, UnitOfPressure.HPA, 29.5299801647, UnitOfPressure.INHG),