Add Matter service actions for water_heater (home-assistant#153577)

Co-authored-by: Norbert Rittel <[email protected]>
Co-authored-by: Joost Lekkerkerker <[email protected]>

Author: 3 people

homeassistant/components/matter/__init__.py

@@ -20,13 +20,14 @@
 from homeassistant.const import CONF_URL, EVENT_HOMEASSISTANT_STOP
 from homeassistant.core import Event, HomeAssistant, callback
 from homeassistant.exceptions import ConfigEntryNotReady
-from homeassistant.helpers import device_registry as dr
+from homeassistant.helpers import config_validation as cv, device_registry as dr
 from homeassistant.helpers.aiohttp_client import async_get_clientsession
 from homeassistant.helpers.issue_registry import (
     IssueSeverity,
     async_create_issue,
     async_delete_issue,
 )
+from homeassistant.helpers.typing import ConfigType
 
 from .adapter import MatterAdapter
 from .addon import get_addon_manager
@@ -40,10 +41,13 @@
     node_from_ha_device_id,
 )
 from .models import MatterDeviceInfo
+from .services import async_setup_services
 
 CONNECT_TIMEOUT = 10
 LISTEN_READY_TIMEOUT = 30
 
+CONFIG_SCHEMA = cv.config_entry_only_config_schema(DOMAIN)
+
 
 @callback
 @cache
@@ -64,6 +68,12 @@ def get_matter_device_info(
     )
 
 
+async def async_setup(hass: HomeAssistant, config: ConfigType) -> bool:
+    """Set up the Matter integration services."""
+    async_setup_services(hass)
+    return True
+
+
 async def async_setup_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
     """Set up Matter from a config entry."""
     if use_addon := entry.data.get(CONF_USE_ADDON):

homeassistant/components/matter/button.py

@@ -155,4 +155,18 @@ async def async_press(self) -> None:
         required_attributes=(clusters.SmokeCoAlarm.Attributes.AcceptedCommandList,),
         value_contains=clusters.SmokeCoAlarm.Commands.SelfTestRequest.command_id,
     ),
+    MatterDiscoverySchema(
+        platform=Platform.BUTTON,
+        entity_description=MatterButtonEntityDescription(
+            key="WaterHeaterManagementCancelBoost",
+            translation_key="cancel_boost",
+            command=clusters.WaterHeaterManagement.Commands.CancelBoost,
+        ),
+        entity_class=MatterCommandButton,
+        required_attributes=(
+            clusters.WaterHeaterManagement.Attributes.AcceptedCommandList,
+        ),
+        value_contains=clusters.WaterHeaterManagement.Commands.CancelBoost.command_id,
+        allow_multi=True,  # Also used in water_heater
+    ),
 ]

homeassistant/components/matter/icons.json

@@ -163,5 +163,10 @@
         "default": "mdi:shield-lock"
       }
     }
+  },
+  "services": {
+    "water_heater_boost": {
+      "service": "mdi:water-boiler"
+    }
   }
 }

homeassistant/components/matter/services.py

@@ -0,0 +1,38 @@
+"""Services for Matter devices."""
+
+from __future__ import annotations
+
+import voluptuous as vol
+
+from homeassistant.components.water_heater import DOMAIN as WATER_HEATER_DOMAIN
+from homeassistant.core import HomeAssistant, callback
+from homeassistant.helpers import config_validation as cv, service
+
+from .const import DOMAIN
+
+ATTR_DURATION = "duration"
+ATTR_EMERGENCY_BOOST = "emergency_boost"
+ATTR_TEMPORARY_SETPOINT = "temporary_setpoint"
+
+SERVICE_WATER_HEATER_BOOST = "water_heater_boost"
+
+
+@callback
+def async_setup_services(hass: HomeAssistant) -> None:
+    """Register the Matter services."""
+
+    service.async_register_platform_entity_service(
+        hass,
+        DOMAIN,
+        SERVICE_WATER_HEATER_BOOST,
+        entity_domain=WATER_HEATER_DOMAIN,
+        schema={
+            # duration >=1
+            vol.Required(ATTR_DURATION): vol.All(vol.Coerce(int), vol.Range(min=1)),
+            vol.Optional(ATTR_EMERGENCY_BOOST): cv.boolean,
+            vol.Optional(ATTR_TEMPORARY_SETPOINT): vol.All(
+                vol.Coerce(int), vol.Range(min=30, max=65)
+            ),
+        },
+        func="async_set_boost",
+    )

homeassistant/components/matter/services.yaml

@@ -0,0 +1,26 @@
+water_heater_boost:
+  target:
+    entity:
+      domain: water_heater
+  fields:
+    duration:
+      selector:
+        number:
+          min: 60
+          max: 14400
+          step: 60
+          mode: box
+      default: 3600
+      required: true
+    emergency_boost:
+      selector:
+        boolean:
+      default: false
+    temporary_setpoint:
+      selector:
+        number:
+          min: 30
+          max: 65
+          step: 1
+          mode: slider
+      default: 65

homeassistant/components/matter/strings.json

@@ -106,6 +106,9 @@
       }
     },
     "button": {
+      "cancel_boost": {
+        "name": "Cancel boost"
+      },
       "pause": {
         "name": "[%key:common::action::pause%]"
       },
@@ -590,6 +593,24 @@
           "description": "The Matter device to add to the other Matter network."
         }
       }
+    },
+    "water_heater_boost": {
+      "name": "Boost water heater",
+      "description": "Enables water heater boost for a specific duration.",
+      "fields": {
+        "duration": {
+          "name": "Duration",
+          "description": "Boost duration"
+        },
+        "emergency_boost": {
+          "name": "Emergency boost",
+          "description": "Whether to enable emergency boost mode."
+        },
+        "temporary_setpoint": {
+          "name": "Temporary setpoint",
+          "description": "Temporary setpoint temperature in Celsius during the boost period."
+        }
+      }
     }
   }
 }

homeassistant/components/matter/water_heater.py

@@ -6,7 +6,9 @@
 from typing import Any, cast
 
 from chip.clusters import Objects as clusters
+from chip.clusters.Types import Nullable
 from matter_server.client.models import device_types
+from matter_server.common.errors import MatterError
 from matter_server.common.helpers.util import create_attribute_path_from_attribute
 
 from homeassistant.components.water_heater import (
@@ -25,6 +27,7 @@
     UnitOfTemperature,
 )
 from homeassistant.core import HomeAssistant, callback
+from homeassistant.exceptions import HomeAssistantError
 from homeassistant.helpers.entity_platform import AddConfigEntryEntitiesCallback
 
 from .entity import MatterEntity, MatterEntityDescription
@@ -40,6 +43,8 @@
     STATE_OFF: 0,
 }
 
+DEFAULT_BOOST_DURATION = 3600  # 1 hour
+
 
 async def async_setup_entry(
     hass: HomeAssistant,
@@ -78,6 +83,30 @@ class MatterWaterHeater(MatterEntity, WaterHeaterEntity):
     _attr_temperature_unit = UnitOfTemperature.CELSIUS
     _platform_translation_key = "water_heater"
 
+    async def async_set_boost(
+        self,
+        duration: int,
+        emergency_boost: bool = False,
+        temporary_setpoint: int | None = None,
+    ) -> None:
+        """Set boost."""
+        boost_info: clusters.WaterHeaterManagement.Structs.WaterHeaterBoostInfoStruct = clusters.WaterHeaterManagement.Structs.WaterHeaterBoostInfoStruct(
+            duration=duration,
+            emergencyBoost=emergency_boost,
+            temporarySetpoint=(
+                temporary_setpoint * TEMPERATURE_SCALING_FACTOR
+                if temporary_setpoint is not None
+                else Nullable
+            ),
+        )
+        try:
+            await self.send_device_command(
+                clusters.WaterHeaterManagement.Commands.Boost(boostInfo=boost_info)
+            )
+        except MatterError as err:
+            raise HomeAssistantError(f"Error sending Boost command: {err}") from err
+        self._update_from_device()
+
     async def async_set_temperature(self, **kwargs: Any) -> None:
         """Set new target temperature."""
         target_temperature: float | None = kwargs.get(ATTR_TEMPERATURE)
@@ -94,11 +123,11 @@ async def async_set_temperature(self, **kwargs: Any) -> None:
     async def async_set_operation_mode(self, operation_mode: str) -> None:
         """Set new operation mode."""
         self._attr_current_operation = operation_mode
-        # Boost 1h (3600s)
+        # Use the constant for boost duration
         boost_info: type[
             clusters.WaterHeaterManagement.Structs.WaterHeaterBoostInfoStruct
         ] = clusters.WaterHeaterManagement.Structs.WaterHeaterBoostInfoStruct(
-            duration=3600
+            duration=DEFAULT_BOOST_DURATION
         )
         system_mode_value = WATER_HEATER_SYSTEM_MODE_MAP[operation_mode]
         await self.write_attribute(

tests/components/matter/snapshots/test_button.ambr

@@ -2479,6 +2479,54 @@
     'state': 'unknown',
   })
 # ---
+# name: test_buttons[silabs_water_heater][button.water_heater_cancel_boost-entry]
+  EntityRegistryEntrySnapshot({
+    'aliases': set({
+    }),
+    'area_id': None,
+    'capabilities': None,
+    'config_entry_id': <ANY>,
+    'config_subentry_id': <ANY>,
+    'device_class': None,
+    'device_id': <ANY>,
+    'disabled_by': None,
+    'domain': 'button',
+    'entity_category': None,
+    'entity_id': 'button.water_heater_cancel_boost',
+    'has_entity_name': True,
+    'hidden_by': None,
+    'icon': None,
+    'id': <ANY>,
+    'labels': set({
+    }),
+    'name': None,
+    'options': dict({
+    }),
+    'original_device_class': None,
+    'original_icon': None,
+    'original_name': 'Cancel boost',
+    'platform': 'matter',
+    'previous_unique_id': None,
+    'suggested_object_id': None,
+    'supported_features': 0,
+    'translation_key': 'cancel_boost',
+    'unique_id': '00000000000004D2-0000000000000019-MatterNodeDevice-2-WaterHeaterManagementCancelBoost-148-65529',
+    'unit_of_measurement': None,
+  })
+# ---
+# name: test_buttons[silabs_water_heater][button.water_heater_cancel_boost-state]
+  StateSnapshot({
+    'attributes': ReadOnlyDict({
+      'friendly_name': 'Water Heater Cancel boost',
+    }),
+    'context': <ANY>,
+    'entity_id': 'button.water_heater_cancel_boost',
+    'last_changed': <ANY>,
+    'last_reported': <ANY>,
+    'last_updated': <ANY>,
+    'state': 'unknown',
+  })
+# ---
 # name: test_buttons[smoke_detector][button.smoke_sensor_identify-entry]
   EntityRegistryEntrySnapshot({
     'aliases': set({

tests/components/matter/test_water_heater.py

@@ -8,13 +8,19 @@
 import pytest
 from syrupy.assertion import SnapshotAssertion
 
+from homeassistant.components.matter.services import (
+    ATTR_DURATION,
+    ATTR_EMERGENCY_BOOST,
+    ATTR_TEMPORARY_SETPOINT,
+    SERVICE_WATER_HEATER_BOOST,
+)
 from homeassistant.components.water_heater import (
     STATE_ECO,
     STATE_HIGH_DEMAND,
     STATE_OFF,
     WaterHeaterEntityFeature,
 )
-from homeassistant.const import Platform
+from homeassistant.const import ATTR_ENTITY_ID, Platform
 from homeassistant.core import HomeAssistant
 from homeassistant.helpers import entity_registry as er
 
@@ -270,3 +276,43 @@ async def test_water_heater_turn_on_off(
         ),
         value=4,
     )
+
+
+@pytest.mark.parametrize("node_fixture", ["silabs_water_heater"])
+async def test_async_boost_actions(
+    hass: HomeAssistant,
+    matter_client: MagicMock,
+    matter_node: MatterNode,
+) -> None:
+    """Test that set boost sends the correct command and updates the device."""
+    state = hass.states.get("water_heater.water_heater")
+    assert state
+
+    # Set boost with duration, emergency_boost, and temporary_setpoint
+    await hass.services.async_call(
+        "matter",
+        SERVICE_WATER_HEATER_BOOST,
+        {
+            ATTR_ENTITY_ID: "water_heater.water_heater",
+            ATTR_DURATION: 60,
+            ATTR_EMERGENCY_BOOST: True,
+            ATTR_TEMPORARY_SETPOINT: 55,
+        },
+        blocking=True,
+    )
+    assert matter_client.send_device_command.call_count == 1
+    assert matter_client.send_device_command.call_args == call(
+        node_id=matter_node.node_id,
+        endpoint_id=2,
+        command=clusters.WaterHeaterManagement.Commands.Boost(
+            boostInfo=clusters.WaterHeaterManagement.Structs.WaterHeaterBoostInfoStruct(
+                duration=60,
+                oneShot=None,
+                emergencyBoost=True,
+                temporarySetpoint=5500,
+                targetPercentage=None,
+                targetReheat=None,
+            )
+        ),
+    )
+    matter_client.send_device_command.reset_mock()