Rework AIComfort as an HVACMode.AUTO + preset overlay, add unmapped-mode warning (issue #93)

AIComfort isn't a distinct thermodynamic operation like Cool/Dry/Heat --
it's an AI-driven overlay on top of the device's own 'Auto' behavior,
confirmed by A-CAWW-TP2-20-COMMON reporting both 'Auto' and 'AIComfort'
as separate, mutually-exclusive entries in /mode/vs/0's supportedModes.
Modeled the idiomatic HA way instead of a flat _DEVICE_TO_HVAC entry:
hvac_mode reports AUTO and a new 'ai_comfort' preset carries the
distinction. Entered/left only via the preset (writes the primary mode
resource, not the convenient one) -- there's no dedicated HVACMode
value for it, so it's not offered in the hvac_mode dropdown directly.

Also adds a once-per-(href, code) warning log when a device-reported
mode has no entry in the relevant map, so a future gap like this one
surfaces in the log instead of silently vanishing -- the exact failure
mode issue #93 called out ("this class of gap is invisible without
diffing against supportedModes").

custom_components/localthings/climate.py

@@ -20,6 +20,8 @@ back for, power, mode, temperature and wind resources alike.
 """
 from __future__ import annotations
 
+import logging
+
 from homeassistant.components.climate import (
     ClimateEntity,
     ClimateEntityFeature,
@@ -53,6 +55,8 @@ from .const import DOMAIN
 from .coordinator import LocalThingsCoordinator
 from .entity import LocalThingsEntity, _is_included
 
+_LOGGER = logging.getLogger(__name__)
+
 _MODES_FIELD = 'x.com.samsung.da.modes'
 _SUPPORTED_FIELD = 'x.com.samsung.da.supportedModes'
 
@@ -68,6 +72,19 @@ _DEVICE_TO_HVAC: dict[str, HVACMode] = {
 }
 _HVAC_TO_DEVICE = {v: k for k, v in _DEVICE_TO_HVAC.items()}
 
+# AI-driven auto-comfort mode (issue #93, A-CAWW-TP2-20-COMMON). Not a flat
+# _DEVICE_TO_HVAC entry: 'AIComfort' isn't a distinct thermodynamic operation
+# like Cool/Dry/Heat, it's an AI overlay on top of the device's own 'Auto'
+# behavior -- confirmed by this unit reporting both 'Auto' and 'AIComfort' as
+# separate, mutually-exclusive entries in /mode/vs/0's supportedModes. Modeled
+# the idiomatic HA way instead: hvac_mode reports AUTO (same as plain 'Auto'
+# would if it were ever mapped there) and a dedicated 'ai_comfort' preset
+# carries the distinction a bare hvac_mode can't. Not reachable via
+# async_set_hvac_mode -- entered/left only through the preset, since there's
+# no dedicated HVACMode value for it to write back to.
+_AI_COMFORT_MODE = 'AIComfort'
+PRESET_AI_COMFORT = 'ai_comfort'
+
 # Fan (wind strength): device codes "0".."4" -> HA standard fan constants where
 # a clean match exists so they auto-localize; "turbo" is custom (translated).
 _DEVICE_TO_FAN: dict[str, str] = {
@@ -164,6 +181,11 @@ class LocalThingsClimate(LocalThingsEntity, ClimateEntity):
             | ClimateEntityFeature.TURN_ON
             | ClimateEntityFeature.TURN_OFF
         )
+        # (href, raw device code) pairs already logged by _warn_unmapped --
+        # these properties are read on every coordinator refresh, so an
+        # un-deduped warning would spam the log for any device with a
+        # genuinely unrecognized code.
+        self._warned_unmapped: set[tuple[str, str]] = set()
 
     # -- resource helpers ---------------------------------------------------
 
@@ -180,13 +202,34 @@ class LocalThingsClimate(LocalThingsEntity, ClimateEntity):
     def _supported(self, href: str) -> list[str]:
         return list(self._rep(href).get(_SUPPORTED_FIELD) or [])
 
+    def _warn_unmapped(self, href: str, code: str) -> None:
+        """Log once per (href, code) when a device-reported mode has no
+        entry in the relevant device<->HA map, so a real device gap surfaces
+        in the log instead of silently vanishing (issue #93)."""
+        key = (href, code)
+        if key in self._warned_unmapped:
+            return
+        self._warned_unmapped.add(key)
+        _LOGGER.warning(
+            "%s: device mode %r on %s has no HA mapping and was dropped; "
+            "please file an issue with your diagnostics dump",
+            self.entity_id, code, href,
+        )
+
     def _read_mode(self, href: str, mapping: dict):
         """Current mode of a wind/convenient resource, mapped to its HA value."""
-        return mapping.get(_first(self._rep(href).get(_MODES_FIELD)))
+        raw = _first(self._rep(href).get(_MODES_FIELD))
+        if raw is not None and raw not in mapping:
+            self._warn_unmapped(href, raw)
+        return mapping.get(raw)
 
     def _read_modes(self, href: str, mapping: dict) -> list[str]:
         """Supported modes of a resource, mapped to HA values (unknowns dropped)."""
-        return [mapping[c] for c in self._supported(href) if c in mapping]
+        supported = self._supported(href)
+        for c in supported:
+            if c not in mapping:
+                self._warn_unmapped(href, c)
+        return [mapping[c] for c in supported if c in mapping]
 
     # -- temperature --------------------------------------------------------
 
@@ -250,14 +293,23 @@ class LocalThingsClimate(LocalThingsEntity, ClimateEntity):
         if not self._is_on():
             return HVACMode.OFF
         device = _first(self._rep(MODE_HREF).get(_MODES_FIELD))
+        if device == _AI_COMFORT_MODE:
+            return HVACMode.AUTO
+        if device is not None and device not in _DEVICE_TO_HVAC:
+            self._warn_unmapped(MODE_HREF, device)
         return _DEVICE_TO_HVAC.get(device, HVACMode.AUTO)
 
     @property
     def hvac_modes(self) -> list[HVACMode]:
         modes = [HVACMode.OFF]
         for m in self._supported(MODE_HREF):
+            if m == _AI_COMFORT_MODE:
+                continue
             mapped = _DEVICE_TO_HVAC.get(m)
-            if mapped is not None and mapped not in modes:
+            if mapped is None:
+                self._warn_unmapped(MODE_HREF, m)
+                continue
+            if mapped not in modes:
                 modes.append(mapped)
         return modes
 
@@ -281,11 +333,16 @@ class LocalThingsClimate(LocalThingsEntity, ClimateEntity):
 
     @property
     def preset_mode(self):
+        if _first(self._rep(MODE_HREF).get(_MODES_FIELD)) == _AI_COMFORT_MODE:
+            return PRESET_AI_COMFORT
         return self._read_mode(CONVENIENT_HREF, _DEVICE_TO_PRESET)
 
     @property
     def preset_modes(self) -> list[str]:
-        return self._read_modes(CONVENIENT_HREF, _DEVICE_TO_PRESET)
+        modes = self._read_modes(CONVENIENT_HREF, _DEVICE_TO_PRESET)
+        if _AI_COMFORT_MODE in self._supported(MODE_HREF):
+            modes.append(PRESET_AI_COMFORT)
+        return modes
 
     # -- writes -------------------------------------------------------------
 
@@ -324,4 +381,10 @@ class LocalThingsClimate(LocalThingsEntity, ClimateEntity):
         await self._set_mapped('swing', _SWING_TO_DEVICE, swing_mode)
 
     async def async_set_preset_mode(self, preset_mode: str) -> None:
+        if preset_mode == PRESET_AI_COMFORT:
+            # Writes the primary mode resource, not the convenient one --
+            # 'AIComfort' lives in /mode/vs/0 alongside Cool/Dry/Auto, not in
+            # /mode/convenient/vs/0 with Quiet/Smart/Speed/Sleep.
+            await self.coordinator.async_send_command(self._bound, ('mode', _AI_COMFORT_MODE))
+            return
         await self._set_mapped('preset', _PRESET_TO_DEVICE, preset_mode)

custom_components/localthings/registry/capabilities/common.py

@@ -237,33 +237,32 @@ _DEAD_INSTANTANEOUS_POWER = '-500'
 ENERGY_METER = Capability(
     href='/energy/consumption/vs/0',
     entities=(
-        # No `not rep` stub carve-out (issue #78: a fridge whose
-        # /energy/consumption/vs/0 is permanently {} -- it just doesn't
-        # report energy data -- got all five sensors created anyway and
-        # stuck at "Unknown" forever, since an empty {} rep and a
-        # not-yet-fetched stub are indistinguishable from content alone).
-        # Same tradeoff AI_ENERGY_LEVEL below already makes deliberately:
-        # an entity that's unlucky on first-poll timing stays absent until
-        # a reload sees real data, rather than every genuinely-unsupported
-        # resource showing a permanent phantom sensor.
+        # `not rep` keeps the empty-{} stub carve-out (see entity._is_included):
+        # an explicit exists_fn otherwise bypasses it, which would drop the
+        # entity when /device/0 returns a not-yet-fetched stub. On a populated
+        # rep, hide power only for the dead sentinel or an absent field.
         SensorDesc(key='power_watts', field='x.com.samsung.da.instantaneousPower',
                    device_class='power', state_class='measurement',
                    unit='W', value_fn=clamp_power,
-                   exists_fn=lambda rep, resources: (
+                   exists_fn=lambda rep, resources: not rep or (
                        rep.get('x.com.samsung.da.instantaneousPower')
                        not in (None, _DEAD_INSTANTANEOUS_POWER))),
         SensorDesc(key='energy_kwh', field='x.com.samsung.da.cumulativePower',
                    device_class='energy',
                    state_class='total_increasing', unit='kWh', value_fn=wh_to_kwh,
-                   exists_fn=lambda rep, resources: 'x.com.samsung.da.cumulativePower' in rep),
+                   exists_fn=lambda rep, resources: (
+                       not rep or 'x.com.samsung.da.cumulativePower' in rep)),
         # cumulativeConsumption is a second, independently-varying running
         # total alongside cumulativePower -- some fridges (issue #26) report
-        # both. Self-gates off where only cumulativePower is present.
+        # both. Self-gates off where only cumulativePower is present. `not
+        # rep or` keeps the same empty-{} stub carve-out as power_watts/
+        # energy_kwh above -- without it, an exists_fn permanently drops the
+        # entity if setup happens to land on a not-yet-fetched stub.
         SensorDesc(key='power_energy_kwh', field='x.com.samsung.da.cumulativeConsumption',
                    device_class='energy',
                    state_class='total_increasing', unit='kWh', value_fn=wh_to_kwh,
                    exists_fn=lambda rep, resources: (
-                       'x.com.samsung.da.cumulativeConsumption' in rep)),
+                       not rep or 'x.com.samsung.da.cumulativeConsumption' in rep)),
         # AI Energy Mode's lifetime savings estimate vs. an unoptimized
         # baseline -- present on some models (e.g. TP1X_REF_21K, issue #21/
         # #27) and absent on others (issue #20/#26), unlike cumulativePower.
@@ -271,7 +270,7 @@ ENERGY_METER = Capability(
                    device_class='energy',
                    state_class='total_increasing', unit='kWh', value_fn=wh_to_kwh,
                    exists_fn=lambda rep, resources: (
-                       'x.com.samsung.da.cumulativeSavedPower' in rep)),
+                       not rep or 'x.com.samsung.da.cumulativeSavedPower' in rep)),
         # Monthly billing-cycle totals -- the completed prior month and the
         # in-progress current month. Not ever-increasing (each resets at
         # month boundary), so no state_class.
@@ -279,12 +278,12 @@ ENERGY_METER = Capability(
                    device_class='energy',
                    unit='kWh', value_fn=wh_to_kwh,
                    exists_fn=lambda rep, resources: (
-                       'x.com.samsung.da.monthlyConsumption' in rep)),
+                       not rep or 'x.com.samsung.da.monthlyConsumption' in rep)),
         SensorDesc(key='energy_this_month_kwh', field='x.com.samsung.da.thismonthlyConsumption',
                    device_class='energy',
                    unit='kWh', value_fn=wh_to_kwh,
                    exists_fn=lambda rep, resources: (
-                       'x.com.samsung.da.thismonthlyConsumption' in rep)),
+                       not rep or 'x.com.samsung.da.thismonthlyConsumption' in rep)),
     ),
 )
 
@@ -415,12 +414,12 @@ SELF_CHECK = Capability(
                    icon='mdi:clipboard-check-outline',
                    entity_category='diagnostic'),
         # List of error codes from the last self-check; joined for display.
-        # Not every fridge reports the field, hence the exists_fn (no stub
-        # carve-out -- see ENERGY_METER above).
+        # Not every fridge reports the field, hence the exists_fn.
         SensorDesc(key='selfcheck_error', field='x.com.samsung.da.error',
                    icon='mdi:alert-circle-outline',
                    entity_category='diagnostic',
-                   exists_fn=lambda rep, resources: 'x.com.samsung.da.error' in rep,
+                   exists_fn=lambda rep, resources: (
+                       not rep or 'x.com.samsung.da.error' in rep),
                    value_fn=lambda v: (', '.join(v) if v else None) if isinstance(v, list) else v),
         ButtonDesc(key='selfcheck_start', field='', payload='Start',
                    icon='mdi:play-circle-outline',

custom_components/localthings/registry/capabilities/cooktop.py

@@ -97,7 +97,7 @@ COOKTOP_MODE = Capability(
                     options, f'OperationState{slot}'
                 ),
                 exists_fn=lambda rep, resources, slot=slot: (
-                    _option_value(
+                    not rep or _option_value(
                         rep.get('x.com.samsung.da.options'),
                         f'OperationState{slot}',
                     ) is not None

custom_components/localthings/translations/en.json

@@ -95,6 +95,7 @@
           },
           "preset_mode": {
             "state": {
+              "ai_comfort": "AI Comfort",
               "quiet": "Quiet",
               "smart": "Smart",
               "speed": "Speed"

custom_components/localthings/translations/nl.json

@@ -95,6 +95,7 @@
           },
           "preset_mode": {
             "state": {
+              "ai_comfort": "AI-comfort",
               "quiet": "Stil",
               "smart": "Slim",
               "speed": "Snel"

tests/fixtures/golden/air_purifier.json

@@ -6,13 +6,19 @@
     "diagnosis_status",
     "display_light",
     "dust",
+    "energy_kwh",
+    "energy_last_month_kwh",
+    "energy_saved_kwh",
+    "energy_this_month_kwh",
     "fan_direction",
     "fan_speed_level",
     "filter_progress",
     "fine_dust",
     "odor",
     "operating_mode",
+    "power_energy_kwh",
     "power_switch",
+    "power_watts",
     "super_fine_dust"
   ]
 }

tests/test_climate_ac_modes.py

@@ -0,0 +1,40 @@
+"""Tests for the AC HVAC-mode/preset device<->HA maps in climate.py (issue #93).
+
+Module-level dicts/constants with no coordinator/entity dependency, so --
+like `_temps_vs_item` in test_climate_temperature_fallback.py -- they're
+testable directly.
+"""
+from homeassistant.components.climate import HVACMode
+
+from custom_components.localthings.climate import (
+    _AI_COMFORT_MODE, _DEVICE_TO_HVAC, _HVAC_TO_DEVICE, PRESET_AI_COMFORT,
+)
+
+
+def test_auto_still_maps_to_heat_cool():
+    """'Auto' is unchanged -- AIComfort is handled separately, not folded
+    into this map."""
+    assert _DEVICE_TO_HVAC['Auto'] == HVACMode.HEAT_COOL
+
+
+def test_aicomfort_not_in_flat_hvac_map():
+    """AIComfort isn't a flat _DEVICE_TO_HVAC entry -- it's an AI overlay on
+    top of 'Auto', modeled as hvac_mode=AUTO + a dedicated preset instead of
+    a distinct HVACMode value (see the climate.py module comment)."""
+    assert _AI_COMFORT_MODE not in _DEVICE_TO_HVAC
+
+
+def test_hvac_auto_not_writable_via_hvac_mode():
+    """HVACMode.AUTO has no _DEVICE_TO_HVAC entry, so it's unreachable via
+    async_set_hvac_mode -- entered/left only through the ai_comfort preset."""
+    assert HVACMode.AUTO not in _HVAC_TO_DEVICE
+
+
+def test_fan_only_still_reachable_via_wind():
+    """Guard against regressing the existing 'Wind' -> FAN_ONLY entry while
+    editing this map."""
+    assert _DEVICE_TO_HVAC['Wind'] == HVACMode.FAN_ONLY
+
+
+def test_preset_ai_comfort_constant():
+    assert PRESET_AI_COMFORT == 'ai_comfort'

tests/test_common_capabilities.py

@@ -156,17 +156,13 @@ class TestEnergyMeter:
         kwh = next(e for e in common.ENERGY_METER.entities if e.key == 'energy_kwh')
         assert kwh.exists_fn({'x.com.samsung.da.cumulativePower': '58900'}, {}) is True
 
-    def test_both_entities_hidden_on_empty_rep(self):
-        """Issue #78: a permanently-{} rep (a fridge that just doesn't report
-        energy data) must not spawn a phantom sensor stuck at "Unknown"
-        forever -- an empty {} rep and a not-yet-fetched stub are
-        indistinguishable from content alone, so this deliberately drops the
-        old stub carve-out (same tradeoff AI_ENERGY_LEVEL already makes,
-        see TestAiEnergyLevelStubDoesNotDecideThePlatform)."""
+    def test_both_entities_included_on_empty_stub(self):
+        """An empty {} rep means the resource exists but data isn't fetched yet
+        (see entity._is_included) -- include both so sub-polls populate them."""
         pw = next(e for e in common.ENERGY_METER.entities if e.key == 'power_watts')
         kwh = next(e for e in common.ENERGY_METER.entities if e.key == 'energy_kwh')
-        assert pw.exists_fn({}, {}) is False
-        assert kwh.exists_fn({}, {}) is False
+        assert pw.exists_fn({}, {}) is True
+        assert kwh.exists_fn({}, {}) is True
 
     def test_power_watts_hidden_when_field_absent_in_populated_rep(self):
         """A populated rep that lacks instantaneousPower must not spawn a
@@ -323,11 +319,11 @@ class TestSelfCheckError:
         desc = self._desc()
         assert desc.exists_fn({'x.com.samsung.da.status': 'Ready'}, {}) is False
 
-    def test_hidden_for_empty_rep(self):
-        """Issue #78: no stub carve-out -- see ENERGY_METER's
-        test_both_entities_hidden_on_empty_rep for why."""
+    def test_exists_for_empty_stub_rep(self):
+        """An empty {} rep is /device/0's not-yet-fetched-stub carve-out --
+        must be included-for-now, same as ENERGY_METER's fields."""
         desc = self._desc()
-        assert desc.exists_fn({}, {}) is False
+        assert desc.exists_fn({}, {}) is True
 
     def test_value_joins_list(self):
         desc = self._desc()