refactor: adopt cleaner write pattern for options arrays

custom_components/localthings/coordinator.py

@@ -22,7 +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.capabilities.common import merge_options_field, remote_control_enabled
 from .registry.discovery import discover, BoundEntity
 from .registry import CAPABILITIES
 from .registry.adapter import flatten
@@ -612,7 +612,24 @@ class LocalThingsCoordinator(DataUpdateCoordinator[dict[str, Any]]):
         # introduced its own races around overlapping writes to the same
         # href. Simpler and safer to just hold the guard for the full,
         # generously-sized window and let it expire on its own.
-        self._observe.apply(write_href, body, source='optimistic')
+        # write_fn bodies that touch x.com.samsung.da.options carry only the
+        # changed token(s) now (issue #54: confirmed sufficient on the wire --
+        # the device merges by prefix itself), not the whole packed array.
+        # observe.apply()'s field-level {**cached, **rep} merge doesn't know
+        # that -- handed the bare token list, it would replace the cached
+        # field outright and wipe every sibling option for the rest of the
+        # settle window. Pre-merge it here the same way the device does, so
+        # the optimistic cache entry stays complete; the minimal `body` below
+        # is still exactly what goes out over the wire.
+        optimistic_body = body
+        new_options = body.get('x.com.samsung.da.options')
+        if isinstance(new_options, list):
+            cached_options = (self._cache.get(write_href) or {}).get('x.com.samsung.da.options')
+            optimistic_body = {
+                **body,
+                'x.com.samsung.da.options': merge_options_field(cached_options, new_options),
+            }
+        self._observe.apply(write_href, optimistic_body, source='optimistic')
         self._observe.mark_write_pending(
             write_href, settle_s=self._POST_TIMEOUT_S + self._POLL_TIMEOUT_S
         )

custom_components/localthings/registry/capabilities/air_purifier.py

@@ -8,11 +8,11 @@ dishwasher.DIAGNOSIS -- identical field/write contract
 (x.com.samsung.da.diagnosisStart, 'Ready' on both dumps).
 
 /mode/vs/0's x.com.samsung.da.options array packs multiple independent
-'<Prefix>_<value>' flags into one list -- the same packed-list/RMW contract
-laundry.py's option_value/replace_in_options already model for
-/course/vs/0's options[] (reused directly below, just against this family's
-own href). Per issue #56's follow-up (five diagnostics dumps captured with
-the physical unit set to Auto/Sleep/Low/Medium/High):
+'<Prefix>_<value>' flags into one list -- the same packed-list contract
+laundry.py's option_value/option_write already model for /course/vs/0's
+options[] (reused directly below, just against this family's own href). Per
+issue #56's follow-up (five diagnostics dumps captured with the physical unit
+set to Auto/Sleep/Low/Medium/High):
   Light_On / Light_Off  -- a plain on/off flag; MODE below models it as a
                             real switch, RMW-replacing just that one entry.
   Comode_Off            -- read 'Off' on *every* one of the five dumps,
@@ -44,7 +44,7 @@ stable capture -- see the issue #56 discussion for what's needed.
 from ..capability import Capability
 from ..entities import BinarySensorDesc, SensorDesc, SwitchDesc
 from .common import int_or_none, sensor_item_value
-from .laundry import bool_option_exists, bool_option_value, option_value, replace_in_options
+from .laundry import bool_option_exists, bool_option_value, option_value, option_write
 
 _AIR_QUALITY_SENSORS = (
     ('dust', 'Dust', 'mdi:blur', 'Dust'),
@@ -135,9 +135,14 @@ AIRFLOW_VS_FALLBACK = Capability(
 
 
 def _light_write(payload, rep, href=None):
-    opts = list(rep.get('x.com.samsung.da.options') or [])
+    # option_write's single-token write is confirmed on a washer's
+    # /course/vs/0 (issue #54), NOT independently on this family's
+    # /mode/vs/0 -- extrapolated on the assumption the same vendor field
+    # merges the same way everywhere. If some unit replaces the field
+    # outright instead, this would drop Comode/OptionCode alongside it on
+    # the next light toggle; revisit if a real device report surfaces that.
     return ['mode', 'vs', '0'], {
-        'x.com.samsung.da.options': replace_in_options(opts, 'Light', payload),
+        'x.com.samsung.da.options': option_write('Light', payload),
     }
 
 

custom_components/localthings/registry/capabilities/common.py

@@ -65,6 +65,33 @@ def _active_alarm_codes(items):
     return ', '.join(codes) if codes else 'none'
 
 
+def merge_options_field(cached, new_tokens):
+    """Merge freshly-written `<Prefix>_<Value>` tokens into a cached
+    x.com.samsung.da.options[]-style array the same way the device itself
+    merges them: match by prefix, replace if present, append if not.
+
+    Confirmed on real hardware (issue #54) that a write only needs to carry
+    the changed token(s), not the whole array -- see laundry.option_write /
+    oven._option_write for the write side. This is the read side of that
+    same fact: coordinator.async_send_command uses it to keep the
+    optimistic cache entry for the written href complete (every sibling
+    option still present) during the write-settle window, since the wire
+    body it applies straight to the cache no longer carries them."""
+    merged = list(cached or [])
+    for token in new_tokens or ():
+        if not isinstance(token, str) or '_' not in token:
+            continue
+        prefix = token.split('_', 1)[0]
+        replaced = False
+        for i, o in enumerate(merged):
+            if isinstance(o, str) and o.startswith(prefix + '_'):
+                merged[i] = token
+                replaced = True
+        if not replaced:
+            merged.append(token)
+    return merged
+
+
 def sensor_item_value(items, sensor_type, index=0):
     """Pull one reading out of a `/sensors/vs/0`-style items[] list -- each
     item is `{type, value: [...]}`; `index` picks which slot of a possibly

custom_components/localthings/registry/capabilities/laundry.py

@@ -146,9 +146,13 @@ BUZZER_SOUND = Capability(
 # Cycle selection over /course/vs/0.
 #
 # The selected course and every other user-tunable option ride in the
-# x.com.samsung.da.options array on /course/vs/0 as `<Prefix>_<value>` tokens;
-# a write is a read-modify-write of that whole array (cycle_write). The set of
-# *selectable* courses is not hardcoded -- it's read live from
+# x.com.samsung.da.options array on /course/vs/0 as `<Prefix>_<value>` tokens.
+# Confirmed on real hardware (issue #54): a write only needs to carry the one
+# changed token -- `{'x.com.samsung.da.options': ['SoftenerLevelCtrl_2']}` --
+# the device matches by prefix, evicts the stale token, and merges the result
+# into the array itself. No read-modify-write of the whole array needed (see
+# option_write). The set of *selectable* courses is not hardcoded -- it's read
+# live from
 # x.com.samsung.da.editCourseList on /wm/editcourse/vs/0 (cycle_options), so we
 # never show a course a given model doesn't have or hide one it does. Course
 # codes are uppercase hex; display names live in translations under
@@ -257,17 +261,17 @@ def _course_codes_from_supported_options(course_rep):
     return []
 
 
-def replace_in_options(options, prefix, new_value):
-    return [f"{prefix}_{new_value}" if isinstance(o, str) and o.startswith(prefix + '_') else o
-            for o in options]
+def option_write(prefix, new_value):
+    """A one-token x.com.samsung.da.options write -- see the module comment
+    above cycle_options for why this doesn't read/rewrite the whole array."""
+    return [f'{prefix}_{new_value}']
 
 
 def cycle_write(p, rep, href=None):
-    opts = list(rep.get('x.com.samsung.da.options') or [])
-    if not opts:
+    if not rep.get('x.com.samsung.da.options'):
         return None
     return ['course', 'vs', '0'], {
-        'x.com.samsung.da.options': replace_in_options(opts, 'Course', p),
+        'x.com.samsung.da.options': option_write('Course', p),
     }
 
 
@@ -339,11 +343,10 @@ def bool_option_write(prefix):
     def write(p, rep, href=None):
         if p not in ('On', 'Off'):
             return None
-        opts = list(rep.get('x.com.samsung.da.options') or [])
-        if not opts:
+        if not rep.get('x.com.samsung.da.options'):
             return None
         return ['course', 'vs', '0'], {
-            'x.com.samsung.da.options': replace_in_options(opts, prefix, p),
+            'x.com.samsung.da.options': option_write(prefix, p),
         }
     return write
 

custom_components/localthings/registry/capabilities/oven.py

@@ -122,10 +122,17 @@ def _option_value(options, prefix):
     return None
 
 
-def _replace_in_options(options, prefix, new_value):
-    """Return a new options list with the `<prefix>_*` slot replaced."""
-    return [f"{prefix}_{new_value}" if o.startswith(prefix + '_') else o
-            for o in options]
+def _option_write(prefix, new_value):
+    """A one-token x.com.samsung.da.options write, mirroring
+    laundry.option_write. NOT independently confirmed on an oven -- issue
+    #54 only confirmed prefix-merge-on-write for a washer's /course/vs/0.
+    This extrapolates that same vendor field/contract to the oven's
+    /mode/vs/0, on the assumption the firmware handles the array the same
+    way there. If that assumption is wrong for some oven, a device that
+    replaces the field outright instead of merging would drop every other
+    option in it (Sound/fastpreheat/etc.) on the next write -- revisit if a
+    real device report surfaces that."""
+    return [f'{prefix}_{new_value}']
 
 
 # ---------------------------------------------------------------------------
@@ -175,47 +182,41 @@ def _oven_mode_write(p, rep, href=None):
 def _lamp_write(p, rep, href=None):
     if p not in ('On', 'Off'):
         return None
-    opts = list(rep.get('x.com.samsung.da.options') or [])
-    if not opts:
+    if not rep.get('x.com.samsung.da.options'):
         return None
     return ['mode', 'vs', '0'], {
-        'x.com.samsung.da.options': _replace_in_options(opts, 'UpperLamp', p),
+        'x.com.samsung.da.options': _option_write('UpperLamp', p),
     }
 
 
 def _sound_write(p, rep, href=None):
     if p not in ('On', 'Off'):
         return None
-    opts = list(rep.get('x.com.samsung.da.options') or [])
-    if not opts:
+    if not rep.get('x.com.samsung.da.options'):
         return None
     return ['mode', 'vs', '0'], {
-        'x.com.samsung.da.options': _replace_in_options(opts, 'Sound', p),
+        'x.com.samsung.da.options': _option_write('Sound', p),
     }
 
 
 def _fastpreheat_write(p, rep, href=None):
     if p not in ('On', 'Off'):
         return None
-    opts = list(rep.get('x.com.samsung.da.options') or [])
-    if not opts:
+    if not rep.get('x.com.samsung.da.options'):
         return None
     return ['mode', 'vs', '0'], {
-        'x.com.samsung.da.options': _replace_in_options(opts, 'fastpreheat', p),
+        'x.com.samsung.da.options': _option_write('fastpreheat', p),
     }
 
 
 def _naturalsteam_write(p, rep, href=None):
     if p not in ('On', 'Off'):
         return None
-    opts = list(rep.get('x.com.samsung.da.options') or [])
-    if not opts:
+    if not rep.get('x.com.samsung.da.options'):
         return None
-    if not any(o.startswith('NaturalSteam_') for o in opts):
-        opts = opts + [f'NaturalSteam_{p}']
-    else:
-        opts = _replace_in_options(opts, 'NaturalSteam', p)
-    return ['mode', 'vs', '0'], {'x.com.samsung.da.options': opts}
+    return ['mode', 'vs', '0'], {
+        'x.com.samsung.da.options': _option_write('NaturalSteam', p),
+    }
 
 
 # ---------------------------------------------------------------------------

custom_components/localthings/registry/capabilities/washer.py

@@ -19,7 +19,7 @@ from ..capability import Capability
 from ..entities import BinarySensorDesc, SelectDesc, SensorDesc
 from .laundry import (
     bool_option_exists, bool_option_switch, cycle_options, cycle_select, hex_pairs, option_value,
-    replace_in_options,
+    option_write,
 )
 
 # ---------------------------------------------------------------------------
@@ -215,8 +215,7 @@ def _dosing_level(prefix):
 
 def _level_write(prefix):
     def write(p, rep, href=None):
-        opts = list(rep.get('x.com.samsung.da.options') or [])
-        if not opts:
+        if not rep.get('x.com.samsung.da.options'):
             return None
         # `p` is the zero-padded supported code the UI selected (e.g. '03');
         # the device stores the level un-padded (e.g. '3'), matching how it
@@ -226,7 +225,7 @@ def _level_write(prefix):
         except (TypeError, ValueError):
             native = p
         return ['course', 'vs', '0'], {
-            'x.com.samsung.da.options': replace_in_options(opts, prefix, native),
+            'x.com.samsung.da.options': option_write(prefix, native),
         }
     return write