Merge remote-tracking branch 'upstream/main' into contrib/cooktop-range-hood

# Conflicts:
#	custom_components/localthings/coordinator.py
#	custom_components/localthings/registry/by_type/__init__.py

custom_components/localthings/coordinator.py

@@ -22,6 +22,7 @@ from smartthings_local.ocf.state_cache import StateCache
 
 from .registry.batch import parse_device0_batch
 from .registry.by_type import for_device, for_device_by_model, for_device_by_resources
+from .registry.capabilities.common import remote_control_enabled
 from .registry.discovery import discover, BoundEntity
 from .registry import CAPABILITIES
 from .registry.adapter import flatten
@@ -37,6 +38,12 @@ _LOGGER = logging.getLogger(__name__)
 
 _SEED_PATH = ['device', '0']
 
+_REMOTE_CONTROL_DISABLED_MESSAGE = (
+    "Remote control is turned off on this device. Check your appliance's "
+    "manual for how to enable remote control before Home Assistant can "
+    "control it."
+)
+
 
 class _NoOpDescriptor:
     """StateCache requires a descriptor with an on_observation hook. This
@@ -517,16 +524,21 @@ class LocalThingsCoordinator(DataUpdateCoordinator[dict[str, Any]]):
         A description-level validate_fn (currently SwitchDesc only) runs
         here rather than per-platform, so rejecting a write with a
         user-facing message -- as opposed to write_fn's silent no-op below
-        -- is available to every platform for free."""
+        -- is available to every platform for free. The remote-control
+        check runs first and applies to every platform unconditionally,
+        ahead of any description-specific validate_fn."""
         desc = bound_entity.desc
         write_fn = getattr(desc, 'write_fn', None)
         if write_fn is None:
             return
         href = bound_entity.href
         rep = self._cache.get(href or '') or {}
+        resources = self._cache.snapshot()
+        if not remote_control_enabled(resources):
+            raise ServiceValidationError(_REMOTE_CONTROL_DISABLED_MESSAGE)
         validate_fn = getattr(desc, 'validate_fn', None)
         if validate_fn is not None:
-            error = validate_fn(payload, rep, self._cache.snapshot())
+            error = validate_fn(payload, rep, resources)
             if error:
                 raise ServiceValidationError(error)
         result = write_fn(payload, rep, href)

custom_components/localthings/manifest.json

@@ -12,5 +12,5 @@
     "pyOpenSSL>=23.0",
     "smartthings-local>=0.1.0"
   ],
-  "version": "0.9.0"
+  "version": "0.10.0"
 }

custom_components/localthings/number.py

@@ -58,6 +58,9 @@ class LocalThingsNumber(LocalThingsEntity, NumberEntity):
 
     @property
     def native_min_value(self) -> float:
+        desc: NumberDesc = self._bound.desc
+        if desc.native_min_fn is not None:
+            return desc.native_min_fn(self.coordinator.resource(self._bound.href))
         r = self._range_from_resource()
         if r is not None:
             return float(r[0])
@@ -67,6 +70,9 @@ class LocalThingsNumber(LocalThingsEntity, NumberEntity):
 
     @property
     def native_max_value(self) -> float:
+        desc: NumberDesc = self._bound.desc
+        if desc.native_max_fn is not None:
+            return desc.native_max_fn(self.coordinator.resource(self._bound.href))
         r = self._range_from_resource()
         if r is not None:
             return float(r[1])
@@ -74,6 +80,15 @@ class LocalThingsNumber(LocalThingsEntity, NumberEntity):
             return self._attr_native_max_value
         return super().native_max_value
 
+    @property
+    def native_step(self) -> float:
+        desc: NumberDesc = self._bound.desc
+        if desc.step_fn is not None:
+            return desc.step_fn(self.coordinator.resource(self._bound.href))
+        if hasattr(self, '_attr_native_step'):
+            return self._attr_native_step
+        return super().native_step
+
     @property
     def native_value(self):
         return (self.coordinator.data or {}).get(self._state_key)

custom_components/localthings/registry/by_type/__init__.py

@@ -3,8 +3,8 @@ from typing import Optional
 
 from ._base import DeviceRegistry
 from . import (
-    airconditioner, cooktop, dishwasher, dryer, oven, range_hood, refrigerator,
-    washer,
+    airconditioner, cooktop, dishwasher, dryer, oven, range as _range,
+    range_hood, refrigerator, washer,
 )
 
 __all__ = [
@@ -21,6 +21,7 @@ _REGISTRY_BY_KEY: dict[str, DeviceRegistry] = {
     'dryer': dryer.REGISTRY,
     'oven': oven.REGISTRY,
     'hood': range_hood.REGISTRY,
+    'range': _range.REGISTRY,
     'range_hood': range_hood.REGISTRY,
     'refrigerator': refrigerator.REGISTRY,
     'washer': washer.REGISTRY,
@@ -115,6 +116,11 @@ def for_device_by_model(model_num: str, description: str) -> Optional[DeviceRegi
         key = 'cooktop'
     if key is None and model_identity.startswith('AHD-'):
         key = 'range_hood'
+    # Range/cooktop-oven combos (e.g. TP1X_DA-KS-RANGE-0102X, issue #44) --
+    # like the RAC/PRAC air conditioners above, these report no oneUiVersion
+    # and don't match the washer/dryer/dishwasher consumer-prefix map either.
+    if key is None and '-RANGE-' in (model_num or '').upper():
+        key = 'range'
     return _REGISTRY_BY_KEY.get(key) if key else None
 
 

custom_components/localthings/registry/by_type/oven.py

@@ -14,5 +14,6 @@ REGISTRY = DeviceRegistry(
         oven.OVEN_OPERATIONAL_STATE,
         oven.OVEN_DOOR,
         oven.OVEN_CONNECTED,
+        oven.OVEN_SPEC,
     ]),
 )

custom_components/localthings/registry/by_type/range.py

@@ -0,0 +1,29 @@
+"""Range (oven + cooktop combo) device registry — issue #44.
+
+Reuses the oven family's cavity/setpoint/mode/operational-state/door/
+connected capabilities wholesale (a range's oven half is the same OCF
+surface as a standalone oven) and adds the cooktop-specific capabilities
+for the burner half.
+"""
+from ..capabilities import common, ignored, oven
+from ..capabilities import range as range_caps
+from ._base import DeviceRegistry, _build
+
+REGISTRY = DeviceRegistry(
+    name='range',
+    capabilities=_build([
+        *ignored.IGNORED,
+        *common.UNIVERSAL,
+        *common.POWER,
+        oven.OVEN_CAVITY,
+        oven.OVEN_SETPOINT,
+        oven.OVEN_MODE,
+        oven.OVEN_OPERATIONAL_STATE,
+        oven.OVEN_DOOR,
+        oven.OVEN_CONNECTED,
+        oven.OVEN_SPEC,
+        range_caps.COOKTOP_STATUS,
+        range_caps.COOKTOP_SPEC,
+        range_caps.COOKTOP_SAFETY,
+    ]),
+)

custom_components/localthings/registry/capabilities/common.py

@@ -119,8 +119,30 @@ KIDS_LOCK_VS_FALLBACK = Capability(
     ),
 )
 
+
+def remote_control_enabled(resources: dict) -> bool:
+    """Single source of truth for the /remotectrl on/off signal, mirroring
+    REMOTE_CONTROL_GENERIC/_VS_FALLBACK's href/field pair and precedence
+    below. Used both to render the read-only Smart Control binary_sensor
+    (via those two descriptors) and, from coordinator.async_send_command,
+    to block writes outright when remote control is off. Both hrefs are
+    poll_tier='warm' below so that gate reads recent state (subscribed
+    when observe is live, subpolled every ~6s otherwise) rather than a
+    once-per-30s cold summary poll. True (assume enabled) when neither
+    href is present -- most device types don't report this capability
+    at all."""
+    generic = resources.get('/remotectrl/0')
+    if generic is not None:
+        return bool(generic.get('value'))
+    fallback = resources.get('/remotectrl/vs/0')
+    if fallback is not None:
+        return str(fallback.get('x.com.samsung.da.remoteControlEnabled')).lower() == 'true'
+    return True
+
+
 REMOTE_CONTROL_GENERIC = Capability(
     href='/remotectrl/0',
+    poll_tier='warm',
     entities=(
         BinarySensorDesc(key='remote_control', field='value',
                          name='Smart Control', device_class='connectivity',
@@ -131,6 +153,7 @@ REMOTE_CONTROL_GENERIC = Capability(
 REMOTE_CONTROL_VS_FALLBACK = Capability(
     href='/remotectrl/vs/0',
     match_fn=lambda rep, resources: '/remotectrl/0' not in resources,
+    poll_tier='warm',
     entities=(
         BinarySensorDesc(key='remote_control',
                          field='x.com.samsung.da.remoteControlEnabled',

custom_components/localthings/registry/capabilities/oven.py

@@ -39,6 +39,15 @@ SETPOINT_MIN_C = 30
 SETPOINT_MAX_C = 270
 SETPOINT_STEP_C = 5
 
+# Verified against issue #44's range dump (NSI6DG9100SRAA, unit reported as
+# "Fahrenheit" on /temperatures/vs/0): Bake mode's modeSpec on /mode/vs/0
+# reports tempMinF/tempMaxF/tempIntervalF = 175/550/5. Kept as a separate
+# constant set rather than converted from the Celsius bounds above, which
+# are themselves unverified (no live dump; see module docstring).
+SETPOINT_MIN_F = 175
+SETPOINT_MAX_F = 550
+SETPOINT_STEP_F = 5
+
 # Mode options seen on NV7000BS-class. No dump exists so this list is inferred
 # from Samsung documentation and firmware observations. The firmware will
 # reject unknown modes; missing entries here are a coverage gap, not a bug.
@@ -129,8 +138,9 @@ def _oven_setpoint_write(p, rep, href=None):
         temp = float(p)
     except (TypeError, ValueError):
         return None
-    temp_i = int(round(temp / SETPOINT_STEP_C) * SETPOINT_STEP_C)
-    if not (SETPOINT_MIN_C <= temp_i <= SETPOINT_MAX_C):
+    min_v, max_v, step_v = _setpoint_bounds(rep)
+    temp_i = int(round(temp / step_v) * step_v)
+    if not (min_v <= temp_i <= max_v):
         return None
     items = rep.get('x.com.samsung.da.items')
     if not items:
@@ -263,14 +273,24 @@ def _oven_temp_unit(rep):
     same aggregate `/temperatures/vs/0` items[] resource type, which on
     fridge hardware carries a per-item `x.com.samsung.da.unit` field
     ('Celsius'/'Fahrenheit') that was previously hardcoded away (issue #7).
-    No live oven dump has surfaced a non-Celsius reading yet, so this keeps
-    the verified '°C' default when the field is absent, but reads it live
-    if a device ever reports otherwise."""
+    Keeps the verified '°C' default when the field is absent (the original
+    NV7000BS-class dump this module was written against), but reads it live
+    -- issue #44's range dump is the first to report 'Fahrenheit' here."""
     items = rep.get('x.com.samsung.da.items') or []
     unit = items[0].get('x.com.samsung.da.unit') if items else None
     return normalize_temp_unit(unit, default='°C')
 
 
+def _setpoint_bounds(rep):
+    """(min, max, step) for the live unit -- see the SETPOINT_*_C/_F
+    constants above for provenance. Bounds must track the unit shown by
+    unit_fn (both read the same live rep), or the HA slider's range would
+    silently mismatch its own displayed unit."""
+    if _oven_temp_unit(rep) == '°F':
+        return SETPOINT_MIN_F, SETPOINT_MAX_F, SETPOINT_STEP_F
+    return SETPOINT_MIN_C, SETPOINT_MAX_C, SETPOINT_STEP_C
+
+
 OVEN_SETPOINT = Capability(
     href='/temperatures/vs/0',
     poll_tier='hot',
@@ -280,6 +300,9 @@ OVEN_SETPOINT = Capability(
                    name='Setpoint', device_class='temperature', unit_fn=_oven_temp_unit,
                    native_min=float(SETPOINT_MIN_C), native_max=float(SETPOINT_MAX_C),
                    step=float(SETPOINT_STEP_C), icon='mdi:thermometer-chevron-up',
+                   native_min_fn=lambda rep: float(_setpoint_bounds(rep)[0]),
+                   native_max_fn=lambda rep: float(_setpoint_bounds(rep)[1]),
+                   step_fn=lambda rep: float(_setpoint_bounds(rep)[2]),
                    value_fn=lambda items: _int(
                        (items[0].get('x.com.samsung.da.desired') if items else None)),
                    write_fn=_oven_setpoint_write),
@@ -314,6 +337,13 @@ OVEN_CONNECTED = Capability(
     ),
 )
 
+# Static cavity capability metadata (count/type/supported features) -- no
+# per-cavity data varies at runtime on any dump seen so far (issue #44's
+# range: single cavity, no supportedFeatureList entries). Bound with no
+# entities purely for coverage; revisit if a multi-cavity dump surfaces
+# fields worth exposing.
+OVEN_SPEC = Capability(href='/oven/spec/vs/0')
+
 OVEN_MODE = Capability(
     href='/mode/vs/0',
     poll_tier='warm',

custom_components/localthings/registry/capabilities/range.py

@@ -0,0 +1,130 @@
+"""Capabilities for the cooktop half of range/combo appliances (issue #44,
+model TP1X_DA-KS-RANGE-0102X).
+
+Not to be confused with PR #23's registry/capabilities/cooktop.py, which
+covers an unrelated standalone-cooktop product (NA9300K-class) that encodes
+burner state as strings inside /mode/vs/0's options array instead of the
+structured /cooktop/status/vs/0 resource this module reads -- two different
+OCF surfaces that happen to share the English word "cooktop".
+
+Unlike the rest of the OCF surface, these hrefs use plain camelCase field
+names (no `x.com.samsung.da.` prefix) -- `/cooktop/status/vs/0` already
+looks like a vendor resource migrated onto OCF-standard-shaped field naming.
+
+`/cooktop/status/vs/0` carries every burner's live state in one `burnerList`
+array (indexed by `burnerNumber`, not by a separate href per burner like
+fridge ice makers), so per-burner entities are hardcoded up to MAX_BURNERS
+and gated by exists_fn against whichever indices the device actually
+reports -- harmless over-declaration, per common.py's UNIVERSAL note, since
+an index absent from burnerList just never binds.
+
+Write surfaces here are unproven (no live device to verify against, same
+caveat as oven.py's RMW writes) -- power level uses the same read-modify-
+write pattern already proven safe elsewhere in this codebase (oven setpoint,
+icemaker toggles).
+"""
+from ..capability import Capability
+from ..entities import BinarySensorDesc, SelectDesc, SensorDesc
+
+# Observed as high as 4 (this issue's dump); user-reported hardware with 5
+# burners exists. Kept a little above both since exists_fn gates unused
+# slots out -- see module docstring.
+MAX_BURNERS = 6
+
+
+def _burner(burner_list, i):
+    for b in (burner_list or []):
+        if b.get('burnerNumber') == i:
+            return b
+    return None
+
+
+def _burner_exists(i):
+    return lambda rep, resources: _burner(rep.get('burnerList'), i) is not None
+
+
+def _burner_field_fn(i, field):
+    return lambda burner_list: (_burner(burner_list, i) or {}).get(field)
+
+
+def _burner_hot_surface_fn(i):
+    get_state = _burner_field_fn(i, 'hotSurfaceState')
+    return lambda burner_list: get_state(burner_list) not in (None, 'normal')
+
+
+def _power_level_options(resources):
+    spec = resources.get('/cooktop/spec/vs/0') or {}
+    return list(spec.get('supportedPowerLevelList') or [])
+
+
+def _burner_power_level_write(i):
+    def write(p, rep, href=None):
+        burner_list = rep.get('burnerList')
+        if not burner_list:
+            return None
+        new_list = []
+        found = False
+        for b in burner_list:
+            if b.get('burnerNumber') == i:
+                b = dict(b)
+                b['powerLevel'] = p
+                found = True
+            new_list.append(b)
+        if not found:
+            return None
+        return ['cooktop', 'status', 'vs', '0'], {'burnerList': new_list}
+    return write
+
+
+def _burner_entities(i):
+    exists = _burner_exists(i)
+    n = i + 1
+    return (
+        SelectDesc(key=f'burner_{i}_power_level', field='burnerList',
+                   name=f'Burner {n} power level', icon='mdi:knob',
+                   options=_power_level_options,
+                   exists_fn=exists,
+                   value_fn=_burner_field_fn(i, 'powerLevel'),
+                   write_fn=_burner_power_level_write(i)),
+        SensorDesc(key=f'burner_{i}_state', field='burnerList',
+                   name=f'Burner {n} state', icon='mdi:stove',
+                   exists_fn=exists,
+                   value_fn=_burner_field_fn(i, 'operationState')),
+        BinarySensorDesc(key=f'burner_{i}_hot_surface', field='burnerList',
+                         name=f'Burner {n} hot surface', device_class='heat',
+                         exists_fn=exists,
+                         value_fn=_burner_hot_surface_fn(i)),
+    )
+
+
+COOKTOP_STATUS = Capability(
+    href='/cooktop/status/vs/0',
+    poll_tier='hot',
+    entities=(
+        SensorDesc(key='cooktop_state', field='operationState',
+                   name='Cooktop state', icon='mdi:pot-steam'),
+        *[e for i in range(MAX_BURNERS) for e in _burner_entities(i)],
+    ),
+)
+
+# Static burner-count/power-level-list metadata, read directly by
+# COOKTOP_STATUS's power-level select (options=_power_level_options) rather
+# than exposed through its own entity -- same "informs another capability,
+# no entity of its own" pattern as /wm/editcourse/vs/0 (ignored.py).
+COOKTOP_SPEC = Capability(href='/cooktop/spec/vs/0')
+
+# settingTime (seconds) is the hot-surface auto-shutoff timer's configured
+# duration (1200s = 20 min in issue #44's dump); state on/off is whether the
+# feature itself is enabled -- not a live "surface is hot right now" alert
+# (that's COOKTOP_STATUS's per-burner hot_surface). No write contract
+# verified, so read-only for now.
+COOKTOP_SAFETY = Capability(
+    href='/cooktop/settings/status/vs/0',
+    poll_tier='warm',
+    entities=(
+        BinarySensorDesc(key='cooktop_safety_shutoff_enabled', field='safetyAlert',
+                         name='Hot surface auto-shutoff enabled',
+                         entity_category='config',
+                         value_fn=lambda v: (v or {}).get('state') == 'on'),
+    ),
+)

custom_components/localthings/registry/entities.py

@@ -85,6 +85,13 @@ class NumberDesc(SamsungEntityDescription):
     native_min: Optional[float] = None
     native_max: Optional[float] = None
     step: Optional[float] = None
+    # Override native_min/native_max/step from the live rep, when set --
+    # same "static default, live override" shape as unit_fn, for resources
+    # whose sane bounds depend on a per-device value (e.g. a temperature
+    # setpoint reported in Celsius on one device, Fahrenheit on another).
+    native_min_fn: Optional[Callable[[dict], float]] = None
+    native_max_fn: Optional[Callable[[dict], float]] = None
+    step_fn: Optional[Callable[[dict], float]] = None
     range_field: Optional[str] = None  # resource field containing [min, max] list
     write_fn: WriteFn = None