1 """Constants for sensor."""
3 from __future__
import annotations
5 from enum
import StrEnum
6 from functools
import partial
7 from typing
import Final
9 import voluptuous
as vol
12 CONCENTRATION_MICROGRAMS_PER_CUBIC_METER,
13 CONCENTRATION_PARTS_PER_BILLION,
14 CONCENTRATION_PARTS_PER_MILLION,
17 SIGNAL_STRENGTH_DECIBELS,
18 SIGNAL_STRENGTH_DECIBELS_MILLIWATT,
21 UnitOfBloodGlucoseConcentration,
24 UnitOfElectricCurrent,
25 UnitOfElectricPotential,
33 UnitOfPrecipitationDepth,
45 DeprecatedConstantEnum,
46 all_with_deprecated_constants,
47 check_if_deprecated_constant,
48 dir_with_deprecated_constants,
53 BloodGlucoseConcentrationConverter,
54 ConductivityConverter,
58 ElectricCurrentConverter,
59 ElectricPotentialConverter,
67 UnitlessRatioConverter,
69 VolumeFlowRateConverter,
72 DOMAIN: Final =
"sensor"
74 CONF_STATE_CLASS: Final =
"state_class"
76 ATTR_LAST_RESET: Final =
"last_reset"
77 ATTR_STATE_CLASS: Final =
"state_class"
78 ATTR_OPTIONS: Final =
"options"
82 """Device class for sensors."""
88 Unit of measurement: `None`
90 ISO8601 format: https://en.wikipedia.org/wiki/ISO_8601
96 Provides a fixed list of options the state of the sensor can be in.
98 Unit of measurement: `None`
101 TIMESTAMP =
"timestamp"
104 Unit of measurement: `None`
106 ISO8601 format: https://en.wikipedia.org/wiki/ISO_8601
110 APPARENT_POWER =
"apparent_power"
113 Unit of measurement: `VA`
117 """Air Quality Index.
119 Unit of measurement: `None`
125 Unit of measurement: `UnitOfArea` units
128 ATMOSPHERIC_PRESSURE =
"atmospheric_pressure"
129 """Atmospheric pressure.
131 Unit of measurement: `UnitOfPressure` units
135 """Percentage of battery that is left.
137 Unit of measurement: `%`
140 BLOOD_GLUCOSE_CONCENTRATION =
"blood_glucose_concentration"
141 """Blood glucose concentration.
143 Unit of measurement: `mg/dL`, `mmol/L`
146 CO =
"carbon_monoxide"
147 """Carbon Monoxide gas concentration.
149 Unit of measurement: `ppm` (parts per million)
152 CO2 =
"carbon_dioxide"
153 """Carbon Dioxide gas concentration.
155 Unit of measurement: `ppm` (parts per million)
158 CONDUCTIVITY =
"conductivity"
161 Unit of measurement: `S/cm`, `mS/cm`, `µS/cm`
167 Unit of measurement: `A`, `mA`
170 DATA_RATE =
"data_rate"
173 Unit of measurement: UnitOfDataRate
176 DATA_SIZE =
"data_size"
179 Unit of measurement: UnitOfInformation
182 DISTANCE =
"distance"
185 Unit of measurement: `LENGTH_*` units
186 - SI /metric: `mm`, `cm`, `m`, `km`
187 - USCS / imperial: `in`, `ft`, `yd`, `mi`
190 DURATION =
"duration"
193 Unit of measurement: `d`, `h`, `min`, `s`, `ms`
199 Use this device class for sensors measuring energy consumption, for example
200 electric energy consumption.
201 Unit of measurement: `J`, `kJ`, `MJ`, `GJ`, `Wh`, `kWh`, `MWh`, `GWh`, `TWh`, `cal`, `kcal`, `Mcal`, `Gcal`
204 ENERGY_STORAGE =
"energy_storage"
207 Use this device class for sensors measuring stored energy, for example the amount
208 of electric energy currently stored in a battery or the capacity of a battery.
210 Unit of measurement: `Wh`, `kWh`, `MWh`, `GWh`, `TWh`, `MJ`, `GJ`
213 FREQUENCY =
"frequency"
216 Unit of measurement: `Hz`, `kHz`, `MHz`, `GHz`
224 - USCS / imperial: `ft³`, `CCF`
227 HUMIDITY =
"humidity"
228 """Relative humidity.
230 Unit of measurement: `%`
233 ILLUMINANCE =
"illuminance"
236 Unit of measurement: `lx`
239 IRRADIANCE =
"irradiance"
243 - SI / metric: `W/m²`
244 - USCS / imperial: `BTU/(h⋅ft²)`
247 MOISTURE =
"moisture"
250 Unit of measurement: `%`
253 MONETARY =
"monetary"
256 Unit of measurement: ISO4217 currency code
258 See https://en.wikipedia.org/wiki/ISO_4217#Active_codes for active codes
261 NITROGEN_DIOXIDE =
"nitrogen_dioxide"
264 Unit of measurement: `µg/m³`
267 NITROGEN_MONOXIDE =
"nitrogen_monoxide"
270 Unit of measurement: `µg/m³`
273 NITROUS_OXIDE =
"nitrous_oxide"
276 Unit of measurement: `µg/m³`
282 Unit of measurement: `µg/m³`
286 """Potential hydrogen (acidity/alkalinity).
288 Unit of measurement: Unitless
292 """Particulate matter <= 1 μm.
294 Unit of measurement: `µg/m³`
298 """Particulate matter <= 10 μm.
300 Unit of measurement: `µg/m³`
304 """Particulate matter <= 2.5 μm.
306 Unit of measurement: `µg/m³`
309 POWER_FACTOR =
"power_factor"
312 Unit of measurement: `%`, `None`
318 Unit of measurement: `W`, `kW`, `MW`, `GW`, `TW`
321 PRECIPITATION =
"precipitation"
322 """Accumulated precipitation.
324 Unit of measurement: UnitOfPrecipitationDepth
325 - SI / metric: `cm`, `mm`
326 - USCS / imperial: `in`
329 PRECIPITATION_INTENSITY =
"precipitation_intensity"
330 """Precipitation intensity.
332 Unit of measurement: UnitOfVolumetricFlux
333 - SI /metric: `mm/d`, `mm/h`
334 - USCS / imperial: `in/d`, `in/h`
337 PRESSURE =
"pressure"
341 - `mbar`, `cbar`, `bar`
347 REACTIVE_POWER =
"reactive_power"
350 Unit of measurement: `var`
353 SIGNAL_STRENGTH =
"signal_strength"
356 Unit of measurement: `dB`, `dBm`
359 SOUND_PRESSURE =
"sound_pressure"
362 Unit of measurement: `dB`, `dBA`
368 Unit of measurement: `SPEED_*` units or `UnitOfVolumetricFlux`
369 - SI /metric: `mm/d`, `mm/h`, `m/s`, `km/h`, `mm/s`
370 - USCS / imperial: `in/d`, `in/h`, `in/s`, `ft/s`, `mph`
372 - Beaufort: `Beaufort`
375 SULPHUR_DIOXIDE =
"sulphur_dioxide"
378 Unit of measurement: `µg/m³`
381 TEMPERATURE =
"temperature"
384 Unit of measurement: `°C`, `°F`, `K`
387 VOLATILE_ORGANIC_COMPOUNDS =
"volatile_organic_compounds"
390 Unit of measurement: `µg/m³`
393 VOLATILE_ORGANIC_COMPOUNDS_PARTS =
"volatile_organic_compounds_parts"
396 Unit of measurement: `ppm`, `ppb`
402 Unit of measurement: `V`, `mV`, `µV`
408 Unit of measurement: `VOLUME_*` units
409 - SI / metric: `mL`, `L`, `m³`
410 - USCS / imperial: `ft³`, `CCF`, `fl. oz.`, `gal` (warning: volumes expressed in
411 USCS/imperial units are currently assumed to be US volumes)
414 VOLUME_STORAGE =
"volume_storage"
415 """Generic stored volume.
417 Use this device class for sensors measuring stored volume, for example the amount
418 of fuel in a fuel tank.
420 Unit of measurement: `VOLUME_*` units
421 - SI / metric: `mL`, `L`, `m³`
422 - USCS / imperial: `ft³`, `CCF`, `fl. oz.`, `gal` (warning: volumes expressed in
423 USCS/imperial units are currently assumed to be US volumes)
426 VOLUME_FLOW_RATE =
"volume_flow_rate"
429 Unit of measurement: UnitOfVolumeFlowRate
430 - SI / metric: `m³/h`, `L/min`, `mL/s`
431 - USCS / imperial: `ft³/min`, `gal/min`
438 - SI / metric: `m³`, `L`
439 - USCS / imperial: `ft³`, `CCF`, `gal` (warning: volumes expressed in
440 USCS/imperial units are currently assumed to be US volumes)
444 """Generic weight, represents a measurement of an object's mass.
446 Weight is used instead of mass to fit with every day language.
448 Unit of measurement: `MASS_*` units
449 - SI / metric: `µg`, `mg`, `g`, `kg`
450 - USCS / imperial: `oz`, `lb`
453 WIND_SPEED =
"wind_speed"
456 Unit of measurement: `SPEED_*` units
457 - SI /metric: `m/s`, `km/h`
458 - USCS / imperial: `ft/s`, `mph`
460 - Beaufort: `Beaufort`
464 NON_NUMERIC_DEVICE_CLASSES = {
465 SensorDeviceClass.DATE,
466 SensorDeviceClass.ENUM,
467 SensorDeviceClass.TIMESTAMP,
470 DEVICE_CLASSES_SCHEMA: Final = vol.All(vol.Lower, vol.Coerce(SensorDeviceClass))
474 DEVICE_CLASSES: Final[list[str]] = [cls.value
for cls
in SensorDeviceClass]
478 """State class for sensors."""
480 MEASUREMENT =
"measurement"
481 """The state represents a measurement in present time."""
484 """The state represents a total amount.
486 For example: net energy consumption"""
488 TOTAL_INCREASING =
"total_increasing"
489 """The state represents a monotonically increasing total.
491 For example: an amount of consumed gas"""
494 STATE_CLASSES_SCHEMA: Final = vol.All(vol.Lower, vol.Coerce(SensorStateClass))
499 _DEPRECATED_STATE_CLASS_MEASUREMENT: Final = DeprecatedConstantEnum(
500 SensorStateClass.MEASUREMENT,
"2025.1"
502 _DEPRECATED_STATE_CLASS_TOTAL: Final = DeprecatedConstantEnum(
503 SensorStateClass.TOTAL,
"2025.1"
505 _DEPRECATED_STATE_CLASS_TOTAL_INCREASING: Final = DeprecatedConstantEnum(
506 SensorStateClass.TOTAL_INCREASING,
"2025.1"
508 STATE_CLASSES: Final[list[str]] = [cls.value
for cls
in SensorStateClass]
510 UNIT_CONVERTERS: dict[SensorDeviceClass | str |
None, type[BaseUnitConverter]] = {
511 SensorDeviceClass.AREA: AreaConverter,
512 SensorDeviceClass.ATMOSPHERIC_PRESSURE: PressureConverter,
513 SensorDeviceClass.BLOOD_GLUCOSE_CONCENTRATION: BloodGlucoseConcentrationConverter,
514 SensorDeviceClass.CONDUCTIVITY: ConductivityConverter,
515 SensorDeviceClass.CURRENT: ElectricCurrentConverter,
516 SensorDeviceClass.DATA_RATE: DataRateConverter,
517 SensorDeviceClass.DATA_SIZE: InformationConverter,
518 SensorDeviceClass.DISTANCE: DistanceConverter,
519 SensorDeviceClass.DURATION: DurationConverter,
520 SensorDeviceClass.ENERGY: EnergyConverter,
521 SensorDeviceClass.ENERGY_STORAGE: EnergyConverter,
522 SensorDeviceClass.GAS: VolumeConverter,
523 SensorDeviceClass.POWER: PowerConverter,
524 SensorDeviceClass.POWER_FACTOR: UnitlessRatioConverter,
525 SensorDeviceClass.PRECIPITATION: DistanceConverter,
526 SensorDeviceClass.PRECIPITATION_INTENSITY: SpeedConverter,
527 SensorDeviceClass.PRESSURE: PressureConverter,
528 SensorDeviceClass.SPEED: SpeedConverter,
529 SensorDeviceClass.TEMPERATURE: TemperatureConverter,
530 SensorDeviceClass.VOLATILE_ORGANIC_COMPOUNDS_PARTS: UnitlessRatioConverter,
531 SensorDeviceClass.VOLTAGE: ElectricPotentialConverter,
532 SensorDeviceClass.VOLUME: VolumeConverter,
533 SensorDeviceClass.VOLUME_STORAGE: VolumeConverter,
534 SensorDeviceClass.VOLUME_FLOW_RATE: VolumeFlowRateConverter,
535 SensorDeviceClass.WATER: VolumeConverter,
536 SensorDeviceClass.WEIGHT: MassConverter,
537 SensorDeviceClass.WIND_SPEED: SpeedConverter,
540 DEVICE_CLASS_UNITS: dict[SensorDeviceClass, set[type[StrEnum] | str |
None]] = {
541 SensorDeviceClass.APPARENT_POWER: set(UnitOfApparentPower),
542 SensorDeviceClass.AQI: {
None},
543 SensorDeviceClass.AREA: set(UnitOfArea),
544 SensorDeviceClass.ATMOSPHERIC_PRESSURE: set(UnitOfPressure),
545 SensorDeviceClass.BATTERY: {PERCENTAGE},
546 SensorDeviceClass.BLOOD_GLUCOSE_CONCENTRATION: set(UnitOfBloodGlucoseConcentration),
547 SensorDeviceClass.CO: {CONCENTRATION_PARTS_PER_MILLION},
548 SensorDeviceClass.CO2: {CONCENTRATION_PARTS_PER_MILLION},
549 SensorDeviceClass.CONDUCTIVITY: set(UnitOfConductivity),
550 SensorDeviceClass.CURRENT: set(UnitOfElectricCurrent),
551 SensorDeviceClass.DATA_RATE: set(UnitOfDataRate),
552 SensorDeviceClass.DATA_SIZE: set(UnitOfInformation),
553 SensorDeviceClass.DISTANCE: set(UnitOfLength),
554 SensorDeviceClass.DURATION: {
559 UnitOfTime.MILLISECONDS,
561 SensorDeviceClass.ENERGY: set(UnitOfEnergy),
562 SensorDeviceClass.ENERGY_STORAGE: set(UnitOfEnergy),
563 SensorDeviceClass.FREQUENCY: set(UnitOfFrequency),
564 SensorDeviceClass.GAS: {
565 UnitOfVolume.CENTUM_CUBIC_FEET,
566 UnitOfVolume.CUBIC_FEET,
567 UnitOfVolume.CUBIC_METERS,
569 SensorDeviceClass.HUMIDITY: {PERCENTAGE},
570 SensorDeviceClass.ILLUMINANCE: {LIGHT_LUX},
571 SensorDeviceClass.IRRADIANCE: set(UnitOfIrradiance),
572 SensorDeviceClass.MOISTURE: {PERCENTAGE},
573 SensorDeviceClass.NITROGEN_DIOXIDE: {CONCENTRATION_MICROGRAMS_PER_CUBIC_METER},
574 SensorDeviceClass.NITROGEN_MONOXIDE: {CONCENTRATION_MICROGRAMS_PER_CUBIC_METER},
575 SensorDeviceClass.NITROUS_OXIDE: {CONCENTRATION_MICROGRAMS_PER_CUBIC_METER},
576 SensorDeviceClass.OZONE: {CONCENTRATION_MICROGRAMS_PER_CUBIC_METER},
577 SensorDeviceClass.PH: {
None},
578 SensorDeviceClass.PM1: {CONCENTRATION_MICROGRAMS_PER_CUBIC_METER},
579 SensorDeviceClass.PM10: {CONCENTRATION_MICROGRAMS_PER_CUBIC_METER},
580 SensorDeviceClass.PM25: {CONCENTRATION_MICROGRAMS_PER_CUBIC_METER},
581 SensorDeviceClass.POWER_FACTOR: {PERCENTAGE,
None},
582 SensorDeviceClass.POWER: {
584 UnitOfPower.KILO_WATT,
585 UnitOfPower.MEGA_WATT,
586 UnitOfPower.GIGA_WATT,
587 UnitOfPower.TERA_WATT,
589 SensorDeviceClass.PRECIPITATION: set(UnitOfPrecipitationDepth),
590 SensorDeviceClass.PRECIPITATION_INTENSITY: set(UnitOfVolumetricFlux),
591 SensorDeviceClass.PRESSURE: set(UnitOfPressure),
592 SensorDeviceClass.REACTIVE_POWER: {UnitOfReactivePower.VOLT_AMPERE_REACTIVE},
593 SensorDeviceClass.SIGNAL_STRENGTH: {
594 SIGNAL_STRENGTH_DECIBELS,
595 SIGNAL_STRENGTH_DECIBELS_MILLIWATT,
597 SensorDeviceClass.SOUND_PRESSURE: set(UnitOfSoundPressure),
598 SensorDeviceClass.SPEED: set(UnitOfSpeed).union(set(UnitOfVolumetricFlux)),
599 SensorDeviceClass.SULPHUR_DIOXIDE: {CONCENTRATION_MICROGRAMS_PER_CUBIC_METER},
600 SensorDeviceClass.TEMPERATURE: set(UnitOfTemperature),
601 SensorDeviceClass.VOLATILE_ORGANIC_COMPOUNDS: {
602 CONCENTRATION_MICROGRAMS_PER_CUBIC_METER
604 SensorDeviceClass.VOLATILE_ORGANIC_COMPOUNDS_PARTS: {
605 CONCENTRATION_PARTS_PER_BILLION,
606 CONCENTRATION_PARTS_PER_MILLION,
608 SensorDeviceClass.VOLTAGE: set(UnitOfElectricPotential),
609 SensorDeviceClass.VOLUME: set(UnitOfVolume),
610 SensorDeviceClass.VOLUME_FLOW_RATE: set(UnitOfVolumeFlowRate),
611 SensorDeviceClass.VOLUME_STORAGE: set(UnitOfVolume),
612 SensorDeviceClass.WATER: {
613 UnitOfVolume.CENTUM_CUBIC_FEET,
614 UnitOfVolume.CUBIC_FEET,
615 UnitOfVolume.CUBIC_METERS,
616 UnitOfVolume.GALLONS,
619 SensorDeviceClass.WEIGHT: set(UnitOfMass),
620 SensorDeviceClass.WIND_SPEED: set(UnitOfSpeed),
623 DEVICE_CLASS_STATE_CLASSES: dict[SensorDeviceClass, set[SensorStateClass]] = {
624 SensorDeviceClass.APPARENT_POWER: {SensorStateClass.MEASUREMENT},
625 SensorDeviceClass.AQI: {SensorStateClass.MEASUREMENT},
626 SensorDeviceClass.AREA: set(SensorStateClass),
627 SensorDeviceClass.ATMOSPHERIC_PRESSURE: {SensorStateClass.MEASUREMENT},
628 SensorDeviceClass.BATTERY: {SensorStateClass.MEASUREMENT},
629 SensorDeviceClass.BLOOD_GLUCOSE_CONCENTRATION: {SensorStateClass.MEASUREMENT},
630 SensorDeviceClass.CO: {SensorStateClass.MEASUREMENT},
631 SensorDeviceClass.CO2: {SensorStateClass.MEASUREMENT},
632 SensorDeviceClass.CONDUCTIVITY: {SensorStateClass.MEASUREMENT},
633 SensorDeviceClass.CURRENT: {SensorStateClass.MEASUREMENT},
634 SensorDeviceClass.DATA_RATE: {SensorStateClass.MEASUREMENT},
635 SensorDeviceClass.DATA_SIZE: set(SensorStateClass),
636 SensorDeviceClass.DATE: set(),
637 SensorDeviceClass.DISTANCE: set(SensorStateClass),
638 SensorDeviceClass.DURATION: set(SensorStateClass),
639 SensorDeviceClass.ENERGY: {
640 SensorStateClass.TOTAL,
641 SensorStateClass.TOTAL_INCREASING,
643 SensorDeviceClass.ENERGY_STORAGE: {SensorStateClass.MEASUREMENT},
644 SensorDeviceClass.ENUM: set(),
645 SensorDeviceClass.FREQUENCY: {SensorStateClass.MEASUREMENT},
646 SensorDeviceClass.GAS: {SensorStateClass.TOTAL, SensorStateClass.TOTAL_INCREASING},
647 SensorDeviceClass.HUMIDITY: {SensorStateClass.MEASUREMENT},
648 SensorDeviceClass.ILLUMINANCE: {SensorStateClass.MEASUREMENT},
649 SensorDeviceClass.IRRADIANCE: {SensorStateClass.MEASUREMENT},
650 SensorDeviceClass.MOISTURE: {SensorStateClass.MEASUREMENT},
651 SensorDeviceClass.MONETARY: {SensorStateClass.TOTAL},
652 SensorDeviceClass.NITROGEN_DIOXIDE: {SensorStateClass.MEASUREMENT},
653 SensorDeviceClass.NITROGEN_MONOXIDE: {SensorStateClass.MEASUREMENT},
654 SensorDeviceClass.NITROUS_OXIDE: {SensorStateClass.MEASUREMENT},
655 SensorDeviceClass.OZONE: {SensorStateClass.MEASUREMENT},
656 SensorDeviceClass.PH: {SensorStateClass.MEASUREMENT},
657 SensorDeviceClass.PM1: {SensorStateClass.MEASUREMENT},
658 SensorDeviceClass.PM10: {SensorStateClass.MEASUREMENT},
659 SensorDeviceClass.PM25: {SensorStateClass.MEASUREMENT},
660 SensorDeviceClass.POWER_FACTOR: {SensorStateClass.MEASUREMENT},
661 SensorDeviceClass.POWER: {SensorStateClass.MEASUREMENT},
662 SensorDeviceClass.PRECIPITATION: set(SensorStateClass),
663 SensorDeviceClass.PRECIPITATION_INTENSITY: {SensorStateClass.MEASUREMENT},
664 SensorDeviceClass.PRESSURE: {SensorStateClass.MEASUREMENT},
665 SensorDeviceClass.REACTIVE_POWER: {SensorStateClass.MEASUREMENT},
666 SensorDeviceClass.SIGNAL_STRENGTH: {SensorStateClass.MEASUREMENT},
667 SensorDeviceClass.SOUND_PRESSURE: {SensorStateClass.MEASUREMENT},
668 SensorDeviceClass.SPEED: {SensorStateClass.MEASUREMENT},
669 SensorDeviceClass.SULPHUR_DIOXIDE: {SensorStateClass.MEASUREMENT},
670 SensorDeviceClass.TEMPERATURE: {SensorStateClass.MEASUREMENT},
671 SensorDeviceClass.TIMESTAMP: set(),
672 SensorDeviceClass.VOLATILE_ORGANIC_COMPOUNDS: {SensorStateClass.MEASUREMENT},
673 SensorDeviceClass.VOLATILE_ORGANIC_COMPOUNDS_PARTS: {SensorStateClass.MEASUREMENT},
674 SensorDeviceClass.VOLTAGE: {SensorStateClass.MEASUREMENT},
675 SensorDeviceClass.VOLUME: {
676 SensorStateClass.TOTAL,
677 SensorStateClass.TOTAL_INCREASING,
679 SensorDeviceClass.VOLUME_STORAGE: {SensorStateClass.MEASUREMENT},
680 SensorDeviceClass.VOLUME_FLOW_RATE: {SensorStateClass.MEASUREMENT},
681 SensorDeviceClass.WATER: {
682 SensorStateClass.TOTAL,
683 SensorStateClass.TOTAL_INCREASING,
685 SensorDeviceClass.WEIGHT: {
686 SensorStateClass.MEASUREMENT,
687 SensorStateClass.TOTAL,
688 SensorStateClass.TOTAL_INCREASING,
690 SensorDeviceClass.WIND_SPEED: {SensorStateClass.MEASUREMENT},
694 __getattr__ = partial(check_if_deprecated_constant, module_globals=globals())
696 dir_with_deprecated_constants, module_globals_keys=[*globals().keys()]
list[str] all_with_deprecated_constants(dict[str, Any] module_globals)