Deprecate aux heat for mqtt climate (#98666)

homeassistant/components/mqtt/climate.py

@@ -45,6 +45,7 @@ from homeassistant.const import (
 from homeassistant.core import HomeAssistant, callback
 import homeassistant.helpers.config_validation as cv
 from homeassistant.helpers.entity_platform import AddEntitiesCallback
+from homeassistant.helpers.issue_registry import IssueSeverity, async_create_issue
 from homeassistant.helpers.template import Template
 from homeassistant.helpers.typing import ConfigType, DiscoveryInfoType
 from homeassistant.util.unit_conversion import TemperatureConverter
@@ -77,6 +78,7 @@ from .const import (
     CONF_TEMP_STATE_TEMPLATE,
     CONF_TEMP_STATE_TOPIC,
     DEFAULT_OPTIMISTIC,
+    DOMAIN,
     PAYLOAD_NONE,
 )
 from .debug_info import log_messages
@@ -92,8 +94,13 @@ from .util import get_mqtt_data, valid_publish_topic, valid_subscribe_topic
 
 _LOGGER = logging.getLogger(__name__)
 
+MQTT_CLIMATE_AUX_DOCS = "https://www.home-assistant.io/integrations/climate.mqtt/"
+
 DEFAULT_NAME = "MQTT HVAC"
 
+# Options CONF_AUX_COMMAND_TOPIC, CONF_AUX_STATE_TOPIC
+# and CONF_AUX_STATE_TEMPLATE were deprecated in HA Core 2023.9
+# Support will be removed in HA Core 2024.3
 CONF_AUX_COMMAND_TOPIC = "aux_command_topic"
 CONF_AUX_STATE_TEMPLATE = "aux_state_template"
 CONF_AUX_STATE_TOPIC = "aux_state_topic"
@@ -255,6 +262,9 @@ def valid_humidity_state_configuration(config: ConfigType) -> ConfigType:
 
 _PLATFORM_SCHEMA_BASE = MQTT_BASE_SCHEMA.extend(
     {
+        # Options CONF_AUX_COMMAND_TOPIC, CONF_AUX_STATE_TOPIC
+        # and CONF_AUX_STATE_TEMPLATE were deprecated in HA Core 2023.9
+        # Support will be removed in HA Core 2024.3
         vol.Optional(CONF_AUX_COMMAND_TOPIC): valid_publish_topic,
         vol.Optional(CONF_AUX_STATE_TEMPLATE): cv.template,
         vol.Optional(CONF_AUX_STATE_TOPIC): valid_subscribe_topic,
@@ -353,6 +363,12 @@ PLATFORM_SCHEMA_MODERN = vol.All(
     # was removed in HA Core 2023.8
     cv.removed(CONF_POWER_STATE_TEMPLATE),
     cv.removed(CONF_POWER_STATE_TOPIC),
+    # Options CONF_AUX_COMMAND_TOPIC, CONF_AUX_STATE_TOPIC
+    # and CONF_AUX_STATE_TEMPLATE were deprecated in HA Core 2023.9
+    # Support will be removed in HA Core 2024.3
+    cv.deprecated(CONF_AUX_COMMAND_TOPIC),
+    cv.deprecated(CONF_AUX_STATE_TEMPLATE),
+    cv.deprecated(CONF_AUX_STATE_TOPIC),
     _PLATFORM_SCHEMA_BASE,
     valid_preset_mode_configuration,
     valid_humidity_range_configuration,
@@ -667,6 +683,9 @@ class MqttClimate(MqttTemperatureControlEntity, ClimateEntity):
             self._attr_swing_mode = SWING_OFF
         if self._topic[CONF_MODE_STATE_TOPIC] is None or self._optimistic:
             self._attr_hvac_mode = HVACMode.OFF
+        # Options CONF_AUX_COMMAND_TOPIC, CONF_AUX_STATE_TOPIC
+        # and CONF_AUX_STATE_TEMPLATE were deprecated in HA Core 2023.9
+        # Support will be removed in HA Core 2024.3
         if self._topic[CONF_AUX_STATE_TOPIC] is None or self._optimistic:
             self._attr_is_aux_heat = False
         self._feature_preset_mode = CONF_PRESET_MODE_COMMAND_TOPIC in config
@@ -738,12 +757,32 @@ class MqttClimate(MqttTemperatureControlEntity, ClimateEntity):
         if self._feature_preset_mode:
             support |= ClimateEntityFeature.PRESET_MODE
 
+        # Options CONF_AUX_COMMAND_TOPIC, CONF_AUX_STATE_TOPIC
+        # and CONF_AUX_STATE_TEMPLATE were deprecated in HA Core 2023.9
+        # Support will be removed in HA Core 2024.3
         if (self._topic[CONF_AUX_STATE_TOPIC] is not None) or (
             self._topic[CONF_AUX_COMMAND_TOPIC] is not None
         ):
             support |= ClimateEntityFeature.AUX_HEAT
         self._attr_supported_features = support
 
+    async def mqtt_async_added_to_hass(self) -> None:
+        """Handle deprecation issues."""
+        if self._attr_supported_features & ClimateEntityFeature.AUX_HEAT:
+            async_create_issue(
+                self.hass,
+                DOMAIN,
+                "deprecated_climate_aux_property_{self.entity_id}",
+                breaks_in_ha_version="2024.3.0",
+                is_fixable=False,
+                translation_key="deprecated_climate_aux_property",
+                translation_placeholders={
+                    "entity_id": self.entity_id,
+                },
+                learn_more_url=MQTT_CLIMATE_AUX_DOCS,
+                severity=IssueSeverity.WARNING,
+            )
+
     def _prepare_subscribe_topics(self) -> None:  # noqa: C901
         """(Re)Subscribe to topics."""
         topics: dict[str, dict[str, Any]] = {}
@@ -876,6 +915,9 @@ class MqttClimate(MqttTemperatureControlEntity, ClimateEntity):
 
             get_mqtt_data(self.hass).state_write_requests.write_state_request(self)
 
+        # Options CONF_AUX_COMMAND_TOPIC, CONF_AUX_STATE_TOPIC
+        # and CONF_AUX_STATE_TEMPLATE were deprecated in HA Core 2023.9
+        # Support will be removed in HA Core 2024.3
         @callback
         @log_messages(self.hass, self.entity_id)
         def handle_aux_mode_received(msg: ReceiveMessage) -> None:
@@ -986,6 +1028,9 @@ class MqttClimate(MqttTemperatureControlEntity, ClimateEntity):
 
             return
 
+    # Options CONF_AUX_COMMAND_TOPIC, CONF_AUX_STATE_TOPIC
+    # and CONF_AUX_STATE_TEMPLATE were deprecated in HA Core 2023.9
+    # Support will be removed in HA Core 2024.3
     async def _set_aux_heat(self, state: bool) -> None:
         await self._publish(
             CONF_AUX_COMMAND_TOPIC,

homeassistant/components/mqtt/strings.json

@@ -15,6 +15,10 @@
     "entity_name_startswith_device_name_yaml": {
       "title": "Manual configured MQTT entities with a name that starts with the device name",
       "description": "Some MQTT entities have an entity name that starts with the device name. This is not expected. To avoid a duplicate name the device name prefix is stripped off the entity name as a work-a-round. Please update your configuration and restart Home Assistant to fix this issue. \n\nList of affected entities:\n\n{config}"
+    },
+    "deprecated_climate_aux_property": {
+      "title": "MQTT entities with auxiliary heat support found",
+      "description": "Entity `{entity_id}` has auxiliary heat support enabled, which has been deprecated for MQTT climate devices. Please adjust your configuration and remove deperated config options from your configration and restart HA to fix this issue."
     }
   },
   "config": {

tests/components/mqtt/test_climate.py

@@ -70,7 +70,6 @@ from tests.typing import MqttMockHAClientGenerator, MqttMockPahoClient
 
 ENTITY_CLIMATE = "climate.test"
 
-
 DEFAULT_CONFIG = {
     mqtt.DOMAIN: {
         climate.DOMAIN: {
@@ -82,7 +81,6 @@ DEFAULT_CONFIG = {
             "temperature_high_command_topic": "temperature-high-topic",
             "fan_mode_command_topic": "fan-mode-topic",
             "swing_mode_command_topic": "swing-mode-topic",
-            "aux_command_topic": "aux-topic",
             "preset_mode_command_topic": "preset-mode-topic",
             "preset_modes": [
                 "eco",
@@ -225,7 +223,6 @@ async def test_supported_features(
         | ClimateEntityFeature.SWING_MODE
         | ClimateEntityFeature.FAN_MODE
         | ClimateEntityFeature.PRESET_MODE
-        | ClimateEntityFeature.AUX_HEAT
         | ClimateEntityFeature.TARGET_TEMPERATURE_RANGE
         | ClimateEntityFeature.TARGET_HUMIDITY
     )
@@ -1249,11 +1246,16 @@ async def test_set_preset_mode_pessimistic(
     assert state.attributes.get("preset_mode") == "home"
 
 
+# Options CONF_AUX_COMMAND_TOPIC, CONF_AUX_STATE_TOPIC
+# and CONF_AUX_STATE_TEMPLATE were deprecated in HA Core 2023.9
+# Support will be removed in HA Core 2024.3
 @pytest.mark.parametrize(
     "hass_config",
     [
         help_custom_config(
-            climate.DOMAIN, DEFAULT_CONFIG, ({"aux_state_topic": "aux-state"},)
+            climate.DOMAIN,
+            DEFAULT_CONFIG,
+            ({"aux_command_topic": "aux-topic", "aux_state_topic": "aux-state"},),
         )
     ],
 )
@@ -1283,7 +1285,18 @@ async def test_set_aux_pessimistic(
     assert state.attributes.get("aux_heat") == "off"
 
 
-@pytest.mark.parametrize("hass_config", [DEFAULT_CONFIG])
+# Options CONF_AUX_COMMAND_TOPIC, CONF_AUX_STATE_TOPIC
+# and CONF_AUX_STATE_TEMPLATE were deprecated in HA Core 2023.9
+# Support will be removed in HA Core 2024.3
+# "aux_command_topic": "aux-topic"
+@pytest.mark.parametrize(
+    "hass_config",
+    [
+        help_custom_config(
+            climate.DOMAIN, DEFAULT_CONFIG, ({"aux_command_topic": "aux-topic"},)
+        )
+    ],
+)
 async def test_set_aux(
     hass: HomeAssistant, mqtt_mock_entry: MqttMockHAClientGenerator
 ) -> None:
@@ -1303,6 +1316,18 @@ async def test_set_aux(
     state = hass.states.get(ENTITY_CLIMATE)
     assert state.attributes.get("aux_heat") == "off"
 
+    support = (
+        ClimateEntityFeature.TARGET_TEMPERATURE
+        | ClimateEntityFeature.AUX_HEAT
+        | ClimateEntityFeature.SWING_MODE
+        | ClimateEntityFeature.FAN_MODE
+        | ClimateEntityFeature.PRESET_MODE
+        | ClimateEntityFeature.TARGET_TEMPERATURE_RANGE
+        | ClimateEntityFeature.TARGET_HUMIDITY
+    )
+
+    assert state.attributes.get("supported_features") == support
+
 
 @pytest.mark.parametrize("hass_config", [DEFAULT_CONFIG])
 async def test_availability_when_connection_lost(
@@ -1548,6 +1573,10 @@ async def test_get_with_templates(
     assert state.attributes.get("preset_mode") == "eco"
 
     # Aux mode
+
+    # Options CONF_AUX_COMMAND_TOPIC, CONF_AUX_STATE_TOPIC
+    # and CONF_AUX_STATE_TEMPLATE were deprecated in HA Core 2023.9
+    # Support will be removed in HA Core 2024.3
     assert state.attributes.get("aux_heat") == "off"
     async_fire_mqtt_message(hass, "aux-state", "switchmeon")
     state = hass.states.get(ENTITY_CLIMATE)