Add Matter Thermostat presets feature

homeassistant/components/matter/climate.py

@@ -16,6 +16,10 @@
     ATTR_TARGET_TEMP_LOW,
     DEFAULT_MAX_TEMP,
     DEFAULT_MIN_TEMP,
+    PRESET_AWAY,
+    PRESET_HOME,
+    PRESET_NONE,
+    PRESET_SLEEP,
     ClimateEntity,
     ClimateEntityDescription,
     ClimateEntityFeature,
@@ -42,6 +46,18 @@
     HVACMode.FAN_ONLY: 7,
 }
 
+# Map of Matter PresetScenarioEnum to HA standard preset constants or custom names
+# This ensures presets are translated correctly using HA's translation system.
+# kUserDefined scenarios always use device-provided names.
+PRESET_SCENARIO_TO_HA_PRESET: dict[int, str] = {
+    clusters.Thermostat.Enums.PresetScenarioEnum.kOccupied: PRESET_HOME,
+    clusters.Thermostat.Enums.PresetScenarioEnum.kUnoccupied: PRESET_AWAY,
+    clusters.Thermostat.Enums.PresetScenarioEnum.kSleep: PRESET_SLEEP,
+    clusters.Thermostat.Enums.PresetScenarioEnum.kWake: "wake",
+    clusters.Thermostat.Enums.PresetScenarioEnum.kVacation: "vacation",
+    clusters.Thermostat.Enums.PresetScenarioEnum.kGoingToSleep: "going_to_sleep",
+}
+
 SINGLE_SETPOINT_DEVICES: set[tuple[int, int]] = {
     # Some devices only have a single setpoint while the matter spec
     # assumes that you need separate setpoints for heating and cooling.
@@ -158,7 +174,6 @@
 }
 
 SystemModeEnum = clusters.Thermostat.Enums.SystemModeEnum
-ControlSequenceEnum = clusters.Thermostat.Enums.ControlSequenceOfOperationEnum
 ThermostatFeature = clusters.Thermostat.Bitmaps.Feature
 
 
@@ -194,10 +209,20 @@ class MatterClimate(MatterEntity, ClimateEntity):
 
     _attr_temperature_unit: str = UnitOfTemperature.CELSIUS
     _attr_hvac_mode: HVACMode = HVACMode.OFF
+    matter_presets: list[clusters.Thermostat.Structs.PresetStruct] | None = None
+    _attr_preset_mode: str | None = None
+    _attr_preset_modes: list[str] | None = None
     _feature_map: int | None = None
 
     _platform_translation_key = "thermostat"
 
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        """Initialize the climate entity."""
+        # Initialize preset handle mapping as instance attribute before calling super().__init__()
+        # because MatterEntity.__init__() calls _update_from_device() which needs this attribute
+        self._preset_handle_by_name: dict[str, bytes | None] = {}
+        super().__init__(*args, **kwargs)
+
     async def async_set_temperature(self, **kwargs: Any) -> None:
         """Set new target temperature."""
         target_hvac_mode: HVACMode | None = kwargs.get(ATTR_HVAC_MODE)
@@ -242,6 +267,36 @@ async def async_set_temperature(self, **kwargs: Any) -> None:
                     matter_attribute=clusters.Thermostat.Attributes.OccupiedCoolingSetpoint,
                 )
 
+    async def async_set_preset_mode(self, preset_mode: str) -> None:
+        """Set new preset mode."""
+        preset_handle = self._preset_handle_by_name[preset_mode]
+
+        # Handle clearing the preset (PRESET_NONE maps to None)
+        if preset_handle is None:
+            # Clear the active preset by setting ActivePresetHandle to None
+            # Use an empty bytes value or None to represent "no preset"
+            await self.send_device_command(
+                clusters.Thermostat.Commands.SetActivePresetRequest(presetHandle=b"")
+            )
+            active_preset_handle = None
+        else:
+            await self.send_device_command(
+                clusters.Thermostat.Commands.SetActivePresetRequest(
+                    presetHandle=preset_handle
+                )
+            )
+            active_preset_handle = preset_handle
+
+        # Optimistically update the endpoint's ActivePresetHandle attribute
+        # to prevent _update_from_device() from reverting to stale device state
+        active_preset_path = create_attribute_path_from_attribute(
+            endpoint_id=self._endpoint.endpoint_id,
+            attribute=clusters.Thermostat.Attributes.ActivePresetHandle,
+        )
+        self._endpoint.set_attribute_value(active_preset_path, active_preset_handle)
+        self._update_from_device()
+        self.async_write_ha_state()
+
     async def async_set_hvac_mode(self, hvac_mode: HVACMode) -> None:
         """Set new target hvac mode."""
 
@@ -266,10 +321,10 @@ async def async_set_hvac_mode(self, hvac_mode: HVACMode) -> None:
     def _update_from_device(self) -> None:
         """Update from device."""
         self._calculate_features()
+
         self._attr_current_temperature = self._get_temperature_in_degrees(
             clusters.Thermostat.Attributes.LocalTemperature
         )
-
         self._attr_current_humidity = (
             int(raw_measured_humidity) / HUMIDITY_SCALING_FACTOR
             if (
@@ -281,6 +336,75 @@ def _update_from_device(self) -> None:
             else None
         )
 
+        self._update_presets()
+
+        self._update_hvac_mode_and_action()
+        self._update_target_temperatures()
+        self._update_temperature_limits()
+
+    @callback
+    def _update_presets(self) -> None:
+        """Update preset modes and active preset."""
+        # Check if the device supports presets feature before attempting to load.
+        # Use the already computed supported features instead of re-reading
+        # the FeatureMap attribute to keep a single source of truth and avoid
+        # casting None when the attribute is temporarily unavailable.
+        supported_features = self._attr_supported_features or 0
+        if not (supported_features & ClimateEntityFeature.PRESET_MODE):
+            # Device does not support presets, skip preset update
+            self._preset_handle_by_name.clear()
+            self._attr_preset_modes = []
+            self._attr_preset_mode = None
+            return
+
+        self.matter_presets = self.get_matter_attribute_value(
+            clusters.Thermostat.Attributes.Presets
+        )
+        # Build preset mapping and list
+        self._preset_handle_by_name.clear()
+        presets = []
+        if self.matter_presets:
+            for i, preset in enumerate(self.matter_presets, start=1):
+                # Map Matter PresetScenarioEnum to HA standard presets for translations
+                if preset.presetScenario in PRESET_SCENARIO_TO_HA_PRESET:
+                    # Use the mapped preset name from the dictionary
+                    ha_preset_name = PRESET_SCENARIO_TO_HA_PRESET[preset.presetScenario]
+                # For unmapped scenarios, use device-provided name
+                elif preset.name and (name := preset.name.strip()):
+                    ha_preset_name = name
+                else:
+                    ha_preset_name = f"Preset{i}"
+
+                presets.append(ha_preset_name)
+                self._preset_handle_by_name[ha_preset_name] = preset.presetHandle
+
+        # Always include PRESET_NONE to allow users to clear the preset
+        presets.append(PRESET_NONE)
+        self._preset_handle_by_name[PRESET_NONE] = None
+
+        self._attr_preset_modes = presets
+
+        # Update active preset mode
+        active_preset_handle = self.get_matter_attribute_value(
+            clusters.Thermostat.Attributes.ActivePresetHandle
+        )
+        if active_preset_handle is None:
+            # Explicitly no active preset selected on device
+            self._attr_preset_mode = PRESET_NONE
+        else:
+            self._attr_preset_mode = None
+            for preset_name, handle in self._preset_handle_by_name.items():
+                if preset_name != PRESET_NONE and handle == active_preset_handle:
+                    self._attr_preset_mode = preset_name
+                    break
+            else:
+                # Device reports an active preset handle that we don't know
+                # Avoid reporting an invalid mode in that case, fall back to PRESET_NONE
+                self._attr_preset_mode = PRESET_NONE
+
+    @callback
+    def _update_hvac_mode_and_action(self) -> None:
+        """Update HVAC mode and action from device."""
         if self.get_matter_attribute_value(clusters.OnOff.Attributes.OnOff) is False:
             # special case: the appliance has a dedicated Power switch on the OnOff cluster
             # if the mains power is off - treat it as if the HVAC mode is off
@@ -332,7 +456,10 @@ def _update_from_device(self) -> None:
                     self._attr_hvac_action = HVACAction.FAN
                 else:
                     self._attr_hvac_action = HVACAction.OFF
-        # update target temperature high/low
+
+    @callback
+    def _update_target_temperatures(self) -> None:
+        """Update target temperature or temperature range."""
         supports_range = (
             self._attr_supported_features
             & ClimateEntityFeature.TARGET_TEMPERATURE_RANGE
@@ -358,6 +485,9 @@ def _update_from_device(self) -> None:
                     clusters.Thermostat.Attributes.OccupiedHeatingSetpoint
                 )
 
+    @callback
+    def _update_temperature_limits(self) -> None:
+        """Update min and max temperature limits."""
         # update min_temp
         if self._attr_hvac_mode == HVACMode.COOL:
             attribute = clusters.Thermostat.Attributes.AbsMinCoolSetpointLimit
@@ -397,6 +527,9 @@ def _calculate_features(
         self._attr_supported_features = (
             ClimateEntityFeature.TARGET_TEMPERATURE | ClimateEntityFeature.TURN_OFF
         )
+        if feature_map & ThermostatFeature.kPresets:
+            self._attr_supported_features |= ClimateEntityFeature.PRESET_MODE
+        # determine supported hvac modes
         if feature_map & ThermostatFeature.kHeating:
             self._attr_hvac_modes.append(HVACMode.HEAT)
         if feature_map & ThermostatFeature.kCooling:
@@ -439,9 +572,13 @@ def _get_temperature_in_degrees(
         optional_attributes=(
             clusters.Thermostat.Attributes.FeatureMap,
             clusters.Thermostat.Attributes.ControlSequenceOfOperation,
+            clusters.Thermostat.Attributes.NumberOfPresets,
             clusters.Thermostat.Attributes.Occupancy,
             clusters.Thermostat.Attributes.OccupiedCoolingSetpoint,
             clusters.Thermostat.Attributes.OccupiedHeatingSetpoint,
+            clusters.Thermostat.Attributes.Presets,
+            clusters.Thermostat.Attributes.PresetTypes,
+            clusters.Thermostat.Attributes.ActivePresetHandle,
             clusters.Thermostat.Attributes.SystemMode,
             clusters.Thermostat.Attributes.ThermostatRunningMode,
             clusters.Thermostat.Attributes.ThermostatRunningState,

homeassistant/components/matter/strings.json

@@ -145,7 +145,16 @@
     },
     "climate": {
       "thermostat": {
-        "name": "Thermostat"
+        "name": "Thermostat",
+        "state_attributes": {
+          "preset_mode": {
+            "state": {
+              "going_to_sleep": "Going to sleep",
+              "vacation": "Vacation",
+              "wake": "Wake"
+            }
+          }
+        }
       }
     },
     "cover": {

tests/components/matter/fixtures/nodes/eve_thermo_v5.json

@@ -501,7 +501,7 @@
       }
     ],
     "1/513/74": 8,
-    "1/513/78": null,
+    "1/513/78": "AQ==",
     "1/513/80": [
       {
         "0": "AQ==",

tests/components/matter/snapshots/test_climate.ambr

@@ -206,6 +206,16 @@
       ]),
       'max_temp': 30.0,
       'min_temp': 10.0,
+      'preset_modes': list([
+        'home',
+        'away',
+        'sleep',
+        'wake',
+        'vacation',
+        'going_to_sleep',
+        'Eco',
+        'none',
+      ]),
     }),
     'config_entry_id': <ANY>,
     'config_subentry_id': <ANY>,
@@ -231,7 +241,7 @@
     'platform': 'matter',
     'previous_unique_id': None,
     'suggested_object_id': None,
-    'supported_features': <ClimateEntityFeature: 385>,
+    'supported_features': <ClimateEntityFeature: 401>,
     'translation_key': 'thermostat',
     'unique_id': '00000000000004D2-000000000000000C-MatterNodeDevice-1-MatterThermostat-513-0',
     'unit_of_measurement': None,
@@ -248,7 +258,18 @@
       ]),
       'max_temp': 30.0,
       'min_temp': 10.0,
-      'supported_features': <ClimateEntityFeature: 385>,
+      'preset_mode': 'home',
+      'preset_modes': list([
+        'home',
+        'away',
+        'sleep',
+        'wake',
+        'vacation',
+        'going_to_sleep',
+        'Eco',
+        'none',
+      ]),
+      'supported_features': <ClimateEntityFeature: 401>,
       'temperature': 17.5,
     }),
     'context': <ANY>,
@@ -482,6 +503,11 @@
       ]),
       'max_temp': 32.0,
       'min_temp': 7.0,
+      'preset_modes': list([
+        'home',
+        'away',
+        'none',
+      ]),
     }),
     'config_entry_id': <ANY>,
     'config_subentry_id': <ANY>,
@@ -507,7 +533,7 @@
     'platform': 'matter',
     'previous_unique_id': None,
     'suggested_object_id': None,
-    'supported_features': <ClimateEntityFeature: 387>,
+    'supported_features': <ClimateEntityFeature: 403>,
     'translation_key': 'thermostat',
     'unique_id': '00000000000004D2-0000000000000096-MatterNodeDevice-1-MatterThermostat-513-0',
     'unit_of_measurement': None,
@@ -527,7 +553,13 @@
       ]),
       'max_temp': 32.0,
       'min_temp': 7.0,
-      'supported_features': <ClimateEntityFeature: 387>,
+      'preset_mode': 'none',
+      'preset_modes': list([
+        'home',
+        'away',
+        'none',
+      ]),
+      'supported_features': <ClimateEntityFeature: 403>,
       'target_temp_high': 26.0,
       'target_temp_low': 20.0,
       'temperature': None,