Add temperature triggers

CODEOWNERS

@@ -1689,6 +1689,8 @@ build.json @home-assistant/supervisor
 /tests/components/tellduslive/ @fredrike
 /homeassistant/components/teltonika/ @karlbeecken
 /tests/components/teltonika/ @karlbeecken
+/homeassistant/components/temperature/ @home-assistant/core
+/tests/components/temperature/ @home-assistant/core
 /homeassistant/components/template/ @Petro31 @home-assistant/core
 /tests/components/template/ @Petro31 @home-assistant/core
 /homeassistant/components/tesla_fleet/ @Bre77

homeassistant/bootstrap.py

@@ -244,6 +244,7 @@ DEFAULT_INTEGRATIONS = {
     "door",
     "garage_door",
     "humidity",
+    "temperature",
 }
 DEFAULT_INTEGRATIONS_RECOVERY_MODE = {
     # These integrations are set up if recovery mode is activated.

homeassistant/components/automation/__init__.py

@@ -157,6 +157,7 @@ _EXPERIMENTAL_TRIGGER_PLATFORMS = {
     "schedule",
     "siren",
     "switch",
+    "temperature",
     "text",
     "update",
     "vacuum",

homeassistant/components/temperature/__init__.py

@@ -0,0 +1,17 @@
+"""Integration for temperature triggers."""
+
+from __future__ import annotations
+
+from homeassistant.core import HomeAssistant
+from homeassistant.helpers import config_validation as cv
+from homeassistant.helpers.typing import ConfigType
+
+DOMAIN = "temperature"
+CONFIG_SCHEMA = cv.empty_config_schema(DOMAIN)
+
+__all__ = []
+
+
+async def async_setup(hass: HomeAssistant, config: ConfigType) -> bool:
+    """Set up the component."""
+    return True

homeassistant/components/temperature/icons.json

@@ -0,0 +1,10 @@
+{
+  "triggers": {
+    "changed": {
+      "trigger": "mdi:thermometer"
+    },
+    "crossed_threshold": {
+      "trigger": "mdi:thermometer"
+    }
+  }
+}

homeassistant/components/temperature/manifest.json

@@ -0,0 +1,8 @@
+{
+  "domain": "temperature",
+  "name": "Temperature",
+  "codeowners": ["@home-assistant/core"],
+  "documentation": "https://www.home-assistant.io/integrations/temperature",
+  "integration_type": "system",
+  "quality_scale": "internal"
+}

homeassistant/components/temperature/strings.json

@@ -0,0 +1,82 @@
+{
+  "common": {
+    "trigger_behavior_description": "The behavior of the targeted entities to trigger on.",
+    "trigger_behavior_name": "Behavior"
+  },
+  "selector": {
+    "number_or_entity": {
+      "choices": {
+        "entity": "Entity",
+        "number": "Number"
+      }
+    },
+    "trigger_behavior": {
+      "options": {
+        "any": "Any",
+        "first": "First",
+        "last": "Last"
+      }
+    },
+    "trigger_temperature_unit": {
+      "options": {
+        "celsius": "Celsius (°C)",
+        "fahrenheit": "Fahrenheit (°F)"
+      }
+    },
+    "trigger_threshold_type": {
+      "options": {
+        "above": "Above",
+        "below": "Below",
+        "between": "Between",
+        "outside": "Outside"
+      }
+    }
+  },
+  "title": "Temperature",
+  "triggers": {
+    "changed": {
+      "description": "Triggers when the temperature changes.",
+      "fields": {
+        "above": {
+          "description": "Only trigger when temperature is above this value.",
+          "name": "Above"
+        },
+        "below": {
+          "description": "Only trigger when temperature is below this value.",
+          "name": "Below"
+        },
+        "unit": {
+          "description": "The unit of temperature for the trigger values. Defaults to the system unit.",
+          "name": "Unit"
+        }
+      },
+      "name": "Temperature changed"
+    },
+    "crossed_threshold": {
+      "description": "Triggers when the temperature crosses a threshold.",
+      "fields": {
+        "behavior": {
+          "description": "[%key:component::temperature::common::trigger_behavior_description%]",
+          "name": "[%key:component::temperature::common::trigger_behavior_name%]"
+        },
+        "lower_limit": {
+          "description": "The lower limit of the threshold.",
+          "name": "Lower limit"
+        },
+        "threshold_type": {
+          "description": "The type of threshold to use.",
+          "name": "Threshold type"
+        },
+        "unit": {
+          "description": "[%key:component::temperature::triggers::changed::fields::unit::description%]",
+          "name": "[%key:component::temperature::triggers::changed::fields::unit::name%]"
+        },
+        "upper_limit": {
+          "description": "The upper limit of the threshold.",
+          "name": "Upper limit"
+        }
+      },
+      "name": "Temperature crossed threshold"
+    }
+  }
+}

homeassistant/components/temperature/trigger.py

@@ -0,0 +1,188 @@
+"""Provides triggers for temperature."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import voluptuous as vol
+
+from homeassistant.components.climate import (
+    ATTR_CURRENT_TEMPERATURE as CLIMATE_ATTR_CURRENT_TEMPERATURE,
+    DOMAIN as CLIMATE_DOMAIN,
+)
+from homeassistant.components.sensor import DOMAIN as SENSOR_DOMAIN, SensorDeviceClass
+from homeassistant.components.water_heater import (
+    ATTR_CURRENT_TEMPERATURE as WATER_HEATER_ATTR_CURRENT_TEMPERATURE,
+    DOMAIN as WATER_HEATER_DOMAIN,
+)
+from homeassistant.components.weather import (
+    ATTR_WEATHER_TEMPERATURE,
+    ATTR_WEATHER_TEMPERATURE_UNIT,
+    DOMAIN as WEATHER_DOMAIN,
+)
+from homeassistant.const import (
+    ATTR_UNIT_OF_MEASUREMENT,
+    CONF_ABOVE,
+    CONF_BELOW,
+    CONF_OPTIONS,
+    UnitOfTemperature,
+)
+from homeassistant.core import HomeAssistant, State, split_entity_id
+from homeassistant.helpers.trigger import (
+    ATTR_BEHAVIOR,
+    BEHAVIOR_ANY,
+    BEHAVIOR_FIRST,
+    BEHAVIOR_LAST,
+    CONF_LOWER_LIMIT,
+    CONF_THRESHOLD_TYPE,
+    CONF_UPPER_LIMIT,
+    ENTITY_STATE_TRIGGER_SCHEMA,
+    EntityNumericalStateAttributeChangedTriggerBase,
+    EntityNumericalStateAttributeCrossedThresholdTriggerBase,
+    EntityNumericalStateBase,
+    ThresholdType,
+    Trigger,
+    TriggerConfig,
+    _number_or_entity,
+    _validate_limits_for_threshold_type,
+    _validate_range,
+    get_device_class_or_undefined,
+)
+from homeassistant.util.unit_conversion import TemperatureConverter
+
+CONF_UNIT = "unit"
+
+_UNIT_MAP = {
+    "celsius": UnitOfTemperature.CELSIUS,
+    "fahrenheit": UnitOfTemperature.FAHRENHEIT,
+}
+
+
+def _validate_temperature_unit(value: str) -> str:
+    """Convert temperature unit option to UnitOfTemperature."""
+    if value in _UNIT_MAP:
+        return _UNIT_MAP[value]
+    raise vol.Invalid(f"Unknown temperature unit: {value}")
+
+
+_UNIT_VALIDATOR = _validate_temperature_unit
+
+TEMPERATURE_CHANGED_TRIGGER_SCHEMA = ENTITY_STATE_TRIGGER_SCHEMA.extend(
+    {
+        vol.Required(CONF_OPTIONS): vol.All(
+            {
+                vol.Optional(CONF_ABOVE): _number_or_entity,
+                vol.Optional(CONF_BELOW): _number_or_entity,
+                vol.Optional(CONF_UNIT): _UNIT_VALIDATOR,
+            },
+            _validate_range(CONF_ABOVE, CONF_BELOW),
+        )
+    }
+)
+
+TEMPERATURE_CROSSED_THRESHOLD_TRIGGER_SCHEMA = ENTITY_STATE_TRIGGER_SCHEMA.extend(
+    {
+        vol.Required(CONF_OPTIONS): vol.All(
+            {
+                vol.Required(ATTR_BEHAVIOR, default=BEHAVIOR_ANY): vol.In(
+                    [BEHAVIOR_FIRST, BEHAVIOR_LAST, BEHAVIOR_ANY]
+                ),
+                vol.Optional(CONF_LOWER_LIMIT): _number_or_entity,
+                vol.Optional(CONF_UPPER_LIMIT): _number_or_entity,
+                vol.Required(CONF_THRESHOLD_TYPE): vol.Coerce(ThresholdType),
+                vol.Optional(CONF_UNIT): _UNIT_VALIDATOR,
+            },
+            _validate_range(CONF_LOWER_LIMIT, CONF_UPPER_LIMIT),
+            _validate_limits_for_threshold_type,
+        )
+    }
+)
+
+_DOMAINS = {SENSOR_DOMAIN, CLIMATE_DOMAIN, WATER_HEATER_DOMAIN, WEATHER_DOMAIN}
+
+
+class _TemperatureTriggerMixin(EntityNumericalStateBase):
+    """Mixin for temperature triggers providing entity filtering, value extraction, and unit conversion."""
+
+    _attributes = {
+        CLIMATE_DOMAIN: CLIMATE_ATTR_CURRENT_TEMPERATURE,
+        SENSOR_DOMAIN: None,  # Use state.state
+        WATER_HEATER_DOMAIN: WATER_HEATER_ATTR_CURRENT_TEMPERATURE,
+        WEATHER_DOMAIN: ATTR_WEATHER_TEMPERATURE,
+    }
+    _domains = _DOMAINS
+
+    def __init__(self, hass: HomeAssistant, config: TriggerConfig) -> None:
+        """Initialize the trigger."""
+        super().__init__(hass, config)
+        self._trigger_unit: str = self._options.get(
+            CONF_UNIT, hass.config.units.temperature_unit
+        )
+
+    def entity_filter(self, entities: set[str]) -> set[str]:
+        """Filter entities: sensor only with device_class temperature."""
+        entities = super().entity_filter(entities)
+        return {
+            entity_id
+            for entity_id in entities
+            if split_entity_id(entity_id)[0] != SENSOR_DOMAIN
+            or get_device_class_or_undefined(self._hass, entity_id)
+            == SensorDeviceClass.TEMPERATURE
+        }
+
+    def _get_entity_unit(self, state: State) -> str | None:
+        """Get the temperature unit of an entity from its state."""
+        domain = split_entity_id(state.entity_id)[0]
+        if domain == SENSOR_DOMAIN:
+            return state.attributes.get(ATTR_UNIT_OF_MEASUREMENT)
+        if domain == WEATHER_DOMAIN:
+            return state.attributes.get(
+                ATTR_WEATHER_TEMPERATURE_UNIT,
+                self._hass.config.units.temperature_unit,
+            )
+        # Climate and water_heater: show_temp converts to system unit
+        return self._hass.config.units.temperature_unit
+
+    def _get_tracked_value(self, state: State) -> Any:
+        """Get the temperature value converted to the trigger's configured unit."""
+        raw_value = super()._get_tracked_value(state)
+        if raw_value is None:
+            return None
+
+        entity_unit = self._get_entity_unit(state)
+        if entity_unit is None or entity_unit == self._trigger_unit:
+            return raw_value
+
+        try:
+            return TemperatureConverter.convert(
+                float(raw_value), entity_unit, self._trigger_unit
+            )
+        except TypeError, ValueError:
+            return raw_value  # Let the base class converter handle the error
+
+
+class TemperatureChangedTrigger(
+    _TemperatureTriggerMixin, EntityNumericalStateAttributeChangedTriggerBase
+):
+    """Trigger for temperature value changes across multiple domains."""
+
+    _schema = TEMPERATURE_CHANGED_TRIGGER_SCHEMA
+
+
+class TemperatureCrossedThresholdTrigger(
+    _TemperatureTriggerMixin, EntityNumericalStateAttributeCrossedThresholdTriggerBase
+):
+    """Trigger for temperature value crossing a threshold across multiple domains."""
+
+    _schema = TEMPERATURE_CROSSED_THRESHOLD_TRIGGER_SCHEMA
+
+
+TRIGGERS: dict[str, type[Trigger]] = {
+    "changed": TemperatureChangedTrigger,
+    "crossed_threshold": TemperatureCrossedThresholdTrigger,
+}
+
+
+async def async_get_triggers(hass: HomeAssistant) -> dict[str, type[Trigger]]:
+    """Return the triggers for temperature."""
+    return TRIGGERS

homeassistant/components/temperature/triggers.yaml

@@ -0,0 +1,75 @@
+.trigger_common_fields:
+  behavior: &trigger_behavior
+    required: true
+    default: any
+    selector:
+      select:
+        translation_key: trigger_behavior
+        options:
+          - first
+          - last
+          - any
+
+.number_or_entity: &number_or_entity
+  required: false
+  selector:
+    choose:
+      choices:
+        number:
+          selector:
+            number:
+              mode: box
+        entity:
+          selector:
+            entity:
+              filter:
+                domain:
+                  - input_number
+                  - number
+                  - sensor
+      translation_key: number_or_entity
+
+.trigger_threshold_type: &trigger_threshold_type
+  required: true
+  default: above
+  selector:
+    select:
+      options:
+        - above
+        - below
+        - between
+        - outside
+      translation_key: trigger_threshold_type
+
+.trigger_unit: &trigger_unit
+  required: false
+  selector:
+    select:
+      options:
+        - celsius
+        - fahrenheit
+      translation_key: trigger_temperature_unit
+
+.trigger_target: &trigger_target
+  entity:
+    - domain: sensor
+      device_class: temperature
+    - domain: climate
+    - domain: water_heater
+    - domain: weather
+
+changed:
+  target: *trigger_target
+  fields:
+    above: *number_or_entity
+    below: *number_or_entity
+    unit: *trigger_unit
+
+crossed_threshold:
+  target: *trigger_target
+  fields:
+    behavior: *trigger_behavior
+    threshold_type: *trigger_threshold_type
+    lower_limit: *number_or_entity
+    upper_limit: *number_or_entity
+    unit: *trigger_unit

script/hassfest/manifest.py

@@ -117,6 +117,7 @@ NO_IOT_CLASS = [
     "system_health",
     "system_log",
     "tag",
+    "temperature",
     "timer",
     "trace",
     "web_rtc",

script/hassfest/quality_scale.py

@@ -2150,6 +2150,7 @@ NO_QUALITY_SCALE = [
     "system_health",
     "system_log",
     "tag",
+    "temperature",
     "timer",
     "trace",
     "usage_prediction",

tests/components/temperature/__init__.py

@@ -0,0 +1 @@
+"""Tests for the temperature integration."""

tests/snapshots/test_bootstrap.ambr

@@ -83,6 +83,7 @@
     'system_health',
     'system_log',
     'tag',
+    'temperature',
     'text',
     'time',
     'timer',
@@ -183,6 +184,7 @@
     'system_health',
     'system_log',
     'tag',
+    'temperature',
     'text',
     'time',
     'timer',