Merge pull request #401 from vmonkey/feature/add-wash

Add AddWash controls and sensors for washers

Dockerfile

@@ -6,4 +6,4 @@ FROM ghcr.io/home-assistant/home-assistant:stable
 # repeats the install attempt on every container recreate. Baking
 # smartthings-local into the image keeps the dev container usable
 # offline and avoids relying on that runtime install path.
-RUN pip3 install --no-cache-dir "smartthings-local>=0.1.2"
+RUN pip3 install --no-cache-dir "smartthings-local>=0.1.8"

README.md

@@ -85,7 +85,7 @@ This repo doesn't include the needed CA bundle. For an example of how to obtain
 5. The flow sends a DTLS `ClientHello` to every port in the `49152-49160` range at once and keeps the one that answers -- a real DTLS server identifies itself in about one round trip, and the probe stops there, so nothing is left behind on the appliance. Only that port is then given a real certificate handshake: it fetches the current UUID from Samsung's cloud gateway, mints a leaf cert signed by your CA, and reads the device's identity and `/device/0`. On success it creates the config entry, already knowing the appliance's serial, model, and type.
 6. Every subsequent device only asks for the host IP. The stored CA credentials are reused, and so is the leaf cert itself -- every appliance accepts the same one -- so adding a second appliance doesn't depend on Samsung's cloud being reachable at all. If a device rejects the reused cert (the UUID behind it does rotate), the flow mints a fresh one and retries by itself.
 
-Entities appear under one HA device per appliance, named for the appliance's type and model. Rename freely: the device is keyed on its serial, not its name.
+Entities appear under one HA device per appliance, named for the appliance's type and model. Rename freely: the device is keyed on the appliance's own OCF device ID, not its name. (Some Samsung models ship the same serial number on every unit of a model, so the serial can't tell two of them apart -- the OCF device ID can.)
 
 ---
 
@@ -95,6 +95,73 @@ Each device has its own **Configure** option in Settings > Devices & Services, u
 
 - **Allow writes even when remote control is reported off** — by default, LocalThings blocks every write with a clear error whenever a device reports remote control off, rather than letting the device silently reject it. Some devices accept certain writes anyway (e.g. default detergent/softener dosing on a washer) even while reporting remote control off. Only enable this if you've confirmed writes actually work on your device with remote control off — otherwise you trade a clear error for a silent failure.
 - **Estimated finish -- minimum change (minutes)** — a washer/dryer/dishwasher's `finish_time` sensor is recomputed from the device's own remaining-time estimate on every poll, which commonly drifts or gets revised by a minute or two between updates. This setting holds `finish_time` at its last reported value until a new estimate differs by at least this many minutes, cutting down on Home Assistant history/logbook noise from a value that hasn't meaningfully changed. Defaults to `3`; set it to `0` to report every computed change.
+- **Remember modes the device reports but doesn't advertise** — some firmware reports a current mode it never lists as supported. Issue #327's air conditioner sits in `Quiet` while offering only `Off/Sleep/Speed/Nano/NanoSleep`, so Home Assistant showed the preset as active but refused to select it. LocalThings remembers any such mode it sees and keeps offering it afterwards, stored on the config entry so it survives a restart — the device only names the mode while it is in it, and you shouldn't have to reach for the physical remote after every reboot. Defaults to on. Turning it off offers only what the device advertises, without discarding what was already learned.
+
+The same **Configure** menu has a **Forget remembered modes** step, which clears what has been learned for that device. Use it if a mode was learned that turns out not to be selectable — otherwise, by design, it stays forever.
+
+---
+
+## Part 5: Reading and writing resources directly
+
+Two HA actions, `localthings.write_resource` and `localthings.read_resource`, talk to a device's OCF resources directly instead of through this integration's entity model. They exist for two overlapping jobs: pinning down a device-specific write contract (the reverse-engineering work `docs/investigations/` and the provenance comments throughout `registry/capabilities/` are all about), and driving a resource this integration doesn't model as an entity yet, without waiting on a release.
+
+Both take a `device_id` (a device picker filtered to this integration) and resolve to exactly one appliance — a target that expands to more than one LocalThings device is rejected rather than silently fanned out across all of them. `href` is always canonical (e.g. `/mode/vs/0`); if the device you targeted is a subdevice — an oven's second cavity, an AC's second indoor unit — it's translated to the real on-the-wire href for you (`/mode/vs/1`, say), and the response reports both forms so there's no ambiguity about what was actually sent.
+
+`write_resource` exists because a single write, one at a time, isn't enough to probe some boards. Issue #300's Samsung wall oven answers `2.04 Changed` to a settings write while idle and then silently reverts it — the write only sticks once a cycle is already running. Finding what actually triggers a cycle needs an *ordered sequence* of writes to different resources, with real delays between them, and a way to check afterward whether anything actually held:
+
+```yaml
+action: localthings.write_resource
+data:
+  device_id: abc123...
+  writes:
+    - href: /mode/vs/0
+      payload:
+        x.com.samsung.da.modes: ["Bake"]
+      settle: 5
+    - href: /operational/state/vs/0
+      payload:
+        x.com.samsung.da.state: "Run"
+  verify_after: 30
+```
+
+Mind the shapes: what you write is sent verbatim, so the field names and types have to be the ones that resource actually uses. `/mode/vs/0` takes `modes` as an *array* on this board; a bare string, or the singular `mode`, is a different field the device will simply ignore. `read_resource` (below) with no `href` is the quickest way to see the real shape of everything before you write to any of it.
+
+Each write in `writes` (1-10 of them) needs `href` and a non-empty `payload`, sent verbatim as a partial-rep POST — this bypasses the remote-control-off block and every `write_fn`/`validate_fn` a normal entity write goes through, and sends exactly the fields you give it, so it can misconfigure your appliance if you get it wrong. `settle` (0-30s, default 0) is how long to wait *after* that write before starting the next one.
+
+By default the whole sequence holds the device session from the first write to the last, settle delays included, so a routine poll or another entity's write can't land between two steps and blur which write the appliance was reacting to. The cost is that nothing else on that device updates until the sequence ends — up to 10 × 30s if you ask for the maximum of both. Set `hold_session_lock: false` to take the session per write and release it across the waits instead, trading that certainty for a device whose entities keep updating throughout.
+
+The response has one `results` entry per write, with `before`/`after` reps and a `changed` flag (every key/value in `payload` present and equal in the immediate readback):
+
+```json
+{
+  "device_id": "abc123...",
+  "results": [
+    {"href": "/mode/vs/0", "actual_href": "/mode/vs/0", "code": "2.04", "raw_code": 68,
+     "accepted": true, "before": {...}, "after": {...}, "changed": true},
+    ...
+  ],
+  "verified": {
+    "/mode/vs/0": {"code": "2.05", "raw_code": 69, "rep": {...}, "held": false}
+  }
+}
+```
+
+`verify_after` (0-60s, default 0, omit to skip) is what actually answers the "did it stick" question: after the sequence finishes, it waits that long and then re-reads every distinct href the sequence touched, reporting the result under `verified`, keyed by canonical href. `changed` tells you the write was accepted and reflected immediately; `held` tells you whether it was still there N seconds later, or whether the board quietly put it back — issue #300's exact symptom. Where an href was written more than once in a sequence, `held` compares against the *last* payload sent to it. A `held` of `null` means the re-read itself didn't come back (check `code` next to it) — unknown, deliberately not reported as a revert.
+
+If the session drops partway through a sequence, the action raises rather than returning, and the error names how many writes completed and which — the appliance is left holding a partial sequence, so knowing where it stopped is the difference between a usable result and starting over blind.
+
+`read_resource` is the read half, and it's deliberately not just a cache lookup:
+
+```yaml
+action: localthings.read_resource
+data:
+  device_id: abc123...
+  href: /mode/vs/0
+```
+
+returning `{"href", "actual_href", "code", "raw_code", "rep"}` off a **live GET straight from the device**, not the cache — which can be up to a poll interval stale, exactly the staleness that would make `held` above meaningless. A sixth key, `body`, appears only when the response isn't a Property map: a Collection (`/device/0`, and the `x.com.samsung.devcol` siblings some boards expose) answers a CBOR list, which `rep` can't carry, and which would otherwise read as an accepted-but-empty resource. Omit `href` and you get `{"resources": {href: rep, ...}}`, the cached snapshot of everything this integration currently tracks on that device, with no GET at all — useful for seeing what's there before you start writing to it, without hammering the appliance.
+
+The **Debug write** panel under a device's Configure menu (Part 4) is the friendlier single-write path over this same machinery — pick an href, type a payload, see the result — for when you don't need a sequence.
 
 ---
 
@@ -135,6 +202,8 @@ custom_components/localthings/
   coordinator.py          Polling + push update coordination, stale-state fallback, write dispatch
   observe.py              CoAP OBSERVE (push-mode) support layered on the coordinator
   diagnostics.py           Redacted diagnostics download (device state + coverage metadata)
+  services.py              write_resource/read_resource actions (device resolution, href translation)
+  services.yaml            Selectors/descriptions for the two services above
   const.py                 Domain, config keys, probe ports
   entity.py                Base entity wiring capability registry -> HA entity
   sensor.py / binary_sensor.py / switch.py / number.py / select.py / button.py / time.py / fan.py / climate.py / water_heater.py
@@ -168,10 +237,16 @@ docker-compose.yml / ha_config/   Local HA dev environment
 If your appliance's type isn't recognized, or it exposes resources this integration doesn't model yet, a Repairs
 issue appears under Settings > System > Repairs pointing you at Settings > Devices & Services > this device >
 the menu > Download diagnostics. That download is already redacted of account/network identifiers (Bixby login
-email, access tokens, device IDs, MAC addresses, serial numbers) before it's generated, so it's safe to attach
+email, access tokens, hashed device IDs, MAC addresses, serial numbers, and the owner-set device name) before it's
+generated, so it's safe to attach
 directly to a new issue using the linked device-support template. This is the fastest way to help add or expand
 support for hardware the maintainers don't have.
 
+When a diagnostics dump alone isn't enough to pin down how a resource actually behaves — whether a write sticks,
+what order things need to happen in, whether the device reverts a change on its own — the `localthings.write_resource`
+and `localthings.read_resource` actions from Part 5 are the tool for probing it directly and reporting back what
+you found.
+
 ---
 
 ## Adding a new appliance type
@@ -196,6 +271,12 @@ If reconnects become persistent (more than a handful per minute), something's ac
 
 Deregistering a device in SmartThings causes a reset of its network settings as soon as it accesses Samsung's servers, dropping it off Wi-Fi until it's re-onboarded through the SmartThings app. As such, consider keeping devices registered even if egress-blocked, to avoid them resetting upon brief internet access.
 
+### Restarting while an appliance is powered off
+
+If Home Assistant restarts while an appliance is unplugged or switched off at the wall, its device and entities still load — restored from the last successful discovery, showing `unavailable` until the appliance answers again. Automations and dashboards keep referring to entities that exist, and the integration retries in the background, so the device comes back on its own within a poll cycle of being powered on. Entities read `unavailable` rather than their last known values on purpose: the integration can't verify what a disconnected appliance is doing, and recorded history is kept by the recorder either way.
+
+This only applies to an appliance the integration has reached at least once. A brand-new device that has never answered has nothing to restore from, so setting it up still requires it to be reachable.
+
 ### Multi-subdevice ("2-in-1") air conditioner systems
 
 Some Samsung installs run more than one indoor subdevice off a single outdoor unit, all reachable over the *one* IP/DTLS session your config entry connects to (a floor-standing + wall-mounted 2-in-1 is a common shape). The integration discovers any sibling subdevices automatically, once, right after the first successful poll — there's nothing to configure. Each discovered subdevice gets its own HA device (linked to the main one via "via device") and its own `climate` card, so it lands in its own room in the dashboard instead of being invisible or mixed into the master's state.

custom_components/localthings/__init__.py

@@ -2,21 +2,51 @@
 
 from __future__ import annotations
 
+import inspect
 import logging
+import re
+from typing import Any
 
+from homeassistant import const as ha_const
 from homeassistant.config_entries import ConfigEntry
 from homeassistant.const import 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 entity_registry as er
+from homeassistant.helpers.typing import ConfigType
 
-from .const import CONF_HOST, CONF_PORT, CONF_SERIAL, DOMAIN, PLATFORMS
-from .coordinator import LocalThingsCoordinator
+from .const import CONF_DEVICE_TYPE, CONF_HOST, CONF_PORT, CONF_SERIAL, DOMAIN, PLATFORMS
+from .coordinator import LocalThingsCoordinator, snapshot_store
 from .registry.identity import resolve_serial
+from .rekey import rekey_entry
+from .services import async_setup_services
 
 _LOGGER = logging.getLogger(__name__)
 
+# UnitOfDensity is the non-deprecated home for this value from whichever HA
+# release introduces it; CONCENTRATION_MICROGRAMS_PER_CUBIC_METER logs a
+# removal warning (2027.8) on those releases every time it's accessed.
+# hacs.json's floor (2025.1.0) predates UnitOfDensity existing at all, so
+# this is a runtime getattr rather than a static import ty could only ever
+# resolve against one HA generation -- see _relabel_particulate_statistics'
+# own new_unit_class feature-detection below for the same pattern. The
+# getattr short-circuits before the deprecated name is ever touched on a
+# release new enough to have UnitOfDensity.
+_unit_of_density = getattr(ha_const, "UnitOfDensity", None)
+PARTICULATE_UNIT = (
+    _unit_of_density.MICROGRAMS_PER_CUBIC_METER
+    if _unit_of_density is not None
+    else ha_const.CONCENTRATION_MICROGRAMS_PER_CUBIC_METER
+)
+
+
+async def async_setup(hass: HomeAssistant, config: ConfigType) -> bool:
+    # Services are process-global, registered once here rather than per
+    # config entry (issue #300) -- see services.async_setup_services.
+    async_setup_services(hass)
+    return True
+
 
 def _serial_from_unique_id(entry: ConfigEntry) -> str:
     """The device identity a pre-v2 entry was created with.
@@ -53,67 +83,114 @@ def _repair_placeholder_keys(hass: HomeAssistant, entry: ConfigEntry, serial: st
     """Re-key registry entries this entry minted from the placeholder identity.
 
     Before the identity moved onto the config entry, the coordinator seeded
-    `device_serial` with the host and only replaced it after the first poll.
+    its device key with the host and only replaced it after the first poll.
     Anything that registered in between -- the connection-mode sensor
     especially, added unconditionally rather than from `bound` -- was
     written into the registry keyed on the IP permanently, orphaned the
     moment the serial-keyed identity appeared (issue #236). Deleting the
     orphans by hand didn't help: the next restart that lost the same race
     recreated them.
-
-    Rewriting beats deleting where possible -- an entity keeps its
-    entity_id, name, area and automations. Only possible when the
-    serial-keyed key is still free; where both exist the placeholder-keyed
-    one is the dead duplicate (unavailable since the restart that created
-    it), so it goes.
     """
     host = entry.data[CONF_HOST]
     if serial == host:
         # A board with no usable serial resolves to the host, so its keys
         # were never placeholders.
         return
+    rekey_entry(hass, entry, host, serial)
+
+
+# Registries whose Dust/FineDust/SuperFineDust sensors gained pm10/pm25/pm1
+# and a unit in the release that introduced entry version 3. Deliberately
+# not every family reading /sensors/vs/0: range_hood and airconditioner
+# still declare no unit for their identically-named sensors, and relabelling
+# their statistics to µg/m³ would assert a unit those entities don't report
+# -- creating the very mismatch this migration exists to prevent.
+_PARTICULATE_TYPED_IN_V3 = frozenset({"air_purifier", "air_monitor"})
+
+# unique_id is f"{DOMAIN}_{serial}_{state_key}"; state_key is the descriptor
+# key, optionally carrying a subdevice prefix and a trailing `_<n>` instance
+# (registry/adapter._key, discovery.instance_suffix). Matching the tail rather
+# than rebuilding the whole id keeps this working for a renamed entity, whose
+# entity_id -- and so its statistic_id -- no longer follows from the key.
+_PARTICULATE_KEY_RE = re.compile(r"_(?:super_fine_dust|fine_dust|dust)(?:_\d+)?$")
+
+
+@callback
+def _relabel_particulate_statistics(hass: HomeAssistant, entry: ConfigEntry) -> bool:
+    """Point existing particulate statistics at the unit they always were.
+
+    These sensors recorded long-term statistics with no unit, and the
+    release carrying this migration gives them µg/m³. Home Assistant treats
+    that as a unit change it can't convert and *suppresses statistics
+    generation entirely* for the entity until someone resolves the repair
+    (sensor.recorder._update_issues -> UNITS_CHANGED_ISSUE, and the matching
+    `continue` in its compile path). Silently freezing the history we just
+    finished labelling is the worst of both outcomes, so the metadata is
+    corrected up front instead.
+
+    Only the metadata row is rewritten, never the recorded values. The
+    readings were always µg/m³ concentrations (issue #325); what was missing
+    was the label, so there is nothing to convert and no way for this to
+    distort history. That is also why it uses
+    `async_update_statistics_metadata` and not `change_statistics_unit`,
+    which would scale every stored value.
+
+    A no-op when this device family isn't one that gained the unit, or when
+    the device never recorded any statistics -- the underlying UPDATE simply
+    matches no rows.
+
+    Returns False only when the recorder wasn't loaded, meaning the caller
+    should leave the entry on its old version and try again next start.
+    """
+    if entry.data.get(CONF_DEVICE_TYPE) not in _PARTICULATE_TYPED_IN_V3:
+        return True
+    if "recorder" not in hass.config.components:
+        # after_dependencies orders the recorder ahead of us when it's
+        # configured, so this is either an install without it (nothing to
+        # relabel, and the retry costs one set lookup per start) or a boot
+        # where it failed to come up. Not distinguishable here, and burning
+        # the one-shot migration on the second case would leave the
+        # statistics suppressed for good.
+        _LOGGER.debug("recorder not loaded, deferring statistics relabel")
+        return False
+
+    from homeassistant.components.recorder.statistics import (
+        STATISTIC_UNIT_TO_UNIT_CONVERTER,
+        async_update_statistics_metadata,
+    )
+
+    kwargs: dict[str, Any] = {"new_unit_of_measurement": PARTICULATE_UNIT}
+    # `new_unit_class` only exists from HA 2025.11; hacs.json still supports
+    # 2025.1, where passing it is a TypeError -- which would propagate out of
+    # async_migrate_entry and fail the whole entry. Where it is supported it
+    # must be named, since omitting it is deprecated from HA 2026.11. µg/m³
+    # has a converter, so the value is 'concentration' rather than None.
+    if "new_unit_class" in inspect.signature(async_update_statistics_metadata).parameters:
+        converter = STATISTIC_UNIT_TO_UNIT_CONVERTER.get(PARTICULATE_UNIT)
+        kwargs["new_unit_class"] = converter.UNIT_CLASS if converter is not None else None
 
     ent_reg = er.async_get(hass)
-    stale_prefix = f"{DOMAIN}_{host}_"
-    for entity in list(er.async_entries_for_config_entry(ent_reg, entry.entry_id)):
-        if not entity.unique_id.startswith(stale_prefix):
+    for registry_entry in er.async_entries_for_config_entry(ent_reg, entry.entry_id):
+        if registry_entry.domain != "sensor":
             continue
-        new_unique_id = f"{DOMAIN}_{serial}_{entity.unique_id[len(stale_prefix) :]}"
-        if ent_reg.async_get_entity_id(entity.domain, DOMAIN, new_unique_id):
-            _LOGGER.debug("removing orphaned entity %s", entity.entity_id)
-            ent_reg.async_remove(entity.entity_id)
-        else:
-            _LOGGER.debug("re-keying entity %s to %s", entity.entity_id, new_unique_id)
-            ent_reg.async_update_entity(entity.entity_id, new_unique_id=new_unique_id)
-
-    dev_reg = dr.async_get(hass)
-    for device in list(dr.async_entries_for_config_entry(dev_reg, entry.entry_id)):
-        # `host` for the master, `host_<key>` for a subdevice (device_info_for).
-        stale = {
-            ident
-            for ident in device.identifiers
-            if ident[0] == DOMAIN and (ident[1] == host or ident[1].startswith(f"{host}_"))
-        }
-        if not stale:
+        if not _PARTICULATE_KEY_RE.search(registry_entry.unique_id):
             continue
-        fresh = {(DOMAIN, f"{serial}{ident[1][len(host) :]}") for ident in stale}
-        existing = dev_reg.async_get_device(identifiers=fresh)
-        if existing is not None and existing.id != device.id:
-            # Removing a device takes its entities with it. Anything still
-            # attached here was re-keyed rather than removed above -- the
-            # surviving copy, not a duplicate -- so move it onto the device
-            # it now belongs to before the removal destroys it too.
-            for entity in er.async_entries_for_device(
-                ent_reg, device.id, include_disabled_entities=True
-            ):
-                ent_reg.async_update_entity(entity.entity_id, device_id=existing.id)
-            _LOGGER.debug("removing orphaned device %s", device.id)
-            dev_reg.async_remove_device(device.id)
-        else:
-            _LOGGER.debug("re-keying device %s to %s", device.id, fresh)
-            dev_reg.async_update_device(
-                device.id, new_identifiers=(device.identifiers - stale) | fresh
+        _LOGGER.debug("relabelling statistics unit for %s", registry_entry.entity_id)
+        try:
+            async_update_statistics_metadata(hass, registry_entry.entity_id, **kwargs)
+        except Exception:
+            # Relabelling is a convenience: without it the user gets Home
+            # Assistant's own units_changed repair, which is where they were
+            # before this migration existed. Never worth failing setup over,
+            # so no recorder-side surprise can cost them the integration.
+            _LOGGER.warning(
+                "Could not relabel statistics unit for %s; Home Assistant will "
+                "offer a units-changed repair for it instead",
+                registry_entry.entity_id,
+                exc_info=True,
             )
+            return True
+    return True
 
 
 async def async_migrate_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
@@ -123,8 +200,25 @@ async def async_migrate_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
     can key its registry entries before the first poll (issue #236), and
     repairs whatever the old placeholder-keyed registration already
     orphaned.
+
+    v2 -> v3 relabels the recorded statistics for the particulate sensors,
+    which gained a device_class/unit in the same release (issue #325).
+
+    v3 -> v4 moves the entry off the serialNum as its identity and onto the
+    OCF device UUID (issue #381). Deliberately almost a no-op here: the
+    UUID lives on the device, and this runs before any I/O -- and before
+    the device is even known to be reachable, since an entry can load
+    entirely from its snapshot while the appliance is off (issue #295).
+    So the migration only guarantees CONF_SERIAL is populated, which is
+    what the coordinator rewrites *from* once a live poll finally hands it
+    a UUID to rewrite *to*.
+
+    The version is still bumped now rather than at that point, because the
+    bump's real job is the `entry.version > 4` downgrade guard below: an
+    entry re-keyed onto a UUID and then loaded by a release that reads
+    CONF_SERIAL as the key would silently orphan every entity it has.
     """
-    if entry.version > 2:
+    if entry.version > 4:
         return False  # downgrade: this release doesn't know the newer shape
 
     if entry.version == 1:
@@ -138,23 +232,62 @@ async def async_migrate_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
         _repair_placeholder_keys(hass, entry, serial)
         _LOGGER.debug("migrated entry %s to version 2 (serial=%s)", entry.entry_id, serial)
 
+    if entry.version == 2 and _relabel_particulate_statistics(hass, entry):
+        hass.config_entries.async_update_entry(entry, version=3)
+        _LOGGER.debug("migrated entry %s to version 3", entry.entry_id)
+
+    if entry.version == 3:
+        # `or host` mirrors what the coordinator has always fallen back to,
+        # so the recorded legacy key is the one this entry's registry
+        # entries were actually minted under even if CONF_SERIAL never got
+        # written (a v1 entry whose migration predates it). Both being
+        # absent shouldn't happen for an entry the config flow created, but
+        # an exception raised here fails the whole entry -- so it bumps the
+        # version and leaves the data alone rather than taking that risk
+        # for a value the coordinator re-derives on its next poll anyway.
+        legacy_key = entry.data.get(CONF_SERIAL) or entry.data.get(CONF_HOST)
+        hass.config_entries.async_update_entry(
+            entry,
+            data={**entry.data, CONF_SERIAL: legacy_key} if legacy_key else entry.data,
+            version=4,
+        )
+        _LOGGER.debug(
+            "migrated entry %s to version 4 (legacy key=%s, awaiting a poll to adopt "
+            "the OCF device id)",
+            entry.entry_id,
+            legacy_key,
+        )
+
     return True
 
 
 async def async_setup_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
     hass.data.setdefault(DOMAIN, {})
     coordinator = LocalThingsCoordinator(hass, entry)
+
+    # Before the first refresh, so the coordinator keeps rescheduling even
+    # when that refresh fails and leaves nothing subscribed: the base class
+    # only re-arms its timer while it has listeners, and an offline load can
+    # legitimately have zero live entities (every one of them disabled, say).
+    # Without this the entry loads once and never polls again (issue #295).
+    entry.async_on_unload(coordinator.async_add_listener(lambda: None))
+
     try:
         await coordinator.async_config_entry_first_refresh()
-    except Exception as err:
-        # `_poll_once` deliberately leaves the session up on a TimeoutError
-        # (see its docstring), so a refresh failing that way leaves a live,
-        # bound UDP socket nothing would ever close. HA retries setup with a
-        # new coordinator, and the source port is fixed by design
-        # (`_local_source_port`), so an abandoned socket would squat the
-        # exact port the next attempt binds.
-        await coordinator.async_close()
-        raise ConfigEntryNotReady(f"Cannot connect to device: {err}") from err
+    except ConfigEntryNotReady:
+        # An entry that has polled successfully before comes up on its last
+        # known entity set and keeps retrying on the normal poll interval,
+        # rather than sitting in setup-retry with a device that reads as
+        # broken and entities that exist only as registry rows (issue #295).
+        #
+        # An entry that has never reached the device has no snapshot, so
+        # there is nothing to show and no device metadata to name it with --
+        # that case still fails, which is also what keeps the door open for
+        # setup flows that need to interact with the device (issue #168).
+        if not await coordinator.async_rehydrate():
+            await coordinator.async_close()
+            raise
+
     hass.data[DOMAIN][entry.entry_id] = coordinator
 
     # Send the DTLS close_notify on Core shutdown, not just on unload (issue
@@ -174,6 +307,25 @@ async def async_setup_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
         hass.bus.async_listen_once(EVENT_HOMEASSISTANT_STOP, _async_close_on_stop)
     )
 
+    # Nothing else reacts to an options-flow save (issue #364): the cloud-
+    # courses Repair and canonical-view cache are only refreshed from
+    # _on_cloud_courses_changed, which only runs when a poll/observe
+    # actually reports new data. Without this, turning "Download cycles"
+    # off would leave an already-open Repair sitting there -- and an
+    # already-named program still offered as a cycle -- until the next
+    # unrelated change happened to fire it, indistinguishable from the
+    # toggle not working. Every other option (CONF_LEARN_MODES,
+    # CONF_BYPASS_REMOTE_CONTROL, ...) is read live on its own next use and
+    # has no comparable standing state to refresh, so this listener exists
+    # for cloud courses specifically rather than as a general
+    # options-changed hook. Must be a coroutine function -- HA wraps
+    # whatever an update listener returns in async_create_task, which raises
+    # on a plain callback's None.
+    async def _async_options_updated(_hass: HomeAssistant, _entry: ConfigEntry) -> None:
+        coordinator._on_cloud_courses_changed()
+
+    entry.async_on_unload(entry.add_update_listener(_async_options_updated))
+
     await hass.config_entries.async_forward_entry_setups(entry, PLATFORMS)
     return True
 
@@ -211,6 +363,16 @@ async def async_remove_config_entry_device(
     return not (device.identifiers & live)
 
 
+async def async_remove_entry(hass: HomeAssistant, entry: ConfigEntry) -> None:
+    """Delete the discovery snapshot this entry accumulated (issue #295).
+
+    Nothing else would: the store is keyed on entry_id, so re-adding the same
+    appliance mints a new one and the old file would linger in .storage
+    forever.
+    """
+    await snapshot_store(hass, entry).async_remove()
+
+
 async def async_unload_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
     unloaded = await hass.config_entries.async_unload_platforms(entry, PLATFORMS)
     if unloaded:

custom_components/localthings/climate.py

@@ -21,6 +21,7 @@ temperature and wind resources alike.
 
 from __future__ import annotations
 
+import asyncio
 import logging
 
 from homeassistant.components.climate import (
@@ -57,9 +58,6 @@ from .registry.capabilities.airconditioner import (
 from .registry.capabilities.airconditioner import (
     HREF_POWER_VS as POWER_VS_HREF,
 )
-from .registry.capabilities.airconditioner import (
-    HREF_TEMP_CONTROL as TEMP_CONTROL_HREF,
-)
 from .registry.capabilities.airconditioner import (
     HREF_TEMP_CURRENT as TEMP_CURRENT_HREF,
 )
@@ -79,7 +77,12 @@ from .registry.capabilities.airconditioner import (
     HREF_WIND_STRENGTH as WIND_STRENGTH_HREF,
 )
 from .registry.capabilities.airconditioner import (
+    _temperature_step,
+    extend_option_code_bit,
+    has_extend_option_code,
+    has_option_code,
     is_legacy_board,
+    option_code_bit,
 )
 from .registry.capabilities.common import normalize_temp_unit
 from .registry.entities import ClimateDesc
@@ -131,6 +134,10 @@ PRESET_AI_COMFORT = "ai_comfort"
 # not modeled as a preset either: nothing confirms it's user-selectable.
 _NON_HVAC_OPTION_CODES = frozenset({"HOMECARE_WIZARD_V2"})
 
+# Seconds to let a legacy board settle into Cool before the WindFree token is
+# written after it -- see _legacy_preset_needs_cool for the measurement.
+_NANO_AFTER_MODE_DELAY = 3
+
 # 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] = {
@@ -267,17 +274,125 @@ class LocalThingsClimate(LocalThingsEntity, ClimateEntity):
     # Nano=windFree, Quiet, Comfort, 2Step, Speed=Fast Turbo, Off=none.
     _LEGACY_PRESET_CODES = ("Off", "Nano", "Quiet", "Comfort", "2Step", "Speed")
 
+    # Good Sleep occupies the same Comode_ slot as the presets above, so a unit
+    # running it reports Comode_Sleep -- or Comode_NanoSleep, which the board
+    # will produce by itself when nano wind is asked for while the timer runs.
+    # Neither is in the list above, and a preset_mode outside preset_modes is
+    # not a state HA allows, so they are added for boards that have the Sleep_
+    # token these codes come with.
+    _LEGACY_SLEEP_PRESET_CODES = ("Sleep", "NanoSleep")
+
+    # HVAC modes _legacy_preset_codes() has a rule for. Anything else is a mode
+    # this transcription has never seen, which is the same "cannot judge" case as
+    # a board that publishes no capability map -- and gets the same fallback.
+    _LEGACY_KNOWN_HVAC = frozenset(
+        {"Cool", "Heat", "HeatClean", "Dry", "Fan", "Wind", "Auto", _AI_COMFORT_MODE}
+    )
+
+    # Which comfort modes a legacy board offers in which HVAC mode, and which of
+    # them it has at all. Both come from the appliance rather than from a table
+    # per model: the unit publishes its capabilities as two bit maps in
+    # /mode/vs/0's options (OptionCode, ExtendOptionCode), and its own app gates
+    # each item on a bit plus the current mode. _legacy_preset_codes() below is
+    # that logic, transcribed from the app's updateOptionsList() so the two can be
+    # compared line by line, with the bit each rule reads named in the comment.
+    #
+    # Confirmed against an ARTIK051_KRAC_18K whose owner read the same lists off
+    # the remote and the app: WindFree in Cool/Dry/Fan and (being an 18K model)
+    # Auto but never Heat, and Fast Turbo and Comfort in Heat because oc[12] is
+    # set. d'light Cool is gated the same way on oc[2], which is zero here -- and
+    # the appliance refuses the token locally too.
+    #
+    # Single User is deliberately not modelled, though the app does gate it on
+    # oc[3] / oc[11]: it has no token of its own. The app's own Single User
+    # command sends `Comode_Smart` -- the Smart Saver token -- with a hardcoded
+    # 24 desired alongside it, so there is nothing to write that would be
+    # distinguishable from the Smart preset below, and no name to give it that
+    # the appliance would recognise.
+
+    def _legacy_preset_codes(self, hvac: str, options: list) -> list[str]:
+        """Comfort-mode codes this unit offers in this HVAC mode.
+
+        Derived only for boards that publish *both* capability maps. One map on
+        its own is not enough: every eoc-gated rule would then read None, and
+        None means "this board does not publish the map", never "the feature is
+        absent". The FAC/CAC boards on record carry only the older map, with
+        values small enough that RAC bit positions all read as zeros, so
+        requiring both also keeps these rules inside the family they were
+        documented for.
+
+        Within the derived path, a bit that cannot be read (a malformed or
+        over-wide token) is treated as permission rather than denial for the
+        codes the unconditional list already carried -- losing a working preset
+        to a parsing failure is worse than offering one too many. Codes that were
+        never in that list (d'light) still need their bit to be explicitly set.
+        """
+        rep = self._rep(MODE_HREF)
+        if (
+            not has_option_code(rep)
+            or not has_extend_option_code(rep)
+            or hvac not in self._LEGACY_KNOWN_HVAC
+        ):
+            return list(self._LEGACY_PRESET_CODES)
+
+        cool = hvac in ("Cool", _AI_COMFORT_MODE)
+        heat = hvac in ("Heat", "HeatClean")
+        codes = ["Off"]
+        # WindFree: shown on eoc[31]; disabled in Heat, in AIComfort, and in Auto
+        # unless this is an 18K model (eoc[30]), where the app switches to Cool for
+        # it instead -- which is what _legacy_preset_needs_cool does.
+        nano_mode_ok = not heat and hvac != _AI_COMFORT_MODE
+        if hvac == "Auto":
+            nano_mode_ok = extend_option_code_bit(rep, 30) is not False
+        if extend_option_code_bit(rep, 31) is not False and nano_mode_ok:
+            codes.append("Nano")
+        if cool or (heat and option_code_bit(rep, 12) is not False):  # Fast Turbo
+            codes.append("Speed")
+        if cool:
+            codes.append("2Step")
+        if cool and option_code_bit(rep, 2):  # d'light Cool -- needs the bit set
+            codes.append("DlightCool")
+        # Quiet reads oc[10] with no mode condition in the app, but the owner of
+        # the unit above sees it in Cool and Heat only, on the remote as well as
+        # in the app -- the observation wins over the reading.
+        if option_code_bit(rep, 10) is not False and (cool or heat):
+            codes.append("Quiet")
+        if cool or (heat and option_code_bit(rep, 12) is not False):  # Comfort
+            codes.append("Comfort")
+        # Smart Saver has no bit of its own and the app hides it from every single
+        # RAC outright (showSaverOption = false), yet the appliance accepts it and
+        # behaves as Samsung documents -- so absence from the app is not absence
+        # from the hardware. Cool-only, per that documentation.
+        if hvac == "Cool":
+            codes.append("Smart")
+        # Good Sleep, which shares this slot: the app enables it in Cool, Heat and
+        # AIComfort only. Both codes, because the board turns Sleep into NanoSleep
+        # by itself when WindFree is running.
+        if (cool or heat) and any(
+            isinstance(option, str) and option.startswith("Sleep_") for option in options
+        ):
+            codes += self._LEGACY_SLEEP_PRESET_CODES
+        return codes
+
     def _legacy_convenient(self) -> dict:
         """A /mode/convenient/vs/0-shaped rep built from the Comode_* token in
         /mode/vs/0's options, for boards that have no convenient resource."""
         options = self._rep(MODE_HREF).get("x.com.samsung.da.options") or []
-        for option in options:
-            if isinstance(option, str) and option.startswith("Comode_"):
-                return {
-                    _MODES_FIELD: [option.split("_", 1)[1]],
-                    _SUPPORTED_FIELD: list(self._LEGACY_PRESET_CODES),
-                }
-        return {}
+        active = next(
+            (o.split("_", 1)[1] for o in options if isinstance(o, str) and o.startswith("Comode_")),
+            None,
+        )
+        if active is None:
+            return {}
+
+        codes = self._legacy_preset_codes(_first(self._rep(MODE_HREF).get(_MODES_FIELD)), options)
+        # Whatever the unit is actually running has to be listed whether the
+        # rules expect it there or not -- a preset_mode outside preset_modes is
+        # not a state HA allows, and the appliance has the last word on what it
+        # is doing (a remote can put it in a mode these rules would not offer).
+        if active not in codes:
+            codes.append(active)
+        return {_MODES_FIELD: [active], _SUPPORTED_FIELD: codes}
 
     def _legacy_airflow(self) -> dict:
         """The /airflow/vs/0 rep, but only when it is the fan/swing channel
@@ -331,7 +446,16 @@ class LocalThingsClimate(LocalThingsEntity, ClimateEntity):
         return bool(self._rep(POWER_HREF).get("value"))
 
     def _supported(self, href: str) -> list[str]:
-        return list(self._rep(href).get(_SUPPORTED_FIELD) or [])
+        """The resource's own supportedModes, plus any code this unit has
+        been seen in but never advertised (issue #327, learned.py).
+
+        Both the option lists (preset_modes, fan_modes, ...) and the write
+        paths resolve codes through here, so a learned code is selectable
+        and writable by virtue of appearing in one list.
+        """
+        supported = list(self._rep(href).get(_SUPPORTED_FIELD) or [])
+        learned = self.coordinator.learned_modes(self._bound.subdevice.to_actual(href))
+        return supported + [code for code in learned if code not in supported]
 
     def _warn_unmapped(self, href: str, code: str) -> None:
         """Log once per (href, code) when a device-reported mode has no
@@ -432,12 +556,11 @@ class LocalThingsClimate(LocalThingsEntity, ClimateEntity):
 
     @property
     def target_temperature_step(self) -> float:
-        return (
-            _num(self._rep(TEMP_CONTROL_HREF).get("increment"))
-            or _num(self._rep(TEMP_CONTROL_HREF).get("x.com.samsung.da.increment"))
-            or _num(self._temps_vs().get("x.com.samsung.da.increment"))
-            or 1.0
-        )
+        # Shared with the write path (airconditioner._climate_write) so a
+        # step read here always matches the step a write is quantized to --
+        # self._resources is this entity's own subdevice's canonical view
+        # (issue #177), the same shape _temperature_step expects.
+        return _temperature_step(self._resources) or 1.0
 
     # -- hvac mode ----------------------------------------------------------
 
@@ -622,6 +745,38 @@ class LocalThingsClimate(LocalThingsEntity, ClimateEntity):
         if self._rep(WIND_OSCILLATION_HREF):
             await self.coordinator.async_send_command(self._bound, ("oscillation", swing_mode))
 
+    async def _legacy_preset_needs_cool(self, code: str) -> None:
+        """Switch a legacy board to Cool first when the preset needs it.
+
+        WindFree does not exist in Auto: `["Comode_Nano"]` written while the unit
+        is in Auto is answered 2.04 Changed and dropped (measured, still
+        Comode_Off at +8s and +45s), and putting `modes: Cool` in the *same* POST
+        does not help -- the mode moves and the token is still dropped, so the
+        board judges the option against the mode it was in. Sent as its own write
+        first, it holds. The appliance's own app pairs `modes: Cool` with its nano
+        command for the same reason.
+
+        Auto only. The app's builder also covers AIComfort, but its
+        `updateOptionsList()` disables the WindFree button there outright, so that
+        pairing can never fire -- and `_legacy_preset_codes()` likewise does not
+        offer `Nano` in AIComfort, which would leave such a branch unreachable.
+
+        The pause is measured, not padding: back to back (same session, no gap at
+        all) the token was dropped again, two seconds apart it held. Three is that
+        with a little margin, and it only ever runs for this one preset in this
+        one HVAC mode.
+        """
+        if not self._legacy_preset() or code != "Nano":
+            return
+        if _first(self._rep(MODE_HREF).get(_MODES_FIELD)) != "Auto":
+            return
+        # Same resolver the rest of the platform uses -- the device code for an HA
+        # mode is read off the unit's own supportedModes rather than assumed.
+        await self.coordinator.async_send_command(
+            self._bound, ("mode", self._device_code_for_hvac(HVACMode.COOL))
+        )
+        await asyncio.sleep(_NANO_AFTER_MODE_DELAY)
+
     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 --
@@ -633,6 +788,7 @@ class LocalThingsClimate(LocalThingsEntity, ClimateEntity):
         # a fixed transform of the HA value -- e.g. 'NanoSleep' -> 'nanosleep').
         for code in self._supported(CONVENIENT_HREF):
             if _preset_to_ha(code) == preset_mode:
+                await self._legacy_preset_needs_cool(code)
                 kind = "preset_legacy" if self._legacy_preset() else "preset"
                 await self.coordinator.async_send_command(self._bound, (kind, code))
                 return

custom_components/localthings/cloudcourse.py

@@ -0,0 +1,377 @@
+"""Cloud "Download" programs on a laundry device (issue #342).
+
+Some course tables carry a course whose recipe isn't fixed in firmware --
+selecting it runs whichever program was last pushed down from the
+SmartThings cloud ("Download" / "Downloaded" in the course catalog). Three
+tokens on ``/course/vs/0``'s ``x.com.samsung.da.options`` array drive it:
+
+  ``CloudExtraCourse_<slot><slot>...``  the device's own list of downloaded
+      program slots, one byte each -- the cloud counterpart of
+      ``EditCourseList_`` for local courses.
+  ``CloudCourse_<blob>``               the persisted default program.
+  ``OneTimeCloudCourse_<blob>``        a this-run-only override.
+
+A ``<blob>`` is an opaque fixed-width payload whose byte 2 is the slot id
+it belongs to. Confirmed on two independent DA_WM_TP1_21_COMMON washers:
+the issue #342 reporter's, whose ``CloudExtraCourse_0A5C286B2D0C55301A``
+enumerates nine slots matching byte 2 of all nine of its programs exactly,
+and the WA55A7700AV dump in ``tests/fixtures``, whose two-slot
+``CloudExtraCourse_5958`` likewise matches its ``CloudCourse`` blob's byte
+2. Blob width is *not* fixed across boards (20 bytes vs 16), which is one
+reason nothing here ever synthesizes one.
+
+``CloudExtraCourse_`` does not mean the same thing on every family, so
+nothing keys off it directly -- see ``cloud_slots``, which is what the rest
+of this module and its callers gate on. Even then, a device can advertise a
+slot whose payload has never been observed, so ``cloud_slots`` answers
+"which exist" while the store answers "which are usable"; the two are
+deliberately allowed to disagree.
+
+What this module does and deliberately does not do
+--------------------------------------------------
+The device advertises *which* slots exist but never what any of them is
+called, and never the full blob for a slot other than the one currently
+loaded. A blob is only observable while the device happens to be sitting on
+that program, so the full payload is *learned by observation* and persisted
+(same rationale as learned.py's mode store), and the human-readable name is
+supplied by the user in the options flow. Nothing is hardcoded: no catalog
+of program ids, no table of blobs, no assumed Download course code. A
+hardcoded catalog was considered and rejected -- a blob is cloud-assigned
+per account/region, so one user's captured payload is not evidence about
+anyone else's device.
+
+Blobs are replayed byte-for-byte, exactly as captured, and never
+decomposed or rebuilt. (Bytes 5/7/9 of the reporter's blobs do decode
+cleanly to that program's temperature/rinse/spin, but the same offsets
+produce nonsense against the WA55A7700AV blob, so that decode is recorded
+in docs/investigations/download-cycle.md rather than shipped.)
+"""
+
+from __future__ import annotations
+
+import threading
+
+from .const import CONF_CLOUD_COURSES
+from .registry.capabilities.common import hex_pairs, option_value
+
+COURSE_HREF = "/course/vs/0"
+
+EXTRA_PREFIX = "CloudExtraCourse"
+DEFAULT_PREFIX = "CloudCourse"
+ONESHOT_PREFIX = "OneTimeCloudCourse"
+COURSE_PREFIX = "Course"
+
+# Synthetic, integration-owned field the coordinator merges onto
+# /course/vs/0's rep so the registry's exists_fn/rep_fn/options/write_fn all
+# reach this store through their existing signatures -- rep_fn in particular
+# receives only its own href's rep, never the resource snapshot, so a
+# sibling-resource lookup isn't available to it. Namespaced away from
+# Samsung's own 'x.com.samsung.da.' fields so it can never collide with one,
+# and merged at read time only: it is never written to the state cache, never
+# sent to the device, and never part of a diagnostics dump.
+FIELD = "x.localthings.cloudCourses"
+
+# Raw-value namespace for a cloud program in the cycle select. A slot id is
+# itself two hex chars, exactly like a local course code, so the two would be
+# indistinguishable (and could collide outright) as bare select values.
+RAW_PREFIX = "cloud:"
+
+# A blob whose first two bytes are FFFF means "no program loaded" rather than
+# naming one -- WA55A7700AV reports
+# OneTimeCloudCourse_FFFF010049004D004A804C0037F0AC00 while sitting on a
+# perfectly ordinary local course, and its byte 2 (01) is not one of the slots
+# its own CloudExtraCourse_ advertises.
+_SENTINEL_PREFIX = "FFFF"
+
+# Distinct from None, which is a real observation that carried no payload.
+# Only "never observed" suppresses a candidate; absent-then-loaded is a
+# genuine transition and should count.
+_UNOBSERVED = object()
+
+# Byte offset within a blob that carries its slot id.
+_SLOT_BYTE = 2
+_MIN_BLOB_BYTES = 4
+
+
+def _hex_bytes(blob):
+    if not isinstance(blob, str) or len(blob) % 2 or len(blob) < _MIN_BLOB_BYTES * 2:
+        return []
+    try:
+        int(blob, 16)
+    except ValueError:
+        return []
+    return hex_pairs(blob.upper())
+
+
+def is_loaded(blob) -> bool:
+    """True when `blob` names an actual program rather than 'none'."""
+    return _slot_and_loaded(blob)[1]
+
+
+def slot_of(blob) -> str | None:
+    """The slot id `blob` belongs to, or None if it names no program."""
+    slot, loaded = _slot_and_loaded(blob)
+    return slot if loaded else None
+
+
+def _slot_and_loaded(blob) -> tuple[str | None, bool]:
+    """Both answers off one parse -- the public pair above needs the same
+    byte split, and observe() asks for both about the same payload."""
+    parts = _hex_bytes(blob)
+    if not parts:
+        return None, False
+    if "".join(parts[:2]) == _SENTINEL_PREFIX:
+        return None, False
+    return parts[_SLOT_BYTE], True
+
+
+def advertised_slots(rep) -> list[str]:
+    """Slot ids this device says it has downloaded programs in, from its own
+    CloudExtraCourse_ token. The authority on *which* programs exist -- this
+    is never inferred from what has been learned so far, so "3 of 9
+    discovered" is answerable."""
+    raw = option_value(rep.get("x.com.samsung.da.options"), EXTRA_PREFIX)
+    if not isinstance(raw, str) or len(raw) % 2:
+        return []
+    # Preserve the device's own order (first-seen wins) while dropping any
+    # repeat, so the flow lists slots the way the appliance does.
+    return list(dict.fromkeys(hex_pairs(raw.upper())))
+
+
+def cloud_slots(rep, courses) -> list[str]:
+    """Advertised slots that are not already selectable courses.
+
+    `CloudExtraCourse_` does not mean the same thing on every family. On the
+    washers its bytes are opaque payload slots sharing nothing with the
+    device's own course list, and selecting one needs the full payload. On
+    the DW5000C dishwasher all four of its bytes *are* course codes in that
+    device's own list (8E/8D/8F/02 -- Plastic, Pots and pans, Baby Care, and
+    one untranslated), so there it is tagging which of its ordinary courses
+    came from the cloud. Those are already selectable as plain `Course_`
+    writes and need nothing from this module.
+
+    Subtracting the course list tells the two apart without having to guess
+    the family: what remains is slots that cannot be selected any other way,
+    which is exactly the set this module exists for.
+    """
+    known = {c.upper() for c in courses or ()}
+    return [slot for slot in advertised_slots(rep) if slot not in known]
+
+
+def supports_cloud_courses(rep, courses) -> bool:
+    """True for a device with downloaded programs it cannot otherwise run."""
+    return bool(cloud_slots(rep, courses))
+
+
+def loaded_slot(rep) -> str | None:
+    """The slot whose payload the appliance currently holds -- the one-time
+    override when one is set, else the saved default.
+
+    Deliberately not gated on the course being Download: the guided setup
+    flow watches this before the Download course has been confirmed, and
+    during that walk a change here *is* the signal that the user selected a
+    different program. A stale token can't produce a false positive because
+    the flow waits for a change from its own baseline, not for a value.
+    """
+    options = rep.get("x.com.samsung.da.options")
+    return slot_of(option_value(options, ONESHOT_PREFIX)) or slot_of(
+        option_value(options, DEFAULT_PREFIX)
+    )
+
+
+def _coerce(stored) -> tuple[str | None, dict[str, dict[str, str]]]:
+    """Restore the persisted record, dropping anything not the shape this
+    module writes -- it round-trips through the config entry as plain JSON
+    and a hand-edited .storage file must not be able to crash setup (same
+    posture as learned._coerce)."""
+    if not isinstance(stored, dict):
+        return None, {}
+    download = stored.get("download_course")
+    if not isinstance(download, str) or not download:
+        download = None
+    slots: dict[str, dict[str, str]] = {}
+    raw_slots = stored.get("slots")
+    if isinstance(raw_slots, dict):
+        for slot, record in raw_slots.items():
+            if not isinstance(slot, str) or not isinstance(record, dict):
+                continue
+            blob = record.get("blob")
+            if not is_loaded(blob) or slot_of(blob) != slot.upper():
+                continue
+            name = record.get("name")
+            slots[slot.upper()] = {
+                "blob": blob.upper(),
+                "name": name if isinstance(name, str) and name.strip() else "",
+            }
+    return download, slots
+
+
+def persist(hass, entry, record: dict) -> None:
+    """Write `record` onto the entry. Runs on the event loop, which
+    async_update_entry requires."""
+    hass.config_entries.async_update_entry(entry, data={**entry.data, CONF_CLOUD_COURSES: record})
+
+
+class CloudCourses:
+    """Per-device store of discovered cloud programs.
+
+    Mutated from whichever thread applied the update (the DTLS reader for an
+    OBSERVE notify, an executor thread for a poll -- see ObserveManager.apply),
+    so every access takes the lock; persistence is the caller's job, on the
+    event loop.
+    """
+
+    def __init__(self, stored_record=None) -> None:
+        self._lock = threading.Lock()
+        download, slots = _coerce(stored_record)
+        self._download_course = download
+        self._slots = slots
+        # Course codes seen at the moment a one-time override was *loaded* --
+        # candidates for "which course means Download on this board", pending
+        # user confirmation (see download_candidates).
+        self._candidates: dict[str, int] = {}
+        # Last one-time payload seen, so a load can be told from a poll that
+        # merely re-reports one. _UNOBSERVED until the first rep arrives.
+        self._last_oneshot: object = _UNOBSERVED
+
+    # -- learning ---------------------------------------------------------
+
+    def observe(self, rep: dict) -> bool:
+        """Learn from one applied /course/vs/0 rep; True if anything changed.
+
+        Two facts are learnable here. A blob is recorded against the slot its
+        own byte 2 names, so a program only has to be sitting loaded once --
+        on either token -- to be replayable forever after.
+
+        The Download course code is only ever taken as a *candidate*, and
+        only at the moment the one-time payload actually *changes* to a
+        loaded value. That instant is the one the device is known to accept a
+        program on, so the course selected then is real evidence. Counting
+        every poll instead would rank by dwell time: tokens in this array are
+        replaced by prefix and never evicted, so a stale OneTimeCloudCourse_
+        outlives its run and sits there through however many polls the
+        appliance spends on some ordinary course afterwards -- which is
+        exactly the course that would then be suggested. A candidate is still
+        never applied without confirmation in the options flow, but a
+        confident wrong suggestion is most of the way to a wrong write, and a
+        wrong write here starts a real wash cycle.
+        """
+        options = rep.get("x.com.samsung.da.options")
+        if not options:
+            return False
+        known_slots = advertised_slots(rep)
+        oneshot = option_value(options, ONESHOT_PREFIX)
+        with self._lock:
+            # Compared once, at the end, against where this pass started --
+            # not set per assignment. The two tokens can name the same slot
+            # with different payloads (a downloaded program with its settings
+            # tweaked for one run is exactly that shape), and a per-assignment
+            # flag would then report a change on every single poll forever:
+            # each pass writes the default's payload and then the one-shot's
+            # over it, so neither is ever "already stored". Every one of those
+            # reports rewrites the config entry, which on the SD-card installs
+            # this integration runs on is the one cost here that really bites.
+            # The end state is stable (the one-shot is written last and wins),
+            # so comparing start to end settles after the first pass.
+            before = {slot: record["blob"] for slot, record in self._slots.items()}
+            for prefix in (DEFAULT_PREFIX, ONESHOT_PREFIX):
+                blob = option_value(options, prefix)
+                slot = slot_of(blob)
+                # A blob whose slot the device doesn't advertise is not a
+                # program this appliance offers -- don't record it.
+                if slot is None or (known_slots and slot not in known_slots):
+                    continue
+                record = self._slots.get(slot)
+                if record is None:
+                    self._slots[slot] = {"blob": blob.upper(), "name": ""}
+                else:
+                    record["blob"] = blob.upper()
+            changed = before != {slot: rec["blob"] for slot, rec in self._slots.items()}
+
+            course = option_value(options, COURSE_PREFIX)
+            # Only a transition we actually watched happen counts. On the
+            # first observation there is nothing to compare against, so a
+            # payload sitting there is equally consistent with "just loaded"
+            # and "left over from last week" -- and on a board that doesn't
+            # clear the token when leaving Download, believing the former
+            # proposes whatever ordinary course the appliance happens to be
+            # on. Accepting that prefill would start a real wash cycle.
+            # (The two dumps in the corpus taken off the Download course both
+            # show the appliance clearing it to the FFFF sentinel, so this
+            # may never fire in practice -- which is not a reason to rely on
+            # it.) Restores don't persist _last_oneshot, so every restart
+            # re-enters this first-observation state deliberately.
+            first_ever = self._last_oneshot is _UNOBSERVED
+            if course and is_loaded(oneshot) and not first_ever and oneshot != self._last_oneshot:
+                self._candidates[course] = self._candidates.get(course, 0) + 1
+            self._last_oneshot = oneshot
+        return changed
+
+    # -- reads ------------------------------------------------------------
+
+    def download_candidates(self) -> list[str]:
+        """Course codes seen at the moment a one-time program was loaded,
+        most-observed first -- what the options flow offers as the likely
+        Download course. Never used for a write on its own."""
+        with self._lock:
+            ranked = sorted(self._candidates.items(), key=lambda kv: (-kv[1], kv[0]))
+        return [code for code, _ in ranked]
+
+    def named(self) -> dict[str, str]:
+        """Slots that are both learned and named -- the only ones offerable
+        as a cycle option. An unnamed slot has no label that isn't either
+        invented or an opaque hex id, so it stays out of the UI until the
+        user supplies one."""
+        with self._lock:
+            return {slot: record["name"] for slot, record in self._slots.items() if record["name"]}
+
+    def snapshot(self) -> dict:
+        with self._lock:
+            return {
+                "download_course": self._download_course,
+                "slots": {slot: dict(record) for slot, record in self._slots.items()},
+            }
+
+    def view(self) -> dict:
+        """What the registry sees under FIELD: only what a write or a label
+        can actually be built from, so a descriptor never has to re-apply
+        this module's rules."""
+        with self._lock:
+            if not self._download_course:
+                return {}
+            return {
+                "download_course": self._download_course,
+                "programs": {
+                    slot: {"blob": record["blob"], "name": record["name"]}
+                    for slot, record in self._slots.items()
+                    if self._is_usable(record)
+                },
+            }
+
+    # -- writes -----------------------------------------------------------
+
+    def set_download_course(self, code: str | None) -> None:
+        with self._lock:
+            self._download_course = code or None
+
+    def set_name(self, slot: str, name: str) -> None:
+        with self._lock:
+            record = self._slots.get(slot.upper())
+            if record is not None:
+                record["name"] = name.strip()
+
+    @staticmethod
+    def _is_usable(record) -> bool:
+        """A slot is offerable once it has a name. The device supplies the
+        payload; only the user can supply the label, so this is the whole
+        rule and it is stated once."""
+        return bool(record["name"])
+
+
+def undiscovered(rep: dict, record: dict, courses) -> list[str]:
+    """Cloud slots that aren't yet usable -- unlearned or unnamed. What the
+    Repairs issue counts, and what the options flow asks the user to walk the
+    appliance through. Counts against cloud_slots, not every advertised byte:
+    a slot that is already a selectable course is nothing to set up."""
+    programs = record.get("slots") or {}
+    return [s for s in cloud_slots(rep, courses) if not (programs.get(s) or {}).get("name")]

custom_components/localthings/config_flow.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import asyncio
 import contextlib
 import datetime
 import errno
@@ -20,6 +21,7 @@ import voluptuous as vol
 from homeassistant import config_entries
 from homeassistant.config_entries import ConfigFlowResult
 from homeassistant.core import callback
+from homeassistant.helpers import device_registry as dr
 from homeassistant.helpers.selector import (
     NumberSelector,
     NumberSelectorConfig,
@@ -33,29 +35,40 @@ from homeassistant.helpers.selector import (
     TextSelectorType,
 )
 
+from . import cloudcourse
 from .const import (
     CLIENTHELLO_PROBE_RETRIES,
     CLIENTHELLO_PROBE_TIMEOUT_S,
     CONF_BYPASS_REMOTE_CONTROL,
     CONF_CA_CERT_PEM,
     CONF_CA_KEY_PEM,
+    CONF_CLOUD_COURSES_ENABLED,
+    CONF_DEVICE_KEY,
     CONF_DEVICE_TYPE,
     CONF_FINISH_TIME_HYSTERESIS_MINUTES,
     CONF_HOST,
     CONF_LEAF_CERT_PEM,
     CONF_LEAF_KEY_PEM,
+    CONF_LEARN_MODES,
     CONF_MANUFACTURER,
     CONF_MODEL,
     CONF_PORT,
     CONF_SERIAL,
+    DEFAULT_CLOUD_COURSES_ENABLED,
     DEFAULT_FINISH_TIME_HYSTERESIS_MINUTES,
+    DEFAULT_LEARN_MODES,
     DOMAIN,
     LIVENESS_PROBE_TIMEOUT_S,
     PREFERRED_PROBE_PORTS,
     PROBE_GET_TIMEOUT_S,
     PROBE_MAX_WORKERS,
     PROBE_PORT_RANGE,
+    SERVICE_WRITE_RESOURCE,
 )
+from .learned import persist as learned_persist
+from .learned import stored as learned_stored
+from .registry.capabilities.laundry import cycle_options, personal_course_labels
+from .registry.subdevices import MAIN
 
 _TEXT = TextSelector(TextSelectorConfig(type=TextSelectorType.TEXT))
 _MULTILINE = TextSelector(TextSelectorConfig(type=TextSelectorType.TEXT, multiline=True))
@@ -68,6 +81,14 @@ _HYSTERESIS_MINUTES = NumberSelector(
     )
 )
 
+# Guided download-cycle setup: how long a round waits for the user to
+# select a program, and how often it live-reads /course/vs/0 while doing
+# so. The read takes the session lock, so the interval is a few seconds
+# rather than sub-second -- fast enough to feel immediate to someone
+# standing at the appliance, slow enough not to starve polling.
+_CLOUD_WAIT_TIMEOUT_S = 180.0
+_CLOUD_PROBE_INTERVAL_S = 3.0
+
 _LOGGER = logging.getLogger(__name__)
 
 _SAMSUNG_CLOUD_HOST = "connect-v2.samsungiotcloud.com"
@@ -163,6 +184,17 @@ def _fetch_samsung_uuid() -> str:
     raise RuntimeError(f"UUID not found in {_SAMSUNG_CLOUD_HOST} certificate subject")
 
 
+def _normalize_pem(text: str) -> str:
+    """Strip a pasted PEM's BOM, CRLF endings, and blank lines before
+    `cryptography` sees it -- a text editor's copy carries all three and
+    fails with an opaque InvalidHeader, while the same file dumped via
+    `type` doesn't (issue #291)."""
+    text = text.lstrip("\ufeff")
+    text = text.replace("\r\n", "\n").replace("\r", "\n")
+    lines = [line for line in text.split("\n") if line.strip()]
+    return "\n".join(lines)
+
+
 def _mint_leaf_cert(ca_cert_pem: str, ca_key_pem: str, uuid: str) -> tuple[str, str]:
     """Mint a fresh RSA-2048 leaf cert signed by the CA.
 
@@ -464,27 +496,84 @@ _CERT_ALERTS = frozenset(
     }
 )
 
-# OpenSSL renders a received fatal alert into its error text as e.g.
-# "tlsv1 alert unknown ca", which DtlsCoapSession.connect() wraps in a
-# ConnectionError. Reading it back tells us what the appliance objected to.
-#
-# Deliberately not the library's diagnostic probe (stateless=False): that
-# mode commits association state on the device, and an orphaned association
-# makes the next attempt time out (RFC 6347 §4.2.8) -- a bad trade on a
-# path the user is about to retry.
+# Older smartthings-local (< 0.1.3) rendered a received fatal alert straight
+# into the handshake exception's text, e.g. "tlsv1 alert unknown ca" wrapped
+# in a ConnectionError -- reading it back told us what the appliance
+# objected to. 0.1.3's "redacted typed failures" removed that: connect()'s
+# exceptions now carry a fixed, non-sensitive message with the real OpenSSL
+# text neither included nor chained (see smartthings_local.errors --
+# "backend errors can contain remote endpoints, local paths, or credential
+# metadata"). _alert_name is kept as a harmless fallback for exception text
+# that does carry it; _resolve_alert below is what actually classifies a
+# failure against a current library.
 _ALERT_RE = re.compile(r"alert ([a-z0-9 ]+)")
 
 
 def _alert_name(exc: Exception) -> str | None:
-    """The TLS alert an appliance sent, if this failure carried one."""
+    """The TLS alert an appliance sent, if this failure's exception text
+    carried one (only ever true against smartthings-local < 0.1.3)."""
     match = _ALERT_RE.search(str(exc).lower())
     return match.group(1).strip().replace(" ", "_") if match else None
 
 
+def _diagnostic_alert(host: str, port: int, cert_pem: str, key_pem: str):
+    """One opt-in stateful handshake against `port`, using our real
+    credentials, so a fatal Alert can be classified from the raw record
+    itself rather than parsed out of an exception's text.
+
+    This is the library's diagnose_dtls_handshake -- deliberately not used
+    for the primary candidate scan (it commits association state on the
+    device, and an orphaned association makes the *next* attempt time out
+    per RFC 6347 §4.2.8). Here it only runs once every real candidate has
+    already failed, to explain a failure that's happening either way --
+    one more orphaned association is a fair trade for a message that says
+    why, on a path the user is about to retry regardless.
+
+    Imported lazily, like `_clienthello_probe`, so an install whose
+    smartthings-local predates this API degrades to a generic message
+    instead of failing to load the config flow at all.
+    """
+    from smartthings_local.protocol.dtls_probe import diagnose_dtls_handshake
+
+    return diagnose_dtls_handshake(
+        host,
+        port,
+        cert_pem=cert_pem,
+        key_pem=key_pem,
+        timeout=CLIENTHELLO_PROBE_TIMEOUT_S,
+        retries=CLIENTHELLO_PROBE_RETRIES,
+    )
+
+
+def _resolve_alert(exc: Exception, host: str, port: int, cert_pem: str, key_pem: str) -> str | None:
+    """The TLS alert `port`'s failed handshake carried, if any -- the
+    exception's own text first (cheap, and all an older library ever
+    offers), then one bounded diagnostic handshake against a current one
+    that redacts it (see _diagnostic_alert)."""
+    name = _alert_name(exc)
+    if name is not None:
+        return name
+    try:
+        result = _diagnostic_alert(host, port, cert_pem, key_pem)
+    except Exception:
+        return None
+    if result.alert is None:
+        return None
+    level, name = result.alert
+    # ProbeResult.alert is set for a *received* alert record of either
+    # level -- fatal (2) means the appliance actually broke off the
+    # handshake over it; a warning (1, e.g. close_notify on an otherwise
+    # ordinary close) is not evidence of a rejection and must not be read
+    # as one. The old exception-text path never had this ambiguity: an
+    # OpenSSL exception only ever rendered for a fatal alert.
+    return name if level == 2 else None
+
+
 def _classify_handshake_failure(
     host: str,
     scan: _PortScan,
     failures: list[tuple[int, Exception]],
+    alerts: dict[int, str] | None = None,
 ) -> CannotConnect:
     """Turn "no port worked" into the most specific thing we can honestly
     say, in rough order of how much the evidence tells us: an alert means
@@ -492,13 +581,21 @@ def _classify_handshake_failure(
     certificate); a confirmed DTLS port that then timed out is likely still
     holding a session from a previous attempt; otherwise the sweep's own
     shape is the evidence.
+
+    `alerts` is the per-port classification `_handshake_and_read` already
+    resolved (exception text, or a diagnostic handshake -- see
+    _resolve_alert); a caller with only raw failures (or an older library)
+    still gets `_alert_name`'s exception-text reading as a fallback.
     """
-    alerts = [name for name in (_alert_name(exc) for _, exc in failures) if name]
-    cert_alerts = [name for name in alerts if name in _CERT_ALERTS]
+    resolved = dict(alerts or {})
+    for port, exc in failures:
+        resolved.setdefault(port, _alert_name(exc))
+    alert_names = [name for name in resolved.values() if name]
+    cert_alerts = [name for name in alert_names if name in _CERT_ALERTS]
     if cert_alerts:
         return CertRejected(f"{host} rejected our certificate (alert {cert_alerts[0]})")
-    if alerts:
-        return HandshakeFailed(f"{host} refused the DTLS handshake (alert {alerts[0]})")
+    if alert_names:
+        return HandshakeFailed(f"{host} refused the DTLS handshake (alert {alert_names[0]})")
     if scan.confirmed:
         return HandshakeTimeout(
             f"DTLS server confirmed on {host}:{scan.confirmed} but the handshake never completed"
@@ -566,7 +663,12 @@ def _read_device(sess, host: str, port: int) -> dict:
 
     from .registry.batch import parse_device0_batch
     from .registry.by_type import resolve as resolve_registry
-    from .registry.identity import read_identity, resolve_model, resolve_serial
+    from .registry.identity import (
+        read_identity,
+        resolve_device_key,
+        resolve_model,
+        resolve_serial,
+    )
 
     identity = read_identity(sess, None)
 
@@ -584,12 +686,19 @@ def _read_device(sess, host: str, port: int) -> dict:
 
     info = resources.get("/information/vs/0", {})
     registry = resolve_registry(resources, device_types=identity.device_types)
+    raw_serial = info.get("x.com.samsung.da.serialNum")
     return {
         "port": port,
         # Resolved through the same helpers _run_discovery uses, so the device
         # the coordinator registers up front is the one discovery would have
         # produced -- no rename, and no re-key, once the first poll lands.
-        "serial": resolve_serial(info.get("x.com.samsung.da.serialNum"), host),
+        #
+        # `device_key` is what the entry is actually keyed on; the serial is
+        # kept alongside it because the coordinator corroborates a later
+        # change of key against it (issue #381). read_identity has already
+        # fetched /oic/p and /oic/d above, so this costs no extra round trip.
+        "device_key": resolve_device_key(identity, raw_serial, host),
+        "serial": resolve_serial(raw_serial, host),
         "model": resolve_model(info.get("x.com.samsung.da.modelNum", ""), identity),
         "manufacturer": identity.manufacturer or "Samsung",
         "device_type_name": registry.name if registry is not None else None,
@@ -597,6 +706,40 @@ def _read_device(sess, host: str, port: int) -> dict:
     }
 
 
+def _diagnose_failures(
+    host: str,
+    scan: _PortScan,
+    failures: list[tuple[int, Exception]],
+    cert_pem: str,
+    key_pem: str,
+) -> dict[int, str]:
+    """At most one diagnostic handshake (see _diagnostic_alert) across every
+    port `_handshake_and_read` just gave up on -- not one per port.
+
+    Called only after that loop has fully exhausted `scan.candidates`, never
+    interleaved with it: `_diagnostic_alert`'s own docstring says the extra
+    orphaned association it costs is a fair trade "on a path the user is
+    about to retry regardless" -- true for the retry `_probe_and_validate`
+    itself makes on a CertRejected (a fresh `_handshake_and_read` call
+    against this same `scan`), but only if that retry's real handshake
+    attempts are the ones landing on a clean slate. Running the diagnostic
+    per candidate mid-loop would pollute exactly the port(s) that retry is
+    about to reattempt; running several of them multiplies both the latency
+    (each is its own bounded handshake) and the pollution for no extra
+    classification value, since _classify_handshake_failure only ever needs
+    one alert to decide.
+
+    Targets a confirmed-live port over an unconfirmed sweep candidate --
+    the one actually worth spending the extra handshake on.
+    """
+    if not failures:
+        return {}
+    by_port = dict(failures)
+    port = next((p for p in scan.confirmed if p in by_port), next(iter(by_port)))
+    alert = _resolve_alert(by_port[port], host, port, cert_pem, key_pem)
+    return {port: alert} if alert is not None else {}
+
+
 def _handshake_and_read(host: str, scan: _PortScan, cert_pem: str, key_pem: str) -> dict:
     """Handshake each candidate in turn, returning the first device that answers."""
     from smartthings_local.protocol.dtls_session import DtlsCoapSession
@@ -620,7 +763,8 @@ def _handshake_and_read(host: str, scan: _PortScan, cert_pem: str, key_pem: str)
             if sess is not None:
                 with contextlib.suppress(Exception):
                     sess.close()
-    raise _classify_handshake_failure(host, scan, failures)
+    alerts = _diagnose_failures(host, scan, failures, cert_pem, key_pem)
+    raise _classify_handshake_failure(host, scan, failures, alerts)
 
 
 def _probe_and_validate(
@@ -664,7 +808,13 @@ def _probe_and_validate(
 
 
 class LocalThingsConfigFlow(config_entries.ConfigFlow, domain=DOMAIN):
-    VERSION = 2
+    # v3 relabels the particulate sensors' recorded statistics; a freshly
+    # created entry has none to relabel, so it starts at the migrated
+    # version rather than walking through v2 (see async_migrate_entry).
+    # v4 keys the entry on the OCF device UUID (issue #381), which the probe
+    # below resolves up front -- so a new entry is already on the v4 shape
+    # and has nothing to re-key either.
+    VERSION = 4
 
     def __init__(self) -> None:
         self._host: str = ""
@@ -683,7 +833,7 @@ class LocalThingsConfigFlow(config_entries.ConfigFlow, domain=DOMAIN):
         """Persist everything the probe resolved, identity included.
 
         The identity fields aren't decoration: the coordinator seeds
-        `device_serial` and its DeviceInfo from them at construction time,
+        `device_key` and its DeviceInfo from them at construction time,
         so entity unique_ids are correct from the first entity that
         registers, even if the first poll is slow or fails (issue #236).
         """
@@ -698,6 +848,7 @@ class LocalThingsConfigFlow(config_entries.ConfigFlow, domain=DOMAIN):
                 CONF_CA_KEY_PEM: self._ca_key_pem,
                 CONF_LEAF_CERT_PEM: info["leaf_cert_pem"],
                 CONF_LEAF_KEY_PEM: info["leaf_key_pem"],
+                CONF_DEVICE_KEY: info["device_key"],
                 CONF_SERIAL: info["serial"],
                 CONF_MODEL: info["model"],
                 CONF_MANUFACTURER: info["manufacturer"],
@@ -722,8 +873,10 @@ class LocalThingsConfigFlow(config_entries.ConfigFlow, domain=DOMAIN):
                 if leaf_cert and leaf_key:
                     existing_leaf = (leaf_cert, leaf_key)
             else:
-                self._ca_cert_pem = user_input[CONF_CA_CERT_PEM].strip()
-                self._ca_key_pem = user_input[CONF_CA_KEY_PEM].strip()
+                # Normalized here, not just before minting: this is also
+                # what gets stored and reused to re-mint the leaf later.
+                self._ca_cert_pem = _normalize_pem(user_input[CONF_CA_CERT_PEM])
+                self._ca_key_pem = _normalize_pem(user_input[CONF_CA_KEY_PEM])
 
             try:
                 info = await self.hass.async_add_executor_job(
@@ -742,7 +895,33 @@ class LocalThingsConfigFlow(config_entries.ConfigFlow, domain=DOMAIN):
                 _LOGGER.exception("Unexpected error during device probe")
                 errors["base"] = "unknown"
             else:
-                await self.async_set_unique_id(f"localthings_{info['serial']}")
+                # An entry created before v4 still carries the serial-keyed
+                # unique_id until its first *live* poll adopts the UUID
+                # (coordinator._resolve_identity) -- which can be a long
+                # while for an appliance that is off, since an entry loads
+                # from its snapshot in the meantime (issue #295). The UUID
+                # check below can't see such an entry, so re-adding this
+                # very appliance during that window would be waved through
+                # as a second entry; the two would then collide the moment
+                # the older one re-keyed, and rekey_entry resolves a
+                # collision by *deleting* the duplicate rows -- taking the
+                # original entry's entity_ids, history and automations with
+                # them. Matched on the legacy key together with the host, so
+                # issue #381's two units (same serial, different addresses)
+                # stay separable.
+                legacy_unique_id = f"localthings_{info['serial']}"
+                if any(
+                    other.unique_id == legacy_unique_id
+                    and other.data.get(CONF_HOST) == self._host
+                    and CONF_DEVICE_KEY not in other.data
+                    for other in existing
+                ):
+                    return self.async_abort(reason="already_configured")
+                # Keyed on the OCF device UUID rather than the serialNum
+                # (issue #381): two units of a model that ship the same
+                # well-formed serial are indistinguishable here otherwise,
+                # and the second one is turned away as already configured.
+                await self.async_set_unique_id(f"localthings_{info['device_key']}")
                 self._abort_if_unique_id_configured()
                 if info["device_type_recognized"]:
                     return self._create_entry(info)
@@ -764,7 +943,7 @@ class LocalThingsConfigFlow(config_entries.ConfigFlow, domain=DOMAIN):
 
         return self.async_show_form(
             step_id=step_id,
-            data_schema=schema,
+            data_schema=self.add_suggested_values_to_schema(schema, user_input),
             errors=errors,
         )
 
@@ -808,15 +987,27 @@ class LocalThingsOptionsFlow(config_entries.OptionsFlow):
     def __init__(self) -> None:
         self._debug_href: str = ""
         self._debug_result: tuple[int, dict] | None = None
+        # Guided download-cycle setup. `_cloud_task` is created once per
+        # round and reused across re-entries (Home Assistant re-enters a
+        # progress step while its spinner is up).
+        self._cloud_task: asyncio.Task[str | None] | None = None
+        self._cloud_slot: str | None = None
+        self._cloud_baseline: str | None = None
 
     def _coordinator(self):
         return self.hass.data.get(DOMAIN, {}).get(self.config_entry.entry_id)
 
     async def async_step_init(self, user_input: dict[str, Any] | None = None) -> ConfigFlowResult:
-        return self.async_show_menu(
-            step_id="init",
-            menu_options=["settings", "debug_write"],
-        )
+        menu = ["settings", "forget_learned_modes", "debug_write"]
+        # Only offered on an appliance that actually advertises downloaded
+        # programs (issue #342) -- every other device would get a menu entry
+        # leading to an empty screen.
+        coord = self._coordinator()
+        if coord is not None and cloudcourse.supports_cloud_courses(
+            coord.cloud_course_rep(), cycle_options(coord.canonical_resources(MAIN))
+        ):
+            menu.insert(1, "cloud_courses")
+        return self.async_show_menu(step_id="init", menu_options=menu)
 
     async def async_step_settings(
         self, user_input: dict[str, Any] | None = None
@@ -839,10 +1030,446 @@ class LocalThingsOptionsFlow(config_entries.OptionsFlow):
                             DEFAULT_FINISH_TIME_HYSTERESIS_MINUTES,
                         ),
                     ): _HYSTERESIS_MINUTES,
+                    vol.Required(
+                        CONF_LEARN_MODES,
+                        default=self.config_entry.options.get(
+                            CONF_LEARN_MODES, DEFAULT_LEARN_MODES
+                        ),
+                    ): bool,
+                    vol.Required(
+                        CONF_CLOUD_COURSES_ENABLED,
+                        default=self.config_entry.options.get(
+                            CONF_CLOUD_COURSES_ENABLED, DEFAULT_CLOUD_COURSES_ENABLED
+                        ),
+                    ): bool,
                 }
             ),
         )
 
+    async def async_step_forget_learned_modes(
+        self, user_input: dict[str, Any] | None = None
+    ) -> ConfigFlowResult:
+        """Confirm-and-clear for the learned-mode store (issue #327).
+
+        The point of learning is that it's permanent, so a code learned
+        from a one-off firmware hiccup would otherwise sit in an option
+        list forever. An empty schema renders as a plain confirmation
+        form; the description lists what's about to be forgotten.
+        """
+        coord = self._coordinator()
+        # learned.py owns the entry key and the persisted shape, so this
+        # step never parses or writes it itself -- including on an unloaded
+        # entry, where a malformed record would otherwise abort the one
+        # screen that can clear it.
+        learned = (
+            coord.learned_snapshot() if coord is not None else learned_stored(self.config_entry)
+        )
+        codes = sorted({code for codes in learned.values() for code in codes})
+
+        if user_input is not None:
+            if coord is not None:
+                coord.forget_learned_modes()
+            else:
+                learned_persist(self.hass, self.config_entry, {})
+            return self.async_create_entry(data=dict(self.config_entry.options))
+
+        return self.async_show_form(
+            step_id="forget_learned_modes",
+            data_schema=vol.Schema({}),
+            description_placeholders={"codes": ", ".join(codes) if codes else "(none)"},
+        )
+
+    async def async_step_cloud_courses(
+        self, user_input: dict[str, Any] | None = None
+    ) -> ConfigFlowResult:
+        """Entry point for download-cycle setup (issue #342).
+
+        Guided setup is offered first because it is the only version of this
+        that a first-time user can complete confidently: it asks about a
+        program in the moment they select it, rather than about a list of hex
+        ids some time later. The bulk form stays for renaming afterwards,
+        which guided setup is bad at.
+
+        Setup still works with cloud_courses_enabled off (see
+        CONF_CLOUD_COURSES_ENABLED's own comment for why) -- someone who
+        wants to name one cycle without turning the feature fully on for
+        everything else still can (issue #364). The catalog's own
+        description covers that state directly rather than through a
+        description_placeholder built here: a placeholder is a literal
+        substitution HA never runs back through translation, so an
+        English sentence assembled in Python would show untranslated text
+        in every other locale -- unlike the SmartThings screen names
+        quoted elsewhere in this catalog, which stay English everywhere
+        because that's a third-party app's own label, not one of ours.
+        """
+        return self.async_show_menu(
+            step_id="cloud_courses",
+            menu_options=["cloud_guided", "cloud_manual"],
+        )
+
+    @callback
+    def async_remove(self) -> None:
+        """Stop probing when the flow goes away.
+
+        Closing the dialog is the documented way to leave guided setup, so it
+        has to actually stop: an abandoned round would otherwise go on
+        live-reading /course/vs/0 every few seconds until its timeout, taking
+        the session lock each time, for a user who has walked away.
+        """
+        if self._cloud_task is not None and not self._cloud_task.done():
+            self._cloud_task.cancel()
+        self._cloud_task = None
+
+    async def async_step_cloud_guided(
+        self, user_input: dict[str, Any] | None = None
+    ) -> ConfigFlowResult:
+        """Start (or restart) a guided discovery round."""
+        coord = self._coordinator()
+        if coord is None:
+            return self.async_abort(reason="not_loaded")
+        self._cloud_task = None
+        self._cloud_slot = None
+        # Baseline: whatever is loaded right now. The round completes when
+        # the appliance moves off it, so the program the user has *already*
+        # selected can't immediately re-trigger and loop the flow.
+        self._cloud_baseline = cloudcourse.loaded_slot(coord.cloud_course_rep())
+        return await self.async_step_cloud_wait()
+
+    async def async_step_cloud_wait(
+        self, user_input: dict[str, Any] | None = None
+    ) -> ConfigFlowResult:
+        """Wait for the user to select a different downloaded program.
+
+        The task is created once and reused across re-entries -- Home
+        Assistant polls this step while the spinner is up, and building a
+        fresh task each time would restart the wait forever.
+        """
+        coord = self._coordinator()
+        if coord is None:
+            return self.async_abort(reason="not_loaded")
+
+        if self._cloud_task is None:
+            self._cloud_task = self.hass.async_create_task(
+                self._await_cloud_selection(coord), eager_start=False
+            )
+        if not self._cloud_task.done():
+            return self.async_show_progress(
+                step_id="cloud_wait",
+                progress_action="cloud_wait",
+                progress_task=self._cloud_task,
+                description_placeholders=self._cloud_progress_placeholders(coord),
+            )
+
+        self._cloud_slot = self._cloud_task.result()
+        self._cloud_task = None
+        if self._cloud_slot is None:
+            return self.async_show_progress_done(next_step_id="cloud_timeout")
+        return self.async_show_progress_done(next_step_id="cloud_name")
+
+    async def _await_cloud_selection(self, coord) -> str | None:
+        """Poll until the loaded program changes; None on timeout."""
+        deadline = time.monotonic() + _CLOUD_WAIT_TIMEOUT_S
+        while time.monotonic() < deadline:
+            slot = await coord.async_probe_cloud_courses()
+            # Only a slot the store actually recorded. The probe reports
+            # whatever payload is loaded, while observe() declines one whose
+            # slot the device doesn't advertise -- offering to name that would
+            # take a name and silently discard it, since there is no record to
+            # hang it on and no payload to replay.
+            if (
+                slot is not None
+                and slot != self._cloud_baseline
+                and coord.cloud_courses.snapshot()["slots"].get(slot)
+            ):
+                return slot
+            await asyncio.sleep(_CLOUD_PROBE_INTERVAL_S)
+        return None
+
+    def _cloud_progress_placeholders(self, coord) -> dict[str, str]:
+        """Counts plus the names assigned so far.
+
+        Listing them is what makes a nine-program walk followable -- it is
+        the only orientation available, since the programs still to do are
+        unnamed by definition. Shown while naming too, where it doubles as
+        duplicate avoidance: the form rejects a repeated name, so seeing the
+        others first beats being bounced.
+
+        In the appliance's own advertised order, which is at least a stable
+        order, without numbering them -- whether that order matches the dial
+        is plausible but unverified, and implying it would be worse than
+        saying nothing.
+        """
+        rep = coord.cloud_course_rep()
+        courses = cycle_options(coord.canonical_resources(MAIN))
+        record = coord.cloud_courses.snapshot()
+        slots = cloudcourse.cloud_slots(rep, courses)
+        names = [n for s in slots if (n := (record["slots"].get(s) or {}).get("name"))]
+        return {
+            "named": str(len(names)),
+            "total": str(len(slots)),
+            "named_list": ", ".join(names) if names else "none yet",
+        }
+
+    async def async_step_cloud_name(
+        self, user_input: dict[str, Any] | None = None
+    ) -> ConfigFlowResult:
+        """Name the program the user just selected.
+
+        Persists immediately rather than batching to the end of the flow, so
+        closing the dialog at any point is a clean "save and exit" -- there is
+        no pending work to lose, and reopening resumes from the store.
+        """
+        coord = self._coordinator()
+        if coord is None or self._cloud_slot is None:
+            return self.async_abort(reason="not_loaded")
+        slot = self._cloud_slot
+        existing = (coord.cloud_courses.snapshot()["slots"].get(slot) or {}).get("name", "")
+
+        if user_input is not None:
+            # Rebuilt into the shared validator's shape. `download_course`
+            # is forwarded only when this form actually carried it, so its
+            # absence still means "not asked about" rather than "clear it".
+            payload: dict[str, Any] = {f"name_{slot}": str(user_input.get("name", "")).strip()}
+            if "download_course" in user_input:
+                payload["download_course"] = user_input["download_course"]
+            errors = self._apply_cloud_course_names(coord, [slot], payload)
+            if errors:
+                return self._cloud_name_form(coord, slot, existing, errors=errors)
+            # Straight back to waiting: the appliance is still sitting on this
+            # program, and the next round baselines on it, so there is nothing
+            # to click through.
+            self._cloud_baseline = slot
+            return await self.async_step_cloud_wait()
+
+        return self._cloud_name_form(coord, slot, existing)
+
+    def _cloud_name_form(
+        self, coord, slot: str, existing: str, errors: dict[str, str] | None = None
+    ) -> ConfigFlowResult:
+        """One text field, with the copy switched on whether this program is
+        already set up. Re-selecting one is not an error -- it is how someone
+        checks their work -- so it gets an edit form rather than a rejection,
+        and the counter deliberately does not move.
+
+        The Download course joins the form the first time round, and only
+        until it is confirmed. Guided setup would otherwise finish having
+        collected names but no course, and a program needs both before it can
+        be offered -- so the whole walk would produce nothing selectable. It
+        is asked here rather than up front because this is the first moment
+        there is evidence to prefill: the user has just loaded a program, so
+        the course showing alongside it is the Download one.
+        """
+        placeholders = self._cloud_progress_placeholders(coord)
+        placeholders["slot"] = slot
+        placeholders["remaining"] = (
+            coord.resource("/operational/state/vs/0").get("x.com.samsung.da.remainingTime") or "--"
+        )
+        fields: dict[Any, Any] = {vol.Optional("name", default=existing): _TEXT}
+        if not coord.cloud_courses.snapshot()["download_course"]:
+            fields[
+                vol.Optional("download_course", description={"suggested_value": self._cloud_course})
+            ] = self._cloud_course_selector(coord)
+        return self.async_show_form(
+            step_id="cloud_name",
+            data_schema=vol.Schema(fields),
+            errors=errors or {},
+            description_placeholders=placeholders,
+            last_step=False,
+        )
+
+    @property
+    def _cloud_course(self) -> str | None:
+        """The best observed candidate, narrowed to what the selector offers.
+
+        Unfiltered, a candidate the appliance's own course list no longer
+        contains would prefill a dropdown that rejects it, and the form would
+        fail validation on a value the user never chose.
+        """
+        coord = self._coordinator()
+        if coord is None:
+            return None
+        available = cycle_options(coord.canonical_resources(MAIN))
+        return next((c for c in coord.cloud_courses.download_candidates() if c in available), None)
+
+    def _cloud_course_selector(self, coord):
+        """The appliance's own course codes, observed candidates first.
+
+        custom_value stays off deliberately: whatever lands here becomes the
+        Course_ token of a real write, and a typed-in code the appliance
+        doesn't offer would start something nobody chose.
+        """
+        available = cycle_options(coord.canonical_resources(MAIN))
+        candidates = [c for c in coord.cloud_courses.download_candidates() if c in available]
+        ordered = candidates + [c for c in available if c not in candidates]
+        return SelectSelector(
+            SelectSelectorConfig(
+                options=ordered,
+                custom_value=False,
+                mode=SelectSelectorMode.DROPDOWN,
+            )
+        )
+
+    async def async_step_cloud_timeout(
+        self, user_input: dict[str, Any] | None = None
+    ) -> ConfigFlowResult:
+        """Nothing was selected in time. Offer another round rather than
+        dropping the user out of the flow -- and an explicit finish, for
+        anyone who doesn't think to close the dialog."""
+        coord = self._coordinator()
+        if coord is None:
+            return self.async_abort(reason="not_loaded")
+        return self.async_show_menu(
+            step_id="cloud_timeout",
+            menu_options=["cloud_guided", "cloud_finish"],
+            description_placeholders=self._cloud_progress_placeholders(coord),
+        )
+
+    async def async_step_cloud_finish(
+        self, user_input: dict[str, Any] | None = None
+    ) -> ConfigFlowResult:
+        return self.async_create_entry(data=dict(self.config_entry.options))
+
+    async def async_step_cloud_manual(
+        self, user_input: dict[str, Any] | None = None
+    ) -> ConfigFlowResult:
+        """Name the cloud "Download" programs this appliance has (issue #342).
+
+        The device advertises how many downloaded programs it holds but never
+        what any of them is called, and only ever exposes the replay payload
+        for the one currently loaded. So this screen can only offer the ones
+        already seen loaded, and asks the user for the names -- the appliance
+        has no name to give and inventing one is not an option (the same rule
+        that governs unrecognized local course codes).
+
+        Also confirms which course code means Download. It is auto-detected
+        by observation, but never used for a write until confirmed here: the
+        options array replaces tokens by prefix and never evicts them, so a
+        stale program token can be reported alongside an unrelated course and
+        make an ordinary wash cycle look like the Download one. Writing the
+        wrong code would start the wrong cycle.
+        """
+        coord = self._coordinator()
+        if coord is None:
+            return self.async_abort(reason="not_loaded")
+
+        store = coord.cloud_courses
+        rep = coord.cloud_course_rep()
+        record = store.snapshot()
+        slots = record["slots"]
+        advertised = cloudcourse.cloud_slots(rep, cycle_options(coord.canonical_resources(MAIN)))
+        # Learned slots keep the appliance's own ordering; anything learned
+        # but no longer advertised still gets a row so a name isn't stranded.
+        known = [s for s in advertised if s in slots] + [s for s in slots if s not in advertised]
+
+        if user_input is not None:
+            errors = self._apply_cloud_course_names(coord, known, user_input)
+            if not errors:
+                return self.async_create_entry(data=dict(self.config_entry.options))
+            return self._cloud_courses_form(coord, known, advertised, errors=errors)
+
+        return self._cloud_courses_form(coord, known, advertised)
+
+    def _apply_cloud_course_names(self, coord, known, user_input) -> dict[str, str]:
+        """Validate and store the submitted names + Download course code.
+
+        The select maps a chosen label back to a raw value by matching display
+        text, so two options sharing a label resolve to whichever comes first.
+        Two sources of collision are checkable here and both are rejected:
+        the user's own names against each other, and against the appliance's
+        personal-course labels, which the device reports verbatim and the
+        select renders as-is.
+
+        A collision with a *translated* local course name is deliberately not
+        checked. The catalog this process can read is English (catalog.py),
+        while what the user actually sees is localized in the frontend -- so
+        checking it would reject "Cotton" for a German user whose dropdown
+        says "Baumwolle", and still miss the real collision when they type
+        "Baumwolle". Wrong in both directions outside one locale, against an
+        outcome the option ordering already makes deterministic (local
+        courses come first, so a shared label resolves to the real cycle).
+        """
+        names = {slot: str(user_input.get(f"name_{slot}", "")).strip() for slot in known}
+        stored_slots = coord.cloud_courses.snapshot()["slots"]
+        taken = {name.casefold() for name in self._device_course_names(coord)}
+        # Programs this form isn't editing. The bulk form edits every slot at
+        # once so this adds nothing there, but guided setup submits one at a
+        # time -- without it, naming two programs the same was accepted, and
+        # the select resolves a shared label to whichever option comes first,
+        # so picking the second would run the first one's payload.
+        taken |= {
+            record["name"].casefold()
+            for slot, record in stored_slots.items()
+            if record["name"] and slot not in known
+        }
+        for name in names.values():
+            if not name:
+                continue
+            if name.casefold() in taken:
+                return {"base": "cloud_course_name_duplicate"}
+            taken.add(name.casefold())
+
+        # Absent means "this form didn't ask" -- the guided name form drops
+        # the field once the course is confirmed -- which must leave the
+        # stored value alone rather than clearing it. A program is only
+        # offerable when both a name and the course are set, so clearing it
+        # here would make naming things remove them from the cycle list.
+        if "download_course" not in user_input:
+            coord.apply_cloud_courses(names)
+            return {}
+
+        # Belt and braces over the selector's own custom_value=False: this
+        # value becomes the Course_ token of a real write, so it is checked
+        # against the appliance's own course list here too, where the store
+        # is actually updated.
+        course = user_input.get("download_course") or None
+        if course is not None and course not in cycle_options(coord.canonical_resources(MAIN)):
+            return {"base": "cloud_course_unknown_course"}
+
+        coord.apply_cloud_courses(names, course)
+        return {}
+
+    def _device_course_names(self, coord) -> set[str]:
+        """Course names this appliance reports itself.
+
+        Only the personal-course labels: the device sends these as text and
+        the select renders them unchanged, so they are the same string in
+        every locale and can be compared against safely. See the caller for
+        why translated course names are not included.
+        """
+        resources = coord.canonical_resources(MAIN)
+        personal = personal_course_labels(resources)
+        return {name for code in cycle_options(resources) if (name := personal.get(code.upper()))}
+
+    def _cloud_courses_form(
+        self, coord, known, advertised, errors: dict[str, str] | None = None
+    ) -> ConfigFlowResult:
+        store = coord.cloud_courses
+        record = store.snapshot()
+        slots = record["slots"]
+
+        fields: dict[Any, Any] = {}
+        for slot in known:
+            fields[vol.Optional(f"name_{slot}", default=slots.get(slot, {}).get("name", ""))] = (
+                _TEXT
+            )
+
+        suggested = record["download_course"] or self._cloud_course
+        fields[vol.Optional("download_course", description={"suggested_value": suggested})] = (
+            self._cloud_course_selector(coord)
+        )
+
+        pending = [s for s in advertised if s not in slots]
+        return self.async_show_form(
+            step_id="cloud_manual",
+            data_schema=vol.Schema(fields),
+            errors=errors or {},
+            description_placeholders={
+                "found": str(len(known)),
+                "total": str(len(advertised)) if advertised else str(len(known)),
+                "pending": ", ".join(pending) if pending else "(none)",
+            },
+        )
+
     async def async_step_debug_write(
         self, user_input: dict[str, Any] | None = None
     ) -> ConfigFlowResult:
@@ -912,8 +1539,33 @@ class LocalThingsOptionsFlow(config_entries.OptionsFlow):
                 return self._show_debug_edit_form(
                     href, current, {"payload": "empty_payload"}, payload
                 )
+            # Goes through the write_resource service (issue #300), not
+            # coord.async_raw_write directly, so there is exactly one code
+            # path that performs a raw write. MAIN's own device -- the
+            # panel's href dropdown already lists actual hrefs off
+            # coord.last_resources, and MAIN.to_actual is identity, so
+            # this preserves the panel's existing behavior byte for byte.
+            dev = dr.async_get(self.hass).async_get_device(
+                identifiers=coord.device_info["identifiers"]
+            )
+            if dev is None:
+                return self.async_abort(reason="not_loaded")
             try:
-                code, new_rep = await coord.async_raw_write(href, payload)
+                response = await self.hass.services.async_call(
+                    DOMAIN,
+                    SERVICE_WRITE_RESOURCE,
+                    {"writes": [{"href": href, "payload": payload}]},
+                    target={"device_id": dev.id},
+                    blocking=True,
+                    return_response=True,
+                )
+                results = (response or {}).get("results")
+                first = results[0] if isinstance(results, list) and results else None
+                raw_code = first.get("raw_code") if isinstance(first, dict) else None
+                after = first.get("after") if isinstance(first, dict) else None
+                if not isinstance(raw_code, int) or not isinstance(after, dict):
+                    raise RuntimeError("write_resource service returned an unexpected shape")
+                code, new_rep = raw_code, after
             except Exception:
                 _LOGGER.exception("debug raw write failed for %s", href)
                 return self._show_debug_edit_form(href, current, {"base": "write_failed"}, payload)

custom_components/localthings/const.py

@@ -30,10 +30,53 @@ CONF_LEAF_KEY_PEM = "leaf_key_pem"
 # output, the host itself for a placeholder-serial board -- issues
 # #83/#189), so it matches what _run_discovery computes on the first poll.
 CONF_SERIAL = "serial"
+# What this entry's devices and entities are keyed on -- normally the OCF
+# device UUID (issue #381). CONF_SERIAL stays alongside it as the pre-v4
+# key to re-key from, and as what corroborates a later change of UUID.
+# Absent until the first live poll, since only the device can report it.
+CONF_DEVICE_KEY = "device_key"
 CONF_MODEL = "model"
 CONF_MANUFACTURER = "manufacturer"
 CONF_DEVICE_TYPE = "device_type"
 
+# entry.data key: modes this device reported itself in but never advertised
+# in the same resource's supportedModes (issue #327). Stored on the entry
+# rather than kept in memory so a mode the device only names while it is
+# active survives a restart -- see learned.py. Shape:
+# {actual_href: [code, ...]}.
+CONF_LEARNED_MODES = "learned_modes"
+
+# Options-flow key: whether learned modes are remembered and offered.
+# Defaults to on; turning it off stops both halves at once (nothing new is
+# learned, nothing already learned is offered) without discarding what was
+# already remembered -- the options flow's reset step does that.
+CONF_LEARN_MODES = "learn_device_modes"
+DEFAULT_LEARN_MODES = True
+
+# entry.data key: cloud "Download" programs discovered on a laundry device
+# (issue #342). Same rationale as CONF_LEARNED_MODES -- a program's full
+# replay payload is only ever visible while the device happens to be sitting
+# on it, so it has to survive a restart -- but a richer shape, because a
+# cloud program also needs a user-supplied name and the device's own
+# Download course code. See cloudcourse.py, which owns the shape. Shape:
+# {"download_course": "87"|null, "slots": {slot: {"blob": ..., "name": ...}}}
+CONF_CLOUD_COURSES = "cloud_courses"
+
+# Options-flow key: whether downloaded programs are offered as selectable
+# cycles and nagged about via the "not set up yet" Repair (issue #364).
+# Defaults to on. Unlike CONF_LEARN_MODES this does not also stop passive
+# observation -- a device that merely *advertises* download slots without
+# the owner ever meaning to use them (SmartThings appears to seed one from
+# the cloud automatically, per #364's reporters) is exactly the case this
+# exists for, and turning it off is the fix. Guided/manual setup stay
+# reachable and still record what they see either way: they are a deliberate
+# per-session action, not the passive background behavior this silences, and
+# leaving them working means flipping the option back on immediately surfaces
+# anything set up in the meantime instead of asking the user to redo it. See
+# coordinator.cloud_courses_enabled for exactly what it gates.
+CONF_CLOUD_COURSES_ENABLED = "cloud_courses_enabled"
+DEFAULT_CLOUD_COURSES_ENABLED = True
+
 # Options-flow key (entry.options, not entry.data): lets a user override
 # the device-wide remote-control-off write block for a specific device
 # (issue #54). Some devices accept certain writes even while reporting
@@ -96,3 +139,9 @@ SUMMARY_INTERVAL_S = 30.0
 DEVICE_SUPPORT_ISSUE_URL = (
     "https://github.com/mbillow/localthings/issues/new?template=device-support.yml"
 )
+
+# Service names (services.py), shared with config_flow.py so the
+# options-flow debug panel calls the exact same service a user could call
+# from an automation (issue #300) -- one code path performs a raw write.
+SERVICE_WRITE_RESOURCE = "write_resource"
+SERVICE_READ_RESOURCE = "read_resource"

custom_components/localthings/diagnostics.py

@@ -16,8 +16,10 @@ from homeassistant.config_entries import ConfigEntry
 from homeassistant.core import HomeAssistant
 from homeassistant.loader import async_get_integration
 
+from . import cloudcourse
 from .const import DOMAIN
 from .coordinator import LocalThingsCoordinator
+from .registry.capabilities.laundry import cycle_options
 from .registry.redact import redact_resources
 from .registry.subdevices import MAIN
 
@@ -32,6 +34,7 @@ async def async_get_config_entry_diagnostics(
     # disk (listdir + open + read_text), which trips HA's event-loop blocking
     # detector when called inline here. Offload it to the executor.
     stl_version = await hass.async_add_executor_job(pkg_version, "smartthings-local")
+    cloud_courses = coordinator.cloud_courses.snapshot()
 
     # /oic/p, /oic/d, and /oic/res sit outside the /device/0 batch captured
     # below, so they'd otherwise never reach an issue report. /oic/d's `rt`
@@ -54,7 +57,7 @@ async def async_get_config_entry_diagnostics(
         # than redacting /information/vs/0 again -- modelNum never matches
         # redact.py's substring rules, so the value is the same either way.
         matching = [b for b in coordinator.bound if b.subdevice == su]
-        res = redact_resources(coordinator.canonical_resources(su))
+        res = redact_resources(coordinator.device_resources(su))
         return {
             "kind": su.kind,
             "key": su.key,
@@ -88,7 +91,7 @@ async def async_get_config_entry_diagnostics(
         # /mode/vs/0 under no attribution. Each sibling reports its own
         # resources in `subdevices` below instead. For a device with no
         # subdevices, this is byte-identical to `last_resources`.
-        "resources": redact_resources(coordinator.canonical_resources(MAIN)),
+        "resources": redact_resources(coordinator.device_resources(MAIN)),
         # Sibling indoor subdevices discovered on this connection (issue
         # #177). subdeviceIdList (the UUID a prefixed subdevice's key comes
         # from) is deliberately NOT redacted here, unlike elsewhere in
@@ -128,6 +131,34 @@ async def async_get_config_entry_diagnostics(
         # about the connection rather than one subdevice's state, and
         # nothing polls it after discovery so it would go stale in there.
         "multidevice": redact_resources(coordinator._multidevice),
+        # Modes this unit reported itself in but never advertised (issue
+        # #327). Reported separately from `resources` on purpose: the dump
+        # above stays exactly what the device said, so a triager can still
+        # see the gap these codes were inferred from. Keyed by actual href,
+        # like the store itself.
+        "learned_modes": {
+            "enabled": coordinator.learning_enabled,
+            "codes": coordinator.learned_snapshot(),
+        },
+        # Cloud "Download" programs discovered on this device (issue #342),
+        # reported separately from `resources` for the same reason as
+        # learned_modes above -- the dump there stays exactly what the device
+        # said, and this is what the integration made of it.
+        #
+        # Reported in full, names included. Half of what can go wrong with
+        # this feature is a configuration question -- which programs got
+        # named, which Download course was confirmed, whether a payload was
+        # ever captured for a slot the device advertises -- and none of that
+        # is answerable from the payloads alone. The names are the user's own
+        # words, so this is the one place they appear; they reach a dump only
+        # because its owner chose to download and share it.
+        "cloud_courses": {
+            "advertised_slots": cloudcourse.advertised_slots(coordinator.cloud_course_rep()),
+            "cloud_slots": cloudcourse.cloud_slots(
+                coordinator.cloud_course_rep(), cycle_options(coordinator.device_resources(MAIN))
+            ),
+            **cloud_courses,
+        },
         "integration_version": integration.version,
         "smartthings_local_version": stl_version,
         "observe_mode": coordinator.observe_mode,

custom_components/localthings/entity.py

@@ -35,12 +35,16 @@ def _is_included(bound: BoundEntity, coordinator: LocalThingsCoordinator) -> boo
     `bound`'s own subdevice's canonical view instead of the raw snapshot,
     same rule as everywhere else a whole-resources-dict scan happens --
     this is a free function, so it can't use self._resources.
+
+    Reads `discovery_resources`, not `last_resources`: on an offline load
+    (issue #295) the live cache is still empty, and judging existence
+    against it would filter every rehydrated entity away.
     """
-    rep = coordinator.last_resources.get(bound.href)
+    rep = coordinator.discovery_resources.get(bound.href)
     if rep is None:
         return False
     if bound.desc.exists_fn is not None:
-        return bound.desc.exists_fn(rep, coordinator.canonical_resources(bound.subdevice))
+        return bound.desc.exists_fn(rep, coordinator.discovery_canonical(bound.subdevice))
     if bound.desc.field:
         if not rep or is_stub_rep(rep):
             return True
@@ -84,7 +88,7 @@ class LocalThingsEntity(CoordinatorEntity[LocalThingsCoordinator]):
         super().__init__(coordinator)
         self._bound = bound
         self._state_key = _key(bound)
-        self._attr_unique_id = f"{DOMAIN}_{coordinator.device_serial}_{self._state_key}"
+        self._attr_unique_id = f"{DOMAIN}_{coordinator.device_key}_{self._state_key}"
         if bound.desc.translation_placeholders is not None:
             self._attr_translation_placeholders = dict(bound.desc.translation_placeholders)
         elif bound.desc.use_instance_name:

custom_components/localthings/learned.py

@@ -0,0 +1,128 @@
+"""Modes a device reports itself in but never advertises as supported.
+
+Some firmwares report a current mode that is missing from the same
+resource's own supported list (issue #327: an ARTIK051 air conditioner
+sitting in 'Quiet' with supportedModes [Off, Sleep, Speed, Nano,
+NanoSleep]). The mode is real -- the remote and the SmartThings app select
+it, and the unit accepts it written back -- so once the device has been
+seen in it, it is remembered and offered alongside the advertised ones.
+
+Learning is deliberately not global. A current value that isn't a
+selectable option is common across this corpus -- an oven idling in
+'NoOperation', a fridge's /mode/vs/0 carrying capability tokens like
+'WATERFILTER_DISABLE' -- and remembering one of those permanently would
+put an option in the UI that the device can only reject. LEARNABLE names
+the canonical hrefs where a reported mode is known to be genuinely
+selectable, and the coordinator narrows it further to the hrefs this
+device actually binds a climate entity to (see _refresh_learnable_hrefs):
+the same href is declared explicitly unmodeled on a dehumidifier and
+empty on an air purifier, and learning for those would persist a code
+nothing ever offers.
+
+This module also owns the entry key the store persists under, so the
+shape lives in exactly one place.
+"""
+
+from __future__ import annotations
+
+import threading
+
+from .const import CONF_LEARNED_MODES
+from .registry.capabilities.airconditioner import HREF_CONVENIENT
+
+MODES_FIELD = "x.com.samsung.da.modes"
+SUPPORTED_FIELD = "x.com.samsung.da.supportedModes"
+
+# Convenient (preset) mode: firmware omits an active preset (e.g. Quiet)
+# from its own supportedModes -- a reporting gap, not a capability
+# difference (issue #327).
+LEARNABLE: frozenset[str] = frozenset({HREF_CONVENIENT})
+
+
+def _codes(value) -> list[str]:
+    """Mode codes from a `modes`-style field, which some firmwares send as
+    a bare string rather than an array."""
+    if isinstance(value, str):
+        return [value]
+    if isinstance(value, (list, tuple)):
+        return [v for v in value if isinstance(v, str)]
+    return []
+
+
+def _coerce(stored) -> dict[str, list[str]]:
+    """Restore the persisted map, dropping anything that isn't the shape
+    this module writes. It round-trips through the config entry as plain
+    JSON, and a hand-edited .storage file shouldn't be able to crash
+    setup."""
+    if not isinstance(stored, dict):
+        return {}
+    restored = {}
+    for href, codes in stored.items():
+        if isinstance(href, str) and (valid := [c for c in _codes(codes) if c]):
+            restored[href] = valid
+    return restored
+
+
+def stored(entry) -> dict[str, list[str]]:
+    """What `entry` has persisted, coerced -- for a reader that can't go
+    through a coordinator (the options flow, on an unloaded entry)."""
+    return _coerce(entry.data.get(CONF_LEARNED_MODES))
+
+
+def persist(hass, entry, codes: dict[str, list[str]]) -> None:
+    """Write `codes` onto the entry. Runs on the event loop, which
+    async_update_entry requires."""
+    hass.config_entries.async_update_entry(entry, data={**entry.data, CONF_LEARNED_MODES: codes})
+
+
+class LearnedModes:
+    """Per-device store of learned codes, keyed by actual (on-the-wire)
+    href so two subdevices of one composite appliance learn separately.
+
+    Mutated from whichever thread applied the update (the DTLS reader for
+    an OBSERVE notify, an executor thread for a poll -- see
+    ObserveManager.apply), so every access takes the lock; persistence is
+    the caller's job, on the event loop.
+    """
+
+    def __init__(self, stored=None) -> None:
+        self._lock = threading.Lock()
+        self._learned = _coerce(stored)
+
+    def observe(self, actual_href: str, rep: dict) -> list[str]:
+        """Learn from one applied rep; returns the codes newly learned, so
+        an empty list means there is nothing to persist.
+
+        A rep that carries no supported list teaches nothing: "missing from
+        the list" is only meaningful against a list that exists, and
+        inventing one for a device that publishes none would offer options
+        nothing ever said were selectable. `rep` is the merged rep
+        ObserveManager.apply stores, so a partial notify carrying `modes`
+        alone (issue #27) still sees the supported list from the last full
+        poll.
+        """
+        supported = _codes(rep.get(SUPPORTED_FIELD))
+        if not supported:
+            return []
+        with self._lock:
+            known = self._learned.get(actual_href, [])
+            new = [
+                code
+                for code in _codes(rep.get(MODES_FIELD))
+                if code and code not in supported and code not in known
+            ]
+            if new:
+                self._learned[actual_href] = [*known, *new]
+        return new
+
+    def codes(self, actual_href: str) -> list[str]:
+        with self._lock:
+            return list(self._learned.get(actual_href, ()))
+
+    def snapshot(self) -> dict[str, list[str]]:
+        with self._lock:
+            return {href: list(codes) for href, codes in self._learned.items()}
+
+    def clear(self) -> None:
+        with self._lock:
+            self._learned = {}

custom_components/localthings/manifest.json

@@ -1,6 +1,7 @@
 {
   "domain": "localthings",
   "name": "LocalThings",
+  "after_dependencies": ["recorder"],
   "codeowners": ["@mbillow"],
   "config_flow": true,
   "dependencies": [],
@@ -10,7 +11,7 @@
   "requirements": [
     "cbor2>=5.4.6",
     "pyOpenSSL>=23.0",
-    "smartthings-local>=0.1.2"
+    "smartthings-local>=0.1.8"
   ],
-  "version": "0.19.0"
+  "version": "0.24.0"
 }

custom_components/localthings/observe.py

@@ -14,6 +14,7 @@ from __future__ import annotations
 import logging
 import threading
 import time
+from collections.abc import Callable
 
 import cbor2
 from smartthings_local.ocf.observe_refresh import ObserveRefreshTask
@@ -55,6 +56,26 @@ SUCCESS_FRACTION = 0.8
 PUSH_HEALTH_WINDOW_S = 60.0
 
 
+def _is_alarms_href(href: str) -> bool:
+    """True for /alarms/vs/<index> in any subdevice-translated shape --
+    the canonical MAIN form (/alarms/vs/0), an indexed subdevice's
+    renumbered instance (/alarms/vs/<key>), or a prefixed subdevice's
+    UUID-qualified form (/<uuid>/alarms/vs/0). `Subdevice.to_actual`
+    (registry/subdevices.py) only ever rewrites the trailing index
+    segment or prepends a prefix -- it never touches the 'alarms/vs'
+    stem -- so matching that fixed segment plus a wildcard tail catches
+    every shape without this module needing to be subdevice-aware.
+
+    See `ObserveManager.apply`'s use of this for why the href matters:
+    unlike most resources, /alarms/vs/0's `x.com.samsung.da.items` array
+    is a complete snapshot of every currently-active alarm, not a
+    possibly-partial field update -- so it must never be merged onto a
+    stale prior rep (issue #348).
+    """
+    head, _, _ = href.rpartition("/")
+    return head.endswith("/alarms/vs")
+
+
 class ObserveManager:
     """Per-device observe-mode state: mode, write-settle guard, and (later)
     subscription/staleness tracking. Pure sync logic — safe to call from
@@ -74,13 +95,31 @@ class ObserveManager:
         self._notified: set[str] = set()
         self._last_notify_ts: float | None = None
         # Wakes try_enter_observe_mode's grace wait early once enough hrefs
-        # have notified. Guards only `_notified` mutations + the `wait_for`.
+        # have notified. Guards `_notified` mutations, the `wait_for`, and
+        # fallback_hrefs (enter_observe_mode assignment, on_notification
+        # discard).
         self._notify_cond = threading.Condition()
+        # Idle while polling, except after downgrade_to_poll (every href
+        # that was subscribed). While in observe mode this is the set of
+        # subscribed hrefs that have not yet notified (issue #92) -- they
+        # stay on the hot/warm sub-poll cadence. on_notification discards
+        # an href once it pushes, so a late first notify self-corrects.
         self.fallback_hrefs: set[str] = set()
+        self._on_applied: Callable[[str, dict, str], None] | None = None
         self._refresh_task: ObserveRefreshTask | None = None
         self._refresh_stop: threading.Event | None = None
         self._refresh_thread: threading.Thread | None = None
 
+    def set_on_applied(self, callback: Callable[[str, dict, str], None]) -> None:
+        """Hook run after every accepted rep, on the applying thread.
+
+        Unlike StateCache.set_on_change it carries the href and rep, and
+        fires even when the rep is unchanged -- which learned.py needs, a
+        device sitting in an unadvertised mode re-sending the same rep
+        every poll.
+        """
+        self._on_applied = callback
+
     def mark_write_pending(self, href: str, settle_s: float = DEFAULT_SETTLE_S) -> None:
         with self._settle_lock:
             self._settle_until[href] = time.monotonic() + settle_s
@@ -110,6 +149,20 @@ class ObserveManager:
         comes through, even though nothing about the device's actual
         supported options changed.
 
+        `_is_alarms_href` is the one exception to that merge (issue #348):
+        /alarms/vs/0's `items` array is always sent as a complete
+        snapshot of every currently-active alarm, never a partial delta
+        -- confirmed by a live `read_resource` GET returning `{}` (no
+        `items` key at all) the moment a washer's board actually clears
+        an alarm, which entity.py already documents as this resource's
+        normal no-alarm shape. Merging that `{}` onto the prior rep the
+        same way as everywhere else silently kept the stale `items`
+        entry forever: an absent key merges as "unchanged" everywhere
+        else, but on this href absent specifically means "cleared".
+        Every family that exposes an alarm sensor shares this href
+        (common.ALARMS, range_hood's own copy), so this is a full
+        replace for all of them, not a washer-specific carve-out.
+
         `apply()` is the sole path StateCache mutations flow through in
         this component (poll, sweep, and OBSERVE notify all funnel here),
         so `_cache_lock` serializes the read-then-write across those
@@ -137,8 +190,15 @@ class ObserveManager:
             self.log.debug("dropping %s update for %s (settling)", source, href)
             return False
         with self._cache_lock:
-            merged = {**(self.cache.get(href) or {}), **rep}
-            return self.cache.apply_rep(href, merged, source=source)
+            merged = dict(rep) if _is_alarms_href(href) else {**(self.cache.get(href) or {}), **rep}
+            changed = self.cache.apply_rep(href, merged, source=source)
+        # Outside the cache lock -- the hook takes locks of its own and
+        # never reads the cache back. `source` is passed along rather than
+        # filtered here: which sources are worth acting on is the hook's
+        # policy, not this manager's.
+        if self._on_applied is not None:
+            self._on_applied(href, merged, source)
+        return changed
 
     def on_notification(self, href: str, payload: bytes) -> None:
         """Wired as DtlsCoapSession.on_notification. Runs on the DTLS
@@ -152,6 +212,10 @@ class ObserveManager:
             return
         with self._notify_cond:
             self._notified.add(href)
+            # Snapshot in enter_observe_mode is at the 80% quorum, not the
+            # full grace period -- a late first push (blockwise refetch)
+            # must drop the href so we don't keep GET-polling a live one.
+            self.fallback_hrefs.discard(href)
             self._last_notify_ts = time.monotonic()
             self._notify_cond.notify_all()
         self.log.debug("observe notify: %s", href)
@@ -171,17 +235,16 @@ class ObserveManager:
             self._last_notify_ts is not None and time.monotonic() - self._last_notify_ts < window_s
         )
 
-    def try_enter_observe_mode(
-        self,
-        session,
-        hrefs: list[str],
-        grace_period_s: float = GRACE_PERIOD_S,
-        success_fraction: float = SUCCESS_FRACTION,
-    ) -> bool:
-        """Blocking — subscribes to every href then waits up to
-        `grace_period_s`, returning early once `success_fraction` of hrefs
-        have notified. Caller must run this in an executor, never on the
-        event loop."""
+    def subscribe_hrefs(self, session, hrefs: list[str]) -> set[str]:
+        """Register OBSERVE on every href; returns the ones that took.
+        Blocking — run in an executor.
+
+        Split from the grace wait below (issue #294) so the coordinator can
+        hold its session lock for just these sends -- each is a fire-and-
+        forget UDP datagram (DtlsCoapSession.subscribe doesn't wait for the
+        device's ack), unlike the wait, which can block for the whole grace
+        period and must not hold a lock a command write is also waiting on.
+        """
         with self._notify_cond:
             self._notified.clear()
         subscribed: set[str] = set()
@@ -192,30 +255,72 @@ class ObserveManager:
                 subscribed.add(href)
             except Exception as e:
                 self.log.warning("subscribe %s failed: %s", href, e)
+        return subscribed
+
+    def await_observe_notifies(
+        self,
+        subscribed: set[str],
+        grace_period_s: float = GRACE_PERIOD_S,
+        success_fraction: float = SUCCESS_FRACTION,
+    ) -> bool:
+        """Blocking — waits up to `grace_period_s`, returning early once
+        `success_fraction` of `subscribed` have notified. Touches no
+        session; safe to run without holding a session lock."""
         if not subscribed:
-            self._stop_refresh_task()
-            self._set_mode(MODE_POLL)
-            self.subscribed_hrefs = set()
             return False
 
         def _fraction_reached() -> bool:
             return len(set(self._notified) & subscribed) / len(subscribed) >= success_fraction
 
         with self._notify_cond:
-            reached = self._notify_cond.wait_for(
-                _fraction_reached,
-                timeout=grace_period_s,
-            )
+            return self._notify_cond.wait_for(_fraction_reached, timeout=grace_period_s)
 
-        if reached:
-            self.subscribed_hrefs = subscribed
-            self._set_mode(MODE_OBSERVE)
-            self.start_refresh_task(session)
-            return True
+    def enter_observe_mode(self, session, subscribed: set[str]) -> None:
+        """Commit a successful attempt. Caller must have re-confirmed
+        `session` is still the live one under its session lock (issue
+        #294) -- committing against a session a reconnect already replaced
+        would claim observe mode with nothing left to notice it's dead."""
+        self.subscribed_hrefs = set(subscribed)
+        # Issue #92: subscribed-but-silent hrefs are counted as covered by
+        # push if we drop this, but they never emit a notify. Keep them on
+        # the poll cadence via fallback_hrefs (otherwise idle in observe).
+        # Same lock as on_notification's discard so a notify in this window
+        # cannot land on a set object that is about to be replaced.
+        with self._notify_cond:
+            self.fallback_hrefs = set(subscribed) - self._notified
+        self._set_mode(MODE_OBSERVE)
+        self.start_refresh_task(session)
 
+    def abandon_observe_attempt(self) -> None:
+        """Drop a failed or stale attempt: no subscriptions worth keeping."""
         self._stop_refresh_task()
         self.subscribed_hrefs = set()
         self._set_mode(MODE_POLL)
+
+    def try_enter_observe_mode(
+        self,
+        session,
+        hrefs: list[str],
+        grace_period_s: float = GRACE_PERIOD_S,
+        success_fraction: float = SUCCESS_FRACTION,
+    ) -> bool:
+        """Blocking — subscribes to every href then waits up to
+        `grace_period_s`, returning early once `success_fraction` of hrefs
+        have notified. Caller must run this in an executor, never on the
+        event loop.
+
+        Single-threaded convenience wrapper around the phase split above
+        (subscribe_hrefs / await_observe_notifies / enter_observe_mode /
+        abandon_observe_attempt) for callers -- direct and most existing
+        tests -- that don't need the lock-scoping those phases exist for."""
+        subscribed = self.subscribe_hrefs(session, hrefs)
+        if not subscribed:
+            self.abandon_observe_attempt()
+            return False
+        if self.await_observe_notifies(subscribed, grace_period_s, success_fraction):
+            self.enter_observe_mode(session, subscribed)
+            return True
+        self.abandon_observe_attempt()
         return False
 
     def _set_mode(self, mode: str) -> None:

custom_components/localthings/registry/by_type/__init__.py

@@ -225,13 +225,16 @@ _OIC_TYPE_TO_KEY: dict[str, str] = {
     "oic.d.dishwasher": "dishwasher",
     "oic.d.dryer": "dryer",
     "oic.d.oven": "oven",
+    "oic.d.range": "range",  # issue #324 -- oven+cooktop combo, no /information/vs/0
     "oic.d.refrigerator": "refrigerator",
+    "oic.d.krefrigerator": "refrigerator",  # issue #328 -- kimchi refrigerator
     "oic.d.washer": "washer",
     "x.com.st.d.airqualitysensor": "air_monitor",
     "x.com.st.d.dehumidifier": "dehumidifier",
     "x.com.st.d.hood": "range_hood",  # AHD-WW-TP1-22-COMMON
     "x.com.st.d.stickcleaner": "vacuum_station",
     "x.com.st.d.steamcloset": "air_dresser",
+    "x.com.st.d.winecellar": "refrigerator",  # issue #328 -- same TP1X_REF_21K board
 }
 
 

custom_components/localthings/registry/by_type/airconditioner.py

@@ -17,7 +17,7 @@ uses unconditionally.
 Reuses dishwasher.DIAGNOSIS for /diagnosis/vs/0.
 """
 
-from ..capabilities import airconditioner, common, dishwasher, ignored
+from ..capabilities import air_purifier, airconditioner, common, dishwasher, ignored
 from ._base import DeviceRegistry, _build
 
 REGISTRY = DeviceRegistry(
@@ -46,6 +46,28 @@ REGISTRY = DeviceRegistry(
             airconditioner.CURRENT_TEMPERATURE,
             airconditioner.CURRENT_TEMPERATURE_VS,
             airconditioner.HUMIDITY,
+            # TP1X_DA-AC-FAC-class (issue #319): shares its /display/vs/0,
+            # /settings/sound/output/vs/0 and /settings/sound/volume/vs/0
+            # shape with the sibling TP1X_DA-AC-AIR board in air_purifier.py.
+            air_purifier.DISPLAY,
+            air_purifier.SOUND_OUTPUT,
+            air_purifier.SOUND_VOLUME,
+            airconditioner.SOUND_MODE,
+            airconditioner.ABSENCE_CLEAN,
+            airconditioner.MDS_ABSENCE_CLEAN,
+            airconditioner.ENERGY_SAVING,
+            airconditioner.EDGE_LIGHTING,
+            airconditioner.LIGHT_STATEFUL,
+            # System Fresh Air Ventilator (PR #316, ACA-KR-TP2-21-AN9000):
+            # WINDFREE/WINDSLEEP are this device's own hrefs; HEPA_FILTER/
+            # DEVICE_ACTIVE reuse air_purifier.py's identical shapes.
+            # AIR_LEVEL_CHECK is not this-device-specific -- see its
+            # removal from _AC_IGNORED above.
+            airconditioner.WINDFREE,
+            airconditioner.WINDSLEEP,
+            air_purifier.HEPA_FILTER,
+            air_purifier.DEVICE_ACTIVE,
+            air_purifier.AIR_LEVEL_CHECK,
             *airconditioner.COVERAGE,
         ]
     ),

custom_components/localthings/registry/by_type/cooktop.py

@@ -22,6 +22,12 @@ REGISTRY = DeviceRegistry(
             cooktop.COOKTOP_CONNECTED,
             cooktop.PAIRED_HOOD_STATUS,
             common.FIRMWARE_UPDATE,
+            # issue #314: /alarms/vs/0 and /kidslock/vs/0 are the same
+            # generic shapes common.UNIVERSAL already models elsewhere --
+            # picked individually rather than pulling in all of UNIVERSAL,
+            # matching this registry's existing hand-picked-common style.
+            common.ALARMS,
+            common.KIDS_LOCK_VS_FALLBACK,
         ]
     ),
 )

custom_components/localthings/registry/by_type/oven.py

@@ -1,6 +1,6 @@
 """Oven device registry."""
 
-from ..capabilities import common, ignored, oven
+from ..capabilities import common, dishwasher, ignored, oven
 from ._base import DeviceRegistry, _build
 
 REGISTRY = DeviceRegistry(
@@ -18,6 +18,9 @@ REGISTRY = DeviceRegistry(
             oven.OVEN_CONNECTED,
             oven.OVEN_SPEC,
             oven.OVEN_RECIPE_COOK,
+            # issue #300: /diagnosis/vs/0 is the same diagnosisStart shape
+            # dishwasher.py and airconditioner.py already reuse.
+            dishwasher.DIAGNOSIS,
         ]
     ),
 )

custom_components/localthings/registry/by_type/refrigerator.py

@@ -13,6 +13,11 @@ REGISTRY = DeviceRegistry(
             fridge.STATUS_LOCK,
             fridge.DOOR_ALERT,
             common.WATER_FILTER,
+            fridge.AIR_FILTER,
+            fridge.DEODOR_FILTER,
+            fridge.AUTO_DOOR_TIMER,
+            fridge.WINECELLAR_PANTRY_ZONE,
+            fridge.WINECELLAR_INFO,
             dishwasher.DIAGNOSIS,
             fridge.ICEMAKER_NIGHTTIME,
             fridge.FLEX_ZONE,
@@ -43,5 +48,6 @@ REGISTRY = DeviceRegistry(
         fridge.DOOR_GENERIC,
         fridge.KIMCHI_ZONE,
         fridge.KIMCHI_DOOR_GENERIC,
+        fridge.AUTO_DOOR_VARIANT,
     ],
 )

custom_components/localthings/registry/by_type/vacuum_station.py

@@ -1,9 +1,7 @@
-"""Stick-vacuum clean/auto-empty station device registry (issue #131).
+"""Stick-vacuum clean/auto-empty station device registry (issues #131 / #219).
 
-See capabilities/vacuum_station.py's module docstring for why this only
-covers the station's own dustbag/dustbin/UV-sanitize state and not any
-vacuum-body control (suction, battery, cleaning mode) -- the diagnostics
-dump this was built from reports none of that.
+Station dustbag/dustbin/UV-sanitize state plus, when present (VS9700),
+wand battery/charging via `/status/stick/vs/0`. No suction/room-map control.
 """
 
 from ..capabilities import common, ignored, vacuum_station
@@ -20,6 +18,7 @@ REGISTRY = DeviceRegistry(
             vacuum_station.DUSTBAG_USAGE,
             vacuum_station.DUSTBIN_SETTING,
             vacuum_station.CLEANSTATION_STATUS,
+            vacuum_station.STICK_BODY,
         ]
     ),
 )

custom_components/localthings/registry/capabilities/air_monitor.py

@@ -7,21 +7,29 @@ only); this registry deliberately doesn't include common.POWER.
 air_purifier.AIR_QUALITY and range_hood.AIR_QUALITY already read via
 common.sensor_item_value -- reused here rather than re-decoded, including
 the same dust/fine_dust/super_fine_dust/odor/clean_level keys so this
-device shares those capabilities' catalog entries. This board additionally
-reports a CO2 reading the other two families don't.
+device shares those capabilities' catalog entries. This board reports a
+CO2 reading; air_purifier.AIR_QUALITY now models the same type when a
+purifier lists it (issue #387).
 
-A second `value` list element on the particulate-matter types (e.g. Dust's
-`['31', '2']`) reads like a coarse quality-grade code, but nothing on this
-board confirms what its scale means -- left unbound rather than guessed;
-index 0 is the only slot any family has ever read.
+A second `value` list element on the particulate-matter types (Dust's
+`['31', '2']`) is the device's own graded air-quality level for that
+reading -- see common.sensor_item_value. Still unbound here: the grade's
+floor differs by board family, and CleanLevel already carries the
+aggregate. This board's own readings are load-bearing evidence for the
+PM mapping, though: 23 grading one step above the floor as FineDust is
+what rules out a PM10-width band for that field.
 
-Dust/FineDust/SuperFineDust aren't assigned an HA `device_class`
-(pm10/pm25/pm1) or `unit` despite reading like plausible ug/m3 particulate
-values: Samsung's own two-tier Korean convention maps only to a PM10/PM2.5
-pair, and this board's three-tier naming doesn't confirm where the extra
-tier or a PM1 reading fits. A wrong guess would silently mislabel every
-reading forever, so they're plain `measurement` sensors named after the
-device's own field instead, matching air_purifier.AIR_QUALITY's precedent.
+Dust/FineDust/SuperFineDust carry the same HA `device_class`/`unit` as the
+purifier family (issue #325, Dust=PM10 / FineDust=PM2.5 /
+SuperFineDust=PM1 in μg/m³). The mapping rests on device-side grading this
+board shares rather than on anything purifier-specific, so typing one
+family and not the other would have been an inconsistency, not caution.
+
+These sensors have recorded *unitless* long-term statistics since issue
+#210, though, and Home Assistant suppresses statistics generation outright
+for an entity whose unit no longer matches its recorded metadata -- so
+stamping a unit on would have silently stopped the history it was meant to
+label. __init__.py's v2->v3 entry migration relabels that metadata first.
 """
 
 from datetime import time as dt_time
@@ -31,6 +39,15 @@ from ..entities import BinarySensorDesc, SensorDesc, SwitchDesc, TimeDesc
 from .air_purifier import _AIR_QUALITY_SENSORS
 from .common import int_or_none, sensor_item_value
 
+# device_class/unit are taken from the shared rows; state_class deliberately
+# is not. air_purifier leaves Odor/CleanLevel unstamped because they read as
+# graded indices on that family, while this board has stamped all five as
+# `measurement` since it was added (issue #210) -- consuming that column
+# would silently drop long-term statistics for two sensors on shipped
+# devices. The pm10/pm25/pm1 labels carry over cleanly, though: they rest on
+# device-side grading this board shares (see the module docstring), and
+# __init__.py's v2->v3 entry migration relabels the unitless statistics
+# these five have been recording so the new unit doesn't suppress them.
 SENSORS = Capability(
     href="/sensors/vs/0",
     poll_tier="warm",
@@ -41,9 +58,11 @@ SENSORS = Capability(
                 field="x.com.samsung.da.items",
                 icon=icon,
                 state_class="measurement",
+                device_class=device_class,
+                unit=unit,
                 value_fn=lambda items, t=sensor_type: sensor_item_value(items, t),
             )
-            for key, icon, sensor_type in _AIR_QUALITY_SENSORS
+            for key, icon, sensor_type, _state_class, device_class, unit in _AIR_QUALITY_SENSORS
         ),
         SensorDesc(
             key="co2",

custom_components/localthings/registry/capabilities/air_purifier.py

@@ -34,7 +34,13 @@ from ..entities import (
     SwitchDesc,
     TimeDesc,
 )
-from .common import epoch_to_utc, filter_usage_percent, int_or_none, sensor_item_value
+from .common import (
+    epoch_to_utc,
+    filter_usage_percent,
+    has_sensor_type,
+    int_or_none,
+    sensor_item_value,
+)
 from .laundry import bool_option_exists, bool_option_value, option_value, option_write
 
 # Newer TP1X_DA-AC-AIR-class boards (issue #130) report fan modes directly
@@ -51,25 +57,90 @@ def _has_top_level_modes(rep, resources):
     return isinstance(rep.get("x.com.samsung.da.supportedModes"), (list, tuple))
 
 
+# Columns: key, icon, device item type, state_class, device_class, unit.
+# state_class is what makes Home Assistant keep long-term statistics --
+# without one, a reading is only in the short-term recorder history and
+# disappears with the next purge (10 days by default), so it can't back a
+# long-range air-quality graph. The values are already numeric
+# (sensor_item_value returns int); three sensors in this same module
+# (filter_progress, fan_speed_level, hepa_filter_usage) already declare one.
+#
+# Only the three particulate readings get it. They fall monotonically with
+# particle size on three independent board families -- 11/9/5 on ARTIK051_TVTL
+# (issue #56), 10/9/6 on AVT-WW-TP1 (issue #190), 18/14/9 on the range hood --
+# which is concentration behaviour, and an average over time is meaningful for
+# it. Odor and CleanLevel read 0-2 on every fixture and look like graded
+# indices instead, where the mean of a grade isn't obviously meaningful; left
+# without a state_class rather than guessing.
+#
+# device_class/unit: Dust=PM10, FineDust=PM2.5, SuperFineDust=PM1, all
+# μg/m³ (issue #325). Three independent lines, none of them naming order --
+# which is what the earlier "plausible but unconfirmed" note rejected:
+#
+#  1. The device grades its own readings. Each dust item's value[] is
+#     [concentration, grade] (see common.sensor_item_value); the grade band
+#     is not shared across the three fields -- a reading of 18 grades one
+#     step *above* the floor as SuperFineDust (air_monitor fixture) but *at*
+#     the floor as Dust (range_hood fixture), both 1-based families. So the
+#     firmware itself treats them as three different scales ordered
+#     coarse-to-fine, rather than one repeated measurement.
+#  2. Where each field's floor/second-band boundary falls brackets the
+#     Korean CAI bands: Dust good at 18, graded up at 31 (CAI PM10 breaks
+#     at 30/31); FineDust good at 14, graded up at 23 (CAI PM2.5 breaks at
+#     15/16); SuperFineDust good at 9, graded up at 18 (PM2.5-style, which
+#     is what a PM1 reading gets -- there is no standard PM1 index).
+#  3. A live ARTIK051_TVTL read against the SmartThings app at the same
+#     moment: Dust matched the app's PM10 exactly, the other two were 1
+#     μg/m³ off in the same order, and the app shows exactly these three
+#     tiers, so there is no fourth candidate to assign.
+#
+# Dust >= FineDust >= SuperFineDust holds on all 11 fixtures that report
+# this resource, which is the cumulative-mass ordering PM10 >= PM2.5 >= PM1
+# requires by definition. The unit literal must stay HA's own spelling of
+# μg/m³ (U+03BC GREEK SMALL LETTER MU, not U+00B5 MICRO SIGN) -- they render
+# alike but only U+03BC is in DEVICE_CLASS_UNITS, and the mismatch is a
+# runtime warning per entity, not a test failure. Pinned by
+# tests/test_sensor_device_class_units.py.
 _AIR_QUALITY_SENSORS = (
-    ("dust", "mdi:blur", "Dust"),
-    ("fine_dust", "mdi:blur", "FineDust"),
-    ("super_fine_dust", "mdi:blur", "SuperFineDust"),
-    ("odor", "mdi:scent", "Odor"),
-    ("clean_level", "mdi:air-filter", "CleanLevel"),
+    ("dust", "mdi:blur", "Dust", "measurement", "pm10", "μg/m³"),
+    ("fine_dust", "mdi:blur", "FineDust", "measurement", "pm25", "μg/m³"),
+    ("super_fine_dust", "mdi:blur", "SuperFineDust", "measurement", "pm1", "μg/m³"),
+    ("odor", "mdi:scent", "Odor", None, None, None),
+    ("clean_level", "mdi:air-filter", "CleanLevel", None, None, None),
 )
 
 AIR_QUALITY = Capability(
     href="/sensors/vs/0",
     poll_tier="warm",
-    entities=tuple(
+    entities=(
+        *(
+            SensorDesc(
+                key=key,
+                field="x.com.samsung.da.items",
+                icon=icon,
+                state_class=state_class,
+                device_class=device_class,
+                unit=unit,
+                value_fn=lambda items, t=sensor_type: sensor_item_value(items, t),
+            )
+            for key, icon, sensor_type, state_class, device_class, unit in _AIR_QUALITY_SENSORS
+        ),
+        # CO2 (issue #387) -- same field/shape air_monitor.SENSORS already
+        # models with device_class='carbon_dioxide'/unit='ppm'. Gated on the
+        # type being listed so boards that don't report it (every current
+        # fixture) don't grow an empty entity. Disabled by default for the
+        # same reason as airconditioner.AIR_QUALITY (issue #166).
         SensorDesc(
-            key=key,
+            key="co2",
             field="x.com.samsung.da.items",
-            icon=icon,
-            value_fn=lambda items, t=sensor_type: sensor_item_value(items, t),
-        )
-        for key, icon, sensor_type in _AIR_QUALITY_SENSORS
+            icon="mdi:molecule-co2",
+            device_class="carbon_dioxide",
+            state_class="measurement",
+            unit="ppm",
+            exists_fn=has_sensor_type("CO2"),
+            enabled_default=False,
+            value_fn=lambda items: sensor_item_value(items, "CO2"),
+        ),
     ),
 )
 
@@ -421,6 +492,10 @@ SOUND_VOLUME = Capability(
             field="level",
             icon="mdi:volume-medium",
             entity_category="config",
+            # Some boards (issue #319's AC) report minLevel/resolution but no
+            # maxLevel -- native_max_fn would silently collapse to 0, giving a
+            # slider with no real range instead of no entity at all.
+            exists_fn=lambda rep, resources: "maxLevel" in rep,
             native_min_fn=lambda rep: int_or_none(rep.get("minLevel")) or 0,
             native_max_fn=lambda rep: int_or_none(rep.get("maxLevel")) or 0,
             step_fn=lambda rep: int_or_none(rep.get("resolution")) or 1,

custom_components/localthings/registry/capabilities/airconditioner.py

@@ -9,6 +9,7 @@ here off the coordinator snapshot. These caps stay out of the global
 capabilities/__init__.py) -- AC-only, by_type registry only.
 """
 
+import math
 from dataclasses import replace
 
 from ..capability import Capability
@@ -22,7 +23,7 @@ from ..entities import (
     SwitchDesc,
 )
 from . import common
-from .common import filter_usage_percent, normalize_temp_unit
+from .common import filter_usage_hours, filter_usage_percent, has_sensor_type, normalize_temp_unit
 from .laundry import option_write
 
 
@@ -100,8 +101,15 @@ def _threshold_write(payload, rep, href=None):
 def _sensor_item_value(items, type_):
     """First value of the /sensors/vs/0 item with the given
     x.com.samsung.da.type. Dust/FineDust/SuperFineDust report a 2-element
-    array; only v[0] is used, since the second element's meaning is
-    unconfirmed. No device_class is set: the resource exposes no unit."""
+    array; only v[0] is used. v[1] is the device's own graded air-quality
+    level for that reading, left unbound because its floor differs by
+    family -- see common.sensor_item_value for the full note.
+
+    No device_class here: unlike air_purifier (issue #325), no AC family
+    has had its dust readings correlated against the app, and every AC
+    fixture reports permanent zeros or ties, so this file's own dumps
+    supply no grade-band evidence either. Returns a string rather than an
+    int, which these diagnostic entities have always done."""
     for it in items or []:
         if isinstance(it, dict) and it.get("x.com.samsung.da.type") == type_:
             v = it.get("x.com.samsung.da.value")
@@ -111,26 +119,6 @@ def _sensor_item_value(items, type_):
     return None
 
 
-def _has_sensor_type(type_):
-    """True when /sensors/vs/0's items[] lists an item of this type.
-
-    This only proves the type is *listed*, not that the reading is real:
-    issue #166 (ARTIK051_PRAC_20K) lists all five types with permanent-zero
-    values on units the reporter confirmed don't have the hardware. So
-    entities gated on this stay disabled by default (see AIR_QUALITY) rather
-    than existence-gated further, to avoid silently dropping real readings
-    on hardware not yet seen.
-    """
-
-    def fn(rep, resources):
-        return any(
-            isinstance(i, dict) and i.get("x.com.samsung.da.type") == type_
-            for i in (rep.get("x.com.samsung.da.items") or [])
-        )
-
-    return fn
-
-
 # Canonical AC resource hrefs. climate.py binds HREF_MODE and reads the
 # CLIMATE_CONSUMED_HREFS siblings off the coordinator snapshot; declared once
 # here so climate.py and the coverage list below can't drift out of sync.
@@ -206,6 +194,28 @@ def _mode_options(rep):
     return opts if isinstance(opts, (list, tuple)) else ()
 
 
+# Samsung's "System Fresh Air Ventilator" (PR #316, model
+# ACA-KR-TP2-21-AN9000, vid DA-AC-DIFFUSER-01001) self-reports oic.d.
+# airconditioner and routes through this same CLIMATE capability, but its
+# /mode/vs/0 supportedModes are Purification/Ventilation/SmartVentilation --
+# none of which climate.py's HVAC-mode table knows, so hvac_mode collapses
+# to a single stuck value with no way to tell the three apart. Gated to
+# devices whose *entire* supported-mode set is this vocabulary, so it can't
+# false-positive on a real AC's Cool/Heat/Dry list.
+_VENTILATION_MODE_VALUES = frozenset(("Purification", "Ventilation", "SmartVentilation"))
+
+
+def _is_ventilation_mode_device(rep, resources):
+    supported = rep.get("x.com.samsung.da.supportedModes")
+    if not isinstance(supported, (list, tuple)) or not supported:
+        return False
+    return set(supported) <= _VENTILATION_MODE_VALUES
+
+
+def _ventilation_mode_write(payload, rep, href=None):
+    return ["mode", "vs", "0"], {"x.com.samsung.da.modes": [payload]}
+
+
 def _has_display_light_option(rep, resources):
     """True when the panel light lives in /mode/vs/0's `Light_*` option
     token rather than a dedicated /light/vs/0 switch -- the two encodings
@@ -245,6 +255,59 @@ def _option_token(rep, prefix):
     return None
 
 
+def option_bit(rep, prefix, index, width):
+    """One capability bit out of the `OptionCode_<n>` / `ExtendOptionCode_<n>` token.
+
+    The appliance packs which features it has into two integers. Its own app reads
+    them by turning the number into binary, left-padding to a fixed width, and
+    indexing that *string* -- so index 0 is the most significant bit, and the
+    indices below are the app's own (`racOptionCodeValue[12]`, and so on), kept
+    identical so the two can be compared line by line.
+
+    Returns None when the token is absent, which is not the same as a zero: a bit
+    that is present and 0 says the feature is missing, while no token at all says
+    only that this board does not publish the map.
+    """
+    raw = _option_token(rep, prefix)
+    if raw is None:
+        return None
+    try:
+        bits = format(int(raw), f"0{width}b")
+    except (TypeError, ValueError):
+        return None
+    if len(bits) != width or not 0 <= index < width:
+        return None  # a number too wide for the map is not one we can read
+    return bits[index] == "1"
+
+
+def option_code_bit(rep, index):
+    """A bit of the 16-wide `OptionCode` map."""
+    return option_bit(rep, "OptionCode", index, 16)
+
+
+def extend_option_code_bit(rep, index):
+    """A bit of the 32-wide `ExtendOptionCode` map."""
+    return option_bit(rep, "ExtendOptionCode", index, 32)
+
+
+def has_option_code(rep):
+    """Whether this board publishes the 16-wide capability map at all."""
+    return _option_token(rep, "OptionCode") is not None
+
+
+def has_extend_option_code(rep):
+    """Whether this board publishes the 32-wide capability map at all.
+
+    Its own name in the app is "Single RAC new option code, as old option code
+    is full", and every RAC-class dump on record carries it while the FAC/CAC
+    ones carry only the older map with values small enough that RAC bit
+    positions read as zeros. So its presence is the closest thing available to
+    "this is the family those bit positions were documented for" -- a proxy,
+    not a proof, and used only to decide whether to read the map at all.
+    """
+    return _option_token(rep, "ExtendOptionCode") is not None
+
+
 def is_legacy_board(resources):
     """True for the board generation whose airflow lives in /airflow/vs/0
     rather than /wind/strength/vs/0 -- every AC dump on record has one shape
@@ -289,6 +352,33 @@ def _has_option_token(prefix):
     )
 
 
+def _has_option_token_any_board(prefix):
+    """Token-presence test with no board-generation gate.
+
+    `_has_option_token` above requires `is_legacy_board`, which was right for
+    the settings it guards but wrong for a token whose presence is itself the
+    only signal that needs checking -- issue #367 found `OutdoorTemp_` live
+    on 14 of 23 recorded fixtures despite none of them being legacy boards.
+    Same shape as `beep`'s Volume_ test and `_has_display_light_option`,
+    which already treat token presence as sufficient across generations."""
+    return lambda rep, resources: _option_token(rep, prefix) is not None
+
+
+def _reports_celsius(resources):
+    """Whether this subdevice's own /temperatures/vs/0 declares Celsius (or
+    says nothing at all, `_temps_vs_unit`'s default).
+
+    Guards `OutdoorTemp_`'s -55 offset below: issue #367's field validation
+    (48h against weather.forecast_home, r=0.92) ran on Celsius-locale boards
+    only -- 13 of the 14 non-legacy fixtures that carry the token declare
+    Celsius, and the offset's own calibration comment is a Celsius reading
+    too. The one Fahrenheit-locale exception on record
+    (`airconditioner_lnx_rac_heatpump`) has nothing to confirm the same
+    additive constant, or degrees C rather than F, still hold -- so this
+    stays off boards that declare anything else, rather than guess."""
+    return _temps_vs_unit(resources.get(HREF_TEMPS_VS) or {}) == "°C"
+
+
 def _option_token_on(prefix):
     return lambda rep: _option_token(rep, prefix) == "On"
 
@@ -311,16 +401,78 @@ def _option_switch_write(prefix):
     return write
 
 
-def _option_number_write(prefix):
+def _option_number_write(prefix, factor=1):
+    """Write a numeric options token. `factor` converts the entity's unit into the
+    token's own: good_sleep is offered in hours while the token counts half hours."""
+
     def write(payload, rep, href=None):
         return (
             ["mode", "vs", "0"],
-            {"x.com.samsung.da.options": option_write(prefix, str(round(float(payload))))},
+            {"x.com.samsung.da.options": option_write(prefix, str(round(float(payload) * factor)))},
         )
 
     return write
 
 
+def _good_sleep_write(payload, rep, href=None):
+    """Good Sleep needs its mode token in the same write as its duration.
+
+    `Sleep_<n>` on its own is answered 2.04 Changed and then thrown away:
+    measured on an ARTIK051_KRAC_18K, writing `["Sleep_4"]` left the token at
+    `Sleep_0` at both +8s and +45s, while the same value written together with
+    `Comode_Sleep` held. So the number is a parameter of the mode, not a
+    setting of its own, and the appliance's app never sends one without the
+    other either.
+
+    Which mode token goes with it depends on nano wind, the way the app decides
+    it: nano and Good Sleep share the single `Comode_` slot, so running both is
+    `Comode_NanoSleep`, and switching the timer off while nano is on leaves nano
+    running rather than turning everything off.
+    """
+    half_hours = round(float(payload) * 2)
+    nano = _option_token(rep, "Comode") in ("Nano", "NanoSleep")
+    if half_hours:
+        comode = "Comode_NanoSleep" if nano else "Comode_Sleep"
+    else:
+        comode = "Comode_Nano" if nano else "Comode_Off"
+    return (
+        ["mode", "vs", "0"],
+        {"x.com.samsung.da.options": [comode, f"Sleep_{half_hours}"]},
+    )
+
+
+# What the appliance itself picks when a Good Sleep mode is asked for with no
+# duration to go with it: writing a bare `Comode_Nano` over a live
+# `Comode_Sleep`/`Sleep_4` came back as `Comode_NanoSleep`/`Sleep_16`. Used only
+# when a sleep preset is selected while the timer reads 0.
+_DEFAULT_SLEEP_HALF_HOURS = 16
+
+
+def _preset_options(code, rep):
+    """The options array for a legacy preset write.
+
+    One `Comode_` token has to express both nano wind and Good Sleep, so
+    selecting nano while the timer is running means `Comode_NanoSleep` -- and it
+    has to carry the duration, because the board otherwise supplies its own.
+    Measured: `["Comode_Nano"]` written over `Comode_Sleep`/`Sleep_4` came back
+    as `Comode_NanoSleep`/`Sleep_16`, silently turning the user's two hours into
+    eight. Writing the pair keeps the two hours.
+
+    Leaving a sleep mode needs no such care: the board zeroes the duration by
+    itself. Measured on the same unit -- a bare `["Comode_Off"]` written over
+    `Comode_Sleep`/`Sleep_4` read back as `Comode_Off`/`Sleep_0` at +8s and +38s
+    -- so the `none` preset cannot leave a stale token behind for the next nano
+    selection to pick up as a running timer.
+    """
+    sleep = _option_token(rep, "Sleep")
+    running = sleep not in (None, "0")
+    if code == "Nano" and running:
+        code = "NanoSleep"
+    if code in ("Sleep", "NanoSleep"):
+        return [f"Comode_{code}", f"Sleep_{sleep if running else _DEFAULT_SLEEP_HALF_HOURS}"]
+    return option_write("Comode", code)
+
+
 def _odor_controller_active(rep):
     """Odor-controller self-clean on/off, from the `SmartCoolClean_<On/Off>`
     option token (matches the SmartThings cloud's airConditionerOdorController
@@ -354,7 +506,68 @@ def _humidity(rep):
     return None
 
 
-def _climate_write(payload, rep, href=None):
+def _quantize_temperature(value, step):
+    """Quantize a temperature to the device's advertised step size.
+
+    Mirrors climate.py's `target_temperature_step`, which defaults to `1.0`
+    when no increment is advertised anywhere (`step=None` or `<=0` here) --
+    so a board with no increment still gets whole-degree writes instead of
+    the raw value passed through unrounded. Returns `None` for a payload
+    that isn't numeric, so the caller can reject the write instead of
+    building a body around a null (coordinator.py's async_send_command
+    already logs and drops a write_fn result of None).
+
+    Normalizes an integral result to `int` here, once, so both write
+    branches serialize `24` rather than `24.0` -- `round(..., 2)` guards
+    against float noise in the division (e.g. `21.7 / 0.1`).
+    """
+    try:
+        numeric = float(value)
+    except (TypeError, ValueError):
+        return None
+    if not math.isfinite(numeric):
+        # float('nan')/float('inf') pass the try/except above (they're
+        # valid floats) but round()/division on them raises ValueError/
+        # OverflowError instead of returning -- reject here so a bad
+        # payload always comes back as a clean None, not an exception
+        # out of write_fn.
+        return None
+    step_value = _num(step) or 1.0
+    if step_value <= 0:
+        step_value = 1.0
+    quantized = round(round(numeric / step_value) * step_value, 2)
+    return int(quantized) if quantized.is_integer() else quantized
+
+
+def _temperature_step(resources):
+    """Device-reported temperature increment, read the same way and in the
+    same order as climate.py's `target_temperature_step`: OCF
+    `/temperature/control/vs/0`'s `increment` (or its vendor-prefixed
+    twin), falling back to vendor `/temperatures/vs/0`. The increment on
+    that second resource lives inside its `items[]` array like every other
+    per-item field, not at the resource's top level -- unwrapped via
+    `_temps_vs_item()`, the same helper `_temps_vs_current`/`_temps_vs_unit`
+    use above, rather than read off `resource` directly.
+
+    `rep` (the bound entity's own resource, `/mode/vs/0` for ClimateDesc --
+    see rep_fn=_first_mode below) never carries an increment, so it isn't a
+    candidate here; only the coordinator's `resources` snapshot is."""
+    if not isinstance(resources, dict):
+        return None
+    control = resources.get(HREF_TEMP_CONTROL)
+    if isinstance(control, dict):
+        step = _num(control.get("increment")) or _num(control.get("x.com.samsung.da.increment"))
+        if step is not None:
+            return step
+    temps_vs = resources.get(HREF_TEMPS_VS)
+    if isinstance(temps_vs, dict):
+        step = _num(_temps_vs_item(temps_vs).get("x.com.samsung.da.increment"))
+        if step is not None:
+            return step
+    return None
+
+
+def _climate_write(payload, rep, href=None, resources=None):
     """Maps a (kind, value) command from the climate platform to the
     (path_segs, body) for that one sub-write; `value` is already the raw
     device code. Power always goes to vendor `/power/vs/0` (OCF `/power/0`
@@ -367,9 +580,12 @@ def _climate_write(payload, rep, href=None):
         return (["power", "vs", "0"], {"x.com.samsung.da.power": "On" if value else "Off"})
     if kind == "mode":
         return (["mode", "vs", "0"], {"x.com.samsung.da.modes": [value]})
-    if kind == "temperature_ocf":
-        return (["temperature", "desired", "0"], {"temperature": round(float(value))})
-    if kind == "temperature":
+    if kind in ("temperature_ocf", "temperature"):
+        quantized = _quantize_temperature(value, _temperature_step(resources))
+        if quantized is None:
+            return None
+        if kind == "temperature_ocf":
+            return (["temperature", "desired", "0"], {"temperature": quantized})
         # Vendor items[] array; only one item observed on every AC dump, id '0'.
         return (
             ["temperatures", "vs", "0"],
@@ -377,7 +593,7 @@ def _climate_write(payload, rep, href=None):
                 "x.com.samsung.da.items": [
                     {
                         "x.com.samsung.da.id": "0",
-                        "x.com.samsung.da.desired": str(round(float(value))),
+                        "x.com.samsung.da.desired": str(quantized),
                     }
                 ]
             },
@@ -401,7 +617,7 @@ def _climate_write(payload, rep, href=None):
     if kind == "swing_legacy":
         return (["airflow", "vs", "0"], {"x.com.samsung.da.direction": value})
     if kind == "preset_legacy":
-        return (["mode", "vs", "0"], {"x.com.samsung.da.options": option_write("Comode", value)})
+        return (["mode", "vs", "0"], {"x.com.samsung.da.options": _preset_options(value, rep)})
     if kind == "preset":
         return (["mode", "convenient", "vs", "0"], {"x.com.samsung.da.modes": value})
     return None
@@ -417,6 +633,17 @@ CLIMATE = Capability(
             rep_fn=_first_mode,
             write_fn=_climate_write,
         ),
+        # Purification/Ventilation/SmartVentilation mode select (PR #316) --
+        # _is_ventilation_mode_device gates this to devices using that
+        # vocabulary exclusively, so a real AC's climate card is unaffected.
+        SelectDesc(
+            key="ventilation_mode",
+            rep_fn=_first_mode,
+            exists_fn=_is_ventilation_mode_device,
+            options_field="x.com.samsung.da.supportedModes",
+            icon="mdi:air-filter",
+            write_fn=_ventilation_mode_write,
+        ),
         # Panel light switch for boards that encode it in /mode/vs/0's options
         # instead of a dedicated /light/vs/0 (see _has_display_light_option).
         # Shares the switch.display_light translation key with DISPLAY_LIGHT
@@ -528,29 +755,68 @@ CLIMATE = Capability(
             icon="mdi:air-filter",
             entity_category="config",
         ),
-        # "Good Sleep" timer. 0 = off; the upper bound is a guess (only 0 has
-        # been observed on hardware), so a write above 0 is unverified.
+        # "Good Sleep" timer, offered in hours. 0 = off.
+        #
+        # The token counts *half* hours, so it is halved on the way in and doubled
+        # on the way out. The appliance's own app pairs a picker of durations with
+        # the values it puts on the wire, one to one:
+        #
+        #   0:00 0:30 1:00 1:30 2:00 2:30 3:00 4:00 5:00 ... 12:00
+        #      0    1    2    3    4    5    6    8   10  ...    24
+        #
+        # which also pins the maximum at 12 hours (its own help text says so:
+        # "will be turned off after a selected period of time (Max. 12 hours)").
+        # Before this the token was published as if it were hours: the entity
+        # capped at 12, which set six, and twelve hours could not be asked for at
+        # all.
+        #
+        # Half-hour steps are what the app offers below three hours; above that it
+        # offers whole hours only, and a half hour up there is untested rather than
+        # known-bad. A Number cannot change step part-way, and turning this into a
+        # Select of the app's sixteen values would change the entity's domain on
+        # every unit that already has it, so the step stays 0.5 throughout.
         NumberDesc(
             key="good_sleep",
-            rep_fn=_option_token_num("Sleep"),
+            rep_fn=_option_token_num("Sleep", divisor=2),
             exists_fn=_has_option_token("Sleep"),
-            write_fn=_option_number_write("Sleep"),
+            write_fn=_good_sleep_write,
             native_min=0,
             native_max=12,
-            step=1,
+            step=0.5,
             unit="h",
             icon="mdi:sleep",
             entity_category="config",
         ),
         # Outdoor temperature, offset by 55 -- calibrated against an
         # independent thermometer (token 75 while it read 20.3°C).
+        #
+        # exists_fn is token-presence-only (issue #367), not is_legacy_board:
+        # gating it there dropped the sensor on every non-legacy board that
+        # reports it -- 14 of 17 fixtures carrying the token in the issue's
+        # own survey. A 48h/289-sample field capture correlated it against
+        # weather.forecast_home at r=0.92, ruling out a firmware constant.
+        # `_reports_celsius` keeps that presence check from also claiming
+        # the -55 Celsius offset for board generations it was never
+        # validated on -- see its own docstring.
+        #
+        # enabled_default=False: multi-split installs (multiple indoor heads
+        # on one outdoor condenser) report the same token on every head, so
+        # a fix here creates one identical sensor per head rather than one
+        # per physical unit (same duplication as the shared energy/power
+        # counters in issue #329). Left disabled so a user with several
+        # heads can enable just one instead of getting N duplicates active
+        # by default.
         SensorDesc(
             key="outdoor_temperature",
             rep_fn=_option_token_num("OutdoorTemp", offset=55),
-            exists_fn=_has_option_token("OutdoorTemp"),
+            exists_fn=lambda rep, resources: (
+                _has_option_token_any_board("OutdoorTemp")(rep, resources)
+                and _reports_celsius(resources)
+            ),
             device_class="temperature",
             state_class="measurement",
             unit="°C",
+            enabled_default=False,
             icon="mdi:home-thermometer-outline",
         ),
         # Filter time in tenths of an hour, counting UP since last filter
@@ -688,16 +954,17 @@ AIR_FILTER = Capability(
             icon="mdi:air-filter",
             entity_category="diagnostic",
         ),
-        # Lifetime hour counter, resets only on filter replacement.
+        # Lifetime hour counter, resets only on filter replacement. Derived
+        # from the percentage and filterCapacity (issue #330) -- filterUsage
+        # itself is not an hour count.
         SensorDesc(
             key="air_filter_usage_hours",
-            field="x.com.samsung.da.filterUsage",
+            rep_fn=filter_usage_hours,
             device_class="duration",
             state_class="total_increasing",
             unit_fn=_filter_unit,
             icon="mdi:air-filter",
             entity_category="diagnostic",
-            value_fn=_int,
         ),
         # Locally writable alarm threshold (see _threshold_write); only
         # surfaces where supportedFilterDesiredUsage is advertised.
@@ -759,13 +1026,12 @@ AIR_FILTER_PM1 = Capability(
         ),
         SensorDesc(
             key="air_filter_pm1_usage_hours",
-            field="x.com.samsung.da.filterUsage",
+            rep_fn=filter_usage_hours,
             device_class="duration",
             state_class="total_increasing",
             unit_fn=_filter_unit,
             icon="mdi:air-filter",
             entity_category="diagnostic",
-            value_fn=_int,
             exists_fn=_has_filter_field("x.com.samsung.da.filterUsage"),
         ),
         SelectDesc(
@@ -1034,10 +1300,257 @@ HUMIDITY = Capability(
     ),
 )
 
+# TP1X_DA-AC-FAC-class additions (issue #319): most of these hrefs are the
+# same shapes air_purifier.py already models on the sibling TP1X_DA-AC-AIR
+# board (DISPLAY/SOUND_OUTPUT/SOUND_VOLUME, reused directly in the
+# registry); SOUND_MODE and the two below are genuinely new.
+
+SOUND_MODE = Capability(
+    href="/settings/sound/mode/vs/0",
+    poll_tier="cold",
+    entities=(
+        # Values seen (mute/tone/voice) are exactly laundry.SOUND_MODE's
+        # vocabulary, so this shares that catalog entry -- but reads the
+        # live supportedModes field rather than laundry's static tuple,
+        # since this resource carries one (issue #319).
+        #
+        # exists_fn is required, not optional here: this board's rep never
+        # reports a live 'mode' value ({"supportedModes": [...]} only), and
+        # entity.py's default field-presence gate would otherwise keep the
+        # select from ever registering -- adapter.flatten() (what the
+        # golden/tests read) has no such gate, so it would look bound while
+        # silently absent from HA. Register on supportedModes' presence
+        # instead; current_option reads unknown until the device reports
+        # 'mode' live.
+        SelectDesc(
+            key="sound_mode",
+            field="mode",
+            icon="mdi:volume-high",
+            entity_category="config",
+            options_field="supportedModes",
+            exists_fn=lambda rep, resources: bool(rep.get("supportedModes")),
+            write_fn=lambda p, rep, href=None: (
+                ["settings", "sound", "mode", "vs", "0"],
+                {"mode": p},
+            ),
+        ),
+    ),
+)
+
+# Absence-detection auto air clean (issue #319) -- a plain On/Off toggle,
+# sibling feature to ABSENCE_POWER_SAVING above but on its own href.
+ABSENCE_CLEAN = Capability(
+    href="/csi/absenceclean/vs/0",
+    poll_tier="cold",
+    entities=(
+        SwitchDesc(
+            key="absence_clean",
+            field="mode",
+            icon="mdi:broom",
+            entity_category="config",
+            value_fn=lambda v: v == "On",
+            write_fn=lambda p, rep, href=None: (
+                ["csi", "absenceclean", "vs", "0"],
+                {"mode": "On" if p == "On" else "Off"},
+            ),
+        ),
+    ),
+)
+
+# The CAC-class board (issue #191) reports the identical {mode,
+# supportedModes: [On, Off]} shape under /mds/absenceclean/vs/0 instead --
+# confirmed against that board's own fixture, not guessed. Shares
+# ABSENCE_CLEAN's key/translation: no dump has ever reported both hrefs
+# together, so there's nothing for the two to collide over in
+# adapter.flatten().
+MDS_ABSENCE_CLEAN = Capability(
+    href="/mds/absenceclean/vs/0",
+    poll_tier="cold",
+    entities=(
+        SwitchDesc(
+            key="absence_clean",
+            field="mode",
+            icon="mdi:broom",
+            entity_category="config",
+            value_fn=lambda v: v == "On",
+            write_fn=lambda p, rep, href=None: (
+                ["mds", "absenceclean", "vs", "0"],
+                {"mode": "On" if p == "On" else "Off"},
+            ),
+        ),
+    ),
+)
+
+# Energy-saving schedule (issue #319). `mode` is a device-chosen preset
+# (e.g. Cooling_60/Off_180) with no confirmed unit for the trailing number
+# (minutes seen elsewhere on this board are unprefixed ints, not
+# underscore-suffixed) -- exposed as a select over the live options rather
+# than translating labels we can't confirm. `state`/`operatingStatus` stay
+# bare diagnostic passthroughs for the same reason.
+ENERGY_SAVING = Capability(
+    href="/csi/energysaving/vs/0",
+    poll_tier="cold",
+    entities=(
+        SelectDesc(
+            key="energy_saving_mode",
+            field="mode",
+            icon="mdi:leaf",
+            entity_category="config",
+            options_field="supportedModes",
+            write_fn=lambda p, rep, href=None: (
+                ["csi", "energysaving", "vs", "0"],
+                {"mode": p},
+            ),
+        ),
+        SensorDesc(
+            key="energy_saving_state",
+            field="state",
+            icon="mdi:leaf",
+            entity_category="diagnostic",
+        ),
+        SensorDesc(
+            key="energy_saving_operating_status",
+            field="operatingStatus",
+            icon="mdi:leaf",
+            entity_category="diagnostic",
+        ),
+    ),
+)
+
+# TP1X_DA-AC-CAC-01001-class additions (issue #288, six System A/C cassette
+# units on the same board test_airconditioner_cac.py's coverage-gap test
+# documents). `convenientMode`/`operatingOption` stay unexposed -- present
+# on every dump seen but no evidence of what either actually controls.
+EDGE_LIGHTING = Capability(
+    href="/edgelighting/vs/0",
+    poll_tier="cold",
+    entities=(
+        SwitchDesc(
+            key="edge_lighting",
+            field="status",
+            icon="mdi:led-strip",
+            entity_category="config",
+            value_fn=lambda v: v == "On",
+            write_fn=lambda p, rep, href=None: (
+                ["edgelighting", "vs", "0"],
+                {"status": "On" if p == "On" else "Off"},
+            ),
+        ),
+        SelectDesc(
+            key="edge_lighting_mode",
+            field="mode",
+            icon="mdi:led-strip-variant",
+            entity_category="config",
+            options_field="modeSupportedList",
+            write_fn=lambda p, rep, href=None: (
+                ["edgelighting", "vs", "0"],
+                {"mode": p},
+            ),
+        ),
+        # Color temperature in Kelvin (3000K/4000K/6500K), not a hue -- a
+        # select over the live-reported codes rather than a light color_temp
+        # entity, consistent with this project's other Kelvin-coded selects.
+        SelectDesc(
+            key="edge_lighting_color",
+            field="colorOption",
+            icon="mdi:palette",
+            entity_category="config",
+            options_field="colorSupportedList",
+            write_fn=lambda p, rep, href=None: (
+                ["edgelighting", "vs", "0"],
+                {"colorOption": p},
+            ),
+        ),
+    ),
+)
+
+# Second, distinct light resource on this board generation -- an
+# always-on-style indicator light with its own status/mode, not to be
+# confused with EDGE_LIGHTING (a different href/rep entirely) or
+# DISPLAY_LIGHT (/light/vs/0's ambient mood light).
+LIGHT_STATEFUL = Capability(
+    href="/light/stateful/vs/0",
+    poll_tier="cold",
+    entities=(
+        SwitchDesc(
+            key="indicator_light",
+            field="status",
+            icon="mdi:led-on",
+            entity_category="config",
+            value_fn=lambda v: v == "On",
+            write_fn=lambda p, rep, href=None: (
+                ["light", "stateful", "vs", "0"],
+                {"status": "On" if p == "On" else "Off"},
+            ),
+        ),
+        SelectDesc(
+            key="indicator_light_mode",
+            field="mode",
+            icon="mdi:led-variant-on",
+            entity_category="config",
+            options_field="supportedModes",
+            write_fn=lambda p, rep, href=None: (
+                ["light", "stateful", "vs", "0"],
+                {"mode": p},
+            ),
+        ),
+    ),
+)
+
+# Wind-Free / Wind-Sleep mode toggles (PR #316, ACA-KR-TP2-21-AN9000). Each
+# on its own dedicated href, so unlike ventilation_mode above these need no
+# device gating -- absent on every other family's dump. Write contract
+# extrapolated from this file's other plain On/Off options-array fields
+# (AIR_PURIFY, AUTO_CLEAN); not confirmed live.
+#
+# NOT the same WindFree already modeled elsewhere: on regular AC boards,
+# WindFree is a `Comode_Nano` token inside /mode/vs/0's options[], surfaced
+# as a climate preset (climate.py's _LEGACY_PRESET_CODES/preset_mode) with
+# real coupling to hvac_mode (disabled in Heat/AIComfort/Auto, timing rules
+# on legacy boards). This device's windfree/windsleep are bare booleans on
+# their own hrefs with no such coupling evidenced -- same feature name,
+# different wire mechanism, so plain switches rather than folding into
+# climate.py's preset machinery.
+WINDFREE = Capability(
+    href="/modeoption/windfree/vs/0",
+    poll_tier="warm",
+    entities=(
+        SwitchDesc(
+            key="windfree",
+            field="x.com.samsung.da.windfree",
+            icon="mdi:leaf",
+            entity_category="config",
+            value_fn=lambda v: v == "On",
+            write_fn=lambda p, rep, href=None: (
+                ["modeoption", "windfree", "vs", "0"],
+                {"x.com.samsung.da.windfree": "On" if p == "On" else "Off"},
+            ),
+        ),
+    ),
+)
+
+WINDSLEEP = Capability(
+    href="/modeoption/windsleep/vs/0",
+    poll_tier="warm",
+    entities=(
+        SwitchDesc(
+            key="windsleep",
+            field="x.com.samsung.da.windsleep",
+            icon="mdi:sleep",
+            entity_category="config",
+            value_fn=lambda v: v == "On",
+            write_fn=lambda p, rep, href=None: (
+                ["modeoption", "windsleep", "vs", "0"],
+                {"x.com.samsung.da.windsleep": "On" if p == "On" else "Off"},
+            ),
+        ),
+    ),
+)
+
 # /sensors/vs/0 items[] carry live air-quality readings. CleanLevel is
 # corroborated as numeric by a top-level x.com.samsung.da.cleanLevel scalar,
 # so it's a measurement; the others stay string diagnostics (see
-# _sensor_item_value). All disabled by default: _has_sensor_type only proves
+# _sensor_item_value). All disabled by default: has_sensor_type only proves
 # the item type is listed, not that the sensor is real (see its docstring).
 AIR_QUALITY = Capability(
     href="/sensors/vs/0",
@@ -1049,7 +1562,7 @@ AIR_QUALITY = Capability(
             icon="mdi:broom",
             entity_category="diagnostic",
             state_class="measurement",
-            exists_fn=_has_sensor_type("CleanLevel"),
+            exists_fn=has_sensor_type("CleanLevel"),
             enabled_default=False,
             value_fn=lambda items: _int(_sensor_item_value(items, "CleanLevel")),
         ),
@@ -1059,7 +1572,7 @@ AIR_QUALITY = Capability(
                 field="x.com.samsung.da.items",
                 icon=icon,
                 entity_category="diagnostic",
-                exists_fn=_has_sensor_type(type_),
+                exists_fn=has_sensor_type(type_),
                 enabled_default=False,
                 value_fn=lambda items, t=type_: _sensor_item_value(items, t),
             )
@@ -1070,6 +1583,25 @@ AIR_QUALITY = Capability(
                 ("super_fine_dust", "mdi:weather-fog", "SuperFineDust"),
             )
         ),
+        # CO2 (PR #316, ACA-KR-TP2-21-AN9000) -- a type this file's other AC
+        # families don't report. Same field/shape air_monitor.SENSORS
+        # already models with device_class='carbon_dioxide'/unit='ppm', so
+        # this matches that descriptor rather than guessing fresh. The dust
+        # keys above stay untyped for the reason in _sensor_item_value: the
+        # pm10/pm25/pm1 mapping is confirmed for the purifier and monitor
+        # families (issue #325), but no AC family has evidence of its own.
+        SensorDesc(
+            key="co2",
+            field="x.com.samsung.da.items",
+            icon="mdi:molecule-co2",
+            entity_category="diagnostic",
+            device_class="carbon_dioxide",
+            state_class="measurement",
+            unit="ppm",
+            exists_fn=has_sensor_type("CO2"),
+            enabled_default=False,
+            value_fn=lambda items: _int(_sensor_item_value(items, "CO2")),
+        ),
     ),
 )
 
@@ -1089,7 +1621,12 @@ _AC_IGNORED = [
     # state or documented write contract. /option/muteonce/vs/0 and
     # /selfcheck/vs/0 are deliberately NOT here -- see MUTE_ONCE above and
     # common.SELF_CHECK, both of which have a confirmed, modelable contract.
-    "/airlevelcheck/vs/0",  # periodic air-quality sensing scheduler plumbing
+    # /airlevelcheck/vs/0 is deliberately NOT here either (PR #316):
+    # despite this list's old description of it as "scheduler plumbing",
+    # both the CAC and TP1X_DA_AC_RAC_01011 fixtures already carry real,
+    # populated periodicSensingActivationState/autoExeState values here --
+    # the AI-Purify feature air_purifier.AIR_LEVEL_CHECK already models,
+    # reused below rather than reinvented.
     "/aisleep/vs/0",  # AI-sleep feedback state (no actionable control)
     "/availablecontrolsets/vs/0",  # opaque hex-encoded control-set bitmap
     "/da/softreset/vs/0",  # soft-reset trigger plumbing
@@ -1117,6 +1654,24 @@ _AC_IGNORED = [
     # registry.subdevices.enumerate_subdevices, hence the entry here rather
     # than a coverage gap.
     "/multidevice/vs/0",
+    # TP1X_DA-AC-FAC-class-only (issue #319) -- scoped here rather than
+    # promoted to the global ignore list since it'd collide with families
+    # that do bind some of these. Only /dnd/autosleep/vs/0 has a precedent
+    # (air_purifier.COVERAGE ignores the same href for the same reason);
+    # the rest are new, each with its own reason below.
+    "/dnd/autosleep/vs/0",  # every field its inert default; needs a schedule editor
+    "/outdoorsharing/vs/0",  # empty on this dump -- outdoor-unit sharing plumbing
+    "/lifestyle/survey/vs/0",  # {list: [""]} placeholder, nothing to expose
+    # supportedVoices carries opaque numeric voice-pack IDs ("100"/"101")
+    # with no live current-selection field and, unlike SOUND_MODE's
+    # self-descriptive mute/tone/voice codes, no confirmed human-readable
+    # meaning to expose them under -- don't guess.
+    "/settings/sound/voice/vs/0",
+    # rssi/wifiFrequency (network housekeeping); lastEnergySavingTime and
+    # cleaningStartTime are inert '1900-01-00' placeholders on this dump;
+    # absenceInfo is an unconfirmed 48-slot P/A history blob with no
+    # documented meaning -- don't guess what it encodes.
+    "/csi/information/vs/0",
 ]
 
 # Built as bare no-entity caps; folded into the AC registry (not global).

custom_components/localthings/registry/capabilities/common.py

@@ -72,15 +72,25 @@ def epoch_to_utc(value):
 
 
 def filter_usage_percent(rep):
-    """Filter usage as a percentage of rated capacity. Several families
-    report `filterUsage` as a raw count in `filterCapacityUnit` (e.g. 100 of
-    a 500-hour capacity), so a plain value with a '%' unit would be wrong.
-    Returns None when capacity is missing/zero."""
-    used = _num(rep.get("x.com.samsung.da.filterUsage"))
+    """Filter usage as a percentage. `filterUsage` is already 0-100 on every
+    family confirmed so far, including ARTIK051_PRAC (issue #330): its own
+    fixture and three live heads all show `filterStatus == 'wash'` at
+    `filterUsage == '100'` regardless of `filterCapacity` (60/224/500 across
+    other families' fixtures), which only holds if `filterUsage` is already
+    a percent -- dividing by capacity again would read that filter as fresh
+    at 20%."""
+    return int_or_none(rep.get("x.com.samsung.da.filterUsage"))
+
+
+def filter_usage_hours(rep):
+    """Elapsed filter hours, derived from the percentage and capacity rather
+    than read off `filterUsage` directly -- `filterUsage` is a percent, not
+    an hour count (issue #330). Returns None when capacity is missing/zero."""
+    pct = filter_usage_percent(rep)
     cap = _num(rep.get("x.com.samsung.da.filterCapacity"))
-    if used is None or not cap:
+    if pct is None or not cap:
         return None
-    return round(used / cap * 100)
+    return round(pct / 100 * cap, 1)
 
 
 def normalize_temp_unit(raw, default="°F"):
@@ -126,6 +136,28 @@ def _active_alarm_codes(items):
     return ", ".join(codes) if codes else "none"
 
 
+def hex_pairs(codes):
+    """'1C1D21...' -> ['1C', '1D', '21', ...]."""
+    return [codes[i : i + 2] for i in range(0, len(codes) - 1, 2)]
+
+
+def option_value(options, prefix):
+    """Find `<prefix>_<value>` in an options[] array and return <value>.
+
+    Lives here rather than in laundry.py, which is where it grew, because
+    cloudcourse.py needs it too and laundry.py imports *that* -- so the
+    reverse import would be a module cycle. The coordinator already imports
+    from this module, so nothing about the dependency direction is unusual;
+    it is specifically the laundry/cloudcourse pair that can't reach each
+    other. Anchored at position 0 so 'Course_' never matches
+    'CloudCourse_'/'OneTimeCloudCourse_'.
+    """
+    for o in options or []:
+        if isinstance(o, str) and o.startswith(prefix + "_"):
+            return o.split("_", 1)[1]
+    return 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
@@ -217,12 +249,42 @@ def _power_sensor_exists(rep, resources):
     return not model_allows_power_on_off(resources)
 
 
+def diagnosis_status(value):
+    """'Ready' -> the catalog's 'ready'; anything else is left raw.
+
+    Shared by dishwasher and dryer, which report the same field.
+    """
+    return "ready" if value == "Ready" else value
+
+
 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 to read
     (index 0 is the raw measurement on every family seen so far). Shared
     by range_hood.AIR_QUALITY, air_purifier.AIR_QUALITY, and
-    air_monitor.SENSORS, which all read the same resource shape."""
+    air_monitor.SENSORS, which all read the same resource shape.
+
+    value[] is 2-element on the fields that carry a magnitude
+    (Dust/FineDust/SuperFineDust/CO2) and 1-element on Odor/CleanLevel.
+    That asymmetry is what index 1 means: it is the device's own graded
+    air-quality level for that reading -- the same kind of value Odor and
+    CleanLevel already *are*, which is why those two have no second slot.
+    It reads 0-2 against index 0's observed 0-31, tracks index 0 within a
+    device, and CleanLevel equals the highest per-field grade on 9 of the
+    11 fixtures reporting this resource (the range hood and one RAC report
+    a higher CleanLevel than any dust grade, so they fold in something
+    else).
+
+    Index 1 is deliberately left unbound rather than exposed as an entity:
+    its floor is not portable. ARTIK051_TVTL grades good air as 0, while
+    AVT-WW-TP1 / A-VTWW-TP2 / TP1X / ASM-KR-TP1 / AHD-WW-TP1 all grade it
+    as 1, so a shared descriptor would need a per-family offset to mean
+    anything, and CleanLevel already carries the aggregate. The grade is
+    still load-bearing as *evidence*: it is what confirms the three dust
+    fields are three different scales rather than one repeated reading --
+    see air_purifier._AIR_QUALITY_SENSORS and
+    tests/test_air_quality_grade_column.py.
+    """
     for item in items or ():
         if not isinstance(item, dict):
             continue
@@ -237,6 +299,30 @@ def sensor_item_value(items, sensor_type, index=0):
     return None
 
 
+def has_sensor_type(type_):
+    """True when /sensors/vs/0's items[] lists an item of this type.
+
+    This only proves the type is *listed*, not that the reading is real:
+    issue #166 (ARTIK051_PRAC_20K) lists all five types with permanent-zero
+    values on units the reporter confirmed don't have the hardware. So
+    entities gated on this stay disabled by default rather than
+    existence-gated further, to avoid silently dropping real readings on
+    hardware not yet seen.
+
+    is_stub_rep(rep) keeps the stub carve-out (see entity._is_included /
+    ENERGY_METER, issue #127): an explicit exists_fn otherwise bypasses it
+    and would drop the entity when /device/0 returns a not-yet-fetched stub.
+    """
+
+    def fn(rep, resources):
+        return is_stub_rep(rep) or any(
+            isinstance(i, dict) and i.get("x.com.samsung.da.type") == type_
+            for i in (rep.get("x.com.samsung.da.items") or [])
+        )
+
+    return fn
+
+
 # OCF-native / vendor '-vs' fallback pairs for power, kids-lock, remote
 # control: each exists as both a standard OCF resource (/power/0,
 # oic.r.switch.binary, plain boolean 'value') and a Samsung vendor

custom_components/localthings/registry/capabilities/dishwasher.py

@@ -9,7 +9,12 @@ wash, auto release dry) are read locally here.
 
 from ..capability import Capability
 from ..entities import ButtonDesc, SelectDesc, SensorDesc, SwitchDesc
-from .laundry import bool_option_switch, cycle_select
+from .common import diagnosis_status
+from .laundry import (
+    bool_option_switch,
+    cycle_select,
+    drum_clean_cycles_remaining,
+)
 
 # ---------------------------------------------------------------------------
 # /dishwasher/vs/0 — cycle wash/dry settings
@@ -51,6 +56,19 @@ DISHWASHER_SETTINGS = Capability(
 # kind of adjacent pair a manual screenshot transcription slips on. The
 # reporter's live confirmation (selecting 'Normal' ran the physical Express
 # 60 program and vice versa) settled it: '86' is Express 60, '83' is Normal.
+#
+# Drum Clean+ maintenance tracking reuses washer.py/dryer.py's (issues #9,
+# #258) DrumCleanProposal_/WashingTimes_/DrumCleanLog_ tokens riding on this
+# same options[] array -- a live dump confirmed the dishwasher reports the
+# identical trio (WashingTimes_18/DrumCleanProposal_20, plus a '|'-joined
+# DrumCleanLog_ history matching the dryer's multi-entry shape), so
+# laundry.drum_clean_cycles_remaining applies unchanged.
+#
+# laundry.drum_clean_last_cleaned (DrumCleanLog_'s own newest entry) is
+# deliberately NOT wired up here (issue #398): a live dishwasher dump
+# showed it moving every 30-90s on its own, including well after a cycle
+# had already finished -- unlike the washer/dryer reports this reader was
+# built from (issues #9, #258), it never settles on a value worth showing.
 
 CYCLE_OPTIONS = Capability(
     href="/course/vs/0",
@@ -60,6 +78,14 @@ CYCLE_OPTIONS = Capability(
         bool_option_switch(
             "auto_release_dry", "mdi:door-open", "AutoDoorRelease", gate_on_presence=True
         ),
+        SensorDesc(
+            key="drum_clean_cycles_remaining",
+            unit="cycles",
+            icon="mdi:dishwasher-alert",
+            state_class="measurement",
+            exists_fn=lambda rep, resources: drum_clean_cycles_remaining(rep) is not None,
+            rep_fn=drum_clean_cycles_remaining,
+        ),
     ),
 )
 
@@ -76,6 +102,9 @@ DIAGNOSIS = Capability(
             field="x.com.samsung.da.diagnosisStart",
             icon="mdi:stethoscope",
             entity_category="diagnostic",
+            device_class="enum",
+            options=("ready",),
+            value_fn=diagnosis_status,
         ),
         ButtonDesc(
             key="diagnosis_start",

custom_components/localthings/registry/capabilities/dryer.py

@@ -11,6 +11,7 @@ the /course/vs/0 cycle select -- lives in laundry.py.
 
 from ..capability import Capability
 from ..entities import SensorDesc, SwitchDesc
+from .common import diagnosis_status
 from .laundry import cycle_select, drum_clean_cycles_remaining, drum_clean_last_cleaned
 
 
@@ -26,7 +27,17 @@ DRYER_SETTINGS = Capability(
     entities=(
         SensorDesc(key="dry_level", field="x.com.samsung.da.dryLevel", icon="mdi:water-percent"),
         SensorDesc(key="dry_time", field="x.com.samsung.da.dryTime", icon="mdi:timer"),
-        SensorDesc(key="dryer_type", field="x.com.samsung.da.dryerType", icon="mdi:tumble-dryer"),
+        SensorDesc(
+            key="dryer_type",
+            field="x.com.samsung.da.dryerType",
+            icon="mdi:tumble-dryer",
+            device_class="enum",
+            # Only 'Electricity' confirmed across shipped fixtures (#366); an
+            # unrecognized value still passes through raw via sensor.py's
+            # options property rather than breaking the entity.
+            options=("electricity",),
+            value_fn=lambda v: v.lower() if isinstance(v, str) else v,
+        ),
         SwitchDesc(
             key="wrinkle_prevent",
             field="x.com.samsung.da.wrinklePrevent",
@@ -46,6 +57,19 @@ DRYER_SETTINGS = Capability(
 # (issue #244). /st/dryercourse/vs/0 re-encodes the same selected course
 # and is ignored (ignored.py), mirroring /st/washercourse/vs/0 for washers.
 #
+# dryer_cycle_table_00 is a separate, older course-code family reported by
+# a DVE45R6300W/A3 (issue #357), confirmed the same way: the reporter
+# selected each cycle on the appliance and read back the resulting raw
+# code. It shares no codes with Table_03 above -- 'a5' Bedding here and
+# '01' Normal are both table-scoped, so a Table_03 dryer never picks up a
+# Table_00 label or vice versa (see laundry.cycle_select's table_href).
+# A DV6800N -- same DA_WM_A51_20_COMMON board, also Table_00 -- confirmed
+# 14 more courses the same way (issue #394); its /course/vs/0 supportedOptions
+# only advertises a different subset of this same table (each model exposes
+# whichever courses its hardware supports), not a conflicting code family --
+# the one code both reporters confirmed, 'a5', means Bedding on both. Folded
+# into the same catalog entry below rather than a new one.
+#
 # Drum Clean+ maintenance tracking (issue #258) reuses washer.py's
 # DrumCleanProposal_/WashingTimes_/DrumCleanLog_ tokens on this same
 # options[] array -- see laundry.drum_clean_cycles_remaining/
@@ -84,7 +108,12 @@ DRYER_DIAGNOSIS = Capability(
     poll_tier="warm",
     entities=(
         SensorDesc(
-            key="diagnosis", field="x.com.samsung.da.diagnosisStart", entity_category="diagnostic"
+            key="diagnosis",
+            field="x.com.samsung.da.diagnosisStart",
+            entity_category="diagnostic",
+            device_class="enum",
+            options=("ready",),
+            value_fn=diagnosis_status,
         ),
     ),
 )

custom_components/localthings/registry/capabilities/fridge.py

@@ -25,7 +25,7 @@ from ..entities import (
     SwitchDesc,
     TimeDesc,
 )
-from .common import normalize_temp_unit
+from .common import int_or_none, normalize_temp_unit
 
 # Display names for the beverage zone, flex zone, ice type, and
 # ice-making-status enums below live in translations/en.json, keyed by the
@@ -266,6 +266,39 @@ DOOR_ALERT = Capability(
 )
 
 
+# Internal deodorizing filter (issue #318, TP1X_REF_21K). Same
+# filterUsage/filterStatus field pair as common.WATER_FILTER, but
+# filterUsage here is already a 0-100 percentage with no filterCapacity to
+# divide by (confirmed by filterStatus=="wash" at filterUsage=="100") --
+# 'air_'-prefixed keys so a fridge with both a water and an air filter gets
+# two distinct entities rather than a unique_id collision.
+AIR_FILTER = Capability(
+    href="/filter/airdustfilter/vs/0",
+    poll_tier="cold",
+    entities=(
+        SensorDesc(
+            key="air_filter_usage",
+            field="x.com.samsung.da.filterUsage",
+            unit="%",
+            state_class="measurement",
+            icon="mdi:air-filter",
+            entity_category="diagnostic",
+            value_fn=int_or_none,
+        ),
+        SensorDesc(
+            key="air_filter_status",
+            field="x.com.samsung.da.filterStatus",
+            device_class="enum",
+            options=("normal", "wash", "replace"),
+            translation_key="filter_status",
+            icon="mdi:air-filter",
+            entity_category="diagnostic",
+            value_fn=lambda v: v.lower() if isinstance(v, str) else v,
+        ),
+    ),
+)
+
+
 def _status_lock_write(field):
     return lambda p, rep, href=None: (
         ["status", "lock", "vs", "0"],
@@ -293,9 +326,154 @@ STATUS_LOCK = Capability(
             value_fn=lambda v: v == "On",
             write_fn=_status_lock_write("x.com.samsung.da.device.sound"),
         ),
+        # Auto Door Open's own voice/sound feedback toggles (issue #328,
+        # TP1X_REF_21K family) -- siblings of auto_door_opener above, not
+        # duplicates of fridge_sound (device.sound is the general appliance
+        # beep, these two gate ado's own prompts). Only seen on the
+        # auto-door-equipped variants (single/kimchi/winecellar), not the
+        # earlier TP1X_REF_21K dumps that predate that feature -- gated on
+        # each field's own presence rather than assumed universal.
+        SwitchDesc(
+            key="auto_door_voice_control",
+            field="x.com.samsung.da.ado.voicecontrol",
+            icon="mdi:microphone",
+            entity_category="config",
+            value_fn=lambda v: v == "On",
+            write_fn=_status_lock_write("x.com.samsung.da.ado.voicecontrol"),
+            exists_fn=lambda rep, resources: "x.com.samsung.da.ado.voicecontrol" in rep,
+        ),
+        SwitchDesc(
+            key="auto_door_sound_control",
+            field="x.com.samsung.da.ado.soundcontrol",
+            icon="mdi:volume-medium",
+            entity_category="config",
+            value_fn=lambda v: v == "On",
+            write_fn=_status_lock_write("x.com.samsung.da.ado.soundcontrol"),
+            exists_fn=lambda rep, resources: "x.com.samsung.da.ado.soundcontrol" in rep,
+        ),
     ),
 )
 
+# Auto Door Open's paired delay setting (issue #328, TP1X_REF_21K family):
+# how long the door stays held open before it re-closes, on/off itself is
+# STATUS_LOCK.auto_door_opener above. Same discrete-options-select shape as
+# DEFINITE_TEMPERATURE_COOLER/FREEZER. Unit unconfirmed -- no supportedList
+# field states it and the report carried no app screenshot -- so this is a
+# raw-code select rather than a guessed seconds/minutes NumberDesc.
+
+
+def _auto_door_timer_write(p, rep, href=None):
+    return ["autodoor", "timer", "vs", "0"], {"x.com.samsung.da.time.desired": p}
+
+
+AUTO_DOOR_TIMER = Capability(
+    href="/autodoor/timer/vs/0",
+    poll_tier="warm",
+    entities=(
+        SelectDesc(
+            key="auto_door_timer",
+            field="x.com.samsung.da.time.desired",
+            icon="mdi:timer-outline",
+            translation_key="auto_door_timer",
+            entity_category="config",
+            options_field="x.com.samsung.da.time.supportedOptions",
+            write_fn=_auto_door_timer_write,
+        ),
+    ),
+)
+
+# /autodoor/<variant>/vs/0 -- one per fridge sub-type sharing the Auto Door
+# Open feature (single-door, kimchi, winecellar seen so far; issue #328).
+# Each reports only x.com.samsung.da.ado.openOptions, declaring which open
+# styles that variant supports -- every dump seen so far carries exactly
+# one option ('Single') with no paired desired/current field to make a
+# choice against, the same "no real choice to expose yet" shape as
+# ignored.py's /mode/0. Bound with no entities to record coverage; revisit
+# if a device ever reports more than one option.
+#
+# A pattern cap rather than one entry per variant: match_fn (not just the
+# prefix) is what actually gates this, so a future variant href needs no
+# code change to stay covered, and /autodoor/timer/vs/0's own exact-href
+# AUTO_DOOR_TIMER above always wins for that href regardless (discover()
+# only falls through to pattern caps when no exact cap matched). This is
+# registry-scoped, not global -- unlike ignored.IGNORED, the unknown-
+# device-type fallback never reaches it, so the prefix caveat in
+# ignored.py's own docstring doesn't apply here.
+AUTO_DOOR_VARIANT = Capability(
+    href=None,
+    href_prefix="/autodoor/",
+    match_fn=lambda rep, resources: "x.com.samsung.da.ado.openOptions" in rep,
+)
+
+# Wine-cellar variant (x.com.st.d.winecellar, issue #328) of the same
+# deodorizing filter AIR_FILTER models -- filterUsage/filterStatus at a
+# different href, same 0-100-percentage-already shape (see AIR_FILTER's own
+# comment). filterUsage reads '-1' on the only dump seen (filterStatus
+# 'normal'), relayed as-is rather than special-cased -- no second dump to
+# confirm whether that's a real sentinel or this unit just not tracking it.
+# Own 'deodor_'-prefixed keys rather than reusing AIR_FILTER.entities
+# verbatim -- same collision AIR_FILTER's own 'air_' prefix was chosen to
+# avoid against WATER_FILTER, and both filters are plausible on one unit
+# (this device's own board reports an internal air filter on other
+# TP1X_REF_21K variants).
+DEODOR_FILTER = Capability(
+    href="/filter/deodorfilter/vs/0",
+    poll_tier="cold",
+    entities=(
+        SensorDesc(
+            key="deodor_filter_usage",
+            field="x.com.samsung.da.filterUsage",
+            unit="%",
+            state_class="measurement",
+            icon="mdi:air-filter",
+            entity_category="diagnostic",
+            value_fn=int_or_none,
+        ),
+        SensorDesc(
+            key="deodor_filter_status",
+            field="x.com.samsung.da.filterStatus",
+            device_class="enum",
+            options=("normal", "wash", "replace"),
+            translation_key="filter_status",
+            icon="mdi:air-filter",
+            entity_category="diagnostic",
+            value_fn=lambda v: v.lower() if isinstance(v, str) else v,
+        ),
+    ),
+)
+
+# Wine-cellar multi-compartment pantry select (issue #328): same
+# mode/supportedOptions shape as PANTRY_ZONE, at its own href with a 5-way
+# option set (Processed_Meat/Cheese/Nuts/Fruit/Wine) instead of PANTRY_ZONE's.
+# Only a "one" instance seen -- not generalized to a pattern cap, same
+# discipline as PANTRY_ZONE itself.
+
+
+def _winecellar_pantry_write(p, rep, href=None):
+    return ["status", "winecellar", "pantry", "one", "vs", "0"], {"x.com.samsung.da.mode": p}
+
+
+WINECELLAR_PANTRY_ZONE = Capability(
+    href="/status/winecellar/pantry/one/vs/0",
+    poll_tier="warm",
+    entities=(
+        SelectDesc(
+            key="winecellar_pantry_zone_mode",
+            field="x.com.samsung.da.mode",
+            icon="mdi:glass-wine",
+            translation_key="winecellar_pantry_zone_mode",
+            entity_category="config",
+            options_field="x.com.samsung.da.supportedOptions",
+            write_fn=_winecellar_pantry_write,
+        ),
+    ),
+)
+
+# Wine-cellar internal table-revision marker (issue #328) -- versioning
+# metadata, not appliance state. Same treatment as ignored.py's
+# /wm/setinfo/vs/0.
+WINECELLAR_INFO = Capability(href="/information/winecellar/vs/0")
+
 # /defrost/delay/vs/0 is the writable toggle to postpone a scheduled
 # defrost. /defrost/block/vs/0 is unrelated: despite the "block" naming,
 # live dumps confirm DEFROST_BLOCK_ON means the defrost cycle is actively

custom_components/localthings/registry/capabilities/laundry.py

@@ -23,9 +23,11 @@ Door-LED keys use NO `x.com.samsung.da.` prefix -- `setBrightness` /
 from datetime import UTC, datetime
 from datetime import time as dt_time
 
+from ... import cloudcourse
 from ...catalog import has_entity_translation
 from ..capability import Capability
 from ..entities import NumberDesc, SelectDesc, SensorDesc, SwitchDesc, TimeDesc
+from .common import hex_pairs, option_value
 
 _LED_LEVELS = ("Low", "High")
 _SOUND_MODES = ("voice", "tone", "mute")
@@ -198,11 +200,6 @@ BUZZER_SOUND = Capability(
 # boards expose the same /course/vs/0 options contract.
 
 
-def hex_pairs(codes):
-    """'1C1D21...' -> ['1C', '1D', '21', ...]."""
-    return [codes[i : i + 2] for i in range(0, len(codes) - 1, 2)]
-
-
 def parse_edit_course_list(raw):
     """'EditCourseList_1C1D21...' -> ['1C', '1D', '21', ...]."""
     if not isinstance(raw, str) or "_" not in raw:
@@ -218,14 +215,6 @@ def cycle_options(resources):
     return _course_codes_from_supported_options(resources.get("/course/vs/0") or {})
 
 
-def option_value(options, prefix):
-    """Find `<prefix>_<value>` in the options array and return <value>."""
-    for o in options or []:
-        if isinstance(o, str) and o.startswith(prefix + "_"):
-            return o.split("_", 1)[1]
-    return None
-
-
 # Drum Clean+ maintenance tracking, from the same options[] array as the
 # selected course -- shared by washer.py (issue #9) and dryer.py (issue
 # #258), identical DrumCleanProposal_/WashingTimes_/DrumCleanLog_ tokens.
@@ -309,26 +298,175 @@ def _course_codes_from_supported_options(course_rep):
     return []
 
 
+def option_tokens(*pairs):
+    """[(prefix, value), ...] -> ['<prefix>_<value>', ...] -- the general
+    form of option_write, for the one write that needs two tokens to land in
+    the same options[] array together (see cycle_write's cloud branch)."""
+    return [f"{prefix}_{value}" for prefix, value in pairs]
+
+
 def option_write(prefix, new_value):
     """A one-token x.com.samsung.da.options write -- see the module comment
     above for why this doesn't read/rewrite the whole array."""
-    return [f"{prefix}_{new_value}"]
+    return option_tokens((prefix, new_value))
+
+
+# ---------------------------------------------------------------------------
+# Cloud "Download" programs, folded into this same cycle select (issue #342).
+#
+# A device that has downloaded programs advertises them on the same
+# /course/vs/0 options array; cloudcourse.py owns the token shapes, the
+# learned store, and the reasoning for all of it. Everything below is just
+# how that store reaches the select: the coordinator merges it onto this
+# href's rep under cloudcourse.FIELD, so the option list, current value,
+# label, and write path each read it from the rep or snapshot they already
+# receive.
+#
+# They ride in the cycle select rather than a select of their own because
+# that is what they are to a user -- on the appliance's own controls,
+# "Download" occupies one position among the ordinary courses, and picking a
+# downloaded program is picking a cycle. Their raw values are namespaced
+# ('cloud:<slot>') so they can never be confused with, or collide with, a
+# two-hex-char local course code.
+#
+# Bound by whichever families declare it. Washers are where this was worked
+# out, but a DW5000C dishwasher advertises the same token (see
+# cloudcourse.py), so nothing below is washer-specific.
+#
+# Confirmed on hardware before any of this was written (issue #342): writing
+# the program token alone, while some other course is selected, is silently
+# ignored -- the course token has to switch to Download in the *same* write.
+# Hence the two-token write, the only one in this module.
+
+
+def _cloud_state(rep):
+    return rep.get(cloudcourse.FIELD) or {}
+
+
+def cloud_options(rep):
+    """Namespaced raw values for every named, learned cloud program."""
+    return [
+        f"{cloudcourse.RAW_PREFIX}{slot}" for slot in sorted(_cloud_state(rep).get("programs", {}))
+    ]
+
+
+def cloud_label(value, resources):
+    """The user's own name for a 'cloud:<slot>' value.
+
+    Cloud program names are user-supplied, never translated: the appliance
+    reports only an opaque slot id, and inventing an English label for one
+    is exactly what this module refuses to do for unrecognized local course
+    codes (see washer_cycle_fallback).
+    """
+    if not isinstance(value, str) or not value.startswith(cloudcourse.RAW_PREFIX):
+        return None
+    slot = value[len(cloudcourse.RAW_PREFIX) :]
+    rep = resources.get(cloudcourse.COURSE_HREF) or {}
+    program = _cloud_state(rep).get("programs", {}).get(slot)
+    return program["name"] if program else None
+
+
+def cloud_current(rep):
+    """'cloud:<slot>' when a named cloud program is the live selection.
+
+    Gated on the course actually being this device's confirmed Download
+    course: tokens in this array are replaced by prefix and never evicted, so
+    a one-time program token outlives the run it belonged to and would
+    otherwise report "Jeans" while an ordinary cotton cycle runs.
+    """
+    state = _cloud_state(rep)
+    download = state.get("download_course")
+    options = rep.get("x.com.samsung.da.options")
+    if not download or option_value(options, "Course") != download:
+        return None
+    blob = option_value(options, cloudcourse.ONESHOT_PREFIX)
+    slot = cloudcourse.slot_of(blob)
+    if slot is None:
+        # No one-time override loaded: the appliance falls back to whatever
+        # the persisted default holds (confirmed with the issue #342
+        # reporter -- leaving Download and returning to it re-selects the
+        # saved program, not the last one-time one).
+        slot = cloudcourse.slot_of(option_value(options, cloudcourse.DEFAULT_PREFIX))
+    if slot is None or slot not in state.get("programs", {}):
+        return None
+    return f"{cloudcourse.RAW_PREFIX}{slot}"
 
 
 def cycle_write(p, rep, href=None):
     if not rep.get("x.com.samsung.da.options"):
         return None
+    if isinstance(p, str) and p.startswith(cloudcourse.RAW_PREFIX):
+        return _cloud_cycle_write(p, rep)
     return ["course", "vs", "0"], {
         "x.com.samsung.da.options": option_write("Course", p),
     }
 
 
+def _cloud_cycle_write(p, rep):
+    state = _cloud_state(rep)
+    download = state.get("download_course")
+    program = state.get("programs", {}).get(p[len(cloudcourse.RAW_PREFIX) :])
+    if not download or program is None:
+        return None
+    # Order matches what the appliance was confirmed to accept.
+    return ["course", "vs", "0"], {
+        "x.com.samsung.da.options": option_tokens(
+            ("Course", download), (cloudcourse.ONESHOT_PREFIX, program["blob"])
+        ),
+    }
+
+
+def personal_course_labels(resources, href="/wm/personalcourse/vs/0"):
+    """Return device-provided personal course names keyed by course code.
+
+    Populated entries use a small TLV payload. The leading field is
+    ``01 <UTF-8-byte-length> <name>``; later fields contain a description and
+    settings and are intentionally left uninterpreted. Empty slots are
+    encoded as ``<code>_00``. Malformed or undecodable entries are ignored so
+    opaque device data can never become a misleading label.
+    """
+    rep = resources.get(href) or {}
+    labels = {}
+    for entry in rep.get("x.com.samsung.da.courses") or []:
+        if not isinstance(entry, str) or "_" not in entry:
+            continue
+        code, encoded = entry.split("_", 1)
+        try:
+            payload = bytes.fromhex(encoded)
+        except ValueError:
+            continue
+        if len(payload) < 3 or payload[0] != 0x01:
+            continue
+        name_length = payload[1]
+        if name_length == 0 or len(payload) < 2 + name_length:
+            continue
+        try:
+            name = payload[2 : 2 + name_length].decode("utf-8")
+        except UnicodeDecodeError:
+            continue
+        if name.strip() and name.isprintable():
+            labels[code.upper()] = name
+    return labels
+
+
+def washer_cycle_fallback(value, resources):
+    """Label a personal washer course from its device-provided name.
+
+    No fallback for an unrecognized standard code -- an invented English
+    label would defeat translation (PR #251 review); the raw code displays
+    instead, same as before this function existed.
+    """
+    if not isinstance(value, str):
+        return None
+    return personal_course_labels(resources).get(value.upper())
+
+
 def _table_id(resources, table_href):
     rep = resources.get(table_href) or {}
     return rep.get("x.com.samsung.da.st.courseTable")
 
 
-def cycle_select(*, translation_key, icon, table_href=None):
+def cycle_select(*, translation_key, icon, table_href=None, display_fn=None):
     """A 'Cycle' select over /course/vs/0, labelled from `translation_key`.
 
     The option list, current value, and write path are shared across
@@ -346,9 +484,19 @@ def cycle_select(*, translation_key, icon, table_href=None):
     instead of borrowing a label from another board generation --
     translating a new table is a translations-only change.
 
+    The raw course code remains writable regardless; its display uses
+    display_fn when supplied, otherwise it remains raw. display_fn is an
+    optional family-specific fallback for untranslated raw values --
+    select.py applies it after catalog lookup to both state and options.
+
     Left at its default for dishwasher, which has no equivalent table-id
     resource and no evidence its codes vary by table the way washer/
     dryer's do.
+
+    Any cloud "Download" programs the user has discovered and named join the
+    same option list, after the local courses -- see the cloud section above.
+    A device with none (or one whose owner hasn't named any yet) gets exactly
+    the list it got before they existed.
     """
     key = translation_key
     if table_href is not None:
@@ -360,13 +508,31 @@ def cycle_select(*, translation_key, icon, table_href=None):
             candidate = f"{translation_key}_{table.lower()}"
             return candidate if has_entity_translation("select", candidate) else "cycle"
 
+    def options(resources):
+        rep = resources.get(cloudcourse.COURSE_HREF) or {}
+        # Local courses first: a user-supplied cloud name that happens to
+        # match a translated course name resolves back to the real local
+        # course on write, which is the safer of the two. The options flow
+        # rejects such a name outright, so this is a backstop, not the fix.
+        return [*cycle_options(resources), *cloud_options(rep)]
+
+    def current(rep):
+        return cloud_current(rep) or option_value(rep.get("x.com.samsung.da.options"), "Course")
+
+    def label(value, resources):
+        cloud = cloud_label(value, resources)
+        if cloud is not None:
+            return cloud
+        return display_fn(value, resources) if display_fn is not None else None
+
     return SelectDesc(
         key="cycle",
         icon=icon,
         translation_key=key,
-        options=cycle_options,
-        exists_fn=lambda rep, resources: bool(cycle_options(resources)),
-        rep_fn=lambda rep: option_value(rep.get("x.com.samsung.da.options"), "Course"),
+        options=options,
+        exists_fn=lambda rep, resources: bool(options(resources)),
+        rep_fn=current,
+        display_fn=label,
         write_fn=cycle_write,
     )
 

custom_components/localthings/registry/capabilities/operational.py

@@ -6,6 +6,7 @@ Shared by dryer/dishwasher/oven/washer families.
 import math
 from datetime import UTC, datetime, timedelta
 
+from ...catalog import translated_states
 from ..capability import Capability
 from ..entities import BinarySensorDesc, ButtonDesc, NumberDesc, SensorDesc
 
@@ -25,7 +26,7 @@ def _to_ocf(v):
 
 
 def _progress(v):
-    return "Idle" if v in (None, "None") else v
+    return "idle" if v in (None, "None") else str(v).lower()
 
 
 def _int(v):
@@ -35,12 +36,48 @@ def _int(v):
         return None
 
 
+def _state_is_active(rep):
+    return _SAMSUNG_STATE_TO_OCF.get(rep.get("x.com.samsung.da.state")) == "active"
+
+
 def _is_active(rep):
     """Check if appliance is actively running and cycle is not finished."""
-    return (
-        _SAMSUNG_STATE_TO_OCF.get(rep.get("x.com.samsung.da.state")) == "active"
-        and rep.get("x.com.samsung.da.progress") != "Finish"
-    )
+    return _state_is_active(rep) and rep.get("x.com.samsung.da.progress") != "Finish"
+
+
+def _just_finished(rep):
+    """progress/progress_percentage's sticky_fn (issue #345, see sensor.py's
+    _apply_sticky): arms their grace window the moment `progress` reads
+    'Finish'.
+
+    Deliberately not also requiring `state == 'active'` in the same rep,
+    unlike _is_active above: #345 reports a washer whose `state` can
+    already read idle by the time `progress` is observed at 'Finish' --
+    the same-family dryer's firmware apparently keeps `state` at 'active'
+    longer, per the report -- so requiring both together risked the arm
+    condition never actually firing on the one device this fixes.
+    _apply_sticky's edge-triggering (only a fresh False->True transition
+    (re)arms) is what keeps a `progress` stuck at 'Finish' indefinitely
+    (the same class of quirk `_completion_minutes` below already works
+    around) from holding this open forever instead."""
+    return rep.get("x.com.samsung.da.progress") == "Finish"
+
+
+def _new_cycle_running(rep):
+    """progress/progress_percentage's sticky_bypass_fn: drop the #345 hold
+    early once a new cycle is genuinely running.
+
+    Gated on `state == 'active'`, unlike _just_finished's arm condition
+    above: issue #358's dryer resets `progress` to its course's first
+    stage ('Drying') in the same moment `state` goes idle, ~4s before
+    settling to 'None' -- confirmed by the reporter's machine_state
+    history, which flips to idle on the exact second progress reads
+    'Drying', in both captured cycles. A bypass keyed on the progress
+    code alone read that as a new cycle and republished it. Releasing
+    late costs nothing -- an unreleased hold still expires on its own --
+    so this side takes the stronger signal."""
+    v = rep.get("x.com.samsung.da.progress")
+    return _state_is_active(rep) and v is not None and v not in ("None", "Finish")
 
 
 def _remaining_seconds(raw):
@@ -75,7 +112,7 @@ def _delay_hours(v):
 def _format_delay(hours):
     total_minutes = round(max(float(hours), 0) * 60)
     h, m = divmod(total_minutes, 60)
-    return f"{h}:{m:02d}:00"
+    return f"{h:02d}:{m:02d}:00"
 
 
 def _delay_field(rep):
@@ -153,19 +190,30 @@ OPERATIONAL_STATE = Capability(
         BinarySensorDesc(
             key="cycle_active",
             device_class="running",
-            rep_fn=lambda rep: (
-                _SAMSUNG_STATE_TO_OCF.get(rep.get("x.com.samsung.da.state")) == "active"
-                and rep.get("x.com.samsung.da.progress") != "Finish"
-            ),
+            rep_fn=_is_active,
         ),
+        # sticky_* (issue #345): once progress reads 'Finish', keep
+        # showing Finish/100 for a grace window even after machine_state
+        # reverts, rather than falling to Idle/0 the instant it does --
+        # see sensor.py's _apply_sticky. rep_fn below is unchanged and
+        # stays the only definition of a live value -- the hold decides
+        # only *whether* to freeze. A second, ungated one here is what
+        # let issue #358's post-Finish tail reach the entity.
         SensorDesc(
             key="progress",
             icon="mdi:progress-wrench",
+            device_class="enum",
+            options=tuple(sorted(translated_states("sensor", "progress"))),
             rep_fn=lambda rep: (
-                "Idle"
-                if _SAMSUNG_STATE_TO_OCF.get(rep.get("x.com.samsung.da.state")) != "active"
+                "idle"
+                if not _state_is_active(rep)
                 else _progress(rep.get("x.com.samsung.da.progress"))
             ),
+            sticky_fn=_just_finished,
+            # The catalog key, not the device's 'Finish': rep_fn is normalized
+            # now, and a held value outside `options` is what HA rejects.
+            sticky_value_fn=lambda rep: "finish",
+            sticky_bypass_fn=_new_cycle_running,
         ),
         SensorDesc(
             key="progress_percentage",
@@ -173,9 +221,12 @@ OPERATIONAL_STATE = Capability(
             state_class="measurement",
             rep_fn=lambda rep: (
                 0
-                if _SAMSUNG_STATE_TO_OCF.get(rep.get("x.com.samsung.da.state")) != "active"
+                if not _state_is_active(rep)
                 else _int(rep.get("x.com.samsung.da.progressPercentage"))
             ),
+            sticky_fn=_just_finished,
+            sticky_value_fn=lambda rep: 100,
+            sticky_bypass_fn=_new_cycle_running,
         ),
         # Only show finish time while actively running -- firmware leaves a
         # stale remainingTime after a cycle ends, frozen at '00:01:00'.

custom_components/localthings/registry/capabilities/oven.py

@@ -401,10 +401,17 @@ OVEN_MODE = Capability(
             value_fn=lambda v: v[0] if v else None,
             write_fn=_oven_mode_write,
         ),
+        # No exists_fn on the NV7000BS-class board this was proven against
+        # (UpperLamp_ is always in its options[]) -- but issue #300's
+        # steam-oven-class WALLOVEN board's options[] has no UpperLamp_
+        # token at all, so this was a phantom, always-off, write-does-
+        # nothing switch there. Same fastpreheat/NaturalSteam-class gap
+        # issue #183 already fixed on the other switches below.
         SwitchDesc(
             key="lamp",
             field="x.com.samsung.da.options",
             icon="mdi:track-light",
+            exists_fn=_has_option("UpperLamp"),
             value_fn=lambda opts: _option_value(opts, "UpperLamp") == "On",
             write_fn=_option_switch_write("UpperLamp"),
         ),

custom_components/localthings/registry/capabilities/range.py

@@ -148,11 +148,13 @@ COOKTOP_STATUS = Capability(
             value_fn=lambda v: str(v).lower() == "on",
         ),
         # Safe to write -- a lock toggle, not a heat control -- via a
-        # direct single-field PUT, no RMW needed.
+        # direct single-field PUT, no RMW needed. No device_class:
+        # SwitchDeviceClass only has 'outlet'/'switch', not 'lock' --
+        # passing it crashed switch platform setup for the whole device
+        # (issue #349, same bug as water_purifier.py's lock switches).
         SwitchDesc(
             key="cooktop_child_lock",
             field="childLock",
-            device_class="lock",
             entity_category="config",
             icon="mdi:lock",
             value_fn=lambda v: str(v).lower() == "on",

custom_components/localthings/registry/capabilities/vacuum_station.py

@@ -1,19 +1,14 @@
 """Capabilities for the Samsung stick-vacuum clean/auto-empty station
-(model A-VSKR-TP1-22-VS9500AL, "Bespoke Jet" clean station, issue #131).
+(models A-VSKR-TP1-22-VS9500AL / A-VSWW-TP1-23-VS9700, issues #131 / #219).
 
-The reporter's diagnostics dump shows no vacuum-body state at all (no
-suction level, no battery, no cleaning-mode/room-mapping control, no
-docked/undocked status even) -- only the clean station's own dustbag,
-dustbin auto-empty settings, and UV-C sanitizing-cycle status. This
-strongly suggests the WiFi/DTLS module lives in the station, not the
-handheld stick: the station is the only "device" this integration's local
-API can see, and the wand's own controls are unrelated hardware not
-reachable this way. Modeled as its own device type -- these hrefs don't
-overlap with any existing family, so there's no shared-href ambiguity to
-resolve against another type (see registry/by_type/__init__.py's
-docstring for that rule).
+The WiFi/DTLS module lives in the clean station. Older VS9500 dumps
+(#131) exposed only dustbag/dustbin/UV-C station state. VS9700 dumps
+(#219) additionally expose `/status/stick/vs/0` with the wand's battery
+%, cleaning/charging status, and BLE link -- still no suction/room-map
+control. Modeled as its own device type -- these hrefs don't overlap with
+any existing family (see registry/by_type/__init__.py's docstring).
 
-Resources verified against the issue #131 diagnostics dump.
+Resources verified against issue #131 and #219 diagnostics dumps.
 """
 
 from ..capability import Capability
@@ -156,3 +151,43 @@ CLEANSTATION_STATUS = Capability(
         ),
     ),
 )
+
+# Wand body state reported through the station (VS9700 / issue #219). Absent
+# on the older VS9500 dump (#131) -- discovery drops entities when the href
+# is missing.
+STICK_BODY = Capability(
+    href="/status/stick/vs/0",
+    poll_tier="warm",
+    entities=(
+        SensorDesc(
+            key="battery",
+            field="x.com.samsung.da.stickbattery",
+            device_class="battery",
+            state_class="measurement",
+            unit="%",
+            value_fn=int_or_none,
+        ),
+        BinarySensorDesc(
+            key="battery_charging",
+            field="x.com.samsung.da.stickcleaningstatus",
+            device_class="battery_charging",
+            value_fn=lambda v: v == "Charging",
+        ),
+        SensorDesc(
+            key="stick_cleaning_status",
+            field="x.com.samsung.da.stickcleaningstatus",
+            icon="mdi:vacuum",
+        ),
+        SensorDesc(
+            key="stick_operation_mode",
+            field="x.com.samsung.da.stickoperationmode",
+            icon="mdi:broom",
+        ),
+        BinarySensorDesc(
+            key="stick_ble_connected",
+            field="x.com.samsung.da.stickbleconnection",
+            device_class="connectivity",
+            value_fn=lambda v: v == "On",
+        ),
+    ),
+)

custom_components/localthings/registry/capabilities/washer.py

@@ -16,7 +16,7 @@ array.
 """
 
 from ..capability import Capability
-from ..entities import BinarySensorDesc, SelectDesc, SensorDesc
+from ..entities import BinarySensorDesc, SelectDesc, SensorDesc, SwitchDesc
 from .laundry import (
     bool_option_exists,
     bool_option_switch,
@@ -27,6 +27,7 @@ from .laundry import (
     hex_pairs,
     option_value,
     option_write,
+    washer_cycle_fallback,
 )
 
 # Course_XX hex code labels (translations/en.json,
@@ -38,9 +39,12 @@ from .laundry import (
 # editCourseList and screenshots (issue #22, a combo's own course set, not
 # implying anything about a plain washer's '1F'); 3 more (Eco Cold, Towels,
 # Self Clean+) verified directly on a WF50A8600AV/US by reading back the raw
-# code after selecting each cycle on the appliance (issue #80). Two code
-# pairs ('21'/'65' Colors, '27'/'5E' Rinse+Spin, and '24'/'54' Towels)
-# legitimately share a label across different course tables -- not typos.
+# code after selecting each cycle on the appliance (issue #80). 2 more
+# ('0A' Towels, 'B0' Mixed Load) reported for a WW90DG5G34ABLE on the same
+# Table_02 family (issue #363). Several codes legitimately share a label
+# across different course tables -- '21'/'65' Colors, '27'/'5E'/'78'
+# Rinse+Spin, '0A'/'33'/'54'/'70' Towels -- not typos. (This list said
+# "'24' Towels" until issue #343 found 24/33 transposed; 24 is Bedding.)
 #
 # No static fallback list is kept here: other models have different actual
 # course sets, so hardcoding one device's list would show/hide the wrong
@@ -50,6 +54,23 @@ from .laundry import (
 # options' MostUsed_* entry was considered as a fallback source (its first
 # byte matches the selected Course_XX on both dumps), but the remaining
 # bytes don't decode to any confirmed course code, so it isn't used.
+#
+# The owner of a Korean Table_02 washer confirmed the names for its newer
+# 69/6A-79/88 course-code family, including Course_69 as AI Wash. Those names
+# live only in the table-scoped translation catalog; a code not confirmed by
+# the owner or device metadata falls back to washer_cycle_fallback, which
+# surfaces a personal-course name only -- no invented English label for an
+# unrecognized standard code (PR #251 review).
+#
+# washer_cycle_table_00 (issue #357) is a separate, older course-code family
+# reported by a WF45R6300AW/US -- confirmed by the reporter selecting each
+# cycle on the appliance and reading back the raw code, the same method used
+# for Table_02's WF50A8600AV/US codes above. A device reporting Table_00 with
+# an unconfirmed code (FlexWash's washer_flexwash_device fixture, for
+# instance) still renders that code raw rather than borrowing a Table_02
+# label -- the two tables are unrelated code spaces despite a handful of
+# overlapping hex values.
+# ---------------------------------------------------------------------------
 
 # /washer/vs/0 -- wash temperature, spin speed, rinse cycle count.
 # Despite the shared href, this is unrelated to dryer.DRYER_SETTINGS (also
@@ -243,6 +264,105 @@ def _bool_option_switch(key, icon, prefix, availability_field):
     )
 
 
+# AddWash -- the little door for adding a forgotten sock mid-cycle -- rides
+# three independent tokens on the same options[] array:
+#
+#   AddWashSet_<0-7>         the alarm setting, and the only writable one:
+#                            a 3-bit mask over the moments it fires, bit 0
+#                            rinse, bit 1 final rinse, bit 2 spin.
+#   AddWashAvailable_<0-7>   the same three bits, but what the running
+#                            course still permits.
+#   AddWashIndicator_On/Off  the panel lamp: laundry may go in right now.
+#
+# Bit order confirmed by watching a WW6500 run a cycle: AddWashAvailable
+# shed one bit as each moment passed (7 through Rinse, then 6, 4, and 0 as
+# Spin began) and reset to 7 at the end, while the lamp tracked the phase
+# with the alarm switched off throughout.
+
+
+def _add_wash_mask(rep, prefix):
+    """One of the 3-bit AddWash masks, or None when its token is absent,
+    malformed, or outside 0-7. Never 0 for a missing token: 0 is a real
+    value, and a mask this model can't represent is a wrong model rather
+    than something to write back."""
+    raw = option_value(rep.get("x.com.samsung.da.options"), prefix)
+    try:
+        mask = int(raw)
+    except (TypeError, ValueError):
+        return None
+    return mask if 0 <= mask <= 0b111 else None
+
+
+def _add_wash_any(prefix):
+    """Whether any of the three moments is set in `prefix`'s mask."""
+
+    def read(rep):
+        mask = _add_wash_mask(rep, prefix)
+        return None if mask is None else mask != 0
+
+    return read
+
+
+def _add_wash_set_write(mask):
+    return ["course", "vs", "0"], {
+        "x.com.samsung.da.options": option_write("AddWashSet", str(mask)),
+    }
+
+
+def _add_wash_alarm_write(p, rep, href=None):
+    # Gated on the mask being readable, like the per-moment writes: a device
+    # reporting a wider mask than these three bits would otherwise have it
+    # truncated to 7 here, silently dropping a moment it supports.
+    mask = _add_wash_mask(rep, "AddWashSet")
+    if p not in ("On", "Off") or mask is None:
+        return None
+    if p == "On" and mask:
+        # Already on, so "on" is a no-op rather than a rewrite to 7. Home
+        # Assistant calls turn_on regardless of current state, so an
+        # automation asserting the alarm on over a rinse-only mask would
+        # otherwise widen it to all three moments with no state change on
+        # this switch to point at. Distinct from the off-then-on case in
+        # _add_wash_bit_switch, where there is no subset left to keep.
+        return None
+    return _add_wash_set_write(0b111 if p == "On" else 0)
+
+
+def _add_wash_bit_switch(key, icon, bit):
+    """One moment the alarm fires at, as its own bit of the mask.
+
+    The mask is the only state, so switching the last moment off lands on 0
+    and takes the alarm with it, and switching one on from 0 turns the alarm
+    back on. The corollary is that switching the master off and on again
+    writes 7, resetting a rinse-only selection to all three moments -- the
+    appliance remembers no previous subset either, so there is nothing to
+    restore.
+    """
+
+    def read(rep):
+        mask = _add_wash_mask(rep, "AddWashSet")
+        return None if mask is None else bool(mask >> bit & 1)
+
+    def write(p, rep, href=None):
+        mask = _add_wash_mask(rep, "AddWashSet")
+        if p not in ("On", "Off") or mask is None:
+            return None
+        return _add_wash_set_write(mask | 1 << bit if p == "On" else mask & ~(1 << bit))
+
+    return SwitchDesc(
+        key=key,
+        icon=icon,
+        entity_category="config",
+        exists_fn=bool_option_exists("AddWashSet"),
+        rep_fn=read,
+        write_fn=write,
+    )
+
+
+def _add_wash_indicator(rep):
+    raw = option_value(rep.get("x.com.samsung.da.options"), "AddWashIndicator")
+    return raw.lower() == "on" if isinstance(raw, str) else None
+
+
 WASHER_COURSE = Capability(
     href="/course/vs/0",
     entities=(
@@ -250,6 +370,7 @@ WASHER_COURSE = Capability(
             translation_key="washer_cycle",
             icon="mdi:washing-machine",
             table_href="/st/washercourse/vs/0",
+            display_fn=washer_cycle_fallback,
         ),
         SensorDesc(
             key="drum_clean_cycles_remaining",
@@ -328,5 +449,33 @@ WASHER_COURSE = Capability(
         _bool_option_switch(
             "intensive", "mdi:washing-machine", "IntensiveSetting", "IntensiveAvailableSet"
         ),
+        SwitchDesc(
+            key="add_wash_alarm",
+            icon="mdi:bell-ring",
+            entity_category="config",
+            exists_fn=bool_option_exists("AddWashSet"),
+            rep_fn=_add_wash_any("AddWashSet"),
+            write_fn=_add_wash_alarm_write,
+        ),
+        _add_wash_bit_switch("add_wash_alarm_rinse", "mdi:water", 0),
+        _add_wash_bit_switch("add_wash_alarm_final_rinse", "mdi:water-check", 1),
+        _add_wash_bit_switch("add_wash_alarm_spin", "mdi:sync", 2),
+        # On at rest: an idle washer reports AddWashAvailable_7 and the mask
+        # only empties as the cycle consumes each moment. This says the cycle
+        # permits AddWash, not that laundry can go in now -- that is
+        # add_wash_indicator.
+        BinarySensorDesc(
+            key="add_wash_available",
+            icon="mdi:tshirt-crew-outline",
+            entity_category="diagnostic",
+            exists_fn=bool_option_exists("AddWashAvailable"),
+            rep_fn=_add_wash_any("AddWashAvailable"),
+        ),
+        BinarySensorDesc(
+            key="add_wash_indicator",
+            icon="mdi:door-open",
+            exists_fn=bool_option_exists("AddWashIndicator"),
+            rep_fn=_add_wash_indicator,
+        ),
     ),
 )

custom_components/localthings/registry/capabilities/water_purifier.py

@@ -182,10 +182,15 @@ FAVORITE_HOTWATER = Capability(
         # adapter.flatten() only ever honors exists_fn, not entity.py's
         # implicit field-presence default -- without it, whichever
         # same-keyed descriptor is processed last would silently win.
+        # No device_class: SwitchDeviceClass only has 'outlet'/'switch',
+        # not 'lock' -- passing it crashed switch platform setup entirely
+        # for the whole device (issue #349), same bug KIDS_LOCK_GENERIC
+        # dodged by switching to BinarySensorDesc (issues #181/#183). This
+        # entity stays a SwitchDesc since it's genuinely writable.
         SwitchDesc(
             key="hotwater_lock",
             field="x.com.samsung.da.switchHotwater",
-            device_class="lock",
+            icon="mdi:lock",
             entity_category="config",
             value_fn=lambda v: v != "Unlocked",
             exists_fn=lambda rep, resources: (
@@ -354,11 +359,13 @@ LOCK = Capability(
     entities=(
         # Shares its key with FAVORITE_HOTWATER's switchHotwater fallback
         # above (issue #144); see the comment there. A stub rep ({}) still
-        # counts as "present" here, matching entity.py's own default.
+        # counts as "present" here, matching entity.py's own default. No
+        # device_class on any of the three locks below -- see the
+        # device_class note on FAVORITE_HOTWATER's hotwater_lock (issue #349).
         SwitchDesc(
             key="hotwater_lock",
             field="x.com.samsung.da.hotwaterLock",
-            device_class="lock",
+            icon="mdi:lock",
             entity_category="config",
             value_fn=lambda v: v != "Unlocked",
             exists_fn=lambda rep, resources: not rep or "x.com.samsung.da.hotwaterLock" in rep,
@@ -370,7 +377,7 @@ LOCK = Capability(
         SwitchDesc(
             key="coldwater_lock",
             field="x.com.samsung.da.coldwaterLock",
-            device_class="lock",
+            icon="mdi:lock",
             entity_category="config",
             value_fn=lambda v: v != "Unlocked",
             write_fn=lambda p, rep, href=None: (
@@ -381,7 +388,7 @@ LOCK = Capability(
         SwitchDesc(
             key="buzz_lock",
             field="x.com.samsung.da.buzzLock",
-            device_class="lock",
+            icon="mdi:lock",
             entity_category="config",
             value_fn=lambda v: v != "Unlocked",
             write_fn=lambda p, rep, href=None: (

custom_components/localthings/registry/entities.py

@@ -19,6 +19,7 @@ WriteFn = Callable[[Any, dict], "tuple[list[str], dict] | None"] | None
 # cross-resource lookups exists_fn needs (e.g. reading a sibling href's live
 # option list).
 ValidateFn = Callable[[Any, dict, dict], "str | None"] | None
+DisplayFn = Callable[[Any, dict], Any] | None
 
 
 def _identity(v: Any) -> Any:
@@ -63,6 +64,18 @@ class SensorDesc(SamsungEntityDescription):
     # (see sensor.py). Only for values expected to jitter between
     # device-side revisions -- not a general-purpose flag.
     hysteresis: bool = False
+    # Opt-in, entity-instance-only hold -- see sensor.py's _apply_sticky
+    # for the full contract (arm/value/bypass semantics, one window per
+    # bypass, why this never touches the coordinator cache).
+    # sticky_fn arms it; sticky_value_fn picks what to freeze at that
+    # moment (defaults to rep_fn's own result); sticky_bypass_fn drops the
+    # hold and lets rep_fn's own live result through; sticky_seconds
+    # bounds how long it can hold. There is deliberately no hook for
+    # computing a live value differently from rep_fn -- see issue #358.
+    sticky_fn: Callable[[dict], bool] | None = None
+    sticky_value_fn: Callable[[dict], Any] | None = None
+    sticky_bypass_fn: Callable[[dict], bool] | None = None
+    sticky_seconds: float = 300.0
 
 
 @dataclass(frozen=True, kw_only=True)
@@ -77,6 +90,10 @@ class SelectDesc(SamsungEntityDescription):
     # snapshot (not just this entity's own href) and returns raw device
     # option values; see select.py's LocalThingsSelect._raw_options().
     options_field: str | None = None  # resource field that contains the live options list
+    # Optional device-specific fallback for values absent from the translation
+    # catalog. Receives (raw_value, canonical_resources); select.py applies it
+    # identically to the current state and every option.
+    display_fn: DisplayFn = None
     write_fn: WriteFn = None
 
 

custom_components/localthings/registry/identity.py

@@ -13,6 +13,12 @@ class DeviceIdentity:
     model: str
     name: str
     serial: str | None
+    # /oic/d's `di` and /oic/p's `pi` -- OCF's own device and platform
+    # UUIDs. Promoted out of `raw` into named fields because
+    # resolve_device_key mints permanent registry keys from them; see its
+    # docstring for why `di` leads.
+    device_id: str | None = None
+    platform_id: str | None = None
     device_types: tuple[str, ...] = ()
     raw: dict[str, dict | list] = field(default_factory=dict)
 
@@ -57,6 +63,63 @@ def resolve_serial(raw_serial: str | None, host: str) -> str:
     return s
 
 
+def is_usable_device_id(value: str | None) -> bool:
+    """True for an OCF `di`/`pi` that actually identifies one unit.
+
+    Rejects OCF's nil UUID, which firmware that never had one assigned
+    reports on every unit of the family -- the #189 failure mode on a new
+    field, and one `is_placeholder_serial`'s repeated-digit rule misses
+    because the dashes make more than one distinct character. Past that the
+    same known-junk rules apply: a board flashed with 'Nothing(SVC)' in one
+    identity field is not one to trust in another.
+    """
+    s = (value or "").strip()
+    if not s:
+        return False
+    if not set(s) - {"0", "-"}:
+        return False
+    return not is_placeholder_serial(s)
+
+
+def ocf_device_key(identity: DeviceIdentity | None) -> str | None:
+    """The OCF-derived half of resolve_device_key's chain, or None when the
+    device reported no usable UUID.
+
+    Split out because "no UUID" and "this UUID" are different answers to a
+    caller holding an existing key: the coordinator must never demote an
+    entry off its UUID just because one poll couldn't read /oic/d.
+    Normalized so firmware that changes case between reads doesn't look
+    like a different appliance.
+    """
+    if identity is None:
+        return None
+    for candidate in (identity.device_id, identity.platform_id):
+        if candidate is not None and is_usable_device_id(candidate):
+            return candidate.strip().lower()
+    return None
+
+
+def resolve_device_key(identity: DeviceIdentity | None, raw_serial: str | None, host: str) -> str:
+    """The identity to mint this device's permanent registry keys from.
+
+    Tried in order: /oic/d's `di`, /oic/p's `pi`, the serialNum, the host.
+
+    `di` leads because it is what the protocol already uses to address this
+    endpoint: if it were wrong or shared, OCF discovery and the DTLS
+    association would not work at all. serialNum is a vendor-populated
+    string nothing depends on, which is why three firmware families have
+    shipped it unusable -- 'Nothing(SVC)' (#83), a flash-unset sentinel
+    (#189), and a well-formed serial duplicated across every unit (#381).
+
+    `pi` is only the fallback despite the spec calling it immutable: it is
+    *platform*-scoped, so a board hosting several logical OCF devices
+    shares one across all of them. `di` is device-scoped, the granularity
+    of a config entry. The serial and host stay below both so a board
+    answering neither resource lands where it always did.
+    """
+    return ocf_device_key(identity) or resolve_serial(raw_serial, host)
+
+
 def resolve_model(model_num: str, identity: DeviceIdentity | None) -> str:
     """The model string to name and register a device under.
 
@@ -143,6 +206,8 @@ def read_identity(sess, serial: str | None) -> DeviceIdentity:
         model=p.get("mnmo") or "",
         name=d.get("n") or "",
         serial=serial,
+        device_id=d.get("di") if isinstance(d.get("di"), str) else None,
+        platform_id=p.get("pi") if isinstance(p.get("pi"), str) else None,
         device_types=_device_types(d),
         # Kept whole rather than field-by-field: outside the /device/0 dump
         # diagnostics already captures, and we don't yet know which fields

custom_components/localthings/registry/redact.py

@@ -30,13 +30,18 @@ _SENSITIVE_SUBSTRINGS = (
     "secret",
 )
 
-# Matched whole, not as substrings: OCF's /oic/d and /oic/p identify the
-# unit with bare one/two-letter keys too short for the substring rules above
-# ('di' is a substring of 'condition', 'display', ...). 'di'/'pi' are the
-# device/platform UUIDs; 'n' is /oic/d's free-text device name, which may
-# carry a person's name -- the device-type signal we actually want from
-# that resource is `rt`, which is not redacted.
-_SENSITIVE_EXACT = frozenset({"di", "pi", "n"})
+# Matched whole, not as substrings: these are bare one/two-letter keys too
+# short for the substring rules above ('n' is a substring of very nearly
+# everything). 'n' is /oic/d's free-text device name, which the owner sets
+# from the SmartThings app and can carry a person's name -- the device-type
+# signal we actually want from that resource is `rt`, which is not redacted.
+#
+# /oic/d's `di` and /oic/p's `pi` are deliberately not redacted: they're
+# randomly-assigned per-unit UUIDs rather than account data, and they are
+# what registry keys are minted from (issue #381), so blanking them hides
+# the identity every entity in a report is named after -- which is exactly
+# what made #381's first diagnostics download unable to answer it.
+_SENSITIVE_EXACT = frozenset({"n"})
 
 
 def _is_sensitive_key(key: str) -> bool:

custom_components/localthings/registry/subdevices.py

@@ -37,6 +37,7 @@ appliance's own bookkeeping, not evidence of a second indoor unit -- see
 from __future__ import annotations
 
 import re
+import time
 from collections.abc import Callable, Sequence
 from dataclasses import dataclass
 
@@ -221,12 +222,12 @@ def _seed_href(path_segs: tuple[str, ...]) -> str:
     return "/" + "/".join(path_segs)
 
 
-def _get_raw(sess, path_segs: tuple[str, ...]):
+def _get_raw(sess, path_segs: tuple[str, ...], timeout: float = 10.0):
     """GET `path_segs` and CBOR-decode the payload, or None on any
     missing/malformed response (a 4.04, a timeout, an empty payload) --
     shared tolerated-absence posture for both callers below."""
     try:
-        code, pl = sess.get(list(path_segs), timeout=10.0)
+        code, pl = sess.get(list(path_segs), timeout=timeout)
         if code == 0x45 and pl:
             return cbor2.loads(pl)
     except Exception:
@@ -234,19 +235,29 @@ def _get_raw(sess, path_segs: tuple[str, ...]):
     return None
 
 
-def _get_batch(sess, path_segs: tuple[str, ...]) -> dict[str, dict]:
+def _get_batch(
+    sess,
+    path_segs: tuple[str, ...],
+    timeout: float = 10.0,
+) -> dict[str, dict]:
     """GET a Samsung Collection resource and parse it the same way
     /device/0 itself is parsed (parse_device0_batch): a [devcol-rep,
     {href, rep}, ...] CBOR list, not a bare Property map."""
-    body = _get_raw(sess, path_segs)
+    body = _get_raw(sess, path_segs, timeout)
     return parse_device0_batch(body) if isinstance(body, list) else {}
 
 
-def _get_property(sess, path_segs: tuple[str, ...]) -> dict:
+def _get_property(
+    sess,
+    path_segs: tuple[str, ...],
+    timeout: float = 10.0,
+) -> dict:
     """GET a plain OCF Property-map resource (a bare dict, not a Collection
-    batch). Used for `/multidevice/vs/0`: listed in `/oic/res` but absent
-    from `/device/0`'s batch, so it needs its own RETRIEVE."""
-    body = _get_raw(sess, path_segs)
+    batch). Used for `/multidevice/vs/0` (issue #177 follow-up): listed in
+    `/oic/res` on the Pattern A reporter's board but absent from
+    `/device/0`'s batch, so it needs its own RETRIEVE, and it answers a
+    single Property map, not a [devcol-rep, ...] list."""
+    body = _get_raw(sess, path_segs, timeout)
     return body if isinstance(body, dict) else {}
 
 
@@ -255,6 +266,11 @@ def enumerate_subdevices(
     resources: dict[str, dict],
     oic_res_links,
     probe_log: Callable[[str, bool], None] | None = None,
+    *,
+    preferred_hrefs: Sequence[str] = (),
+    time_budget: float | None = None,
+    collection_timeout: float = 10.0,
+    property_timeout: float = 10.0,
 ) -> tuple[list[Subdevice], dict[str, dict]]:
     """Discover every sibling indoor subdevice reachable over `sess`'s
     connection.
@@ -269,6 +285,13 @@ def enumerate_subdevices(
     or not it answered, so diagnostics can tell "checked, nothing there"
     apart from "never checked".
 
+    `preferred_hrefs` only changes the order of the flat Property fallback;
+    it never filters the device's resource surface. When `time_budget` is
+    supplied, probes are bounded by one shared monotonic deadline and this
+    returns every candidate/resource confirmed before it. This makes first
+    setup finite even when firmware silently drops unknown paths instead of
+    returning 4.04.
+
     Every candidate whose seed answers with a non-empty batch is returned
     here -- this function can't tell a real sibling from an unused
     SmartThings slot that answers the same shape; that requires
@@ -282,6 +305,30 @@ def enumerate_subdevices(
     # casing, and probing it twice would materialize the same physical
     # subdevice as two Subdevice candidates.
     probed_ids: set[str] = set()
+    deadline = time.monotonic() + max(0.0, time_budget) if time_budget is not None else None
+    budget_exhausted = False
+
+    def _next_timeout(maximum: float) -> float | None:
+        """Clamp one probe to the remaining enumeration wall-clock budget."""
+        nonlocal budget_exhausted
+        if deadline is None:
+            return maximum
+        remaining = deadline - time.monotonic()
+        if remaining <= 0:
+            budget_exhausted = True
+            return None
+        return min(maximum, remaining)
+
+    def _flat_probe_hrefs():
+        """Preferred live-state hrefs first, then every remaining master href."""
+        seen = set()
+        for href in preferred_hrefs:
+            if href in resources and href not in seen:
+                seen.add(href)
+                yield href
+        for href in sorted(resources):
+            if href not in seen:
+                yield href
 
     def _probed(seed_href: str, batch: dict) -> None:
         if probe_log is not None:
@@ -296,7 +343,10 @@ def enumerate_subdevices(
             return
         probed_ids.add(sub_id.lower())
         seed = (sub_id, "device", "0")
-        batch = _get_batch(sess, seed)
+        timeout = _next_timeout(collection_timeout)
+        if timeout is None:
+            return
+        batch = _get_batch(sess, seed, timeout)
         _probed(_seed_href(seed), batch)
         if batch:
             subdevice = Subdevice(kind="prefixed", key=sub_id, seed_path=seed)
@@ -307,10 +357,12 @@ def enumerate_subdevices(
         # doesn't always expose its own `/<uuid>/device/0` Collection. With
         # no Collection to seed from and no per-UUID entry in /oic/res to
         # enumerate hrefs from, the only signal left is that a composite
-        # device's siblings share the master's own resource surface -- so
-        # probe every href the master answered this cycle, individually,
-        # under this UUID's prefix, and keep whichever answer. Each is a
-        # plain tolerated-404 RETRIEVE.
+        # device's siblings are the same physical board family as the
+        # subdevice this config entry already talks to -- so probe every
+        # href the master itself answered this cycle, individually, under
+        # this UUID's prefix, and keep whichever ones answer before the
+        # optional enumeration deadline. Each is a plain tolerated-404
+        # RETRIEVE, same posture as every other probe in this function.
         #
         # Known gap: a firmware that echoes the master's own state back
         # under an unrecognized prefix, rather than 4.04ing, would pass
@@ -321,12 +373,15 @@ def enumerate_subdevices(
         # reps against the master's own values for the same hrefs.
         flat_hrefs = []
         first = True
-        for href in sorted(resources):
+        for href in _flat_probe_hrefs():
             if not first:
                 sess.pace()
             first = False
+            timeout = _next_timeout(property_timeout)
+            if timeout is None:
+                break
             actual = f"/{sub_id}{href}"
-            rep = _get_property(sess, tuple(actual.strip("/").split("/")))
+            rep = _get_property(sess, tuple(actual.strip("/").split("/")), timeout)
             _probed(actual, rep)
             if rep:
                 flat_hrefs.append(href)
@@ -353,14 +408,20 @@ def enumerate_subdevices(
     listed = sorted(i for i in ids if isinstance(i, str) and i)
     for sub_id in listed:
         _probe_prefixed(sub_id)
+        if budget_exhausted:
+            break
 
     # --- Pattern C: UUID prefix advertised only via /oic/res ----------------
     # (AWM-WW-AID-26-ONEBODY washer+dryer combo, issue #241.) No
     # /subdevices/vs/0 and /device/<n> 404s; the only trace of the sibling
     # is a UUID-prefixed link in /oic/res (the x.com.samsung.da.multidevice
     # link). Its own tree answers a full Collection at /<uuid>/device/0,
-    # exactly Pattern B's transform, so every UUID path prefix seen in
-    # /oic/res is treated as a candidate. _probe_prefixed's probed_ids
+    # exactly Pattern B's transform, so a UUID prefix attached to that
+    # resource type is treated as a candidate. Other UUID-prefixed links are
+    # not evidence of a sibling: some single-unit AC boards advertise only
+    # per-prefix file-transfer resources, and probing those prefixes against
+    # every master href needlessly burns the setup timeout budget.
+    # _probe_prefixed's probed_ids
     # guard (not a set difference against `listed`) is what keeps an id
     # already named by subdeviceIdList from being probed twice, since the
     # two sources can disagree on case.
@@ -369,11 +430,13 @@ def enumerate_subdevices(
             m.group(1)
             for link in _iter_oic_res_hrefs(oic_res_links)
             for m in [_UUID_PREFIX_RE.match(link.get("href", ""))]
-            if m
+            if m and "x.com.samsung.da.multidevice" in (link.get("rt") or ())
         }
     )
     for sub_id in linked:
         _probe_prefixed(sub_id)
+        if budget_exhausted:
+            break
 
     # --- Pattern A: indexed siblings (ARTIK051_DONGLE_FAC_18K) --------------
     indices = sorted(
@@ -390,8 +453,11 @@ def enumerate_subdevices(
         # this replaces from identity.py.
         indices = list(_SPECULATIVE_DEVICE_INDICES)
     for n in indices:
+        timeout = _next_timeout(collection_timeout)
+        if timeout is None:
+            break
         seed = ("device", str(n))
-        batch = _get_batch(sess, seed)
+        batch = _get_batch(sess, seed, timeout)
         _probed(_seed_href(seed), batch)
         if not batch:
             continue
@@ -399,18 +465,26 @@ def enumerate_subdevices(
         fetched.update(batch)  # already real /x/<n> hrefs, no normalization needed
         subdevices.append(subdevice)
 
-    # /multidevice/vs/0: listed in /oic/res on some boards but never in
-    # /device/0's batch, so it needs its own RETRIEVE. A plain corroborating
-    # count (numofsubdevice), confirmed read-only -- captured for
-    # diagnostics only, folded into the merged resources dict like any
-    # other href (see airconditioner._AC_IGNORED). Not a gate:
-    # discover_partitioned's entity-level liveness check decides
-    # materialization without it.
+    # /multidevice/vs/0 (issue #177 follow-up): the Pattern A reporter's
+    # board lists it in /oic/res but it never appears in /device/0's batch,
+    # so it needs its own RETRIEVE. It's a plain corroborating count
+    # (x.com.samsung.da.numofsubdevice), confirmed read-only (a write
+    # attempt returned CoAP 4.00) -- captured for diagnostics only, folded
+    # into the merged resources dict like any other href (see
+    # airconditioner._AC_IGNORED, which is what keeps it from surfacing as
+    # an unbound-href gap). NOT a gate: discover_partitioned's entity-level
+    # liveness check decides materialization correctly without it, and only
+    # this one board family is known to expose it at all. Whether it agrees
+    # with the number of subdevices actually materialized is the
+    # coordinator's call to log (it owns the logger; this module doesn't),
+    # not this function's.
     multidevice_seed = ("multidevice", "vs", "0")
-    multidevice = _get_property(sess, multidevice_seed)
-    _probed(_seed_href(multidevice_seed), multidevice)
-    if multidevice:
-        fetched["/multidevice/vs/0"] = multidevice
+    timeout = _next_timeout(property_timeout)
+    if timeout is not None:
+        multidevice = _get_property(sess, multidevice_seed, timeout)
+        _probed(_seed_href(multidevice_seed), multidevice)
+        if multidevice:
+            fetched["/multidevice/vs/0"] = multidevice
 
     return subdevices, fetched
 

custom_components/localthings/rekey.py

@@ -0,0 +1,90 @@
+"""Move an entry's registry entries from one device key to another.
+
+The key (registry.identity.resolve_device_key) is permanent in three
+places, so changing it means rewriting the registries rather than storing
+a new value -- anything left behind is orphaned. Rewriting rather than
+recreating is what keeps an entity's entity_id, and with it its history,
+area and automations.
+
+Its own module because both callers need it: the v1 -> v2 migration in
+__init__.py and the coordinator's first-poll adoption (issue #381).
+"""
+
+from __future__ import annotations
+
+import logging
+
+from homeassistant.config_entries import ConfigEntry
+from homeassistant.core import HomeAssistant, callback
+from homeassistant.helpers import device_registry as dr
+from homeassistant.helpers import entity_registry as er
+
+from .const import DOMAIN
+
+_LOGGER = logging.getLogger(__name__)
+
+
+@callback
+def rekey_entry(hass: HomeAssistant, entry: ConfigEntry, old_key: str, new_key: str) -> None:
+    """Rewrite everything this entry registered under `old_key` to `new_key`.
+
+    All three permanent places move together: entity unique_ids
+    (f"{DOMAIN}_{key}_{state_key}"), device identifiers ((DOMAIN, key), plus
+    (DOMAIN, f"{key}_{subdevice}") per subdevice -- see device_info_for),
+    and the entry's own unique_id. Leaving that last one behind would let
+    the config flow's duplicate check wave through a re-add of this very
+    appliance.
+
+    Idempotent, so it is safe to attempt on every poll rather than tracking
+    whether it has run. Where both keys already exist the `old_key` copy is
+    the dead one, so it is removed rather than rewritten over the live entry.
+
+    Must run on the event loop; the registry helpers require it.
+    """
+    if old_key == new_key:
+        return
+
+    new_entry_unique_id = f"{DOMAIN}_{new_key}"
+    if entry.unique_id != new_entry_unique_id:
+        hass.config_entries.async_update_entry(entry, unique_id=new_entry_unique_id)
+
+    ent_reg = er.async_get(hass)
+    stale_prefix = f"{DOMAIN}_{old_key}_"
+    for entity in list(er.async_entries_for_config_entry(ent_reg, entry.entry_id)):
+        if not entity.unique_id.startswith(stale_prefix):
+            continue
+        new_unique_id = f"{DOMAIN}_{new_key}_{entity.unique_id[len(stale_prefix) :]}"
+        if ent_reg.async_get_entity_id(entity.domain, DOMAIN, new_unique_id):
+            _LOGGER.debug("removing orphaned entity %s", entity.entity_id)
+            ent_reg.async_remove(entity.entity_id)
+        else:
+            _LOGGER.debug("re-keying entity %s to %s", entity.entity_id, new_unique_id)
+            ent_reg.async_update_entity(entity.entity_id, new_unique_id=new_unique_id)
+
+    dev_reg = dr.async_get(hass)
+    for device in list(dr.async_entries_for_config_entry(dev_reg, entry.entry_id)):
+        stale = {
+            ident
+            for ident in device.identifiers
+            if ident[0] == DOMAIN and (ident[1] == old_key or ident[1].startswith(f"{old_key}_"))
+        }
+        if not stale:
+            continue
+        fresh = {(DOMAIN, f"{new_key}{ident[1][len(old_key) :]}") for ident in stale}
+        existing = dev_reg.async_get_device(identifiers=fresh)
+        if existing is not None and existing.id != device.id:
+            # Removing a device takes its entities with it. Anything still
+            # attached here was re-keyed rather than removed above -- the
+            # surviving copy, not a duplicate -- so move it onto the device
+            # it now belongs to before the removal destroys it too.
+            for entity in er.async_entries_for_device(
+                ent_reg, device.id, include_disabled_entities=True
+            ):
+                ent_reg.async_update_entity(entity.entity_id, device_id=existing.id)
+            _LOGGER.debug("removing orphaned device %s", device.id)
+            dev_reg.async_remove_device(device.id)
+        else:
+            _LOGGER.debug("re-keying device %s to %s", device.id, fresh)
+            dev_reg.async_update_device(
+                device.id, new_identifiers=(device.identifiers - stale) | fresh
+            )

custom_components/localthings/select.py

@@ -49,7 +49,7 @@ def _translation_state(value: str, known: frozenset[str]) -> str | None:
     return snake if snake in known else None
 
 
-def _display(value, translation_key: str | None):
+def _display(value, translation_key: str | None, fallback_fn=None):
     """Turn a raw device option/state value into what's shown in the UI.
 
     `translation_key` is the entity's already-resolved key (it can itself
@@ -67,14 +67,21 @@ def _display(value, translation_key: str | None):
     """
     if not isinstance(value, str):
         return value
-    if translation_key:
-        known = translated_states("select", translation_key)
-        if not known:
-            # No state table for this key: either untranslated, or its
-            # options deliberately aren't (an unrecognized course table).
-            return value
-        if translated := _translation_state(value, known):
-            return translated
+    known = translated_states("select", translation_key) if translation_key else frozenset()
+    if translated := _translation_state(value, known):
+        return translated
+    if fallback_fn is not None and (fallback := fallback_fn(value)) is not None:
+        return fallback
+    if translation_key and not known:
+        # No state table for this key: either the entity isn't translated at
+        # all, or its name is translated but its options deliberately aren't
+        # (an unrecognized course table, say). Nothing named this value, so
+        # the raw device value is the best choice -- the cosmetic reshaping
+        # below would only mangle an opaque code, turning a course '0E' into
+        # '0 E'. Reached only when the fallback *declined* the value, not
+        # merely when none was supplied: cycle_select always supplies one now
+        # (it labels cloud programs) and returns None for everything else.
+        return value
     if value.islower():
         return value.replace("_", " ").title()
     return _CAMEL_BOUNDARY_RE.sub(" ", value)
@@ -85,7 +92,15 @@ class LocalThingsSelect(LocalThingsEntity, SelectEntity):
         super().__init__(coordinator, bound)
         desc = cast(SelectDesc, bound.desc)
         if not desc.options_field and not callable(desc.options):
-            self._attr_options = [_display(o, self.translation_key) for o in desc.options]
+            self._attr_options = [self._display_option(o) for o in desc.options]
+
+    def _display_option(self, value):
+        """Normalize both current state and options through one path."""
+        display_fn = cast(SelectDesc, self._bound.desc).display_fn
+        fallback_fn = (
+            (lambda raw: display_fn(raw, self._resources)) if display_fn is not None else None
+        )
+        return _display(value, self.translation_key, fallback_fn)
 
     def _raw_options(self) -> list[str]:
         desc = cast(SelectDesc, self._bound.desc)
@@ -106,17 +121,17 @@ class LocalThingsSelect(LocalThingsEntity, SelectEntity):
     def options(self) -> list[str]:
         desc = cast(SelectDesc, self._bound.desc)
         if desc.options_field or callable(desc.options):
-            return [_display(o, self.translation_key) for o in self._raw_options()]
+            return [self._display_option(o) for o in self._raw_options()]
         return self._attr_options
 
     @property
     def current_option(self):
         raw = (self.coordinator.data or {}).get(self._state_key)
-        return _display(raw, self.translation_key)
+        return self._display_option(raw)
 
     async def async_select_option(self, option: str) -> None:
         raw = next(
-            (o for o in self._raw_options() if _display(o, self.translation_key) == option),
+            (o for o in self._raw_options() if self._display_option(o) == option),
             option,
         )
         await self.coordinator.async_send_command(self._bound, raw)

custom_components/localthings/sensor.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import time
 from datetime import timedelta
 from typing import cast
 
@@ -48,9 +49,12 @@ class LocalThingsSensor(LocalThingsEntity, SensorEntity):
             SensorDeviceClass(desc.device_class) if desc.device_class else None
         )
         self._attr_state_class = SensorStateClass(desc.state_class) if desc.state_class else None
-        if desc.options:
-            self._attr_options = list(desc.options)
+        # Always set, so the `options` property below can read it unguarded.
+        self._attr_options = list(desc.options) if desc.options else None
         self._hysteresis_value = None
+        self._sticky_value = None
+        self._sticky_until: float | None = None
+        self._sticky_spent = False
 
     @property
     def native_unit_of_measurement(self):
@@ -59,14 +63,86 @@ class LocalThingsSensor(LocalThingsEntity, SensorEntity):
             return desc.unit_fn(self.coordinator.resource(self._bound.href))
         return self._attr_native_unit_of_measurement
 
+    @property
+    def options(self):
+        """Declared options, plus whatever this device is actually reporting.
+
+        HA raises for an enum state outside `options`, which would turn any
+        device value we don't have a translation for into a broken entity --
+        the opposite of this registry's rule that an unrecognized value
+        renders raw. Admitting the live value keeps it displayable; it just
+        shows untranslated (PR #341 review).
+        """
+        if self._attr_options is None:
+            return None
+        value = self.native_value
+        if not isinstance(value, str) or value in self._attr_options:
+            return self._attr_options
+        return [*self._attr_options, value]
+
     @property
     def native_value(self):
         raw = (self.coordinator.data or {}).get(self._state_key)
         desc = cast(SensorDesc, self._bound.desc)
+        if desc.sticky_fn is not None:
+            raw = self._apply_sticky(raw, desc)
         if not desc.hysteresis:
             return raw
         return self._apply_hysteresis(raw)
 
+    def _apply_sticky(self, raw, desc: SensorDesc):
+        """Freeze this entity at a value for up to `desc.sticky_seconds`
+        after `desc.sticky_fn` next stops matching this href's live rep
+        (issue #345 -- see operational.py's `_just_finished` for the
+        motivating case). Entity-instance state only, exactly like
+        `_hysteresis_value` above -- never written back to the coordinator
+        cache, so write_fn, diagnostics, and the observe-mode sweep
+        comparison keep seeing real device data throughout.
+
+        `sticky_fn`/`sticky_bypass_fn` read this href's live rep rather
+        than the already-computed `raw`, so they can key on fields rep_fn
+        has collapsed away -- but they never compute a value. `raw` and
+        the frozen `sticky_value` are the only things returned here, so a
+        held entity and a free-running one agree on what "live" means; a
+        hook that broke that rule caused issue #358.
+
+        At most one window per `sticky_bypass_fn` cycle: arming marks the
+        hold spent, and only the bypass clears that. So a `sticky_fn` that
+        keeps matching (firmware leaving the field stuck -- the quirk
+        `_completion_minutes` works around) can't extend the window, and
+        one flapping in and out can't restart it either, before or after
+        expiry. Expiry alone doesn't re-open the door: without something
+        the calibre of "a new cycle is actually running" in between, a
+        second Finish is the same Finish, and re-arming on it would strobe
+        the entity between held and live once per window -- exactly the
+        repeated announcements #345 and #358 are about.
+
+        `sticky_bypass_fn` drops the hold and returns `raw`, for when "not
+        sticky right now" is ambiguous between "went idle, honor the hold"
+        and "genuinely moved on to new data". It is both the early release
+        and the only re-arm, so it should demand positive evidence of that
+        move; when unsure, letting the window run out is the cheaper
+        mistake.
+        """
+        assert desc.sticky_fn is not None  # native_value only calls this when set
+        rep = self.coordinator.resource(self._bound.href)
+        now = time.monotonic()
+
+        if desc.sticky_fn(rep):
+            if not self._sticky_spent:
+                self._sticky_value = (
+                    desc.sticky_value_fn(rep) if desc.sticky_value_fn is not None else raw
+                )
+                self._sticky_until = now + desc.sticky_seconds
+                self._sticky_spent = True
+        elif desc.sticky_bypass_fn is not None and desc.sticky_bypass_fn(rep):
+            self._sticky_until = None
+            self._sticky_spent = False
+            return raw
+
+        holding = self._sticky_until is not None and now < self._sticky_until
+        return self._sticky_value if holding else raw
+
     def _apply_hysteresis(self, raw):
         """Hold the last value this entity actually reported until a new one
         differs by at least the configured threshold, regardless of how long
@@ -111,7 +187,7 @@ class LocalThingsConnectionModeSensor(CoordinatorEntity[LocalThingsCoordinator],
 
     def __init__(self, coordinator: LocalThingsCoordinator) -> None:
         super().__init__(coordinator)
-        self._attr_unique_id = f"{DOMAIN}_{coordinator.device_serial}_connection_mode"
+        self._attr_unique_id = f"{DOMAIN}_{coordinator.device_key}_connection_mode"
 
     @property
     def device_info(self) -> DeviceInfo:

custom_components/localthings/services.py

@@ -0,0 +1,229 @@
+"""Home Assistant services for direct OCF resource read/write access
+(issue #300): a raw-transport escape hatch for reverse-engineering a
+device's write contract -- an ordered multi-write sequence with settle
+delays and a delayed re-read, which the single-write options-flow debug
+panel can't express. Both sit on the same coordinator primitives the panel
+now calls too (config_flow.py), so there is exactly one code path that
+performs a raw write.
+
+Kept thin on purpose: session/lock ownership lives on the coordinator
+(coordinator.py). This module only resolves the service call's device
+target to a `(coordinator, subdevice)` pair, translates canonical hrefs
+through that subdevice, and shapes the response.
+"""
+
+from __future__ import annotations
+
+from typing import Any, cast
+
+import voluptuous as vol
+from homeassistant.core import HomeAssistant, ServiceCall, ServiceResponse, SupportsResponse
+from homeassistant.exceptions import ServiceValidationError
+from homeassistant.helpers import config_validation as cv
+from homeassistant.helpers import device_registry as dr
+
+from .const import DOMAIN, SERVICE_READ_RESOURCE, SERVICE_WRITE_RESOURCE
+from .coordinator import LocalThingsCoordinator, normalize_href
+from .registry.subdevices import MAIN, Subdevice
+
+ATTR_HREF = "href"
+ATTR_PAYLOAD = "payload"
+ATTR_SETTLE = "settle"
+ATTR_WRITES = "writes"
+ATTR_VERIFY_AFTER = "verify_after"
+ATTR_HOLD_SESSION_LOCK = "hold_session_lock"
+ATTR_DEVICE_ID = "device_id"
+
+_WRITE_ITEM_SCHEMA = vol.Schema(
+    {
+        vol.Required(ATTR_HREF): str,
+        # Not `dict` here: a non-dict payload must fail the same way an
+        # empty one does -- coordinator.async_raw_write_sequence's
+        # ServiceValidationError -- not a raw schema vol.Invalid, so every
+        # caller sees one consistent error shape regardless of which rule
+        # a bad payload tripped.
+        vol.Required(ATTR_PAYLOAD): object,
+        vol.Optional(ATTR_SETTLE): vol.Coerce(float),
+    }
+)
+
+# Structural validation only (types, and unwrapping a bare dict into a
+# one-item list) -- the semantic checks (non-empty payload, non-root href,
+# the 1..10/settle/verify_after ranges) live on
+# LocalThingsCoordinator.async_raw_write_sequence, so every caller gets the
+# same ServiceValidationError + translation key regardless of whether it
+# reached the primitive through this service, the options-flow panel, or a
+# future caller.
+_WRITE_RESOURCE_SCHEMA = vol.Schema(
+    {
+        **cv.TARGET_SERVICE_FIELDS,
+        vol.Required(ATTR_WRITES): vol.All(cv.ensure_list, [_WRITE_ITEM_SCHEMA]),
+        vol.Optional(ATTR_VERIFY_AFTER): vol.Coerce(float),
+        vol.Optional(ATTR_HOLD_SESSION_LOCK): cv.boolean,
+    }
+)
+
+_READ_RESOURCE_SCHEMA = vol.Schema(
+    {
+        **cv.TARGET_SERVICE_FIELDS,
+        vol.Optional(ATTR_HREF): str,
+    }
+)
+
+
+def _resolve_target(
+    hass: HomeAssistant, call: ServiceCall
+) -> tuple[LocalThingsCoordinator, Subdevice, str]:
+    """The one `(coordinator, subdevice, device_id)` a service call's
+    device target names.
+
+    Deliberately strict about count, not just presence: the `target:
+    device:` selector in services.yaml still lets a user pick an area or
+    label in the picker, and the frontend expands that into a `device_id`
+    list before the call reaches here -- more than one entry means an
+    area/label fanned this out across several appliances, which a raw
+    debug write must never do silently (issue #300).
+    """
+    device_ids = cv.ensure_list(call.data.get(ATTR_DEVICE_ID) or [])
+    if len(device_ids) != 1:
+        raise ServiceValidationError(
+            translation_domain=DOMAIN,
+            translation_key="service_device_target_invalid",
+        )
+    device_id = device_ids[0]
+
+    dev_reg = dr.async_get(hass)
+    device = dev_reg.async_get(device_id)
+    if device is None:
+        raise ServiceValidationError(
+            translation_domain=DOMAIN,
+            translation_key="service_device_not_found",
+        )
+
+    for coordinator in hass.data.get(DOMAIN, {}).values():
+        if device.identifiers & coordinator.device_info.get("identifiers", set()):
+            return coordinator, MAIN, device_id
+        for sub in coordinator.subdevices:
+            if device.identifiers & coordinator.device_info_for(sub).get("identifiers", set()):
+                return coordinator, sub, device_id
+
+    raise ServiceValidationError(
+        translation_domain=DOMAIN,
+        translation_key="service_device_not_loaded",
+    )
+
+
+async def _async_write_resource(hass: HomeAssistant, call: ServiceCall) -> ServiceResponse:
+    coordinator, subdevice, device_id = _resolve_target(hass, call)
+    writes_in: list[dict[str, Any]] = call.data[ATTR_WRITES]
+
+    # Canonical -> actual translation happens here, not in the coordinator
+    # (issue #177), whose raw-write primitive has no notion of subdevices --
+    # identity transform for MAIN. Normalized first, or a trailing slash
+    # slips past to_actual onto the master (see coordinator.normalize_href).
+    canonicals = [normalize_href(w[ATTR_HREF]) for w in writes_in]
+    raw_writes = [
+        {
+            "href": subdevice.to_actual(canonical),
+            "payload": w.get(ATTR_PAYLOAD),
+            "settle": w.get(ATTR_SETTLE, 0.0),
+        }
+        for canonical, w in zip(canonicals, writes_in, strict=True)
+    ]
+    sequence = await coordinator.async_raw_write_sequence(
+        raw_writes,
+        verify_after=call.data.get(ATTR_VERIFY_AFTER, 0.0),
+        hold_session_lock=call.data.get(ATTR_HOLD_SESSION_LOCK, True),
+    )
+
+    results = [
+        {
+            "href": canonical,
+            "actual_href": result["href"],
+            "code": result["code"],
+            "raw_code": result["raw_code"],
+            "accepted": result["accepted"],
+            "before": result["before"],
+            "after": result["after"],
+            "changed": result["changed"],
+        }
+        for canonical, result in zip(canonicals, sequence["results"], strict=True)
+    ]
+    response: dict[str, Any] = {"device_id": device_id, "results": results}
+    if "verified" in sequence:
+        # Keyed off the same normalized canonicals the sequence was built
+        # from, so the lookup can't miss and return an actual href where the
+        # contract promises a canonical one.
+        canonical_by_actual = {subdevice.to_actual(c): c for c in canonicals}
+        response["verified"] = {
+            canonical_by_actual.get(actual_href, actual_href): verified
+            for actual_href, verified in sequence["verified"].items()
+        }
+    return response
+
+
+async def _async_read_resource(hass: HomeAssistant, call: ServiceCall) -> ServiceResponse:
+    coordinator, subdevice, _device_id = _resolve_target(hass, call)
+    href = call.data.get(ATTR_HREF)
+    if not href:
+        # No href -> the cached snapshot, not a live sweep of every known
+        # href: lets a user enumerate what exists without hammering the
+        # device (see this module's docstring and the coordinator's
+        # canonical_resources).
+        # device_resources, not canonical_resources: this response is what
+        # the appliance reported, without the fields this integration merges
+        # on for its own use (see coordinator.entity_resources).
+        snapshot: dict[str, Any] = {"resources": coordinator.device_resources(subdevice)}
+        return cast(ServiceResponse, snapshot)
+
+    # Same normalize-before-translate order as the write path above.
+    canonical = normalize_href(href)
+    actual_href = subdevice.to_actual(canonical)
+    code, rep, body = await coordinator.async_raw_read(actual_href)
+    read_result: dict[str, Any] = {
+        "href": canonical,
+        "actual_href": actual_href,
+        "code": f"{code >> 5}.{code & 0x1F:02d}",
+        "raw_code": code,
+        "rep": rep,
+    }
+    # `body` only when it isn't the Property map already in `rep` -- a
+    # Collection (`/device/0`, `/sec/devices`) answers a CBOR list, which
+    # `rep` can't carry and which used to vanish into an empty-looking
+    # 2.05 (issue #335). Omitted for the ordinary map case rather than
+    # duplicating every rep in every response.
+    if body is not None and not isinstance(body, dict):
+        read_result["body"] = body
+    return cast(ServiceResponse, read_result)
+
+
+def async_setup_services(hass: HomeAssistant) -> None:
+    """Register the write_resource/read_resource services (issue #300).
+
+    Called once from `async_setup`, not per config entry: services are
+    process-global, and `hass.services.async_register` on an
+    already-registered name just replaces the handler, so re-registering
+    on every entry setup would silently rebind to whichever entry loaded
+    last. `async_unload_entry` must never call the inverse of this.
+    """
+
+    async def _handle_write(call: ServiceCall) -> ServiceResponse:
+        return await _async_write_resource(hass, call)
+
+    async def _handle_read(call: ServiceCall) -> ServiceResponse:
+        return await _async_read_resource(hass, call)
+
+    hass.services.async_register(
+        DOMAIN,
+        SERVICE_WRITE_RESOURCE,
+        _handle_write,
+        schema=_WRITE_RESOURCE_SCHEMA,
+        supports_response=SupportsResponse.OPTIONAL,
+    )
+    hass.services.async_register(
+        DOMAIN,
+        SERVICE_READ_RESOURCE,
+        _handle_read,
+        schema=_READ_RESOURCE_SCHEMA,
+        supports_response=SupportsResponse.ONLY,
+    )

custom_components/localthings/services.yaml

@@ -0,0 +1,88 @@
+write_resource:
+  name: Write resource
+  description: >-
+    Send one or more raw partial-rep writes straight to a device's OCF
+    resources, in order, with an optional settle delay between steps and a
+    delayed re-read at the end -- for reverse-engineering a device's write
+    contract (issue #300), not day-to-day control. This bypasses the
+    remote-control-off block and every write_fn/validate_fn a normal entity
+    write goes through, and sends exactly the fields you give it verbatim:
+    it can misconfigure your appliance. Prefer a real entity, or the Debug
+    write panel in the integration's Configure menu, for anything this
+    integration already models.
+  fields:
+    device_id:
+      name: Device
+      description: The appliance to write to, or one of its subdevices.
+      required: true
+      selector:
+        device:
+          integration: localthings
+    writes:
+      name: Writes
+      description: >-
+        1-10 writes to perform in order. Each item needs href (the
+        canonical resource, e.g. /mode/vs/0) and payload (a non-empty
+        object sent verbatim as a partial-rep POST); settle is how many
+        seconds to wait after that write before starting the next one
+        (0-30, default 0).
+      required: true
+      example: >-
+        [{"href": "/mode/vs/0", "payload": {"x.com.samsung.da.modes":
+        ["Bake"]}, "settle": 3}]
+      selector:
+        object:
+    hold_session_lock:
+      name: Hold the session for the whole sequence
+      description: >-
+        Keep the device session for the entire sequence, settle delays
+        included, so nothing else -- a routine poll, another entity's write
+        -- can land between two steps and blur which write the appliance
+        was reacting to. On by default. Turning it off takes the session
+        per write and frees it across the waits, which lets entities keep
+        updating during a long sequence at the cost of that certainty.
+      required: false
+      default: true
+      selector:
+        boolean:
+    verify_after:
+      name: Verify after
+      description: >-
+        Seconds to wait after the whole sequence finishes before
+        re-reading every href touched, to see whether the values held or
+        were reverted by the board. 0 (default) skips verification.
+      required: false
+      default: 0
+      selector:
+        number:
+          min: 0
+          max: 60
+          step: 0.5
+          unit_of_measurement: seconds
+          mode: box
+
+read_resource:
+  name: Read resource
+  description: >-
+    Read a device's OCF resources directly, bypassing this integration's
+    entity model. Give an href for a live GET straight from the device --
+    deliberately not the cache, which can be up to a poll interval stale --
+    or omit it to get the cached snapshot of every resource this
+    integration currently tracks on that device.
+  fields:
+    device_id:
+      name: Device
+      description: The appliance to read from, or one of its subdevices.
+      required: true
+      selector:
+        device:
+          integration: localthings
+    href:
+      name: Resource href
+      description: >-
+        Canonical resource href to read (e.g. /mode/vs/0). Omit to get the
+        cached snapshot of every tracked resource instead of a live GET.
+      required: false
+      example: /mode/vs/0
+      selector:
+        text:

custom_components/localthings/translations/cs.json

@@ -108,6 +108,15 @@
       },
       "softener_low": {
         "name": "Málo aviváže"
+      },
+      "add_wash_available": {
+        "name": "AddWash povoleno"
+      },
+      "add_wash_indicator": {
+        "name": "AddWash připraveno"
+      },
+      "stick_ble_connected": {
+        "name": "Tyč připojena přes BLE"
       }
     },
     "button": {
@@ -152,11 +161,13 @@
               "smart": "Chytrý",
               "speed": "Rychlý",
               "nano": "WindFree",
+              "sleep": "Spánek",
               "nanosleep": "WindFree spánek",
               "longwind": "Dlouhý vánek",
               "motionindirect": "Nepřímý vzduch při pohybu",
               "motiondirect": "Přímý vzduch při pohybu",
               "drycomfort": "Komfortní sušení",
+              "dlightcool": "d'light Cool",
               "2step": "2stupňový"
             }
           }
@@ -223,6 +234,9 @@
       "air_filter_threshold": {
         "name": "Práh upozornění na filtr"
       },
+      "auto_door_timer": {
+        "name": "Časovač automatického otevírání dvířek"
+      },
       "beverage_zone_mode": {
         "name": "Režim zóny nápojů",
         "state": {
@@ -253,7 +267,11 @@
         "name": "Zvuk bzučáku",
         "state": {
           "off": "Vypnuto",
-          "on": "Zapnuto"
+          "on": "Zapnuto",
+          "volume_off": "Vypnuto",
+          "volume_low": "Nízká",
+          "volume_med": "Střední",
+          "volume_high": "Vysoká"
         }
       },
       "discharging_time": {
@@ -295,7 +313,16 @@
           "07": "Předoplach",
           "8d": "Hrnce a pánve",
           "8e": "Plast",
-          "8f": "Dětské potřeby"
+          "8f": "Dětské potřeby",
+          "82": "Automatický",
+          "8a": "Normální",
+          "a7": "Intenzivní",
+          "a8": "Expresní",
+          "8c": "Extra tichý",
+          "88": "Samočištění",
+          "85": "Jemné",
+          "0c": "Express",
+          "0d": "Samočištění"
         }
       },
       "dispense_type": {
@@ -310,6 +337,35 @@
           "4": "Alarm 4"
         }
       },
+      "dryer_cycle_table_00": {
+        "name": "Cyklus",
+        "state": {
+          "01": "Normální",
+          "9c": "Intenzivní",
+          "a5": "Ložní prádlo",
+          "9e": "Nežehlivé prádlo",
+          "9b": "Parní dezinfekce+",
+          "27": "Osvěžení",
+          "a0": "Provětrání",
+          "a4": "Časové sušení",
+          "a6": "Rychlé sušení",
+          "a3": "Sportovní oblečení",
+          "a2": "Jemné prádlo",
+          "9a": "Bavlna",
+          "ca": "Provětrání",
+          "db": "Super Speed",
+          "99": "Smíšená náplň",
+          "93": "Žehlení",
+          "b5": "Vlna",
+          "d7": "Outdoor péče",
+          "96": "Studený vzduch",
+          "97": "Teplý vzduch",
+          "7f": "Časové sušení",
+          "98": "Rychlé sušení 35",
+          "eb": "Jemné prádlo",
+          "b6": "Syntetika"
+        }
+      },
       "dryer_cycle_table_03": {
         "name": "Cyklus",
         "state": {
@@ -337,7 +393,27 @@
           "4c": "Osvěžení vzduchem",
           "51": "Eko bavlna",
           "53": "AI sušení+",
-          "4e": "Automatické sušení"
+          "4e": "Automatické sušení",
+          "26": "Provětrání",
+          "2a": "Hygienické sušení+",
+          "02": "AI sušení",
+          "03": "Super Speed",
+          "05": "Ložní prádlo",
+          "07": "Jemné prádlo",
+          "09": "Košile",
+          "0b": "Péče o prošívané bundy",
+          "0c": "Outdoor impregnace",
+          "0e": "Ručníky",
+          "0f": "Vlna",
+          "11": "Studený vzduch",
+          "28": "Vnitřní dezinfekce horkým vzduchem",
+          "37": "Halenky",
+          "38": "Žehlení",
+          "39": "Odvlhčování místnosti",
+          "3a": "Hygienické sušení",
+          "3b": "Ložní prádlo/Odstranění prachu",
+          "3c": "Sportovní oblečení",
+          "3d": "Džíny"
         }
       },
       "favorite_capacity": {
@@ -459,9 +535,11 @@
           "kimchi_storage_crunfch": "Křupavé kimči",
           "kimchi_storage_buy": "Kupované kimči",
           "storage_fridge_normal": "Chlazení",
+          "storage_fridge": "Chlazení",
           "storage_fridge_cold": "Chlazení, silné",
           "storage_fridge_warm": "Chlazení, slabé",
           "storage_freezer_normal": "Mražení",
+          "storage_freezer": "Mražení",
           "storage_freezer_cold": "Mražení, silné",
           "storage_freezer_warm": "Mražení, slabé",
           "kimchi_ripe_low_temp": "Zrání kimči, nízká teplota",
@@ -474,7 +552,8 @@
           "storage_fresh_cereal": "Obiloviny",
           "storage_fridge_drink": "Nápoje",
           "storage_fresh_wine": "Víno",
-          "storage_fresh_potato_banana": "Brambory a banány"
+          "storage_fresh_potato_banana": "Brambory a banány",
+          "newmode_kimchi_0000": "Nový režim"
         }
       },
       "pantry_zone_mode": {
@@ -485,6 +564,16 @@
           "fdr_drinks": "Nápoje"
         }
       },
+      "winecellar_pantry_zone_mode": {
+        "name": "Režim spíže",
+        "state": {
+          "processed_meat": "Zpracované maso",
+          "cheese": "Sýr",
+          "nuts": "Ořechy",
+          "fruit": "Ovoce",
+          "wine": "Víno"
+        }
+      },
       "range_burner_power_level": {
         "name": "Výkon hořáku {number}",
         "state": {
@@ -536,6 +625,9 @@
           "mute": "Ztlumeno"
         }
       },
+      "energy_saving_mode": {
+        "name": "Režim úspory energie"
+      },
       "air_purifier_sound_mode": {
         "name": "Zvukový režim",
         "state": {
@@ -572,12 +664,51 @@
           "extra_hot": "Extra horká"
         }
       },
+      "washer_cycle_table_00": {
+        "name": "Cyklus",
+        "state": {
+          "01": "Normální",
+          "70": "Intenzivní",
+          "55": "Bílé prádlo",
+          "71": "Ložní prádlo",
+          "72": "Dezinfekce",
+          "77": "Nežehlivé prádlo",
+          "57": "Samočištění+",
+          "73": "Máchání + odstřeďování",
+          "74": "Sportovní oblečení",
+          "75": "Jemné prádlo",
+          "78": "Rychlé praní"
+        }
+      },
       "washer_cycle_table_02": {
         "name": "Cyklus",
         "state": {
           "01": "Normální",
+          "02": "Extra intenzivní",
+          "03": "Super Eco",
           "04": "Rychlé praní",
+          "05": "Vlna/Spodní prádlo",
+          "06": "Ložní prádlo",
+          "07": "Outdoor",
+          "08": "Máchání+odstřeďování",
+          "09": "Čištění bubnu",
+          "0a": "Ručníky",
+          "0b": "Praní varem",
+          "0c": "Dětské potřeby",
+          "0d": "Pouze odstřeďování",
+          "0e": "Zataženo",
+          "0f": "Čisté praní",
+          "10": "Sušicí odstřeďování",
+          "11": "Letní ložní prádlo",
+          "12": "Bavlna",
+          "13": "Černá bavlna",
+          "14": "Jemné spodní prádlo",
+          "15": "Sportovní oblečení",
+          "16": "Halenky",
           "17": "Stažený program",
+          "18": "Soft Bubble",
+          "19": "AI praní",
+          "1a": "Košile",
           "1b": "Bavlna",
           "1c": "Eco 40-60",
           "1d": "Super rychlé",
@@ -587,7 +718,7 @@
           "21": "Barevné prádlo",
           "22": "Vlna",
           "23": "Outdoor",
-          "24": "Ručníky",
+          "24": "Ložní prádlo",
           "25": "Syntetika",
           "26": "Jemné prádlo",
           "27": "Máchání+odstřeďování",
@@ -600,8 +731,9 @@
           "2f": "Sportovní oblečení",
           "30": "Zataženo",
           "32": "Košile",
-          "33": "Ložní prádlo",
+          "33": "Ručníky",
           "34": "Smíšené",
+          "35": "Eko bavlna",
           "36": "Praní+sušení",
           "37": "Sušení vzduchem",
           "38": "Sušení bavlny",
@@ -616,14 +748,34 @@
           "60": "Samočištění+",
           "65": "Barevné prádlo",
           "66": "Džíny",
+          "69": "AI praní",
+          "6a": "Vlna",
+          "6b": "Džíny",
+          "6c": "Halenky",
+          "6d": "Jemné prádlo",
+          "6e": "Sportovní oblečení",
+          "6f": "Ložní prádlo",
+          "70": "Ručníky",
+          "71": "Rychlé praní",
+          "72": "Košile",
+          "73": "Dezinfekce",
+          "74": "Čištění bubnu",
+          "75": "Outdoor",
+          "76": "Dětské potřeby",
+          "77": "Bavlna",
+          "78": "Máchání + odstřeďování",
+          "79": "Pouze odstřeďování",
           "7c": "Bílé prádlo",
           "7d": "Ložní prádlo/nepromokavé",
           "7e": "Samočištění",
           "7f": "Vlna/jemné",
           "86": "Hloubkové praní",
           "87": "Stažený program",
+          "88": "Péče o domácí mazlíčky",
           "8f": "Intenzivní studená",
-          "96": "Méně mikrovláken"
+          "96": "Méně mikrovláken",
+          "a0": "15min rychlé praní",
+          "b0": "Smíšená náplň"
         }
       },
       "washer_dry_level": {
@@ -663,6 +815,38 @@
       },
       "freezer_temperature_setpoint": {
         "name": "Teplota mrazicí zóny"
+      },
+      "edge_lighting_mode": {
+        "name": "Režim okrajového osvětlení",
+        "state": {
+          "smart": "Chytrý",
+          "high": "Vysoký",
+          "low": "Nízký"
+        }
+      },
+      "edge_lighting_color": {
+        "name": "Barva okrajového osvětlení",
+        "state": {
+          "3000k": "3000 K",
+          "4000k": "4000 K",
+          "6500k": "6500 K"
+        }
+      },
+      "indicator_light_mode": {
+        "name": "Režim kontrolky",
+        "state": {
+          "smart": "Chytrý",
+          "high": "Vysoký",
+          "low": "Nízký"
+        }
+      },
+      "ventilation_mode": {
+        "name": "Režim",
+        "state": {
+          "purification": "Čištění",
+          "ventilation": "Větrání",
+          "smartventilation": "Chytré větrání"
+        }
       }
     },
     "sensor": {
@@ -678,6 +862,9 @@
       "air_filter_usage_hours": {
         "name": "Hodiny využití filtru"
       },
+      "deodor_filter_usage": {
+        "name": "Využití filtru"
+      },
       "air_quality_standard": {
         "name": "Norma kvality vzduchu"
       },
@@ -751,6 +938,12 @@
       "stick_status": {
         "name": "Stav tyče"
       },
+      "stick_operation_mode": {
+        "name": "Provozní režim tyče"
+      },
+      "stick_cleaning_status": {
+        "name": "Stav čištění tyče"
+      },
       "uvc_operation_time": {
         "name": "Doba provozu UV-C"
       },
@@ -785,6 +978,12 @@
           "indirect": "Nepřímý"
         }
       },
+      "energy_saving_state": {
+        "name": "Stav úspory energie"
+      },
+      "energy_saving_operating_status": {
+        "name": "Provozní stav úspory energie"
+      },
       "current_temp_c": {
         "name": "Teplota"
       },
@@ -792,10 +991,16 @@
         "name": "Teplota"
       },
       "diagnosis": {
-        "name": "Diagnostika"
+        "name": "Diagnostika",
+        "state": {
+          "ready": "Připraveno"
+        }
       },
       "diagnosis_status": {
-        "name": "Stav diagnostiky"
+        "name": "Stav diagnostiky",
+        "state": {
+          "ready": "Připraveno"
+        }
       },
       "drum_clean_cycles_remaining": {
         "name": "Čištění bubnu za"
@@ -810,7 +1015,10 @@
         "name": "Doba sušení"
       },
       "dryer_type": {
-        "name": "Typ sušičky"
+        "name": "Typ sušičky",
+        "state": {
+          "electricity": "Elektřina"
+        }
       },
       "dust": {
         "name": "Prach"
@@ -939,7 +1147,23 @@
         "name": "Teplota sondy"
       },
       "progress": {
-        "name": "Průběh"
+        "name": "Průběh",
+        "state": {
+          "idle": "Nečinný",
+          "weightsensing": "Detekce náplně",
+          "wash": "Praní",
+          "rinse": "Máchání",
+          "spin": "Odstřeďování",
+          "finish": "Dokončeno",
+          "steaming": "Napařování",
+          "airwashing": "Osvěžení vzduchem",
+          "drying": "Sušení",
+          "dryingwithdooropen": "Větrání",
+          "cooling": "Chlazení",
+          "predrain": "Vypouštění",
+          "prewash": "Předpírka",
+          "sanitizing": "Dezinfekce"
+        }
       },
       "progress_percentage": {
         "name": "Průběh v procentech"
@@ -1038,6 +1262,9 @@
       "absence_power_saving_active": {
         "name": "Úspora energie při nepřítomnosti aktivní"
       },
+      "absence_clean": {
+        "name": "Čištění při nepřítomnosti"
+      },
       "motion_detect_wind_active": {
         "name": "Vyhýbání se proudu vzduchu při pohybu aktivní"
       },
@@ -1071,6 +1298,12 @@
       "auto_door_opener": {
         "name": "Automatické otevírání dvířek"
       },
+      "auto_door_sound_control": {
+        "name": "Zvuk automatického otevírání dvířek"
+      },
+      "auto_door_voice_control": {
+        "name": "Hlasové ovládání automatického otevírání dvířek"
+      },
       "auto_release_dry": {
         "name": "Automatické uvolnění při sušení"
       },
@@ -1137,6 +1370,18 @@
       "intensive": {
         "name": "Intenzivní"
       },
+      "add_wash_alarm": {
+        "name": "Alarm AddWash"
+      },
+      "add_wash_alarm_rinse": {
+        "name": "AddWash při máchání"
+      },
+      "add_wash_alarm_final_rinse": {
+        "name": "AddWash při posledním máchání"
+      },
+      "add_wash_alarm_spin": {
+        "name": "AddWash při odstřeďování"
+      },
       "lamp": {
         "name": "Lampa"
       },
@@ -1202,6 +1447,18 @@
       },
       "ventilation_alarm": {
         "name": "Alarm větrání"
+      },
+      "edge_lighting": {
+        "name": "Okrajové osvětlení"
+      },
+      "indicator_light": {
+        "name": "Kontrolka"
+      },
+      "windfree": {
+        "name": "Režim Wind-Free"
+      },
+      "windsleep": {
+        "name": "Noční režim"
       }
     },
     "time": {
@@ -1290,17 +1547,25 @@
         "title": "Možnosti LocalThings",
         "menu_options": {
           "settings": "Nastavení zápisu pro dálkové ovládání",
+          "cloud_courses": "Stažené cykly",
+          "forget_learned_modes": "Zapomenout zapamatované režimy",
           "debug_write": "Ladění: zápis do prostředku"
         }
       },
       "settings": {
         "title": "Nastavení zápisu pro dálkové ovládání",
-        "description": "Některá zařízení přijímají určité zápisy (např. výchozí dávkování pracího prostředku/aviváže v pračce) i když hlásí vypnuté dálkové ovládání. LocalThings ve výchozím nastavení blokuje každý zápis srozumitelnou chybou, kdykoli zařízení hlásí vypnuté dálkové ovládání, místo aby jej zařízení tiše odmítlo. Povolte toto pouze tehdy, pokud jste ověřili, že zápisy na tomto zařízení skutečně fungují i s vypnutým dálkovým ovládáním – jinak tuto srozumitelnou chybu vyměníte za tiché selhání.",
+        "description": "Některá zařízení přijímají určité zápisy (např. výchozí dávkování pracího prostředku/aviváže v pračce) i když hlásí vypnuté dálkové ovládání. LocalThings ve výchozím nastavení blokuje každý zápis srozumitelnou chybou, kdykoli zařízení hlásí vypnuté dálkové ovládání, místo aby jej zařízení tiše odmítlo. Povolte toto pouze tehdy, pokud jste ověřili, že zápisy na tomto zařízení skutečně fungují i s vypnutým dálkovým ovládáním – jinak tuto srozumitelnou chybu vyměníte za tiché selhání.\n\nNěkterá zařízení hlásí režim, který nikdy neuvedou mezi podporovanými – například klimatizace běžící v režimu Quiet, která nabízí pouze Off/Sleep/Speed. LocalThings si každý takový režim zapamatuje a dál jej nabízí, takže zůstane volitelný, jakmile v něm zařízení alespoň jednou bylo. Vypnutím této volby se budou nabízet pouze režimy, které zařízení samo uvádí; k vymazání již zapamatovaných použijte „Zapomenout zapamatované režimy“ v předchozí nabídce. Zařízení pro praní se staženými cykly z cloudu zde dostane připomenutí, jakmile nahlásí cyklus, který Home Assistant zatím nemůže nabídnout -- některá zařízení jej nahlásí, i když jste obrazovku „Stažené cykly“ v aplikaci SmartThings sami nikdy neotevřeli. Vypněte tuto možnost, chcete-li připomenutí zastavit a skrýt už pojmenované stažené cykly ze seznamu cyklů; nic z toho, co je již nastaveno, se neztratí, a po opětovném zapnutí se to hned znovu objeví.",
         "data": {
           "bypass_remote_control_lock": "Povolit zápis i když je dálkové ovládání hlášeno jako vypnuté",
-          "finish_time_hysteresis_minutes": "Odhadovaný konec -- minimální změna (minuty)"
+          "finish_time_hysteresis_minutes": "Odhadovaný konec -- minimální změna (minuty)",
+          "learn_device_modes": "Pamatovat si režimy, které zařízení hlásí, ale neuvádí jako podporované",
+          "cloud_courses_enabled": "Nabízet stažené cykly"
         }
       },
+      "forget_learned_modes": {
+        "title": "Zapomenout zapamatované režimy",
+        "description": "Aktuálně zapamatováno: {codes}\n\nJde o režimy, ve kterých se toto zařízení samo hlásilo, aniž by je uvádělo mezi podporovanými; jsou uchovány, aby zůstaly volitelné. Zapomenutí je řešením, pokud se některý ukázal jako chybný – cokoli, co zařízení skutečně znovu nahlásí, si systém opět zapamatuje, pokud zároveň nevypnete volbu „Pamatovat si režimy, které zařízení hlásí, ale neuvádí jako podporované“ v nastavení."
+      },
       "debug_write": {
         "title": "Ladění: zápis do prostředku",
         "description": "Nástroj pro pokročilé uživatele k odhalení chování zápisu specifického pro dané zařízení. Vyberte prostředek (href), do kterého chcete zapisovat, nebo zadejte vlastní, který není uveden v seznamu. Toto obchází blokování při vypnutém dálkovém ovládání a odesílá přesně ta pole, která zadáte -- může to špatně nakonfigurovat váš spotřebič, používejte tedy záměrně.",
@@ -1322,20 +1587,63 @@
           "debug_write": "Zapsat do dalšího prostředku",
           "finish": "Dokončit"
         }
+      },
+      "cloud_manual": {
+        "title": "Stažené cykly",
+        "description": "Toto zařízení hlásí {total} stažených cyklů; {found} jich bylo dosud zjištěno.\n\nNastavení staženého cyklu jsou viditelná pouze tehdy, když je daný cyklus právě načtený, a zařízení nikdy nehlásí jejich názvy. Chcete-li doplnit chybějící ({pending}): v aplikaci SmartThings (ne na samotném zařízení) otevřete toto zařízení a klepněte na „Stažené cykly“ -- samostatný řádek odlišný od „Cyklus“, níže na obrazovce, a ten, na kterém zde záleží. Poté postupně projděte jednotlivé stažené programy, u každého se na pár sekund zastavte, aby jej LocalThings zaznamenal, a vraťte se sem.\n\nKaždému z nich zadejte název, který chcete vidět v Home Assistant. Necháte-li název prázdný, daný cyklus zůstane mimo seznam cyklů. Názvy musí být jedinečné.\n\nStažený program je program na tomto zařízení, který spouští stažený cyklus. Rozpoznává se automaticky, ale před použitím jej zde potvrďte: výběrem staženého cyklu se do zařízení zapíše tento kód programu.",
+        "data": {
+          "download_course": "Kód programu „Stažený program“"
+        }
+      },
+      "cloud_courses": {
+        "title": "Stažené cykly",
+        "description": "Průvodce nastavením vás provede: v aplikaci SmartThings (ne na samotném zařízení) otevřete toto zařízení a klepněte na „Stažené cykly“ -- samostatný řádek odlišný od „Cyklus“, níže na obrazovce, a ten, na kterém zde záleží. Vyberte tam cyklus, vraťte se sem a jakmile je nalezen, pojmenujte ho – jeden po druhém.\n\nÚprava názvů zobrazí vše dosud nalezené najednou – použijte ji později k přejmenování nebo opravě. Pojmenování funguje v obou případech, ale pojmenovaný cyklus se nabízí jako vybratelný cyklus jen tehdy, když je v nastavení zařízení zapnuto „Nabízet stažené cykly“.",
+        "menu_options": {
+          "cloud_guided": "Průvodce nastavením",
+          "cloud_manual": "Upravit názvy"
+        }
+      },
+      "cloud_wait": {
+        "title": "Stažené cykly"
+      },
+      "cloud_name": {
+        "title": "Pojmenujte tento cyklus",
+        "description": "Pozice „Stažené cykly“ zařízení nyní obsahuje nový cyklus (pozice {slot}) a hlásí zbývající čas {remaining}.\n\nZadejte název, který chcete vidět v Home Assistant, a poté na obrazovce „Stažené cykly“ v aplikaci SmartThings vyberte další cyklus, který ještě není označen jako „Stažený“. Necháte-li pole prázdné, tento cyklus zůstane mimo seznam.\n\nDosud pojmenováno ({named} z {total}): {named_list}\n\nNázvy musí být jedinečné. Toto okno můžete kdykoli zavřít – názvy se ukládají průběžně.",
+        "data": {
+          "name": "Název",
+          "download_course": "Kód programu „Stažený program“"
+        }
+      },
+      "cloud_timeout": {
+        "title": "Nebyl vybrán žádný cyklus",
+        "description": "Na zařízení se nic nezměnilo. Ujistěte se, že jste v aplikaci SmartThings klepli na „Stažené cykly“ -- samostatný řádek odlišný od „Cyklus“, níže na obrazovce -- a vybrali cyklus, který ještě nebyl označen jako „Stažený“, a poté klepli na Hotovo.\n\nDosud pojmenováno ({named} z {total}): {named_list}\n\nVše dosud pojmenované je již uloženo.",
+        "menu_options": {
+          "cloud_guided": "Počkat znovu",
+          "cloud_finish": "Dokončit"
+        }
       }
     },
     "error": {
       "empty_payload": "Zadejte alespoň jedno pole k zápisu.",
-      "write_failed": "Zápis se nezdařil. Podrobnosti najdete v protokolech Home Assistant."
+      "write_failed": "Zápis se nezdařil. Podrobnosti najdete v protokolech Home Assistant.",
+      "cloud_course_name_duplicate": "Dva cykly mají stejný název. Názvy musí být jedinečné.",
+      "cloud_course_unknown_course": "Tento program zařízení nenabízí. Vyberte jej ze seznamu."
     },
     "abort": {
       "not_loaded": "Toto zařízení ještě není připojeno. Zkuste to znovu, až se načte."
+    },
+    "progress": {
+      "cloud_wait": "V aplikaci SmartThings (ne na samotném zařízení) otevřete toto zařízení a klepněte na „Stažené cykly“ -- samostatný řádek odlišný od „Cyklus“, níže na obrazovce, který uvádí pouze cykly rozpoznatelné tímto způsobem. Vyberte cyklus, který ještě není označen jako „Stažený“, a klepněte na Hotovo.\n\nZařízení nemusí být poblíž ani spuštěné -- stačí, když je zapnuté a připojené.\n\nDosud pojmenováno ({named} z {total}): {named_list}\n\nToto okno můžete kdykoli zavřít – názvy se ukládají průběžně."
     }
   },
   "issues": {
     "device_gap": {
       "title": "Neúplné pokrytí funkcí pro {device_name}",
       "description": "Toto zařízení nemá úplné pokrytí funkcí. Buď nebyl rozpoznán jeho typ spotřebiče, nebo některé jím poskytované prostředky ještě nejsou namodelovány. Bude i nadále fungovat se vším, co je již podporováno. Podporu můžete pomoci rozšířit tak, že přejdete do Nastavení > Zařízení a služby > {device_name} > nabídka (vpravo nahoře) > Stáhnout diagnostiku a poté ji vložíte do odkazované šablony issue."
+    },
+    "cloud_courses_undiscovered": {
+      "title": "Stažené cykly nejsou nastaveny pro {device_name}",
+      "description": "{device_name} má {pending} z {total} stažených cyklů, které Home Assistant zatím nemůže nabídnout. Stažený cyklus lze použít až poté, co byl na zařízení zjištěn načtený -- na obrazovce „Stažené cykly“ v aplikaci SmartThings, ne na obrazovce „Cyklus“ -- a co jste mu dali název.\n\nChcete-li je nastavit, přejděte do Nastavení > Zařízení a služby > LocalThings > {device_name} > Konfigurovat > Stažené cykly a postupujte podle pokynů.\n\nStažené cykly nepoužíváte? Přejděte místo toho do Konfigurovat > Nastavení zařízení a vypněte „Nabízet stažené cykly“, čímž toto připomenutí natrvalo umlčíte."
     }
   },
   "exceptions": {
@@ -1356,6 +1664,30 @@
     },
     "intensive_unavailable_for_cycle": {
       "message": "Intenzivní není u vybraného cyklu k dispozici."
+    },
+    "command_failed": {
+      "message": "Příkaz pro {href} selhal i po opětovném připojení: {error}"
+    },
+    "debug_read_failed": {
+      "message": "Čtení z {href} selhalo: {error}"
+    },
+    "debug_too_many_writes": {
+      "message": "Zadejte 1 až 10 zápisů."
+    },
+    "debug_settle_out_of_range": {
+      "message": "Hodnota settle musí být mezi 0 a 30 sekundami."
+    },
+    "debug_verify_after_out_of_range": {
+      "message": "Hodnota verify_after musí být mezi 0 a 60 sekundami."
+    },
+    "service_device_target_invalid": {
+      "message": "Tato služba vyžaduje přesně jedno cílové zařízení."
+    },
+    "service_device_not_found": {
+      "message": "Pro tento cíl nebylo nalezeno žádné odpovídající zařízení."
+    },
+    "service_device_not_loaded": {
+      "message": "Toto zařízení ještě není připojeno. Zkuste to znovu, až se načte."
     }
   }
 }

custom_components/localthings/translations/en.json

@@ -108,6 +108,15 @@
       },
       "softener_low": {
         "name": "Softener low"
+      },
+      "add_wash_available": {
+        "name": "AddWash allowed"
+      },
+      "add_wash_indicator": {
+        "name": "AddWash ready"
+      },
+      "stick_ble_connected": {
+        "name": "Stick BLE connected"
       }
     },
     "button": {
@@ -152,11 +161,13 @@
               "smart": "Smart",
               "speed": "Speed",
               "nano": "WindFree",
+              "sleep": "Sleep",
               "nanosleep": "WindFree sleep",
               "longwind": "Long wind",
               "motionindirect": "Motion indirect",
               "motiondirect": "Motion direct",
               "drycomfort": "Dry comfort",
+              "dlightcool": "d'light Cool",
               "2step": "2-Step"
             }
           }
@@ -223,6 +234,9 @@
       "air_filter_threshold": {
         "name": "Filter alarm threshold"
       },
+      "auto_door_timer": {
+        "name": "Auto door open timer"
+      },
       "beverage_zone_mode": {
         "name": "Beverage zone mode",
         "state": {
@@ -253,7 +267,11 @@
         "name": "Buzzer sound",
         "state": {
           "off": "Off",
-          "on": "On"
+          "on": "On",
+          "volume_off": "Off",
+          "volume_low": "Low",
+          "volume_med": "Medium",
+          "volume_high": "High"
         }
       },
       "discharging_time": {
@@ -294,8 +312,17 @@
           "0e": "AI Wash",
           "07": "Pre blast",
           "8d": "Pots and pans",
+          "85": "Delicate",
+          "0c": "Express",
+          "0d": "Self clean",
           "8e": "Plastic",
-          "8f": "Baby Care"
+          "8f": "Baby Care",
+          "82": "Auto",
+          "8a": "Normal",
+          "a7": "Heavy",
+          "a8": "Express",
+          "8c": "Extra Silence",
+          "88": "Self Clean"
         }
       },
       "dispense_type": {
@@ -310,6 +337,35 @@
           "4": "Alarm 4"
         }
       },
+      "dryer_cycle_table_00": {
+        "name": "Cycle",
+        "state": {
+          "01": "Normal",
+          "9c": "Heavy Duty",
+          "a5": "Bedding",
+          "9e": "Perm Press",
+          "9b": "Steam Sanitize+",
+          "27": "Refresh",
+          "a0": "Air Fluff",
+          "a4": "Time Dry",
+          "a6": "Quick Dry",
+          "a3": "Active Wear",
+          "a2": "Delicates",
+          "9a": "Cotton",
+          "ca": "Air Wash",
+          "db": "Super Speed",
+          "99": "Mixed Load",
+          "93": "Iron Dry",
+          "b5": "Wool",
+          "d7": "Outdoor Care",
+          "96": "Cool Air",
+          "97": "Warm Air",
+          "7f": "Time Dry",
+          "98": "Quick Dry 35",
+          "eb": "Delicates",
+          "b6": "Synthetics"
+        }
+      },
       "dryer_cycle_table_03": {
         "name": "Cycle",
         "state": {
@@ -325,8 +381,10 @@
           "23": "Quick Dry 35'",
           "24": "Cool air",
           "25": "Warm air",
+          "26": "Air wash",
           "27": "Time dry",
           "29": "AI Dry",
+          "2a": "Hygiene Care+",
           "1a": "Wool",
           "1b": "Bedding",
           "1c": "Shirts",
@@ -337,7 +395,25 @@
           "4c": "Air Refresh",
           "51": "Eco Cotton",
           "53": "AI Dry+",
-          "4e": "Self Dry"
+          "4e": "Self Dry",
+          "02": "AI Dry",
+          "03": "Super Speed",
+          "05": "Bedding",
+          "07": "Delicates",
+          "09": "Shirts",
+          "0b": "Padding Care",
+          "0c": "Outdoor Water-Repellent Care",
+          "0e": "Towels",
+          "0f": "Wool",
+          "11": "Cool air",
+          "28": "Interior Hot Air Sanitize",
+          "37": "Blouses",
+          "38": "Iron dry",
+          "39": "Room Dehumidify",
+          "3a": "Hygiene Care",
+          "3b": "Bedding/Dust Off",
+          "3c": "Activewear",
+          "3d": "Denim"
         }
       },
       "favorite_capacity": {
@@ -461,9 +537,11 @@
           "storage_fridge_normal": "Fridge",
           "storage_fridge_cold": "Fridge, strong",
           "storage_fridge_warm": "Fridge, weak",
+          "storage_fridge": "Fridge",
           "storage_freezer_normal": "Freezer",
           "storage_freezer_cold": "Freezer, strong",
           "storage_freezer_warm": "Freezer, weak",
+          "storage_freezer": "Freezer",
           "kimchi_ripe_low_temp": "Kimchi ripening, low temperature",
           "kimchi_ripe_normal_temp": "Kimchi ripening, room temperature",
           "kimchi_ripe_kkakdugi": "Kkakdugi ripening",
@@ -474,7 +552,8 @@
           "storage_fresh_cereal": "Grains",
           "storage_fridge_drink": "Beverages",
           "storage_fresh_wine": "Wine",
-          "storage_fresh_potato_banana": "Potato & banana"
+          "storage_fresh_potato_banana": "Potato & banana",
+          "newmode_kimchi_0000": "New mode"
         }
       },
       "pantry_zone_mode": {
@@ -485,6 +564,16 @@
           "fdr_drinks": "Drinks"
         }
       },
+      "winecellar_pantry_zone_mode": {
+        "name": "Pantry zone mode",
+        "state": {
+          "processed_meat": "Processed meat",
+          "cheese": "Cheese",
+          "nuts": "Nuts",
+          "fruit": "Fruit",
+          "wine": "Wine"
+        }
+      },
       "range_burner_power_level": {
         "name": "Burner {number} power level",
         "state": {
@@ -536,6 +625,9 @@
           "mute": "Mute"
         }
       },
+      "energy_saving_mode": {
+        "name": "Energy saving mode"
+      },
       "air_purifier_sound_mode": {
         "name": "Sound mode",
         "state": {
@@ -572,12 +664,51 @@
           "extra_hot": "Extra hot"
         }
       },
+      "washer_cycle_table_00": {
+        "name": "Cycle",
+        "state": {
+          "01": "Normal",
+          "70": "Heavy Duty",
+          "55": "Whites",
+          "71": "Bedding",
+          "72": "Sanitize",
+          "77": "Perm Press",
+          "57": "Self Clean+",
+          "73": "Rinse + Spin",
+          "74": "Active Wear",
+          "75": "Delicates",
+          "78": "Quick Wash"
+        }
+      },
       "washer_cycle_table_02": {
         "name": "Cycle",
         "state": {
           "01": "Normal",
+          "02": "Extra Heavy Duty",
+          "03": "Super Eco Wash",
           "04": "Quick Wash",
+          "05": "Wool/Lingerie",
+          "06": "Bedding",
+          "07": "Outdoor",
+          "08": "Rinse+Spin",
+          "09": "Drum Clean",
+          "0a": "Towels",
+          "0b": "Boil Wash",
+          "0c": "Baby Care",
+          "0d": "Spin Only",
+          "0e": "Cloudy Day",
+          "0f": "Pure Wash",
+          "10": "Spin Dry",
+          "11": "Summer Bedding",
+          "12": "Cottons",
+          "13": "Black Cottons",
+          "14": "Delicate Underwear",
+          "15": "Activewear",
+          "16": "Blouses",
           "17": "Downloaded",
+          "18": "Soft Bubble",
+          "19": "AI Wash",
+          "1a": "Shirts",
           "1b": "Cotton",
           "1c": "Eco 40-60",
           "1d": "Super Speed",
@@ -587,7 +718,7 @@
           "21": "Colors",
           "22": "Wool",
           "23": "Outdoor",
-          "24": "Towels",
+          "24": "Bedding",
           "25": "Synthetics",
           "26": "Delicates",
           "27": "Rinse+Spin",
@@ -600,8 +731,9 @@
           "2f": "Activewear",
           "30": "Cloudy Day",
           "32": "Shirts",
-          "33": "Bedding",
+          "33": "Towels",
           "34": "Mixed",
+          "35": "E Cotton",
           "36": "Wash+Dry",
           "37": "Air Wash",
           "38": "Cotton Dry",
@@ -616,14 +748,34 @@
           "60": "Self Clean+",
           "65": "Colors",
           "66": "Denim",
+          "69": "AI Wash",
+          "6a": "Wool",
+          "6b": "Denim",
+          "6c": "Blouses",
+          "6d": "Delicates",
+          "6e": "Active Wear",
+          "6f": "Bedding",
+          "70": "Towels",
+          "71": "Quick Wash",
+          "72": "Shirts",
+          "73": "Sanitize",
+          "74": "Drum Clean",
+          "75": "Outdoor",
+          "76": "Baby Care",
+          "77": "Cottons",
+          "78": "Rinse + Spin",
+          "79": "Spin Only",
           "7c": "Whites",
           "7d": "Bedding/Waterproof",
           "7e": "Self-Clean",
           "7f": "Wool/Delicate",
           "86": "Deep Wash",
           "87": "Download",
+          "88": "Pet Care",
           "8f": "Intense Cold",
-          "96": "Less Microfiber"
+          "96": "Less Microfiber",
+          "a0": "15' Quick Wash",
+          "b0": "Mixed Load"
         }
       },
       "washer_dry_level": {
@@ -663,6 +815,38 @@
       },
       "freezer_temperature_setpoint": {
         "name": "Freezer temperature"
+      },
+      "edge_lighting_mode": {
+        "name": "Edge lighting mode",
+        "state": {
+          "smart": "Smart",
+          "high": "High",
+          "low": "Low"
+        }
+      },
+      "edge_lighting_color": {
+        "name": "Edge lighting color",
+        "state": {
+          "3000k": "3000 K",
+          "4000k": "4000 K",
+          "6500k": "6500 K"
+        }
+      },
+      "indicator_light_mode": {
+        "name": "Indicator light mode",
+        "state": {
+          "smart": "Smart",
+          "high": "High",
+          "low": "Low"
+        }
+      },
+      "ventilation_mode": {
+        "name": "Mode",
+        "state": {
+          "purification": "Purification",
+          "ventilation": "Ventilation",
+          "smartventilation": "Smart Ventilation"
+        }
       }
     },
     "sensor": {
@@ -678,6 +862,9 @@
       "air_filter_usage_hours": {
         "name": "Filter usage hours"
       },
+      "deodor_filter_usage": {
+        "name": "Filter usage"
+      },
       "air_quality_standard": {
         "name": "Air quality standard"
       },
@@ -751,6 +938,12 @@
       "stick_status": {
         "name": "Stick status"
       },
+      "stick_operation_mode": {
+        "name": "Stick operation mode"
+      },
+      "stick_cleaning_status": {
+        "name": "Stick cleaning status"
+      },
       "uvc_operation_time": {
         "name": "UV-C operation time"
       },
@@ -785,6 +978,12 @@
           "indirect": "Indirect"
         }
       },
+      "energy_saving_state": {
+        "name": "Energy saving state"
+      },
+      "energy_saving_operating_status": {
+        "name": "Energy saving operating status"
+      },
       "current_temp_c": {
         "name": "Temperature"
       },
@@ -792,10 +991,16 @@
         "name": "Temperature"
       },
       "diagnosis": {
-        "name": "Diagnosis"
+        "name": "Diagnosis",
+        "state": {
+          "ready": "Ready"
+        }
       },
       "diagnosis_status": {
-        "name": "Diagnosis status"
+        "name": "Diagnosis status",
+        "state": {
+          "ready": "Ready"
+        }
       },
       "drum_clean_cycles_remaining": {
         "name": "Drum clean due in"
@@ -810,7 +1015,10 @@
         "name": "Dry time"
       },
       "dryer_type": {
-        "name": "Dryer type"
+        "name": "Dryer type",
+        "state": {
+          "electricity": "Electricity"
+        }
       },
       "dust": {
         "name": "Dust"
@@ -939,7 +1147,23 @@
         "name": "Probe temperature"
       },
       "progress": {
-        "name": "Progress"
+        "name": "Progress",
+        "state": {
+          "idle": "Idle",
+          "weightsensing": "Weight sensing",
+          "wash": "Washing",
+          "rinse": "Rinsing",
+          "spin": "Spinning",
+          "finish": "Finished",
+          "steaming": "Steaming",
+          "airwashing": "Air washing",
+          "drying": "Drying",
+          "dryingwithdooropen": "Venting",
+          "cooling": "Cooling",
+          "predrain": "Pre-drain",
+          "prewash": "Pre-wash",
+          "sanitizing": "Sanitizing"
+        }
       },
       "progress_percentage": {
         "name": "Progress percent"
@@ -1038,6 +1262,9 @@
       "absence_power_saving_active": {
         "name": "Absence power saving active"
       },
+      "absence_clean": {
+        "name": "Absence clean"
+      },
       "motion_detect_wind_active": {
         "name": "Motion-detect wind avoidance active"
       },
@@ -1071,6 +1298,12 @@
       "auto_door_opener": {
         "name": "Auto door opener"
       },
+      "auto_door_sound_control": {
+        "name": "Auto door sound"
+      },
+      "auto_door_voice_control": {
+        "name": "Auto door voice control"
+      },
       "auto_release_dry": {
         "name": "Auto release dry"
       },
@@ -1137,6 +1370,18 @@
       "intensive": {
         "name": "Intensive"
       },
+      "add_wash_alarm": {
+        "name": "AddWash alarm"
+      },
+      "add_wash_alarm_rinse": {
+        "name": "AddWash rinse"
+      },
+      "add_wash_alarm_final_rinse": {
+        "name": "AddWash final rinse"
+      },
+      "add_wash_alarm_spin": {
+        "name": "AddWash spin"
+      },
       "lamp": {
         "name": "Lamp"
       },
@@ -1202,6 +1447,18 @@
       },
       "ventilation_alarm": {
         "name": "Ventilation alarm"
+      },
+      "edge_lighting": {
+        "name": "Edge lighting"
+      },
+      "indicator_light": {
+        "name": "Indicator light"
+      },
+      "windfree": {
+        "name": "Wind-Free mode"
+      },
+      "windsleep": {
+        "name": "Sleep mode"
       }
     },
     "time": {
@@ -1290,17 +1547,25 @@
         "title": "LocalThings options",
         "menu_options": {
           "settings": "Device settings",
+          "cloud_courses": "Download cycles",
+          "forget_learned_modes": "Forget remembered modes",
           "debug_write": "Debug: write to a resource"
         }
       },
       "settings": {
         "title": "Device settings",
-        "description": "Some devices accept certain writes (e.g. default detergent/softener dosing on a washer) even while reporting remote control off. By default, LocalThings blocks every write with a clear error whenever a device reports remote control off, rather than letting the device silently reject it. Only enable this if you've confirmed writes actually work on this device with remote control off -- otherwise you'll trade that clear error for a silent failure.\n\nEstimated finish time is recomputed from the device's remaining-time estimate on every poll, which can drift or get revised by a minute or two between updates. Raise the minimum-change value below to hold the sensor at its last reported value until the estimate moves by at least that many minutes, cutting down on history/logbook noise. Set it to 0 to report every computed change.",
+        "description": "Some devices accept certain writes (e.g. default detergent/softener dosing on a washer) even while reporting remote control off. By default, LocalThings blocks every write with a clear error whenever a device reports remote control off, rather than letting the device silently reject it. Only enable this if you've confirmed writes actually work on this device with remote control off -- otherwise you'll trade that clear error for a silent failure.\n\nEstimated finish time is recomputed from the device's remaining-time estimate on every poll, which can drift or get revised by a minute or two between updates. Raise the minimum-change value below to hold the sensor at its last reported value until the estimate moves by at least that many minutes, cutting down on history/logbook noise. Set it to 0 to report every computed change.\n\nSome models report a mode they never list as supported -- an air conditioner sitting in Quiet that only offers Off/Sleep/Speed, for instance. LocalThings remembers any such mode it sees and keeps offering it, so it stays selectable once the device has been in it at least once. Turn this off to offer only what the device advertises; use \"Forget remembered modes\" on the previous screen to clear what has already been remembered.\n\nA laundry device with cloud-downloaded cycles gets a reminder here once it's reported one Home Assistant can't offer yet -- some devices report one even if you've never opened the SmartThings app's \"Download cycles\" screen yourself. Turn this off to stop that reminder and hide any already-named downloaded cycles from the cycle list; nothing already set up is lost, and turning it back on brings it right back.",
         "data": {
           "bypass_remote_control_lock": "Allow writes even when remote control is reported off",
-          "finish_time_hysteresis_minutes": "Estimated finish -- minimum change (minutes)"
+          "finish_time_hysteresis_minutes": "Estimated finish -- minimum change (minutes)",
+          "learn_device_modes": "Remember modes the device reports but doesn't advertise",
+          "cloud_courses_enabled": "Offer downloaded cycles"
         }
       },
+      "forget_learned_modes": {
+        "title": "Forget remembered modes",
+        "description": "Currently remembered: {codes}\n\nThese are modes this device reported itself in without listing them as supported, kept so they stay selectable. Forgetting them is the fix if one turned out to be bogus -- anything the device genuinely reports again will simply be remembered again, unless you also turn off \"Remember modes the device reports but doesn't advertise\" in Device settings."
+      },
       "debug_write": {
         "title": "Debug: write to a resource",
         "description": "Power-user tool for pinning down device-specific write behavior. Pick the resource (href) you want to write to, or type a custom one that isn't listed. This bypasses the remote-control-off block and sends exactly the fields you provide -- it can misconfigure your appliance, so use it deliberately.",
@@ -1322,20 +1587,63 @@
           "debug_write": "Write another resource",
           "finish": "Finish"
         }
+      },
+      "cloud_manual": {
+        "title": "Download cycles",
+        "description": "This appliance reports {total} downloaded cycle(s); {found} have been seen so far.\n\nA downloaded cycle's settings are only visible while that cycle is loaded, and the appliance never reports their names. To add the missing ones ({pending}): in the SmartThings app (not on the appliance itself), open this appliance and tap \"Download cycles\" -- a separate row from \"Cycle\", further down the screen, and the one that matters here. Step through each downloaded program in turn, pausing a few seconds on each so LocalThings can see it, then come back here.\n\nGive each one the name you want to see in Home Assistant. Leave a name blank to keep that cycle out of the cycle list. Names must be unique.\n\nThe Download cycle is the course on this appliance that runs a downloaded program. It is detected automatically, but confirm it here before use: selecting a downloaded cycle writes this course code to the appliance.",
+        "data": {
+          "download_course": "Download cycle course code"
+        }
+      },
+      "cloud_courses": {
+        "title": "Download cycles",
+        "description": "Guided setup walks you through it: in the SmartThings app (not on the appliance itself), open this appliance and tap \"Download cycles\" -- a separate row from \"Cycle\", further down the screen, and the one that matters here. Pick a cycle there, then come back and name it as it's found, one at a time.\n\nEdit names shows everything found so far at once — use it to rename or correct something later. Naming works either way, but a named cycle is only offered as a selectable cycle while \"Offer downloaded cycles\" is on in Device settings.",
+        "menu_options": {
+          "cloud_guided": "Guided setup",
+          "cloud_manual": "Edit names"
+        }
+      },
+      "cloud_wait": {
+        "title": "Download cycles"
+      },
+      "cloud_name": {
+        "title": "Name this cycle",
+        "description": "The appliance's \"Download cycles\" slot now holds a new cycle (slot {slot}) and reports {remaining} remaining.\n\nGive it the name you want to see in Home Assistant, then in the SmartThings app's \"Download cycles\" screen pick the next one that isn't already marked \"Downloaded\". Leave it blank to keep this cycle out of the list.\n\nNamed so far ({named} of {total}): {named_list}\n\nNames must be unique. You can close this dialog whenever you like — names are saved as you go.",
+        "data": {
+          "name": "Name",
+          "download_course": "Download cycle course code"
+        }
+      },
+      "cloud_timeout": {
+        "title": "No cycle selected",
+        "description": "Nothing changed on the appliance. Make sure you tapped \"Download cycles\" in the SmartThings app -- a separate row from \"Cycle\", further down the screen -- and picked one that wasn't already marked \"Downloaded\", then tapped Done.\n\nNamed so far ({named} of {total}): {named_list}\n\nEverything named so far is already saved.",
+        "menu_options": {
+          "cloud_guided": "Wait again",
+          "cloud_finish": "Finish"
+        }
       }
     },
     "error": {
       "empty_payload": "Enter at least one field to write.",
-      "write_failed": "The write failed. Check the Home Assistant logs for details."
+      "write_failed": "The write failed. Check the Home Assistant logs for details.",
+      "cloud_course_name_duplicate": "Two cycles have the same name. Names must be unique.",
+      "cloud_course_unknown_course": "That course isn't one this appliance offers. Pick one from the list."
     },
     "abort": {
       "not_loaded": "This device isn't connected yet. Try again once it has loaded."
+    },
+    "progress": {
+      "cloud_wait": "In the SmartThings app (not on the appliance itself), open this appliance and tap \"Download cycles\" -- a separate row from \"Cycle\", further down the screen, that lists only the cycles this can detect. Pick one that isn't already marked \"Downloaded\", then tap Done.\n\nThe appliance doesn't need to be nearby or running the cycle -- just powered on and connected.\n\nNamed so far ({named} of {total}): {named_list}\n\nYou can close this dialog at any time — names are saved as you go."
     }
   },
   "issues": {
     "device_gap": {
       "title": "Incomplete capability coverage for {device_name}",
       "description": "This device is missing full capability coverage. Either its appliance type wasn't recognized, or some of the resources it exposes aren't modeled yet. It'll keep working with whatever is already supported. You can help expand support by going to Settings > Devices & Services > {device_name} > the menu (top right) > Download diagnostics, then filing it with the linked issue template."
+    },
+    "cloud_courses_undiscovered": {
+      "title": "Downloaded cycles not set up for {device_name}",
+      "description": "{device_name} has {pending} of {total} downloaded cycle(s) that Home Assistant can't offer yet. A downloaded cycle can only be used once the appliance has been seen with it loaded -- in the SmartThings app's \"Download cycles\" screen, not the \"Cycle\" one -- and you've given it a name.\n\nTo set them up, go to Settings > Devices & Services > LocalThings > {device_name} > Configure > Download cycles and follow the instructions there.\n\nDon't use downloaded cycles? Go to Configure > Device settings instead and turn off \"Offer downloaded cycles\" to silence this reminder for good."
     }
   },
   "exceptions": {
@@ -1356,6 +1664,30 @@
     },
     "intensive_unavailable_for_cycle": {
       "message": "Intensive isn't available on the selected cycle."
+    },
+    "command_failed": {
+      "message": "The command to {href} failed even after reconnecting: {error}"
+    },
+    "debug_read_failed": {
+      "message": "The read from {href} failed: {error}"
+    },
+    "debug_too_many_writes": {
+      "message": "Provide between 1 and 10 writes."
+    },
+    "debug_settle_out_of_range": {
+      "message": "settle must be between 0 and 30 seconds."
+    },
+    "debug_verify_after_out_of_range": {
+      "message": "verify_after must be between 0 and 60 seconds."
+    },
+    "service_device_target_invalid": {
+      "message": "This service requires exactly one target device."
+    },
+    "service_device_not_found": {
+      "message": "No matching device was found for that target."
+    },
+    "service_device_not_loaded": {
+      "message": "This device isn't connected yet. Try again once it has loaded."
     }
   }
 }

custom_components/localthings/translations/es.json

@@ -53,17 +53,25 @@
         "title": "Opciones de LocalThings",
         "menu_options": {
           "settings": "Ajustes del dispositivo",
+          "cloud_courses": "Ciclos descargados",
+          "forget_learned_modes": "Olvidar los modos recordados",
           "debug_write": "Depuración: escribir en un recurso"
         }
       },
       "settings": {
         "title": "Ajustes del dispositivo",
-        "description": "Algunos dispositivos aceptan ciertas escrituras (p. ej. la dosificación por defecto de detergente/suavizante en una lavadora) incluso cuando informan de control remoto desactivado. Por defecto, LocalThings bloquea cada escritura con un error claro cuando un dispositivo informa de control remoto desactivado, en lugar de dejar que el dispositivo la rechace en silencio. Solo actívalo si has confirmado que las escrituras funcionan de verdad en este dispositivo con el control remoto desactivado; si no, cambiarás ese error claro por un fallo silencioso.\n\nLa hora estimada de finalización se recalcula a partir de la estimación de tiempo restante del dispositivo en cada sondeo, que puede variar o revisarse uno o dos minutos entre actualizaciones. Sube el valor de cambio mínimo siguiente para mantener el sensor en su último valor notificado hasta que la estimación varíe al menos esa cantidad de minutos, reduciendo el ruido en el historial/registro de actividad. Ponlo a 0 para notificar cada cambio calculado.",
+        "description": "Algunos dispositivos aceptan ciertas escrituras (p. ej. la dosificación por defecto de detergente/suavizante en una lavadora) incluso cuando informan de control remoto desactivado. Por defecto, LocalThings bloquea cada escritura con un error claro cuando un dispositivo informa de control remoto desactivado, en lugar de dejar que el dispositivo la rechace en silencio. Solo actívalo si has confirmado que las escrituras funcionan de verdad en este dispositivo con el control remoto desactivado; si no, cambiarás ese error claro por un fallo silencioso.\n\nLa hora estimada de finalización se recalcula a partir de la estimación de tiempo restante del dispositivo en cada sondeo, que puede variar o revisarse uno o dos minutos entre actualizaciones. Sube el valor de cambio mínimo siguiente para mantener el sensor en su último valor notificado hasta que la estimación varíe al menos esa cantidad de minutos, reduciendo el ruido en el historial/registro de actividad. Ponlo a 0 para notificar cada cambio calculado.\n\nAlgunos modelos notifican un modo que nunca incluyen entre los admitidos: por ejemplo, un aire acondicionado en modo Quiet que solo ofrece Off/Sleep/Speed. LocalThings recuerda cualquier modo así que detecte y lo sigue ofreciendo, de modo que quede seleccionable en cuanto el dispositivo haya estado en él al menos una vez. Desactívalo para ofrecer solo lo que el dispositivo anuncia; usa «Olvidar los modos recordados» en la pantalla anterior para borrar lo ya recordado. Un dispositivo de lavandería con ciclos descargados de la nube recibe aquí un aviso en cuanto informa de uno que Home Assistant aún no puede ofrecer -- algunos dispositivos informan de uno incluso si nunca has abierto tú mismo la pantalla \"Descarga de Programas\" de la app SmartThings. Desactiva esto para detener ese aviso y ocultar los ciclos descargados ya nombrados de la lista de ciclos; no se pierde nada de lo ya configurado, y al volver a activarlo reaparece de inmediato.",
         "data": {
           "bypass_remote_control_lock": "Permitir escrituras incluso cuando el control remoto se notifica como desactivado",
-          "finish_time_hysteresis_minutes": "Finalización estimada -- cambio mínimo (minutos)"
+          "finish_time_hysteresis_minutes": "Finalización estimada -- cambio mínimo (minutos)",
+          "learn_device_modes": "Recordar los modos que el dispositivo notifica pero no anuncia",
+          "cloud_courses_enabled": "Ofrecer ciclos descargados"
         }
       },
+      "forget_learned_modes": {
+        "title": "Olvidar los modos recordados",
+        "description": "Recordados actualmente: {codes}\n\nSon modos en los que este dispositivo se notificó a sí mismo sin incluirlos entre los admitidos; se conservan para que sigan siendo seleccionables. Olvidarlos es la solución si alguno resultó ser erróneo: cualquier modo que el dispositivo vuelva a notificar de verdad se recordará otra vez, salvo que además desactives «Recordar los modos que el dispositivo notifica pero no anuncia» en los ajustes del dispositivo."
+      },
       "debug_write": {
         "title": "Depuración: escribir en un recurso",
         "description": "Herramienta para usuarios avanzados para precisar el comportamiento de escritura específico del dispositivo. Elige el recurso (href) sobre el que quieres escribir, o escribe uno personalizado que no esté en la lista. Esto omite el bloqueo de control remoto desactivado y envía exactamente los campos que proporciones; puede desconfigurar tu electrodoméstico, así que úsalo deliberadamente.",
@@ -85,20 +93,63 @@
           "debug_write": "Escribir otro recurso",
           "finish": "Finalizar"
         }
+      },
+      "cloud_manual": {
+        "title": "Ciclos descargados",
+        "description": "Este dispositivo informa de {total} ciclos descargados; se han detectado {found} hasta ahora.\n\nLos ajustes de un ciclo descargado solo son visibles mientras ese ciclo está cargado, y el dispositivo nunca informa de sus nombres. Para añadir los que faltan ({pending}): en la app SmartThings (no en el dispositivo), abre este dispositivo y toca \"Descarga de Programas\" -- una fila aparte de \"Ciclo\", más abajo en la pantalla, y la que importa aquí. Ve pasando por cada programa descargado uno a uno, deteniéndote unos segundos en cada uno para que LocalThings pueda detectarlo, y vuelve aquí.\n\nDa a cada uno el nombre que quieras ver en Home Assistant. Deja un nombre en blanco para mantener ese ciclo fuera de la lista de ciclos. Los nombres deben ser únicos.\n\nDescarga de Programas es el programa de este dispositivo que ejecuta un ciclo descargado. Se detecta automáticamente, pero confírmalo aquí antes de usarlo: seleccionar un ciclo descargado escribe este código de programa en el dispositivo.",
+        "data": {
+          "download_course": "Código de programa de Descarga de Programas"
+        }
+      },
+      "cloud_courses": {
+        "title": "Ciclos descargados",
+        "description": "La configuración guiada te acompaña: en la app SmartThings (no en el dispositivo), abre este dispositivo y toca \"Descarga de Programas\" -- una fila aparte de \"Ciclo\", más abajo en la pantalla, y la que importa aquí. Elige un ciclo allí, vuelve aquí y ponle nombre en cuanto se detecte, uno por uno.\n\nEditar nombres muestra todo lo encontrado hasta ahora de una vez — úsalo más adelante para renombrar o corregir algo. Nombrar funciona en cualquier caso, pero un ciclo con nombre solo se ofrece como ciclo seleccionable mientras \"Ofrecer ciclos descargados\" esté activado en los ajustes del dispositivo.",
+        "menu_options": {
+          "cloud_guided": "Configuración guiada",
+          "cloud_manual": "Editar nombres"
+        }
+      },
+      "cloud_wait": {
+        "title": "Ciclos descargados"
+      },
+      "cloud_name": {
+        "title": "Nombra este ciclo",
+        "description": "La ranura \"Descarga de Programas\" del dispositivo ahora tiene un ciclo nuevo (ranura {slot}) e informa de {remaining} restantes.\n\nDale el nombre que quieras ver en Home Assistant y luego, en la pantalla \"Descarga de Programas\" de la app SmartThings, elige el siguiente que no esté ya marcado como \"Descargado\". Déjalo en blanco para mantener este ciclo fuera de la lista.\n\nNombrados hasta ahora ({named} de {total}): {named_list}\n\nLos nombres deben ser únicos. Puedes cerrar este cuadro de diálogo cuando quieras — los nombres se guardan sobre la marcha.",
+        "data": {
+          "name": "Nombre",
+          "download_course": "Código de programa de Descarga de Programas"
+        }
+      },
+      "cloud_timeout": {
+        "title": "No se seleccionó ningún ciclo",
+        "description": "No ha cambiado nada en el dispositivo. Asegúrate de haber tocado \"Descarga de Programas\" en la app SmartThings -- una fila aparte de \"Ciclo\", más abajo en la pantalla -- y de haber elegido uno que no estuviera ya marcado como \"Descargado\", y luego tocado Hecho.\n\nNombrados hasta ahora ({named} de {total}): {named_list}\n\nTodo lo nombrado hasta ahora ya está guardado.",
+        "menu_options": {
+          "cloud_guided": "Esperar de nuevo",
+          "cloud_finish": "Finalizar"
+        }
       }
     },
     "error": {
       "empty_payload": "Introduce al menos un campo para escribir.",
-      "write_failed": "La escritura falló. Consulta los registros de Home Assistant para más detalles."
+      "write_failed": "La escritura falló. Consulta los registros de Home Assistant para más detalles.",
+      "cloud_course_name_duplicate": "Dos ciclos tienen el mismo nombre. Los nombres deben ser únicos.",
+      "cloud_course_unknown_course": "Ese programa no es uno que ofrezca este dispositivo. Elige uno de la lista."
     },
     "abort": {
       "not_loaded": "Este dispositivo aún no está conectado. Inténtalo de nuevo cuando se haya cargado."
+    },
+    "progress": {
+      "cloud_wait": "En la app SmartThings (no en el dispositivo), abre este dispositivo y toca \"Descarga de Programas\" -- una fila aparte de \"Ciclo\", más abajo en la pantalla, que solo lista los ciclos que se pueden detectar así. Elige uno que no esté ya marcado como \"Descargado\" y toca Hecho.\n\nEl dispositivo no necesita estar cerca ni ejecutando el ciclo -- solo encendido y conectado.\n\nNombrados hasta ahora ({named} de {total}): {named_list}\n\nPuedes cerrar este cuadro de diálogo en cualquier momento — los nombres se guardan sobre la marcha."
     }
   },
   "issues": {
     "device_gap": {
       "title": "Cobertura de capacidades incompleta para {device_name}",
       "description": "A este dispositivo le falta cobertura completa de capacidades. O su tipo de electrodoméstico no fue reconocido, o algunos de los recursos que expone aún no están modelados. Seguirá funcionando con lo que ya está soportado. Puedes ayudar a ampliar el soporte yendo a Ajustes > Dispositivos y servicios > {device_name} > el menú (arriba a la derecha) > Descargar diagnósticos, y reportándolo con la plantilla de incidencia enlazada."
+    },
+    "cloud_courses_undiscovered": {
+      "title": "Ciclos descargados sin configurar para {device_name}",
+      "description": "{device_name} tiene {pending} de {total} ciclos descargados que Home Assistant todavía no puede ofrecer. Un ciclo descargado solo se puede usar una vez que el dispositivo se ha visto con él cargado -- en la pantalla \"Descarga de Programas\" de la app SmartThings, no en la de \"Ciclo\" -- y le has dado un nombre.\n\nPara configurarlos, ve a Ajustes > Dispositivos y servicios > LocalThings > {device_name} > Configurar > Ciclos descargados y sigue las instrucciones que aparecen allí.\n\n¿No usas ciclos descargados? Ve a Configurar > Ajustes del dispositivo y desactiva \"Ofrecer ciclos descargados\" para silenciar este aviso definitivamente."
     }
   },
   "exceptions": {
@@ -119,6 +170,30 @@
     },
     "intensive_unavailable_for_cycle": {
       "message": "El modo intensivo no está disponible en el ciclo seleccionado."
+    },
+    "command_failed": {
+      "message": "El comando para {href} falló incluso después de reconectar: {error}"
+    },
+    "debug_read_failed": {
+      "message": "La lectura desde {href} falló: {error}"
+    },
+    "debug_too_many_writes": {
+      "message": "Proporciona entre 1 y 10 escrituras."
+    },
+    "debug_settle_out_of_range": {
+      "message": "settle debe estar entre 0 y 30 segundos."
+    },
+    "debug_verify_after_out_of_range": {
+      "message": "verify_after debe estar entre 0 y 60 segundos."
+    },
+    "service_device_target_invalid": {
+      "message": "Este servicio requiere exactamente un dispositivo de destino."
+    },
+    "service_device_not_found": {
+      "message": "No se encontró ningún dispositivo coincidente para ese destino."
+    },
+    "service_device_not_loaded": {
+      "message": "Este dispositivo aún no está conectado. Vuelve a intentarlo cuando se haya cargado."
     }
   },
   "entity": {
@@ -228,8 +303,17 @@
       "softener_low": {
         "name": "Poco suavizante"
       },
+      "add_wash_available": {
+        "name": "AddWash permitido"
+      },
+      "add_wash_indicator": {
+        "name": "AddWash disponible"
+      },
       "auto_clean_running": {
         "name": "Limpieza automática en curso"
+      },
+      "stick_ble_connected": {
+        "name": "Aspiradora conectada por BLE"
       }
     },
     "button": {
@@ -274,11 +358,13 @@
               "smart": "Inteligente",
               "speed": "Rápido",
               "nano": "WindFree",
+              "sleep": "Sueño",
               "nanosleep": "WindFree sueño",
               "longwind": "Viento prolongado",
               "motionindirect": "Indirecto al movimiento",
               "motiondirect": "Directo al movimiento",
               "drycomfort": "Confort seco",
+              "dlightcool": "d'light Cool",
               "2step": "2 pasos"
             }
           }
@@ -345,6 +431,9 @@
       "air_filter_threshold": {
         "name": "Umbral de alarma del filtro"
       },
+      "auto_door_timer": {
+        "name": "Temporizador de apertura automática de puerta"
+      },
       "beverage_zone_mode": {
         "name": "Modo de zona de bebidas",
         "state": {
@@ -375,7 +464,11 @@
         "name": "Volumen",
         "state": {
           "off": "Apagado",
-          "on": "Encendido"
+          "on": "Encendido",
+          "volume_off": "Apagado",
+          "volume_low": "Bajo",
+          "volume_med": "Medio",
+          "volume_high": "Alto"
         }
       },
       "discharging_time": {
@@ -417,7 +510,16 @@
           "07": "Prelavado intenso",
           "8d": "Ollas y sartenes",
           "8e": "Plástico",
-          "8f": "Cuidado del bebé"
+          "8f": "Cuidado del bebé",
+          "82": "Automático",
+          "8a": "Normal",
+          "a7": "Intenso",
+          "a8": "Express",
+          "8c": "Extra silencioso",
+          "88": "Autolimpieza",
+          "85": "Delicado",
+          "0c": "Express",
+          "0d": "Autolimpieza"
         }
       },
       "dispense_type": {
@@ -432,6 +534,35 @@
           "4": "Alarma 4"
         }
       },
+      "dryer_cycle_table_00": {
+        "name": "Ciclo",
+        "state": {
+          "01": "Normal",
+          "9c": "Servicio intensivo",
+          "a5": "Ropa de cama",
+          "9e": "Planchado fácil",
+          "9b": "Desinfección por vapor+",
+          "27": "Renovar",
+          "a0": "Aireación",
+          "a4": "Secado por tiempo",
+          "a6": "Secado rápido",
+          "a3": "Ropa deportiva",
+          "a2": "Delicados",
+          "9a": "Algodón",
+          "ca": "Aireación",
+          "db": "Súper velocidad",
+          "99": "Carga mixta",
+          "93": "Planchado fácil",
+          "b5": "Lana",
+          "d7": "Cuidado para exterior",
+          "96": "Aire frío",
+          "97": "Aire caliente",
+          "7f": "Secado por tiempo",
+          "98": "Secado rápido 35",
+          "eb": "Delicados",
+          "b6": "Sintéticos"
+        }
+      },
       "dryer_cycle_table_03": {
         "name": "Ciclo",
         "state": {
@@ -459,7 +590,27 @@
           "4c": "Renovación de aire",
           "51": "Eco algodón",
           "53": "Secado IA+",
-          "4e": "Autosecado"
+          "4e": "Autosecado",
+          "26": "Aireación",
+          "2a": "Cuidado higiénico+",
+          "02": "Secado IA",
+          "03": "Súper velocidad",
+          "05": "Ropa de cama",
+          "07": "Delicados",
+          "09": "Camisas",
+          "0b": "Cuidado de acolchados",
+          "0c": "Cuidado hidrófugo para exterior",
+          "0e": "Toallas",
+          "0f": "Lana",
+          "11": "Aire frío",
+          "28": "Desinfección interior con aire caliente",
+          "37": "Blusas",
+          "38": "Planchado fácil",
+          "39": "Deshumidificación de habitación",
+          "3a": "Cuidado higiénico",
+          "3b": "Ropa de cama/Antipolvo",
+          "3c": "Ropa deportiva",
+          "3d": "Denim"
         }
       },
       "favorite_capacity": {
@@ -581,9 +732,11 @@
           "kimchi_storage_crunfch": "Kimchi crujiente",
           "kimchi_storage_buy": "Kimchi comprado",
           "storage_fridge_normal": "Frigorífico",
+          "storage_fridge": "Frigorífico",
           "storage_fridge_cold": "Frigorífico, fuerte",
           "storage_fridge_warm": "Frigorífico, suave",
           "storage_freezer_normal": "Congelador",
+          "storage_freezer": "Congelador",
           "storage_freezer_cold": "Congelador, fuerte",
           "storage_freezer_warm": "Congelador, suave",
           "kimchi_ripe_low_temp": "Maduración kimchi, baja temperatura",
@@ -596,7 +749,8 @@
           "storage_fresh_cereal": "Cereales",
           "storage_fridge_drink": "Bebidas",
           "storage_fresh_wine": "Vino",
-          "storage_fresh_potato_banana": "Patata y plátano"
+          "storage_fresh_potato_banana": "Patata y plátano",
+          "newmode_kimchi_0000": "Modo nuevo"
         }
       },
       "pantry_zone_mode": {
@@ -607,6 +761,16 @@
           "fdr_drinks": "Bebidas"
         }
       },
+      "winecellar_pantry_zone_mode": {
+        "name": "Modo de zona de despensa",
+        "state": {
+          "processed_meat": "Embutidos",
+          "cheese": "Queso",
+          "nuts": "Frutos secos",
+          "fruit": "Fruta",
+          "wine": "Vino"
+        }
+      },
       "range_burner_power_level": {
         "name": "Nivel de potencia del fuego {number}",
         "state": {
@@ -658,6 +822,9 @@
           "mute": "Silencio"
         }
       },
+      "energy_saving_mode": {
+        "name": "Modo de ahorro de energía"
+      },
       "air_purifier_sound_mode": {
         "name": "Modo de sonido",
         "state": {
@@ -694,12 +861,51 @@
           "extra_hot": "Muy caliente"
         }
       },
+      "washer_cycle_table_00": {
+        "name": "Ciclo",
+        "state": {
+          "01": "Normal",
+          "70": "Servicio intensivo",
+          "55": "Blancos",
+          "71": "Ropa de cama",
+          "72": "Desinfección",
+          "77": "Planchado fácil",
+          "57": "Autolimpieza+",
+          "73": "Aclarar + Centrifugar",
+          "74": "Ropa deportiva",
+          "75": "Delicados",
+          "78": "Lavado rápido"
+        }
+      },
       "washer_cycle_table_02": {
         "name": "Ciclo",
         "state": {
           "01": "Normal",
+          "02": "Servicio Extra Intensivo",
+          "03": "Super Eco",
           "04": "Lavado rápido",
+          "05": "Lana/Lencería",
+          "06": "Ropa de cama",
+          "07": "Exterior",
+          "08": "Aclarar + Centrifugar",
+          "09": "Limpieza de Tambor",
+          "0a": "Toallas",
+          "0b": "Lavado a ebullición",
+          "0c": "Cuidado del bebé",
+          "0d": "Solo centrifugar",
+          "0e": "Día nublado",
+          "0f": "Lavado puro",
+          "10": "Secado-centrifugado",
+          "11": "Ropa de cama de verano",
+          "12": "Algodón",
+          "13": "Algodón negro",
+          "14": "Ropa interior delicada",
+          "15": "Ropa deportiva",
+          "16": "Blusas",
           "17": "Descargado",
+          "18": "Burbuja suave",
+          "19": "Lavado IA",
+          "1a": "Camisas",
           "1b": "Algodón",
           "1c": "Eco 40-60",
           "1d": "Súper velocidad",
@@ -709,7 +915,7 @@
           "21": "Color",
           "22": "Lana",
           "23": "Exterior",
-          "24": "Toallas",
+          "24": "Ropa de cama",
           "25": "Sintéticos",
           "26": "Delicados",
           "27": "Aclarar + Centrifugar",
@@ -722,8 +928,9 @@
           "2f": "Ropa deportiva",
           "30": "Día nublado",
           "32": "Camisas",
-          "33": "Ropa de cama",
+          "33": "Toallas",
           "34": "Mezcla",
+          "35": "Algodón E",
           "36": "Lavado + Secado",
           "37": "Lavado con aire",
           "38": "Secado de algodón",
@@ -738,14 +945,34 @@
           "60": "Autolimpieza+",
           "65": "Color",
           "66": "Denim",
+          "69": "Lavado IA",
+          "6a": "Lana",
+          "6b": "Denim",
+          "6c": "Blusas",
+          "6d": "Delicados",
+          "6e": "Ropa deportiva",
+          "6f": "Ropa de cama",
+          "70": "Toallas",
+          "71": "Lavado rápido",
+          "72": "Camisas",
+          "73": "Desinfección",
+          "74": "Limpieza de Tambor",
+          "75": "Exterior",
+          "76": "Cuidado del bebé",
+          "77": "Algodón",
+          "78": "Aclarar + Centrifugar",
+          "79": "Solo centrifugar",
           "7c": "Blancos",
           "7d": "Ropa de cama / Impermeable",
           "7e": "Autolimpieza",
           "7f": "Lana / Delicados",
           "86": "Lavado profundo",
           "87": "Descarga de Programas",
+          "88": "Cuidado de mascotas",
           "8f": "Lavado en frío",
-          "96": "Menos microfibras"
+          "96": "Menos microfibras",
+          "a0": "Lavado rápido 15'",
+          "b0": "Carga mixta"
         }
       },
       "washer_dry_level": {
@@ -785,6 +1012,38 @@
       },
       "freezer_temperature_setpoint": {
         "name": "Temperatura del congelador"
+      },
+      "edge_lighting_mode": {
+        "name": "Modo de iluminación perimetral",
+        "state": {
+          "smart": "Inteligente",
+          "high": "Alto",
+          "low": "Bajo"
+        }
+      },
+      "edge_lighting_color": {
+        "name": "Color de iluminación perimetral",
+        "state": {
+          "3000k": "3000 K",
+          "4000k": "4000 K",
+          "6500k": "6500 K"
+        }
+      },
+      "indicator_light_mode": {
+        "name": "Modo de luz indicadora",
+        "state": {
+          "smart": "Inteligente",
+          "high": "Alto",
+          "low": "Bajo"
+        }
+      },
+      "ventilation_mode": {
+        "name": "Modo",
+        "state": {
+          "purification": "Purificación",
+          "ventilation": "Ventilación",
+          "smartventilation": "Ventilación inteligente"
+        }
       }
     },
     "sensor": {
@@ -797,6 +1056,9 @@
       "air_filter_usage_hours": {
         "name": "Horas de uso del filtro"
       },
+      "deodor_filter_usage": {
+        "name": "Uso del filtro"
+      },
       "air_quality_standard": {
         "name": "Estándar de calidad del aire"
       },
@@ -870,6 +1132,12 @@
       "stick_status": {
         "name": "Estado de la aspiradora"
       },
+      "stick_operation_mode": {
+        "name": "Modo de funcionamiento de la aspiradora"
+      },
+      "stick_cleaning_status": {
+        "name": "Estado de limpieza de la aspiradora"
+      },
       "uvc_operation_time": {
         "name": "Tiempo de funcionamiento UV-C"
       },
@@ -904,6 +1172,12 @@
           "indirect": "Indirecto"
         }
       },
+      "energy_saving_state": {
+        "name": "Estado de ahorro de energía"
+      },
+      "energy_saving_operating_status": {
+        "name": "Estado de funcionamiento del ahorro de energía"
+      },
       "current_temp_c": {
         "name": "Temperatura"
       },
@@ -911,10 +1185,16 @@
         "name": "Temperatura"
       },
       "diagnosis": {
-        "name": "Diagnóstico"
+        "name": "Diagnóstico",
+        "state": {
+          "ready": "Listo"
+        }
       },
       "diagnosis_status": {
-        "name": "Estado del diagnóstico"
+        "name": "Estado del diagnóstico",
+        "state": {
+          "ready": "Listo"
+        }
       },
       "drum_clean_cycles_remaining": {
         "name": "Limpieza de tambor en"
@@ -929,7 +1209,10 @@
         "name": "Tiempo de secado"
       },
       "dryer_type": {
-        "name": "Tipo de secadora"
+        "name": "Tipo de secadora",
+        "state": {
+          "electricity": "Electricidad"
+        }
       },
       "dust": {
         "name": "Polvo"
@@ -1058,7 +1341,23 @@
         "name": "Temperatura de la sonda"
       },
       "progress": {
-        "name": "Progreso"
+        "name": "Progreso",
+        "state": {
+          "idle": "Inactiva",
+          "weightsensing": "Detección de carga",
+          "wash": "Lavado",
+          "rinse": "Aclarado",
+          "spin": "Centrifugado",
+          "finish": "Finalizado",
+          "steaming": "Vaporización",
+          "airwashing": "Lavado con aire",
+          "drying": "Secado",
+          "dryingwithdooropen": "Ventilación",
+          "cooling": "Enfriamiento",
+          "predrain": "Drenaje previo",
+          "prewash": "Prelavado",
+          "sanitizing": "Desinfección"
+        }
       },
       "progress_percentage": {
         "name": "Porcentaje de progreso"
@@ -1160,6 +1459,9 @@
       "absence_power_saving_active": {
         "name": "Ahorro por ausencia activo"
       },
+      "absence_clean": {
+        "name": "Limpieza por ausencia"
+      },
       "motion_detect_wind_active": {
         "name": "Evitación de viento por detección de movimiento activa"
       },
@@ -1193,6 +1495,12 @@
       "auto_door_opener": {
         "name": "Apertura automática de puerta"
       },
+      "auto_door_sound_control": {
+        "name": "Sonido de apertura automática de puerta"
+      },
+      "auto_door_voice_control": {
+        "name": "Control por voz de apertura automática de puerta"
+      },
       "auto_release_dry": {
         "name": "Liberación automática de secado"
       },
@@ -1259,6 +1567,18 @@
       "intensive": {
         "name": "Intensivo"
       },
+      "add_wash_alarm": {
+        "name": "Aviso AddWash"
+      },
+      "add_wash_alarm_rinse": {
+        "name": "AddWash en aclarado"
+      },
+      "add_wash_alarm_final_rinse": {
+        "name": "AddWash en último aclarado"
+      },
+      "add_wash_alarm_spin": {
+        "name": "AddWash en centrifugado"
+      },
       "lamp": {
         "name": "Lámpara"
       },
@@ -1324,6 +1644,18 @@
       },
       "ventilation_alarm": {
         "name": "Alarma de ventilación"
+      },
+      "edge_lighting": {
+        "name": "Iluminación perimetral"
+      },
+      "indicator_light": {
+        "name": "Luz indicadora"
+      },
+      "windfree": {
+        "name": "Modo Wind-Free"
+      },
+      "windsleep": {
+        "name": "Modo nocturno"
       }
     },
     "time": {

custom_components/localthings/translations/it.json

@@ -108,6 +108,15 @@
       },
       "softener_low": {
         "name": "Aggiungi ammorbidente"
+      },
+      "add_wash_available": {
+        "name": "AddWash consentito"
+      },
+      "add_wash_indicator": {
+        "name": "AddWash disponibile"
+      },
+      "stick_ble_connected": {
+        "name": "Scopa elettrica connessa via BLE"
       }
     },
     "button": {
@@ -152,11 +161,13 @@
               "smart": "Smart",
               "speed": "Veloce",
               "nano": "WindFree",
+              "sleep": "Sonno",
               "nanosleep": "WindFree sonno",
               "longwind": "Vento prolungato",
               "motionindirect": "Indiretto al movimento",
               "motiondirect": "Diretto al movimento",
               "drycomfort": "Comfort asciugatura",
+              "dlightcool": "d'light Cool",
               "2step": "2 fasi"
             }
           }
@@ -223,6 +234,9 @@
       "air_filter_threshold": {
         "name": "Soglia allarme filtro"
       },
+      "auto_door_timer": {
+        "name": "Timer apertura automatica sportello"
+      },
       "beverage_zone_mode": {
         "name": "Modalità zona bevande",
         "state": {
@@ -253,7 +267,11 @@
         "name": "Suono cicalino",
         "state": {
           "off": "Spento",
-          "on": "Acceso"
+          "on": "Acceso",
+          "volume_off": "Spento",
+          "volume_low": "Basso",
+          "volume_med": "Medio",
+          "volume_high": "Alto"
         }
       },
       "discharging_time": {
@@ -295,7 +313,16 @@
           "07": "Prelavaggio intenso",
           "8d": "Pentole e padelle",
           "8e": "Plastica",
-          "8f": "Bambini"
+          "8f": "Bambini",
+          "82": "Automatico",
+          "8a": "Normale",
+          "a7": "Intenso",
+          "a8": "Express",
+          "8c": "Extra silenzioso",
+          "88": "Autopulizia",
+          "85": "Delicato",
+          "0c": "Express",
+          "0d": "Autopulizia"
         }
       },
       "dispense_type": {
@@ -310,6 +337,35 @@
           "4": "Allarme 4"
         }
       },
+      "dryer_cycle_table_00": {
+        "name": "Ciclo",
+        "state": {
+          "01": "Normale",
+          "9c": "Intenso",
+          "a5": "Biancheria da letto",
+          "9e": "Pronto da stirare",
+          "9b": "Igienizzante a vapore+",
+          "27": "Rinfresca",
+          "a0": "Arieggiatura",
+          "a4": "Asciugatura a tempo",
+          "a6": "Asciugatura rapida",
+          "a3": "Abbigliamento sportivo",
+          "a2": "Delicati",
+          "9a": "Cotone",
+          "ca": "Arieggiatura",
+          "db": "Super Speed",
+          "99": "Carico misto",
+          "93": "Pronto da stirare",
+          "b5": "Lana",
+          "d7": "Cura outdoor",
+          "96": "Aria fredda",
+          "97": "Aria calda",
+          "7f": "Asciugatura a tempo",
+          "98": "Asciugatura rapida 35",
+          "eb": "Delicati",
+          "b6": "Sintetici"
+        }
+      },
       "dryer_cycle_table_03": {
         "name": "Ciclo",
         "state": {
@@ -337,7 +393,27 @@
           "4c": "Rinfresca",
           "51": "Eco cotone",
           "53": "Asciugatura AI+",
-          "4e": "Autoasciugatura"
+          "4e": "Autoasciugatura",
+          "26": "Arieggiatura",
+          "2a": "Cura igienica+",
+          "02": "Asciugatura AI",
+          "03": "Super Speed",
+          "05": "Biancheria da letto",
+          "07": "Delicati",
+          "09": "Camicie",
+          "0b": "Cura piumini",
+          "0c": "Cura idrorepellente outdoor",
+          "0e": "Asciugamani",
+          "0f": "Lana",
+          "11": "Aria fredda",
+          "28": "Sanificazione interna ad aria calda",
+          "37": "Camicette",
+          "38": "Pronto da stirare",
+          "39": "Deumidificazione ambiente",
+          "3a": "Cura igienica",
+          "3b": "Biancheria da letto/Antipolvere",
+          "3c": "Abbigliamento sportivo",
+          "3d": "Jeans"
         }
       },
       "favorite_capacity": {
@@ -459,9 +535,11 @@
           "kimchi_storage_crunfch": "Kimchi croccante",
           "kimchi_storage_buy": "Kimchi acquistato",
           "storage_fridge_normal": "Frigorifero",
+          "storage_fridge": "Frigorifero",
           "storage_fridge_cold": "Frigorifero, forte",
           "storage_fridge_warm": "Frigorifero, debole",
           "storage_freezer_normal": "Congelatore",
+          "storage_freezer": "Congelatore",
           "storage_freezer_cold": "Congelatore, forte",
           "storage_freezer_warm": "Congelatore, debole",
           "kimchi_ripe_low_temp": "Maturazione kimchi, bassa temperatura",
@@ -474,7 +552,8 @@
           "storage_fresh_cereal": "Cereali",
           "storage_fridge_drink": "Bevande",
           "storage_fresh_wine": "Vino",
-          "storage_fresh_potato_banana": "Patate e banane"
+          "storage_fresh_potato_banana": "Patate e banane",
+          "newmode_kimchi_0000": "Nuova modalità"
         }
       },
       "pantry_zone_mode": {
@@ -485,6 +564,16 @@
           "fdr_drinks": "Bevande"
         }
       },
+      "winecellar_pantry_zone_mode": {
+        "name": "Modalità zona dispensa",
+        "state": {
+          "processed_meat": "Salumi",
+          "cheese": "Formaggio",
+          "nuts": "Frutta secca",
+          "fruit": "Frutta",
+          "wine": "Vino"
+        }
+      },
       "range_burner_power_level": {
         "name": "Livello potenza fornello {number}",
         "state": {
@@ -536,6 +625,9 @@
           "mute": "Muto"
         }
       },
+      "energy_saving_mode": {
+        "name": "Modalità risparmio energetico"
+      },
       "air_purifier_sound_mode": {
         "name": "Modalità audio",
         "state": {
@@ -572,12 +664,51 @@
           "extra_hot": "Extra caldo"
         }
       },
+      "washer_cycle_table_00": {
+        "name": "Ciclo",
+        "state": {
+          "01": "Normale",
+          "70": "Intenso",
+          "55": "Bianchi",
+          "71": "Biancheria da letto",
+          "72": "Igienizzante",
+          "77": "Pronto da stirare",
+          "57": "Self Clean+",
+          "73": "Risciacquo+Centrifuga",
+          "74": "Abbigliamento sportivo",
+          "75": "Delicati",
+          "78": "Lavaggio rapido"
+        }
+      },
       "washer_cycle_table_02": {
         "name": "Ciclo",
         "state": {
           "01": "Normale",
+          "02": "Extra Intenso",
+          "03": "Super Eco",
           "04": "Lavaggio rapido",
+          "05": "Lana/Lingerie",
+          "06": "Biancheria da letto",
+          "07": "Capi outdoor",
+          "08": "Risciacquo+Centrifuga",
+          "09": "Pulizia cestello",
+          "0a": "Asciugamani",
+          "0b": "Lavaggio a ebollizione",
+          "0c": "Bambini",
+          "0d": "Solo centrifuga",
+          "0e": "Giornata nuvolosa",
+          "0f": "Lavaggio puro",
+          "10": "Asciugatura centrifuga",
+          "11": "Biancheria da letto estiva",
+          "12": "Cotone",
+          "13": "Cotone nero",
+          "14": "Biancheria intima delicata",
+          "15": "Abbigliamento sportivo",
+          "16": "Camicette",
           "17": "Scaricato",
+          "18": "Soft Bubble",
+          "19": "Lavaggio AI",
+          "1a": "Camicie",
           "1b": "Cotone",
           "1c": "Eco 40-60",
           "1d": "Super Speed",
@@ -587,7 +718,7 @@
           "21": "Colorati",
           "22": "Lana",
           "23": "Capi outdoor",
-          "24": "Asciugamani",
+          "24": "Biancheria da letto",
           "25": "Sintetici",
           "26": "Delicati",
           "27": "Risciacquo+Centrifuga",
@@ -600,8 +731,9 @@
           "2f": "Abbigliamento sportivo",
           "30": "Giornata nuvolosa",
           "32": "Camicie",
-          "33": "Biancheria da letto",
+          "33": "Asciugamani",
           "34": "Misti",
+          "35": "Cotone E",
           "36": "Lavaggio+Asciugatura",
           "37": "Lavaggio ad aria",
           "38": "Asciugatura cotone",
@@ -616,14 +748,34 @@
           "60": "Self Clean+",
           "65": "Colorati",
           "66": "Jeans",
+          "69": "Lavaggio AI",
+          "6a": "Lana",
+          "6b": "Jeans",
+          "6c": "Camicette",
+          "6d": "Delicati",
+          "6e": "Abbigliamento sportivo",
+          "6f": "Biancheria da letto",
+          "70": "Asciugamani",
+          "71": "Lavaggio rapido",
+          "72": "Camicie",
+          "73": "Igienizzante",
+          "74": "Pulizia cestello",
+          "75": "Capi outdoor",
+          "76": "Bambini",
+          "77": "Cotone",
+          "78": "Risciacquo+Centrifuga",
+          "79": "Solo centrifuga",
           "7c": "Bianchi",
           "7d": "Biancheria da letto/Impermeabile",
           "7e": "Pulizia cestello",
           "7f": "Lana/Delicati",
           "86": "Lavaggio profondo",
           "87": "Scaricato",
+          "88": "Cura animali",
           "8f": "Intenso a freddo",
-          "96": "Riduci microfibre"
+          "96": "Riduci microfibre",
+          "a0": "Rapido 15'",
+          "b0": "Carico misto"
         }
       },
       "washer_dry_level": {
@@ -663,6 +815,38 @@
       },
       "freezer_temperature_setpoint": {
         "name": "Temperatura freezer"
+      },
+      "edge_lighting_mode": {
+        "name": "Modalità illuminazione perimetrale",
+        "state": {
+          "smart": "Smart",
+          "high": "Alta",
+          "low": "Bassa"
+        }
+      },
+      "edge_lighting_color": {
+        "name": "Colore illuminazione perimetrale",
+        "state": {
+          "3000k": "3000 K",
+          "4000k": "4000 K",
+          "6500k": "6500 K"
+        }
+      },
+      "indicator_light_mode": {
+        "name": "Modalità spia luminosa",
+        "state": {
+          "smart": "Smart",
+          "high": "Alta",
+          "low": "Bassa"
+        }
+      },
+      "ventilation_mode": {
+        "name": "Modalità",
+        "state": {
+          "purification": "Purificazione",
+          "ventilation": "Ventilazione",
+          "smartventilation": "Ventilazione intelligente"
+        }
       }
     },
     "sensor": {
@@ -678,6 +862,9 @@
       "air_filter_usage_hours": {
         "name": "Ore di utilizzo filtro"
       },
+      "deodor_filter_usage": {
+        "name": "Utilizzo filtro"
+      },
       "air_quality_standard": {
         "name": "Standard qualità aria"
       },
@@ -751,6 +938,12 @@
       "stick_status": {
         "name": "Stato scopa elettrica"
       },
+      "stick_operation_mode": {
+        "name": "Modalità operativa scopa elettrica"
+      },
+      "stick_cleaning_status": {
+        "name": "Stato pulizia scopa elettrica"
+      },
       "uvc_operation_time": {
         "name": "Tempo funzionamento UV-C"
       },
@@ -785,6 +978,12 @@
           "indirect": "Indiretto"
         }
       },
+      "energy_saving_state": {
+        "name": "Stato risparmio energetico"
+      },
+      "energy_saving_operating_status": {
+        "name": "Stato di funzionamento del risparmio energetico"
+      },
       "current_temp_c": {
         "name": "Temperatura"
       },
@@ -792,10 +991,16 @@
         "name": "Temperatura"
       },
       "diagnosis": {
-        "name": "Diagnosi"
+        "name": "Diagnosi",
+        "state": {
+          "ready": "Pronto"
+        }
       },
       "diagnosis_status": {
-        "name": "Stato diagnosi"
+        "name": "Stato diagnosi",
+        "state": {
+          "ready": "Pronto"
+        }
       },
       "drum_clean_cycles_remaining": {
         "name": "Pulizia cestello fra"
@@ -810,7 +1015,10 @@
         "name": "Tempo di asciugatura"
       },
       "dryer_type": {
-        "name": "Tipo di asciugatrice"
+        "name": "Tipo di asciugatrice",
+        "state": {
+          "electricity": "Elettricità"
+        }
       },
       "dust": {
         "name": "Polvere"
@@ -939,7 +1147,23 @@
         "name": "Temperatura sonda"
       },
       "progress": {
-        "name": "Avanzamento"
+        "name": "Avanzamento",
+        "state": {
+          "idle": "Inattivo",
+          "weightsensing": "Rilevamento del carico",
+          "wash": "Lavaggio",
+          "rinse": "Risciacquo",
+          "spin": "Centrifuga",
+          "finish": "Completato",
+          "steaming": "Vapore",
+          "airwashing": "Lavaggio ad aria",
+          "drying": "Asciugatura",
+          "dryingwithdooropen": "Ventilazione",
+          "cooling": "Raffreddamento",
+          "predrain": "Scarico preliminare",
+          "prewash": "Prelavaggio",
+          "sanitizing": "Igienizzazione"
+        }
       },
       "progress_percentage": {
         "name": "Avanzamento percentuale"
@@ -1038,6 +1262,9 @@
       "absence_power_saving_active": {
         "name": "Risparmio energetico in assenza attivo"
       },
+      "absence_clean": {
+        "name": "Pulizia in assenza"
+      },
       "motion_detect_wind_active": {
         "name": "Elusione flusso d'aria a rilevamento movimento attiva"
       },
@@ -1071,6 +1298,12 @@
       "auto_door_opener": {
         "name": "Apertura automatica sportello"
       },
+      "auto_door_sound_control": {
+        "name": "Suono apertura automatica sportello"
+      },
+      "auto_door_voice_control": {
+        "name": "Controllo vocale apertura automatica sportello"
+      },
       "auto_release_dry": {
         "name": "Apertura automatica per asciugatura"
       },
@@ -1137,6 +1370,18 @@
       "intensive": {
         "name": "Intensivo"
       },
+      "add_wash_alarm": {
+        "name": "Avviso AddWash"
+      },
+      "add_wash_alarm_rinse": {
+        "name": "AddWash al risciacquo"
+      },
+      "add_wash_alarm_final_rinse": {
+        "name": "AddWash all'ultimo risciacquo"
+      },
+      "add_wash_alarm_spin": {
+        "name": "AddWash alla centrifuga"
+      },
       "lamp": {
         "name": "Lampada"
       },
@@ -1202,6 +1447,18 @@
       },
       "ventilation_alarm": {
         "name": "Allarme ventilazione"
+      },
+      "edge_lighting": {
+        "name": "Illuminazione perimetrale"
+      },
+      "indicator_light": {
+        "name": "Spia luminosa"
+      },
+      "windfree": {
+        "name": "Modalità Wind-Free"
+      },
+      "windsleep": {
+        "name": "Modalità notte"
       }
     },
     "time": {
@@ -1290,17 +1547,25 @@
         "title": "Opzioni LocalThings",
         "menu_options": {
           "settings": "Impostazioni dispositivo",
+          "cloud_courses": "Cicli scaricati",
+          "forget_learned_modes": "Dimentica le modalità memorizzate",
           "debug_write": "Debug: scrivi su una risorsa"
         }
       },
       "settings": {
         "title": "Impostazioni dispositivo",
-        "description": "Alcuni dispositivi accettano determinate scritture (ad esempio, il dosaggio predefinito di detersivo/ammorbidente su una lavatrice) anche quando segnalano che il controllo remoto è disattivato. Per impostazione predefinita, LocalThings blocca ogni scrittura con un errore chiaro ogni volta che un dispositivo segnala che il controllo remoto è disattivato, invece di consentire al dispositivo di rifiutarla silenziosamente. Abilitare questa opzione solo se si è verificato che le scritture funzionano effettivamente su questo dispositivo con il controllo remoto disattivato; in caso contrario, si sostituirà l'errore chiaro con un errore silenzioso.\n\nIl tempo di fine stimato viene ricalcolato dalla stima del tempo rimanente del dispositivo a ogni interrogazione, che può variare o essere rivista di uno o due minuti tra un aggiornamento e l'altro. Aumentare il valore di variazione minima riportato di seguito per mantenere il sensore al suo ultimo valore segnalato finché la stima non si sposta di almeno quel numero di minuti, riducendo il rumore nella cronologia/registro. Impostarlo su 0 per segnalare ogni variazione calcolata.",
+        "description": "Alcuni dispositivi accettano determinate scritture (ad esempio, il dosaggio predefinito di detersivo/ammorbidente su una lavatrice) anche quando segnalano che il controllo remoto è disattivato. Per impostazione predefinita, LocalThings blocca ogni scrittura con un errore chiaro ogni volta che un dispositivo segnala che il controllo remoto è disattivato, invece di consentire al dispositivo di rifiutarla silenziosamente. Abilitare questa opzione solo se si è verificato che le scritture funzionano effettivamente su questo dispositivo con il controllo remoto disattivato; in caso contrario, si sostituirà l'errore chiaro con un errore silenzioso.\n\nIl tempo di fine stimato viene ricalcolato dalla stima del tempo rimanente del dispositivo a ogni interrogazione, che può variare o essere rivista di uno o due minuti tra un aggiornamento e l'altro. Aumentare il valore di variazione minima riportato di seguito per mantenere il sensore al suo ultimo valore segnalato finché la stima non si sposta di almeno quel numero di minuti, riducendo il rumore nella cronologia/registro. Impostarlo su 0 per segnalare ogni variazione calcolata.\n\nAlcuni modelli segnalano una modalità che non elencano mai tra quelle supportate: ad esempio un condizionatore in modalità Quiet che offre solo Off/Sleep/Speed. LocalThings memorizza ogni modalità di questo tipo che rileva e continua a proporla, così resta selezionabile una volta che il dispositivo vi è stato almeno una volta. Disattivare questa opzione per proporre solo ciò che il dispositivo dichiara; usare «Dimentica le modalità memorizzate» nella schermata precedente per cancellare quanto già memorizzato. Un dispositivo per il bucato con cicli scaricati dal cloud riceve qui un promemoria non appena ne segnala uno che Home Assistant non può ancora offrire -- alcuni dispositivi ne segnalano uno anche se non è mai stata aperta la schermata \"Cicli scaricati\" dell'app SmartThings. Disattivarlo per interrompere il promemoria e nascondere dall'elenco dei cicli quelli scaricati già nominati; nulla di quanto già configurato va perso, e riattivandolo riappare subito.",
         "data": {
           "bypass_remote_control_lock": "Consenti la scrittura anche quando il controllo remoto risulta disattivato.",
-          "finish_time_hysteresis_minutes": "Tempo finale stimato - variazione minima (minuti)"
+          "finish_time_hysteresis_minutes": "Tempo finale stimato - variazione minima (minuti)",
+          "learn_device_modes": "Memorizza le modalità che il dispositivo segnala ma non dichiara supportate",
+          "cloud_courses_enabled": "Offri cicli scaricati"
         }
       },
+      "forget_learned_modes": {
+        "title": "Dimentica le modalità memorizzate",
+        "description": "Attualmente memorizzate: {codes}\n\nSono modalità in cui questo dispositivo si è dichiarato senza elencarle tra quelle supportate; vengono conservate perché restino selezionabili. Dimenticarle è la soluzione se una si è rivelata errata: qualsiasi modalità che il dispositivo segnali davvero di nuovo verrà memorizzata un'altra volta, a meno che non si disattivi anche «Memorizza le modalità che il dispositivo segnala ma non dichiara supportate» nelle impostazioni del dispositivo."
+      },
       "debug_write": {
         "title": "Debug: scrivi su una risorsa",
         "description": "Strumento avanzato per definire con precisione il comportamento di scrittura specifico del dispositivo. Seleziona la risorsa (href) su cui desideri scrivere oppure digitane una personalizzata non presente nell'elenco. Questo bypassa il blocco di disattivazione del controllo remoto e invia esattamente i campi specificati; tuttavia, potrebbe causare una configurazione errata del dispositivo, quindi utilizzalo con cautela.",
@@ -1322,20 +1587,63 @@
           "debug_write": "Scrivi un'altra risorsa",
           "finish": "Fine"
         }
+      },
+      "cloud_manual": {
+        "title": "Cicli scaricati",
+        "description": "Questo dispositivo segnala {total} cicli scaricati; finora ne sono stati rilevati {found}.\n\nLe impostazioni di un ciclo scaricato sono visibili solo mentre quel ciclo è caricato, e il dispositivo non ne segnala mai il nome. Per aggiungere quelli mancanti ({pending}): nell'app SmartThings (non sul dispositivo), aprire questo dispositivo e toccare \"Cicli scaricati\" -- una riga separata da \"Ciclo\", più in basso nella schermata, ed è quella che conta qui. Scorrere ciascun programma scaricato uno alla volta, sostando qualche secondo su ognuno perché LocalThings possa rilevarlo, e tornare qui.\n\nAssegnare a ciascuno il nome che si desidera vedere in Home Assistant. Lasciare un nome vuoto per escludere quel ciclo dall'elenco dei cicli. I nomi devono essere univoci.\n\nIl ciclo Scaricato è il programma su questo dispositivo che esegue un programma scaricato. Viene rilevato automaticamente, ma confermarlo qui prima dell'uso: selezionare un ciclo scaricato scrive questo codice di programma sul dispositivo.",
+        "data": {
+          "download_course": "Codice programma del ciclo Scaricato"
+        }
+      },
+      "cloud_courses": {
+        "title": "Cicli scaricati",
+        "description": "La configurazione guidata accompagna l'utente: nell'app SmartThings (non sul dispositivo), aprire questo dispositivo e toccare \"Cicli scaricati\" -- una riga separata da \"Ciclo\", più in basso nella schermata, ed è quella che conta qui. Scegliere un ciclo lì, poi tornare qui e assegnargli un nome non appena viene rilevato, uno alla volta.\n\nModifica nomi mostra tutto ciò che è stato trovato finora in una sola volta — usarla in seguito per rinominare o correggere qualcosa. Assegnare un nome funziona comunque, ma un ciclo con nome viene offerto come ciclo selezionabile solo quando \"Offri cicli scaricati\" è attivo nelle impostazioni del dispositivo.",
+        "menu_options": {
+          "cloud_guided": "Configurazione guidata",
+          "cloud_manual": "Modifica nomi"
+        }
+      },
+      "cloud_wait": {
+        "title": "Cicli scaricati"
+      },
+      "cloud_name": {
+        "title": "Assegna un nome a questo ciclo",
+        "description": "Lo slot \"Cicli scaricati\" del dispositivo ora contiene un nuovo ciclo (slot {slot}) e segnala {remaining} rimanenti.\n\nAssegnargli il nome che si desidera vedere in Home Assistant, quindi nella schermata \"Cicli scaricati\" dell'app SmartThings scegliere il successivo non ancora contrassegnato come \"Scaricato\". Lasciare vuoto per escludere questo ciclo dall'elenco.\n\nAssegnati finora ({named} di {total}): {named_list}\n\nI nomi devono essere univoci. È possibile chiudere questa finestra in qualsiasi momento — i nomi vengono salvati man mano.",
+        "data": {
+          "name": "Nome",
+          "download_course": "Codice programma del ciclo Scaricato"
+        }
+      },
+      "cloud_timeout": {
+        "title": "Nessun ciclo selezionato",
+        "description": "Non è cambiato nulla sul dispositivo. Assicurarsi di aver toccato \"Cicli scaricati\" nell'app SmartThings -- una riga separata da \"Ciclo\", più in basso nella schermata -- e di aver scelto un ciclo non ancora contrassegnato come \"Scaricato\", quindi di aver toccato Fine.\n\nAssegnati finora ({named} di {total}): {named_list}\n\nTutto ciò che è stato assegnato finora è già salvato.",
+        "menu_options": {
+          "cloud_guided": "Attendi di nuovo",
+          "cloud_finish": "Fine"
+        }
       }
     },
     "error": {
       "empty_payload": "Inserisci almeno un campo da scrivere.",
-      "write_failed": "Operazione di scrittura non riuscita. Controlla i registri di Home Assistant per i dettagli."
+      "write_failed": "Operazione di scrittura non riuscita. Controlla i registri di Home Assistant per i dettagli.",
+      "cloud_course_name_duplicate": "Due cicli hanno lo stesso nome. I nomi devono essere univoci.",
+      "cloud_course_unknown_course": "Quel programma non è tra quelli offerti da questo dispositivo. Selezionarne uno dall'elenco."
     },
     "abort": {
       "not_loaded": "Questo dispositivo non è ancora connesso. Riprova dopo il caricamento."
+    },
+    "progress": {
+      "cloud_wait": "Nell'app SmartThings (non sul dispositivo), aprire questo dispositivo e toccare \"Cicli scaricati\" -- una riga separata da \"Ciclo\", più in basso nella schermata, che elenca solo i cicli rilevabili in questo modo. Scegliere uno non ancora contrassegnato come \"Scaricato\", quindi toccare Fine.\n\nIl dispositivo non deve essere nelle vicinanze né in esecuzione -- deve solo essere acceso e connesso.\n\nAssegnati finora ({named} di {total}): {named_list}\n\nÈ possibile chiudere questa finestra in qualsiasi momento — i nomi vengono salvati man mano."
     }
   },
   "issues": {
     "device_gap": {
       "title": "Copertura delle funzionalità incompleta per {device_name}",
       "description": "Questo dispositivo non è completamente supportato. Il tipo di dispositivo non è stato riconosciuto oppure alcune delle risorse che espone non sono ancora state modellate. Continuerò a funzionare con le funzionalità già supportate. Puoi contribuire ad ampliare il supporto andando su Impostazioni > Dispositivi e servizi > {device_name} > il menu (in alto a destra) > Scarica diagnostica, quindi inviando una segnalazione tramite il modulo di segnalazione collegato."
+    },
+    "cloud_courses_undiscovered": {
+      "title": "Cicli scaricati non configurati per {device_name}",
+      "description": "{device_name} ha {pending} cicli scaricati su {total} che Home Assistant non può ancora offrire. Un ciclo scaricato può essere usato solo dopo che il dispositivo è stato rilevato con quel ciclo caricato -- nella schermata \"Cicli scaricati\" dell'app SmartThings, non in quella \"Ciclo\" -- ed è stato assegnato un nome.\n\nPer configurarli, andare su Impostazioni > Dispositivi e servizi > LocalThings > {device_name} > Configura > Cicli scaricati e seguire le istruzioni presenti lì.\n\nNon si usano cicli scaricati? Andare invece su Configura > Impostazioni dispositivo e disattivare \"Offri cicli scaricati\" per silenziare questo promemoria definitivamente."
     }
   },
   "exceptions": {
@@ -1356,6 +1664,30 @@
     },
     "intensive_unavailable_for_cycle": {
       "message": "Intensivo non è disponibile per il ciclo selezionato."
+    },
+    "command_failed": {
+      "message": "Il comando per {href} è fallito anche dopo la riconnessione: {error}"
+    },
+    "debug_read_failed": {
+      "message": "La lettura da {href} è fallita: {error}"
+    },
+    "debug_too_many_writes": {
+      "message": "Specificare da 1 a 10 scritture."
+    },
+    "debug_settle_out_of_range": {
+      "message": "settle deve essere compreso tra 0 e 30 secondi."
+    },
+    "debug_verify_after_out_of_range": {
+      "message": "verify_after deve essere compreso tra 0 e 60 secondi."
+    },
+    "service_device_target_invalid": {
+      "message": "Questo servizio richiede esattamente un dispositivo di destinazione."
+    },
+    "service_device_not_found": {
+      "message": "Nessun dispositivo corrispondente trovato per quella destinazione."
+    },
+    "service_device_not_loaded": {
+      "message": "Questo dispositivo non è ancora connesso. Riprova una volta caricato."
     }
   }
 }

custom_components/localthings/translations/ko.json

@@ -108,6 +108,15 @@
       },
       "softener_low": {
         "name": "섬유유연제 부족"
+      },
+      "add_wash_available": {
+        "name": "애드워시 허용"
+      },
+      "add_wash_indicator": {
+        "name": "애드워시 가능"
+      },
+      "stick_ble_connected": {
+        "name": "스틱 BLE 연결됨"
       }
     },
     "button": {
@@ -152,11 +161,13 @@
               "smart": "스마트",
               "speed": "스피드",
               "nano": "무풍",
+              "sleep": "숙면",
               "nanosleep": "무풍 수면",
               "longwind": "롱바람",
               "motionindirect": "간접풍",
               "motiondirect": "직접풍",
               "drycomfort": "쾌적 제습",
+              "dlightcool": "d'light Cool",
               "2step": "2단계"
             }
           }
@@ -223,6 +234,9 @@
       "air_filter_threshold": {
         "name": "필터 알림 기준"
       },
+      "auto_door_timer": {
+        "name": "오토 오픈 도어 타이머"
+      },
       "beverage_zone_mode": {
         "name": "음료 보관 모드",
         "state": {
@@ -253,7 +267,11 @@
         "name": "부저음",
         "state": {
           "off": "끄기",
-          "on": "켜기"
+          "on": "켜기",
+          "volume_off": "끔",
+          "volume_low": "낮음",
+          "volume_med": "중간",
+          "volume_high": "높음"
         }
       },
       "discharging_time": {
@@ -295,7 +313,16 @@
           "07": "애벌 세척",
           "8d": "냄비 및 팬",
           "8e": "플라스틱",
-          "8f": "젖병 살균"
+          "8f": "젖병 살균",
+          "82": "자동",
+          "8a": "표준",
+          "a7": "강력",
+          "a8": "급속",
+          "8c": "저소음",
+          "88": "내부 세척",
+          "85": "섬세",
+          "0c": "급속",
+          "0d": "내부 세척"
         }
       },
       "dispense_type": {
@@ -310,6 +337,35 @@
           "4": "알림음 4"
         }
       },
+      "dryer_cycle_table_00": {
+        "name": "코스",
+        "state": {
+          "01": "표준건조",
+          "9c": "강력건조",
+          "a5": "이불",
+          "9e": "구김방지",
+          "9b": "스팀살균+",
+          "27": "리프레시",
+          "a0": "송풍",
+          "a4": "시간건조",
+          "a6": "쾌속건조",
+          "a3": "운동복",
+          "a2": "섬세의류",
+          "9a": "면의류",
+          "ca": "송풍",
+          "db": "쾌속건조",
+          "99": "혼합",
+          "93": "다림질건조",
+          "b5": "울",
+          "d7": "아웃도어케어",
+          "96": "송풍건조",
+          "97": "온풍건조",
+          "7f": "시간건조",
+          "98": "쾌속건조 35분",
+          "eb": "섬세의류",
+          "b6": "합성섬유"
+        }
+      },
       "dryer_cycle_table_03": {
         "name": "코스",
         "state": {
@@ -337,7 +393,27 @@
           "4c": "에어 리프레시",
           "51": "에코 면",
           "53": "AI 맞춤건조+",
-          "4e": "자체 건조"
+          "4e": "자체 건조",
+          "26": "송풍",
+          "2a": "살균건조+",
+          "02": "AI 맞춤건조",
+          "03": "쾌속건조",
+          "05": "이불",
+          "07": "섬세의류",
+          "09": "셔츠",
+          "0b": "패딩케어",
+          "0c": "아웃도어발수케어",
+          "0e": "타월",
+          "0f": "울",
+          "11": "송풍건조",
+          "28": "열풍내부살균",
+          "37": "블라우스",
+          "38": "다림질건조",
+          "39": "공간제습",
+          "3a": "살균건조",
+          "3b": "이불/먼지털기",
+          "3c": "피트니스",
+          "3d": "데님"
         }
       },
       "favorite_capacity": {
@@ -459,9 +535,11 @@
           "kimchi_storage_crunfch": "아삭 김치",
           "kimchi_storage_buy": "구입 김치",
           "storage_fridge_normal": "냉장",
+          "storage_fridge": "냉장",
           "storage_fridge_cold": "냉장 강",
           "storage_fridge_warm": "냉장 약",
           "storage_freezer_normal": "냉동",
+          "storage_freezer": "냉동",
           "storage_freezer_cold": "냉동 강",
           "storage_freezer_warm": "냉동 약",
           "kimchi_ripe_low_temp": "김치 저온 숙성",
@@ -474,7 +552,8 @@
           "storage_fresh_cereal": "곡류",
           "storage_fridge_drink": "음료",
           "storage_fresh_wine": "와인",
-          "storage_fresh_potato_banana": "감자 및 바나나"
+          "storage_fresh_potato_banana": "감자 및 바나나",
+          "newmode_kimchi_0000": "새 모드"
         }
       },
       "pantry_zone_mode": {
@@ -485,6 +564,16 @@
           "fdr_drinks": "음료"
         }
       },
+      "winecellar_pantry_zone_mode": {
+        "name": "팬트리실 모드",
+        "state": {
+          "processed_meat": "가공육",
+          "cheese": "치즈",
+          "nuts": "견과류",
+          "fruit": "과일",
+          "wine": "와인"
+        }
+      },
       "range_burner_power_level": {
         "name": "{number}번 화구 화력",
         "state": {
@@ -536,6 +625,9 @@
           "mute": "음소거"
         }
       },
+      "energy_saving_mode": {
+        "name": "절전 모드"
+      },
       "air_purifier_sound_mode": {
         "name": "소리 모드",
         "state": {
@@ -572,12 +664,51 @@
           "extra_hot": "고온수"
         }
       },
+      "washer_cycle_table_00": {
+        "name": "코스",
+        "state": {
+          "01": "표준세탁",
+          "70": "강력세탁",
+          "55": "흰옷",
+          "71": "이불",
+          "72": "살균",
+          "77": "구김방지",
+          "57": "통세척+",
+          "73": "헹굼+탈수",
+          "74": "운동복",
+          "75": "섬세의류",
+          "78": "쾌속세탁"
+        }
+      },
       "washer_cycle_table_02": {
         "name": "코스",
         "state": {
           "01": "표준세탁",
+          "02": "초강력세탁",
+          "03": "초절약세탁",
           "04": "쾌속세탁",
+          "05": "울/란제리",
+          "06": "이불",
+          "07": "아웃도어",
+          "08": "헹굼+탈수",
+          "09": "무세제통세척",
+          "0a": "타월",
+          "0b": "삶음세탁",
+          "0c": "아기옷",
+          "0d": "탈수단독",
+          "0e": "흐린날세탁",
+          "0f": "청정세탁",
+          "10": "건조탈수",
+          "11": "여름이불",
+          "12": "면의류",
+          "13": "검은면의류",
+          "14": "섬세속옷",
+          "15": "피트니스",
+          "16": "블라우스",
           "17": "다운로드 코스",
+          "18": "소프트버블",
+          "19": "AI 맞춤세탁",
+          "1a": "셔츠",
           "1b": "면",
           "1c": "에코 40-60",
           "1d": "쾌속세탁",
@@ -587,7 +718,7 @@
           "21": "컬러 의류",
           "22": "울",
           "23": "아웃도어",
-          "24": "타월",
+          "24": "이불",
           "25": "합성섬유",
           "26": "섬세의류",
           "27": "헹굼+탈수",
@@ -600,8 +731,9 @@
           "2f": "피트니스",
           "30": "흐린 날",
           "32": "셔츠",
-          "33": "이불",
+          "33": "타월",
           "34": "혼합",
+          "35": "에코 면",
           "36": "세탁+건조",
           "37": "에어워시",
           "38": "면 건조",
@@ -616,14 +748,34 @@
           "60": "통세척+",
           "65": "컬러 의류",
           "66": "데님",
+          "69": "AI 맞춤세탁",
+          "6a": "울",
+          "6b": "데님",
+          "6c": "블라우스",
+          "6d": "섬세의류",
+          "6e": "운동복",
+          "6f": "이불",
+          "70": "타월",
+          "71": "쾌속세탁",
+          "72": "셔츠",
+          "73": "살균",
+          "74": "무세제통세척",
+          "75": "아웃도어",
+          "76": "아기옷",
+          "77": "면",
+          "78": "헹굼+탈수",
+          "79": "탈수만",
           "7c": "흰옷",
           "7d": "이불/방수 의류",
           "7e": "통세척",
           "7f": "울/섬세",
           "86": "찌든 때 세탁",
           "87": "다운로드",
+          "88": "펫케어",
           "8f": "강력 냉수 세탁",
-          "96": "미세플라스틱저감"
+          "96": "미세플라스틱저감",
+          "a0": "15분 쾌속세탁",
+          "b0": "혼합 세탁"
         }
       },
       "washer_dry_level": {
@@ -663,6 +815,38 @@
       },
       "freezer_temperature_setpoint": {
         "name": "냉동실 온도"
+      },
+      "edge_lighting_mode": {
+        "name": "엣지 라이팅 모드",
+        "state": {
+          "smart": "스마트",
+          "high": "높음",
+          "low": "낮음"
+        }
+      },
+      "edge_lighting_color": {
+        "name": "엣지 라이팅 색상",
+        "state": {
+          "3000k": "3000 K",
+          "4000k": "4000 K",
+          "6500k": "6500 K"
+        }
+      },
+      "indicator_light_mode": {
+        "name": "표시등 모드",
+        "state": {
+          "smart": "스마트",
+          "high": "높음",
+          "low": "낮음"
+        }
+      },
+      "ventilation_mode": {
+        "name": "모드",
+        "state": {
+          "purification": "청정",
+          "ventilation": "환기",
+          "smartventilation": "스마트환기"
+        }
       }
     },
     "sensor": {
@@ -678,6 +862,9 @@
       "air_filter_usage_hours": {
         "name": "필터 사용 시간"
       },
+      "deodor_filter_usage": {
+        "name": "필터 사용량"
+      },
       "air_quality_standard": {
         "name": "공기질 기준"
       },
@@ -751,6 +938,12 @@
       "stick_status": {
         "name": "스틱 청소기 상태"
       },
+      "stick_operation_mode": {
+        "name": "스틱 작동 모드"
+      },
+      "stick_cleaning_status": {
+        "name": "스틱 청소 상태"
+      },
       "uvc_operation_time": {
         "name": "UV-C 작동 시간"
       },
@@ -785,6 +978,12 @@
           "indirect": "간접풍"
         }
       },
+      "energy_saving_state": {
+        "name": "절전 상태"
+      },
+      "energy_saving_operating_status": {
+        "name": "절전 작동 상태"
+      },
       "current_temp_c": {
         "name": "온도"
       },
@@ -792,10 +991,16 @@
         "name": "온도"
       },
       "diagnosis": {
-        "name": "진단"
+        "name": "진단",
+        "state": {
+          "ready": "준비됨"
+        }
       },
       "diagnosis_status": {
-        "name": "진단 상태"
+        "name": "진단 상태",
+        "state": {
+          "ready": "준비됨"
+        }
       },
       "drum_clean_cycles_remaining": {
         "name": "통세척까지 남은 횟수"
@@ -810,7 +1015,10 @@
         "name": "건조 시간"
       },
       "dryer_type": {
-        "name": "건조기 유형"
+        "name": "건조기 유형",
+        "state": {
+          "electricity": "전기"
+        }
       },
       "dust": {
         "name": "미세먼지"
@@ -939,7 +1147,23 @@
         "name": "탐침 온도계 현재 온도"
       },
       "progress": {
-        "name": "진행률"
+        "name": "진행률",
+        "state": {
+          "idle": "대기",
+          "weightsensing": "세탁물 감지",
+          "wash": "세탁",
+          "rinse": "헹굼",
+          "spin": "탈수",
+          "finish": "완료",
+          "steaming": "스팀",
+          "airwashing": "에어워시",
+          "drying": "건조",
+          "dryingwithdooropen": "환기",
+          "cooling": "냉각",
+          "predrain": "사전 배수",
+          "prewash": "애벌빨래",
+          "sanitizing": "살균"
+        }
       },
       "progress_percentage": {
         "name": "진행률"
@@ -1038,6 +1262,9 @@
       "absence_power_saving_active": {
         "name": "부재 절전 작동"
       },
+      "absence_clean": {
+        "name": "부재 청소"
+      },
       "motion_detect_wind_active": {
         "name": "모션 감지 바람 회피 작동"
       },
@@ -1071,6 +1298,12 @@
       "auto_door_opener": {
         "name": "오토 오픈 도어"
       },
+      "auto_door_sound_control": {
+        "name": "오토 오픈 도어 소리"
+      },
+      "auto_door_voice_control": {
+        "name": "오토 오픈 도어 음성 안내"
+      },
       "auto_release_dry": {
         "name": "자동 문 열림 건조"
       },
@@ -1137,6 +1370,18 @@
       "intensive": {
         "name": "강력"
       },
+      "add_wash_alarm": {
+        "name": "애드워시 알림"
+      },
+      "add_wash_alarm_rinse": {
+        "name": "애드워시 헹굼"
+      },
+      "add_wash_alarm_final_rinse": {
+        "name": "애드워시 마지막 헹굼"
+      },
+      "add_wash_alarm_spin": {
+        "name": "애드워시 탈수"
+      },
       "lamp": {
         "name": "램프"
       },
@@ -1202,6 +1447,18 @@
       },
       "ventilation_alarm": {
         "name": "환기 알림"
+      },
+      "edge_lighting": {
+        "name": "엣지 라이팅"
+      },
+      "indicator_light": {
+        "name": "표시등"
+      },
+      "windfree": {
+        "name": "무풍 모드"
+      },
+      "windsleep": {
+        "name": "취침 모드"
       }
     },
     "time": {
@@ -1290,17 +1547,25 @@
         "title": "LocalThings 옵션",
         "menu_options": {
           "settings": "기기 설정",
+          "cloud_courses": "다운로드 코스",
+          "forget_learned_modes": "기억된 모드 지우기",
           "debug_write": "디버그: 리소스에 쓰기"
         }
       },
       "settings": {
         "title": "기기 설정",
-        "description": "일부 기기는 스마트 컨트롤이 꺼져 있다고 보고하는 동안에도 특정 쓰기 요청(예: 세탁기의 기본 세제/섬유유연제 투입량)을 받아들입니다. 기본적으로 LocalThings는 기기가 스마트 컨트롤 꺼짐을 보고하면 기기가 쓰기 요청을 조용히 거부하도록 두지 않고, 명확한 오류와 함께 모든 쓰기를 차단합니다. 스마트 컨트롤이 꺼진 상태에서도 이 기기에 쓰기가 실제로 동작하는 것을 확인한 경우에만 이 옵션을 활성화하세요. 그렇지 않으면 명확한 오류 대신 아무 표시 없이 쓰기에 실패할 수 있습니다.\n\n예상 완료 시각은 기기가 보고하는 남은 시간 추정치를 사용하여 상태를 확인할 때마다 다시 계산합니다. 이 추정치는 업데이트 사이에 1~2분 정도 변하거나 수정될 수 있습니다. 아래의 최소 변경량을 늘리면 추정치가 설정한 시간(분) 이상 변할 때까지 센서가 마지막으로 보고된 값을 유지하므로 기록과 로그북에 불필요한 항목이 쌓이는 것을 줄일 수 있습니다. 계산된 모든 변경 사항을 보고하려면 0으로 설정하세요.",
+        "description": "일부 기기는 스마트 컨트롤이 꺼져 있다고 보고하는 동안에도 특정 쓰기 요청(예: 세탁기의 기본 세제/섬유유연제 투입량)을 받아들입니다. 기본적으로 LocalThings는 기기가 스마트 컨트롤 꺼짐을 보고하면 기기가 쓰기 요청을 조용히 거부하도록 두지 않고, 명확한 오류와 함께 모든 쓰기를 차단합니다. 스마트 컨트롤이 꺼진 상태에서도 이 기기에 쓰기가 실제로 동작하는 것을 확인한 경우에만 이 옵션을 활성화하세요. 그렇지 않으면 명확한 오류 대신 아무 표시 없이 쓰기에 실패할 수 있습니다.\n\n예상 완료 시각은 기기가 보고하는 남은 시간 추정치를 사용하여 상태를 확인할 때마다 다시 계산합니다. 이 추정치는 업데이트 사이에 1~2분 정도 변하거나 수정될 수 있습니다. 아래의 최소 변경량을 늘리면 추정치가 설정한 시간(분) 이상 변할 때까지 센서가 마지막으로 보고된 값을 유지하므로 기록과 로그북에 불필요한 항목이 쌓이는 것을 줄일 수 있습니다. 계산된 모든 변경 사항을 보고하려면 0으로 설정하세요.\n\n일부 모델은 지원 목록에 없는 모드를 현재 모드로 보고합니다. 예를 들어 Off/Sleep/Speed만 제공하면서 Quiet 모드로 동작 중이라고 보고하는 에어컨이 그렇습니다. LocalThings는 이렇게 발견한 모드를 기억해 두고 계속 제공하므로, 기기가 한 번이라도 그 모드였다면 이후에도 선택할 수 있습니다. 이 옵션을 끄면 기기가 지원한다고 알린 모드만 제공합니다. 이미 기억된 항목을 지우려면 이전 화면의 '기억된 모드 지우기'를 사용하세요. 클라우드에서 다운로드한 코스가 있는 세탁기는 Home Assistant가 아직 제공할 수 없는 코스를 보고하는 즉시 여기에서 알림을 받습니다. 일부 기기는 SmartThings 앱의 \"다운로드 코스\" 화면을 직접 연 적이 없어도 이런 코스를 보고합니다. 이 옵션을 끄면 이 알림이 멈추고 이미 이름을 지정한 다운로드 코스도 코스 목록에서 숨겨집니다. 이미 설정한 내용은 사라지지 않으며, 다시 켜면 즉시 원래대로 돌아옵니다.",
         "data": {
           "bypass_remote_control_lock": "스마트 컨트롤이 꺼진 것으로 보고되어도 쓰기 허용",
-          "finish_time_hysteresis_minutes": "예상 완료 시각 - 최소 변경량(분)"
+          "finish_time_hysteresis_minutes": "예상 완료 시각 - 최소 변경량(분)",
+          "learn_device_modes": "기기가 보고하지만 지원 목록에 없는 모드 기억하기",
+          "cloud_courses_enabled": "다운로드 코스 제공"
         }
       },
+      "forget_learned_modes": {
+        "title": "기억된 모드 지우기",
+        "description": "현재 기억된 항목: {codes}\n\n이 기기가 지원 목록에 넣지 않은 채 자신의 현재 모드로 보고했던 모드들이며, 계속 선택할 수 있도록 보관되어 있습니다. 잘못된 항목이 기억되었다면 지우면 됩니다. 다만 기기가 실제로 다시 보고하면 다시 기억되므로, 그러길 원하지 않는다면 기기 설정에서 '기기가 보고하지만 지원 목록에 없는 모드 기억하기'도 함께 꺼 주세요."
+      },
       "debug_write": {
         "title": "디버그: 리소스에 쓰기",
         "description": "기기별 쓰기 동작을 파악하기 위한 고급 사용자용 도구입니다. 쓰려는 리소스(href)를 선택하거나 목록에 없는 값을 직접 입력하세요. 이 기능은 스마트 컨트롤 꺼짐 차단을 우회하고 입력한 필드를 그대로 전송합니다. 가전제품이 잘못 설정될 수 있으므로 신중하게 사용하세요.",
@@ -1322,20 +1587,63 @@
           "debug_write": "다른 리소스에 쓰기",
           "finish": "완료"
         }
+      },
+      "cloud_manual": {
+        "title": "다운로드 코스",
+        "description": "이 기기는 다운로드한 코스를 {total}개 보고하며, 지금까지 {found}개를 확인했습니다.\n\n다운로드한 코스의 설정은 해당 코스가 로드되어 있는 동안에만 확인할 수 있고, 기기는 그 이름을 전달하지 않습니다. 누락된 항목({pending}개)을 추가하려면 기기가 아닌 SmartThings 앱에서 이 기기를 열고 \"다운로드 코스\"를 탭하세요. 이는 화면 아래쪽에 있는 \"코스\"와는 별도의 항목이며, 여기서 중요한 것은 이 항목입니다. 그런 다음 다운로드된 프로그램을 하나씩 차례로 실행하면서 LocalThings가 인식할 수 있도록 몇 초씩 머무른 뒤 이 화면으로 돌아오세요.\n\n각 코스에 Home Assistant에서 보고 싶은 이름을 입력하세요. 이름을 비워 두면 해당 코스는 코스 목록에서 제외됩니다. 이름은 서로 달라야 합니다.\n\n다운로드 코스는 이 기기에서 다운로드된 프로그램을 실행하는 코스입니다. 자동으로 감지되지만 사용하기 전에 여기서 확인하세요. 다운로드한 코스를 선택하면 이 코스 코드가 기기에 기록됩니다.",
+        "data": {
+          "download_course": "다운로드 코스 코드"
+        }
+      },
+      "cloud_courses": {
+        "title": "다운로드 코스",
+        "description": "안내 설정은 다음과 같이 진행됩니다. 기기가 아닌 SmartThings 앱에서 이 기기를 열고 \"다운로드 코스\"를 탭하세요. 이는 화면 아래쪽에 있는 \"코스\"와는 별도의 항목이며, 여기서 중요한 것은 이 항목입니다. 그곳에서 코스를 선택한 다음 돌아와서, 코스가 확인될 때마다 하나씩 이름을 지정하세요.\n\n이름 편집은 지금까지 찾은 모든 코스를 한 번에 보여줍니다. 나중에 이름을 바꾸거나 수정할 때 사용하세요. 이름 지정은 어느 경우든 가능하지만, 이름을 지정한 코스는 기기 설정에서 \"다운로드 코스 제공\"이 켜져 있을 때만 선택 가능한 코스로 제공됩니다.",
+        "menu_options": {
+          "cloud_guided": "안내 설정",
+          "cloud_manual": "이름 편집"
+        }
+      },
+      "cloud_wait": {
+        "title": "다운로드 코스"
+      },
+      "cloud_name": {
+        "title": "이 코스 이름 지정",
+        "description": "기기의 \"다운로드 코스\" 슬롯에 이제 새 코스(슬롯 {slot})가 들어 있으며 {remaining} 남았다고 표시됩니다.\n\nHome Assistant에서 보고 싶은 이름을 입력한 다음, SmartThings 앱의 \"다운로드 코스\" 화면에서 아직 \"다운로드됨\"으로 표시되지 않은 다음 코스를 선택하세요. 비워 두면 이 코스는 목록에서 제외됩니다.\n\n지금까지 이름 지정됨 ({named}/{total}개): {named_list}\n\n이름은 서로 달라야 합니다. 이 창은 언제든지 닫을 수 있습니다. 이름은 진행하는 대로 저장됩니다.",
+        "data": {
+          "name": "이름",
+          "download_course": "다운로드 코스 코드"
+        }
+      },
+      "cloud_timeout": {
+        "title": "선택된 코스 없음",
+        "description": "기기에서 변경된 내용이 없습니다. SmartThings 앱에서 \"다운로드 코스\"(화면 아래쪽에 있는 \"코스\"와는 별도의 항목)를 탭하고, 아직 \"다운로드됨\"으로 표시되지 않은 코스를 선택한 다음 완료를 탭했는지 확인하세요.\n\n지금까지 이름 지정됨 ({named}/{total}개): {named_list}\n\n지금까지 이름을 지정한 항목은 이미 저장되었습니다.",
+        "menu_options": {
+          "cloud_guided": "다시 대기",
+          "cloud_finish": "완료"
+        }
       }
     },
     "error": {
       "empty_payload": "쓸 필드를 하나 이상 입력하세요.",
-      "write_failed": "쓰기에 실패했습니다. 자세한 내용은 Home Assistant 로그에서 확인하세요."
+      "write_failed": "쓰기에 실패했습니다. 자세한 내용은 Home Assistant 로그에서 확인하세요.",
+      "cloud_course_name_duplicate": "두 코스의 이름이 같습니다. 이름은 서로 달라야 합니다.",
+      "cloud_course_unknown_course": "이 기기가 제공하지 않는 코스입니다. 목록에서 선택하세요."
     },
     "abort": {
       "not_loaded": "이 기기는 아직 연결되지 않았습니다. 기기를 불러온 후 다시 시도하세요."
+    },
+    "progress": {
+      "cloud_wait": "기기가 아닌 SmartThings 앱에서 이 기기를 열고 \"다운로드 코스\"를 탭하세요. 이는 화면 아래쪽에 있는 \"코스\"와는 별도의 항목이며, 이 방식으로 인식할 수 있는 코스만 나열됩니다. 아직 \"다운로드됨\"으로 표시되지 않은 코스를 선택한 다음 완료를 탭하세요.\n\n기기가 근처에 있거나 코스를 실행 중일 필요는 없습니다. 전원이 켜져 있고 연결되어 있기만 하면 됩니다.\n\n지금까지 이름 지정됨 ({named}/{total}개): {named_list}\n\n이 창은 언제든지 닫을 수 있습니다. 이름은 진행하는 대로 저장됩니다."
     }
   },
   "issues": {
     "device_gap": {
       "title": "{device_name}의 기능 지원이 완전하지 않음",
       "description": "이 기기의 일부 기능이 아직 완전히 지원되지 않습니다. 가전제품 유형이 인식되지 않았거나, 기기가 제공하는 일부 리소스가 아직 구현되지 않았습니다. 현재 지원되는 기능은 계속 사용할 수 있습니다. 설정 > 기기 및 서비스 > {device_name} > 오른쪽 위 메뉴 > 진단 정보 다운로드로 이동하여 진단 정보를 내려받은 뒤, 연결된 이슈 양식에 첨부하면 지원 범위를 넓히는 데 도움을 줄 수 있습니다."
+    },
+    "cloud_courses_undiscovered": {
+      "title": "{device_name}의 다운로드 코스가 설정되지 않음",
+      "description": "{device_name}에는 Home Assistant가 아직 제공할 수 없는 다운로드한 코스가 {total}개 중 {pending}개 있습니다. 다운로드한 코스는 SmartThings 앱의 \"다운로드 코스\" 화면(\"코스\" 화면이 아님)에서 기기가 해당 코스로 로드된 상태로 확인되고 이름을 지정한 후에만 사용할 수 있습니다.\n\n설정하려면 설정 > 기기 및 서비스 > LocalThings > {device_name} > 구성 > 다운로드 코스로 이동하여 안내를 따르세요.\n\n다운로드 코스를 사용하지 않나요? 대신 구성 > 기기 설정으로 이동하여 \"다운로드 코스 제공\"을 꺼서 이 알림을 완전히 중지하세요."
     }
   },
   "exceptions": {
@@ -1356,6 +1664,30 @@
     },
     "intensive_unavailable_for_cycle": {
       "message": "선택한 코스에서는 강력 세탁을 사용할 수 없습니다."
+    },
+    "command_failed": {
+      "message": "재연결 후에도 {href} 명령이 실패했습니다: {error}"
+    },
+    "debug_read_failed": {
+      "message": "{href}에서 읽기가 실패했습니다: {error}"
+    },
+    "debug_too_many_writes": {
+      "message": "1~10개의 쓰기를 지정하세요."
+    },
+    "debug_settle_out_of_range": {
+      "message": "settle 값은 0에서 30초 사이여야 합니다."
+    },
+    "debug_verify_after_out_of_range": {
+      "message": "verify_after 값은 0에서 60초 사이여야 합니다."
+    },
+    "service_device_target_invalid": {
+      "message": "이 서비스는 정확히 하나의 대상 기기가 필요합니다."
+    },
+    "service_device_not_found": {
+      "message": "해당 대상에 일치하는 기기를 찾을 수 없습니다."
+    },
+    "service_device_not_loaded": {
+      "message": "이 기기는 아직 연결되지 않았습니다. 로드된 후 다시 시도하세요."
     }
   }
 }

custom_components/localthings/translations/nl.json

@@ -108,6 +108,15 @@
       },
       "softener_low": {
         "name": "Wasverzachter bijna op"
+      },
+      "add_wash_available": {
+        "name": "AddWash toegestaan"
+      },
+      "add_wash_indicator": {
+        "name": "AddWash beschikbaar"
+      },
+      "stick_ble_connected": {
+        "name": "Steel via BLE verbonden"
       }
     },
     "button": {
@@ -152,11 +161,13 @@
               "smart": "Slim",
               "speed": "Snel",
               "nano": "WindFree",
+              "sleep": "Slaap",
               "nanosleep": "WindFree-slaap",
               "longwind": "Lange wind",
               "motionindirect": "Beweging indirect",
               "motiondirect": "Beweging direct",
               "drycomfort": "Droog comfort",
+              "dlightcool": "d'light Cool",
               "2step": "2-Step"
             }
           }
@@ -223,6 +234,9 @@
       "air_filter_threshold": {
         "name": "Filteralarmdrempel"
       },
+      "auto_door_timer": {
+        "name": "Timer automatische deuropener"
+      },
       "beverage_zone_mode": {
         "name": "Modus drankenzone",
         "state": {
@@ -253,7 +267,11 @@
         "name": "Zoemergeluid",
         "state": {
           "off": "Uit",
-          "on": "Aan"
+          "on": "Aan",
+          "volume_off": "Uit",
+          "volume_low": "Laag",
+          "volume_med": "Gemiddeld",
+          "volume_high": "Hoog"
         }
       },
       "discharging_time": {
@@ -295,7 +313,16 @@
           "07": "Voorspoelen",
           "8d": "Potten en pannen",
           "8e": "Kunststof",
-          "8f": "Babyverzorging"
+          "8f": "Babyverzorging",
+          "82": "Auto",
+          "8a": "Normaal",
+          "a7": "Intensief",
+          "a8": "Express",
+          "8c": "Extra stil",
+          "88": "Zelfreiniging",
+          "85": "Delicaat",
+          "0c": "Express",
+          "0d": "Zelfreiniging"
         }
       },
       "dispense_type": {
@@ -310,6 +337,35 @@
           "4": "Alarm 4"
         }
       },
+      "dryer_cycle_table_00": {
+        "name": "Programma",
+        "state": {
+          "01": "Normaal",
+          "9c": "Intensief",
+          "a5": "Beddengoed",
+          "9e": "Strijkvrij",
+          "9b": "Stoomhygiëne+",
+          "27": "Opfrissen",
+          "a0": "Luchtdrogen",
+          "a4": "Tijdprogramma",
+          "a6": "Snel drogen",
+          "a3": "Sportkleding",
+          "a2": "Fijne was",
+          "9a": "Katoen",
+          "ca": "Luchtverfrissing",
+          "db": "Super Speed",
+          "99": "Gemengde was",
+          "93": "Strijkdroog",
+          "b5": "Wol",
+          "d7": "Outdoorverzorging",
+          "96": "Koude lucht",
+          "97": "Warme lucht",
+          "7f": "Tijdprogramma",
+          "98": "Snel drogen 35",
+          "eb": "Fijne was",
+          "b6": "Synthetisch"
+        }
+      },
       "dryer_cycle_table_03": {
         "name": "Programma",
         "state": {
@@ -337,7 +393,27 @@
           "4c": "Opfrissen",
           "51": "Eco katoen",
           "53": "AI drogen+",
-          "4e": "Zelf drogen"
+          "4e": "Zelf drogen",
+          "26": "Luchtverfrissing",
+          "2a": "Hygiënische verzorging+",
+          "02": "AI drogen",
+          "03": "Super Speed",
+          "05": "Beddengoed",
+          "07": "Fijne was",
+          "09": "Overhemden",
+          "0b": "Paddingverzorging",
+          "0c": "Waterafstotende outdoorverzorging",
+          "0e": "Handdoeken",
+          "0f": "Wol",
+          "11": "Koude lucht",
+          "28": "Interne desinfectie met hete lucht",
+          "37": "Blouses",
+          "38": "Strijkdroog",
+          "39": "Ruimte ontvochtigen",
+          "3a": "Hygiënisch drogen",
+          "3b": "Beddengoed/Stof verwijderen",
+          "3c": "Sportkleding",
+          "3d": "Spijkergoed"
         }
       },
       "favorite_capacity": {
@@ -459,9 +535,11 @@
           "kimchi_storage_crunfch": "Knapperige kimchi",
           "kimchi_storage_buy": "Gekochte kimchi",
           "storage_fridge_normal": "Koelkast",
+          "storage_fridge": "Koelkast",
           "storage_fridge_cold": "Koelkast, sterk",
           "storage_fridge_warm": "Koelkast, zwak",
           "storage_freezer_normal": "Vriezer",
+          "storage_freezer": "Vriezer",
           "storage_freezer_cold": "Vriezer, sterk",
           "storage_freezer_warm": "Vriezer, zwak",
           "kimchi_ripe_low_temp": "Kimchi rijpen, lage temperatuur",
@@ -474,7 +552,8 @@
           "storage_fresh_cereal": "Granen",
           "storage_fridge_drink": "Dranken",
           "storage_fresh_wine": "Wijn",
-          "storage_fresh_potato_banana": "Aardappelen en bananen"
+          "storage_fresh_potato_banana": "Aardappelen en bananen",
+          "newmode_kimchi_0000": "Nieuwe modus"
         }
       },
       "pantry_zone_mode": {
@@ -485,6 +564,16 @@
           "fdr_drinks": "Dranken"
         }
       },
+      "winecellar_pantry_zone_mode": {
+        "name": "Modus voorraadzone",
+        "state": {
+          "processed_meat": "Vleeswaren",
+          "cheese": "Kaas",
+          "nuts": "Noten",
+          "fruit": "Fruit",
+          "wine": "Wijn"
+        }
+      },
       "range_burner_power_level": {
         "name": "Vermogensniveau brander {number}",
         "state": {
@@ -536,6 +625,9 @@
           "mute": "Stil"
         }
       },
+      "energy_saving_mode": {
+        "name": "Energiebesparingsmodus"
+      },
       "air_purifier_sound_mode": {
         "name": "Geluidsmodus",
         "state": {
@@ -572,12 +664,51 @@
           "extra_hot": "Extra heet"
         }
       },
+      "washer_cycle_table_00": {
+        "name": "Programma",
+        "state": {
+          "01": "Normaal",
+          "70": "Intensief",
+          "55": "Witte was",
+          "71": "Beddengoed",
+          "72": "Hygiëne",
+          "77": "Strijkvrij",
+          "57": "Self Clean+",
+          "73": "Spoelen + centrifugeren",
+          "74": "Sportkleding",
+          "75": "Fijne was",
+          "78": "Snelle was"
+        }
+      },
       "washer_cycle_table_02": {
         "name": "Programma",
         "state": {
           "01": "Normaal",
+          "02": "Extra intensief",
+          "03": "Super Eco",
           "04": "Snelle was",
+          "05": "Wol/Lingerie",
+          "06": "Beddengoed",
+          "07": "Outdoor",
+          "08": "Spoelen+centrifugeren",
+          "09": "Trommel reinigen",
+          "0a": "Handdoeken",
+          "0b": "Kookwas",
+          "0c": "Babyverzorging",
+          "0d": "Alleen centrifugeren",
+          "0e": "Bewolkte dag",
+          "0f": "Zuivere was",
+          "10": "Droogcentrifugeren",
+          "11": "Zomer beddengoed",
+          "12": "Katoen",
+          "13": "Zwart katoen",
+          "14": "Fijn ondergoed",
+          "15": "Sportkleding",
+          "16": "Blouses",
           "17": "Gedownload",
+          "18": "Soft Bubble",
+          "19": "AI Wash",
+          "1a": "Overhemden",
           "1b": "Katoen",
           "1c": "Eco 40-60",
           "1d": "Super Speed",
@@ -587,7 +718,7 @@
           "21": "Bonte was",
           "22": "Wol",
           "23": "Outdoor",
-          "24": "Handdoeken",
+          "24": "Beddengoed",
           "25": "Synthetisch",
           "26": "Fijne was",
           "27": "Spoelen+centrifugeren",
@@ -600,8 +731,9 @@
           "2f": "Sportkleding",
           "30": "Bewolkte dag",
           "32": "Overhemden",
-          "33": "Beddengoed",
+          "33": "Handdoeken",
           "34": "Gemengd",
+          "35": "Eco katoen",
           "36": "Wassen+drogen",
           "37": "Air Wash",
           "38": "Katoen drogen",
@@ -616,14 +748,34 @@
           "60": "Self Clean+",
           "65": "Bonte was",
           "66": "Spijkergoed",
+          "69": "AI wassen",
+          "6a": "Wol",
+          "6b": "Spijkergoed",
+          "6c": "Blouses",
+          "6d": "Fijne was",
+          "6e": "Sportkleding",
+          "6f": "Beddengoed",
+          "70": "Handdoeken",
+          "71": "Snelle was",
+          "72": "Overhemden",
+          "73": "Hygiëne",
+          "74": "Trommel reinigen",
+          "75": "Outdoor",
+          "76": "Babyverzorging",
+          "77": "Katoen",
+          "78": "Spoelen + centrifugeren",
+          "79": "Alleen centrifugeren",
           "7c": "Witte was",
           "7d": "Beddengoed/waterdicht",
           "7e": "Self Clean",
           "7f": "Wol/fijne was",
           "86": "Diep wassen",
           "87": "Gedownload",
+          "88": "Huisdierverzorging",
           "8f": "Intensief koud",
-          "96": "Minder microvezels"
+          "96": "Minder microvezels",
+          "a0": "15' Snelle was",
+          "b0": "Gemengde was"
         }
       },
       "washer_dry_level": {
@@ -663,6 +815,38 @@
       },
       "freezer_temperature_setpoint": {
         "name": "Temperatuur vriesgedeelte"
+      },
+      "edge_lighting_mode": {
+        "name": "Randverlichtingsmodus",
+        "state": {
+          "smart": "Slim",
+          "high": "Hoog",
+          "low": "Laag"
+        }
+      },
+      "edge_lighting_color": {
+        "name": "Randverlichtingskleur",
+        "state": {
+          "3000k": "3000 K",
+          "4000k": "4000 K",
+          "6500k": "6500 K"
+        }
+      },
+      "indicator_light_mode": {
+        "name": "Indicatorlampjemodus",
+        "state": {
+          "smart": "Slim",
+          "high": "Hoog",
+          "low": "Laag"
+        }
+      },
+      "ventilation_mode": {
+        "name": "Modus",
+        "state": {
+          "purification": "Zuivering",
+          "ventilation": "Ventilatie",
+          "smartventilation": "Slimme ventilatie"
+        }
       }
     },
     "sensor": {
@@ -678,6 +862,9 @@
       "air_filter_usage_hours": {
         "name": "Filterverbruik (uren)"
       },
+      "deodor_filter_usage": {
+        "name": "Filterverbruik"
+      },
       "air_quality_standard": {
         "name": "Luchtkwaliteitsnorm"
       },
@@ -751,6 +938,12 @@
       "stick_status": {
         "name": "Status steel"
       },
+      "stick_operation_mode": {
+        "name": "Bedieningsmodus steel"
+      },
+      "stick_cleaning_status": {
+        "name": "Schoonmaakstatus steel"
+      },
       "uvc_operation_time": {
         "name": "UV-C-bedrijfstijd"
       },
@@ -785,6 +978,12 @@
           "indirect": "Indirect"
         }
       },
+      "energy_saving_state": {
+        "name": "Energiebesparing status"
+      },
+      "energy_saving_operating_status": {
+        "name": "Bedrijfsstatus energiebesparing"
+      },
       "current_temp_c": {
         "name": "Temperatuur"
       },
@@ -792,10 +991,16 @@
         "name": "Temperatuur"
       },
       "diagnosis": {
-        "name": "Diagnose"
+        "name": "Diagnose",
+        "state": {
+          "ready": "Gereed"
+        }
       },
       "diagnosis_status": {
-        "name": "Diagnosestatus"
+        "name": "Diagnosestatus",
+        "state": {
+          "ready": "Gereed"
+        }
       },
       "drum_clean_cycles_remaining": {
         "name": "Trommelreiniging over"
@@ -810,7 +1015,10 @@
         "name": "Droogtijd"
       },
       "dryer_type": {
-        "name": "Type droger"
+        "name": "Type droger",
+        "state": {
+          "electricity": "Elektriciteit"
+        }
       },
       "dust": {
         "name": "Stof"
@@ -939,7 +1147,23 @@
         "name": "Sondetemperatuur"
       },
       "progress": {
-        "name": "Voortgang"
+        "name": "Voortgang",
+        "state": {
+          "idle": "Inactief",
+          "weightsensing": "Beladingsdetectie",
+          "wash": "Wassen",
+          "rinse": "Spoelen",
+          "spin": "Centrifugeren",
+          "finish": "Voltooid",
+          "steaming": "Stomen",
+          "airwashing": "Luchtreiniging",
+          "drying": "Drogen",
+          "dryingwithdooropen": "Ventileren",
+          "cooling": "Koelen",
+          "predrain": "Vooraf afpompen",
+          "prewash": "Voorwas",
+          "sanitizing": "Ontsmetten"
+        }
       },
       "progress_percentage": {
         "name": "Voortgangspercentage"
@@ -1038,6 +1262,9 @@
       "absence_power_saving_active": {
         "name": "Energiebesparing bij afwezigheid actief"
       },
+      "absence_clean": {
+        "name": "Reiniging bij afwezigheid"
+      },
       "motion_detect_wind_active": {
         "name": "Bewegingsdetectie luchtstroomvermijding actief"
       },
@@ -1071,6 +1298,12 @@
       "auto_door_opener": {
         "name": "Automatische deuropener"
       },
+      "auto_door_sound_control": {
+        "name": "Geluid automatische deuropener"
+      },
+      "auto_door_voice_control": {
+        "name": "Spraakbediening automatische deuropener"
+      },
       "auto_release_dry": {
         "name": "Auto Release Dry"
       },
@@ -1137,6 +1370,18 @@
       "intensive": {
         "name": "Intensief"
       },
+      "add_wash_alarm": {
+        "name": "AddWash-melding"
+      },
+      "add_wash_alarm_rinse": {
+        "name": "AddWash bij spoelen"
+      },
+      "add_wash_alarm_final_rinse": {
+        "name": "AddWash laatste spoeling"
+      },
+      "add_wash_alarm_spin": {
+        "name": "AddWash centrifugeren"
+      },
       "lamp": {
         "name": "Lamp"
       },
@@ -1202,6 +1447,18 @@
       },
       "ventilation_alarm": {
         "name": "Ventilatiealarm"
+      },
+      "edge_lighting": {
+        "name": "Randverlichting"
+      },
+      "indicator_light": {
+        "name": "Indicatorlampje"
+      },
+      "windfree": {
+        "name": "Wind-Free modus"
+      },
+      "windsleep": {
+        "name": "Slaapmodus"
       }
     },
     "time": {
@@ -1290,17 +1547,25 @@
         "title": "LocalThings-opties",
         "menu_options": {
           "settings": "Apparaatinstellingen",
+          "cloud_courses": "Gedownloade programma's",
+          "forget_learned_modes": "Onthouden modi vergeten",
           "debug_write": "Foutopsporing: naar een resource schrijven"
         }
       },
       "settings": {
         "title": "Apparaatinstellingen",
-        "description": "Sommige apparaten accepteren bepaalde schrijfbewerkingen (bijvoorbeeld de standaarddosering van wasmiddel of wasverzachter op een wasmachine), ook als ze melden dat de afstandsbediening is uitgeschakeld. LocalThings blokkeert standaard elke schrijfbewerking met een duidelijke foutmelding wanneer een apparaat meldt dat de afstandsbediening is uitgeschakeld, in plaats van het apparaat de opdracht stilzwijgend te laten weigeren. Schakel deze optie alleen in als je hebt bevestigd dat schrijfbewerkingen op dit apparaat echt werken wanneer de afstandsbediening is uitgeschakeld. Anders verruil je de duidelijke foutmelding voor een stille mislukking.\n\nDe geschatte eindtijd wordt bij elke poll opnieuw berekend op basis van de resterende tijd die het apparaat opgeeft, wat kan afwijken of met een minuut of wat worden bijgesteld tussen updates. Verhoog de minimale wijziging hieronder om de sensor op zijn laatst gerapporteerde waarde te houden totdat de schatting met minstens dat aantal minuten verandert, wat de ruis in geschiedenis/logboek vermindert. Zet op 0 om elke berekende wijziging te rapporteren.",
+        "description": "Sommige apparaten accepteren bepaalde schrijfbewerkingen (bijvoorbeeld de standaarddosering van wasmiddel of wasverzachter op een wasmachine), ook als ze melden dat de afstandsbediening is uitgeschakeld. LocalThings blokkeert standaard elke schrijfbewerking met een duidelijke foutmelding wanneer een apparaat meldt dat de afstandsbediening is uitgeschakeld, in plaats van het apparaat de opdracht stilzwijgend te laten weigeren. Schakel deze optie alleen in als je hebt bevestigd dat schrijfbewerkingen op dit apparaat echt werken wanneer de afstandsbediening is uitgeschakeld. Anders verruil je de duidelijke foutmelding voor een stille mislukking.\n\nDe geschatte eindtijd wordt bij elke poll opnieuw berekend op basis van de resterende tijd die het apparaat opgeeft, wat kan afwijken of met een minuut of wat worden bijgesteld tussen updates. Verhoog de minimale wijziging hieronder om de sensor op zijn laatst gerapporteerde waarde te houden totdat de schatting met minstens dat aantal minuten verandert, wat de ruis in geschiedenis/logboek vermindert. Zet op 0 om elke berekende wijziging te rapporteren.\n\nSommige modellen melden een modus die ze nooit als ondersteund opgeven: bijvoorbeeld een airco die in Quiet staat maar alleen Off/Sleep/Speed aanbiedt. LocalThings onthoudt elke zo waargenomen modus en blijft die aanbieden, zodat hij selecteerbaar blijft zodra het apparaat er minstens één keer in heeft gestaan. Schakel dit uit om alleen aan te bieden wat het apparaat opgeeft; gebruik \"Onthouden modi vergeten\" in het vorige scherm om te wissen wat al is onthouden. Een wasapparaat met uit de cloud gedownloade programma's krijgt hier een herinnering zodra het er een meldt die Home Assistant nog niet kan aanbieden -- sommige apparaten melden er een, ook als je het scherm \"Gedownloade programma's\" in de SmartThings-app zelf nooit hebt geopend. Zet dit uit om die herinnering te stoppen en al benoemde gedownloade programma's uit de programmalijst te verbergen; niets van wat al is ingesteld gaat verloren, en bij opnieuw inschakelen verschijnt het meteen weer.",
         "data": {
           "bypass_remote_control_lock": "Schrijfbewerkingen toestaan wanneer afstandsbediening als uitgeschakeld wordt gemeld",
-          "finish_time_hysteresis_minutes": "Geschatte eindtijd -- minimale wijziging (minuten)"
+          "finish_time_hysteresis_minutes": "Geschatte eindtijd -- minimale wijziging (minuten)",
+          "learn_device_modes": "Modi onthouden die het apparaat meldt maar niet als ondersteund opgeeft",
+          "cloud_courses_enabled": "Gedownloade programma's aanbieden"
         }
       },
+      "forget_learned_modes": {
+        "title": "Onthouden modi vergeten",
+        "description": "Nu onthouden: {codes}\n\nDit zijn modi waarin dit apparaat zichzelf meldde zonder ze als ondersteund op te geven; ze worden bewaard zodat ze selecteerbaar blijven. Vergeten is de oplossing als er een onterecht tussen staat: alles wat het apparaat echt opnieuw meldt, wordt gewoon opnieuw onthouden, tenzij je ook \"Modi onthouden die het apparaat meldt maar niet als ondersteund opgeeft\" bij Apparaatinstellingen uitzet."
+      },
       "debug_write": {
         "title": "Foutopsporing: naar een resource schrijven",
         "description": "Geavanceerd hulpmiddel om apparaatspecifiek schrijfgedrag te onderzoeken. Kies de resource (href) waarnaar je wilt schrijven, of voer een aangepaste resource in die niet in de lijst staat. Hiermee wordt de blokkering bij een uitgeschakelde afstandsbediening omzeild en worden precies de opgegeven velden verzonden. Dit kan de configuratie van je apparaat verstoren, dus gebruik het bewust.",
@@ -1322,20 +1587,63 @@
           "debug_write": "Naar een andere resource schrijven",
           "finish": "Voltooien"
         }
+      },
+      "cloud_manual": {
+        "title": "Gedownloade programma's",
+        "description": "Dit apparaat meldt {total} gedownloade programma's; {found} daarvan zijn tot nu toe gezien.\n\nDe instellingen van een gedownload programma zijn alleen zichtbaar zolang dat programma geladen is, en het apparaat meldt nooit de naam ervan. Om de ontbrekende ({pending}) toe te voegen: open in de SmartThings-app (niet op het apparaat zelf) dit apparaat en tik op \"Gedownloade programma's\" -- een aparte regel, los van \"Programma\", verderop op het scherm, en degene die hier telt. Doorloop dan elk gedownload programma na elkaar, pauzeer bij elk een paar seconden zodat LocalThings het kan zien, en kom hierna terug.\n\nGeef elk programma de naam die je in Home Assistant wilt zien. Laat een naam leeg om dat programma buiten de programmalijst te houden. Namen moeten uniek zijn.\n\nHet programma \"Gedownload\" is het programma op dit apparaat dat een gedownload programma uitvoert. Het wordt automatisch gedetecteerd, maar bevestig dit hier voor gebruik: als je een gedownload programma selecteert, wordt deze programmacode naar het apparaat geschreven.",
+        "data": {
+          "download_course": "Programmacode van \"Gedownload\""
+        }
+      },
+      "cloud_courses": {
+        "title": "Gedownloade programma's",
+        "description": "Begeleide installatie loodst je stap voor stap: open in de SmartThings-app (niet op het apparaat zelf) dit apparaat en tik op \"Gedownloade programma's\" -- een aparte regel, los van \"Programma\", verderop op het scherm, en degene die hier telt. Kies daar een programma, kom terug en geef het een naam zodra het gevonden is, één voor één.\n\nNamen bewerken toont in één keer alles wat tot nu toe is gevonden — gebruik dit later om iets te hernoemen of te corrigeren. Namen geven werkt sowieso, maar een benoemd programma wordt alleen als selecteerbaar programma aangeboden zolang \"Gedownloade programma's aanbieden\" aan staat in de apparaatinstellingen.",
+        "menu_options": {
+          "cloud_guided": "Begeleide installatie",
+          "cloud_manual": "Namen bewerken"
+        }
+      },
+      "cloud_wait": {
+        "title": "Gedownloade programma's"
+      },
+      "cloud_name": {
+        "title": "Geef dit programma een naam",
+        "description": "Het vak \"Gedownloade programma's\" van het apparaat bevat nu een nieuw programma (slot {slot}) en meldt nog {remaining} resterend.\n\nGeef het de naam die je in Home Assistant wilt zien en kies daarna in het scherm \"Gedownloade programma's\" van de SmartThings-app het volgende programma dat nog niet als \"Gedownload\" is gemarkeerd. Laat het veld leeg om dit programma buiten de lijst te houden.\n\nTot nu toe benoemd ({named} van {total}): {named_list}\n\nNamen moeten uniek zijn. Je kunt dit venster op elk moment sluiten — namen worden onderweg opgeslagen.",
+        "data": {
+          "name": "Naam",
+          "download_course": "Programmacode van \"Gedownload\""
+        }
+      },
+      "cloud_timeout": {
+        "title": "Geen programma geselecteerd",
+        "description": "Er is niets veranderd op het apparaat. Zorg dat je in de SmartThings-app op \"Gedownloade programma's\" hebt getikt -- een aparte regel, los van \"Programma\", verderop op het scherm -- en een programma hebt gekozen dat nog niet als \"Gedownload\" was gemarkeerd, en daarna op Klaar hebt getikt.\n\nTot nu toe benoemd ({named} van {total}): {named_list}\n\nAlles wat tot nu toe benoemd is, is al opgeslagen.",
+        "menu_options": {
+          "cloud_guided": "Opnieuw wachten",
+          "cloud_finish": "Voltooien"
+        }
       }
     },
     "error": {
       "empty_payload": "Voer ten minste één veld in om te schrijven.",
-      "write_failed": "De schrijfbewerking is mislukt. Raadpleeg de Home Assistant-logboeken voor meer informatie."
+      "write_failed": "De schrijfbewerking is mislukt. Raadpleeg de Home Assistant-logboeken voor meer informatie.",
+      "cloud_course_name_duplicate": "Twee programma's hebben dezelfde naam. Namen moeten uniek zijn.",
+      "cloud_course_unknown_course": "Dat programma biedt dit apparaat niet aan. Kies er een uit de lijst."
     },
     "abort": {
       "not_loaded": "Dit apparaat is nog niet verbonden. Probeer het opnieuw zodra het is geladen."
+    },
+    "progress": {
+      "cloud_wait": "Open in de SmartThings-app (niet op het apparaat zelf) dit apparaat en tik op \"Gedownloade programma's\" -- een aparte regel, los van \"Programma\", verderop op het scherm, die alleen de programma's toont die op deze manier te herkennen zijn. Kies er een die nog niet als \"Gedownload\" is gemarkeerd en tik op Klaar.\n\nHet apparaat hoeft niet in de buurt te zijn of het programma uit te voeren -- het moet alleen aan staan en verbonden zijn.\n\nTot nu toe benoemd ({named} van {total}): {named_list}\n\nJe kunt dit venster op elk moment sluiten — namen worden onderweg opgeslagen."
     }
   },
   "issues": {
     "device_gap": {
       "title": "Onvolledige ondersteuning van mogelijkheden voor {device_name}",
       "description": "Niet alle mogelijkheden van dit apparaat worden ondersteund. Het apparaattype is niet herkend of sommige beschikbare resources zijn nog niet gemodelleerd. Het apparaat blijft werken met de mogelijkheden die al worden ondersteund. Je kunt helpen de ondersteuning uit te breiden: ga naar Instellingen > Apparaten & diensten > {device_name} > het menu (rechtsboven) > Diagnostische gegevens downloaden en voeg het bestand daarna bij via de gekoppelde issue-template."
+    },
+    "cloud_courses_undiscovered": {
+      "title": "Gedownloade programma's niet ingesteld voor {device_name}",
+      "description": "{device_name} heeft {pending} van de {total} gedownloade programma's die Home Assistant nog niet kan aanbieden. Een gedownload programma kan pas worden gebruikt zodra het apparaat ermee geladen is gezien -- in het scherm \"Gedownloade programma's\" van de SmartThings-app, niet in \"Programma\" -- en je het een naam hebt gegeven.\n\nGa om ze in te stellen naar Instellingen > Apparaten & diensten > LocalThings > {device_name} > Configureren > Gedownloade programma's en volg de instructies daar.\n\nGebruik je geen gedownloade programma's? Ga dan naar Configureren > Apparaatinstellingen en zet \"Gedownloade programma's aanbieden\" uit om deze herinnering voorgoed te stoppen."
     }
   },
   "exceptions": {
@@ -1356,6 +1664,30 @@
     },
     "intensive_unavailable_for_cycle": {
       "message": "Intensief is niet beschikbaar voor het geselecteerde programma."
+    },
+    "command_failed": {
+      "message": "Het commando naar {href} is ook na opnieuw verbinden mislukt: {error}"
+    },
+    "debug_read_failed": {
+      "message": "Het lezen van {href} is mislukt: {error}"
+    },
+    "debug_too_many_writes": {
+      "message": "Geef tussen de 1 en 10 schrijfacties op."
+    },
+    "debug_settle_out_of_range": {
+      "message": "settle moet tussen 0 en 30 seconden liggen."
+    },
+    "debug_verify_after_out_of_range": {
+      "message": "verify_after moet tussen 0 en 60 seconden liggen."
+    },
+    "service_device_target_invalid": {
+      "message": "Deze service vereist precies één doelapparaat."
+    },
+    "service_device_not_found": {
+      "message": "Er is geen bijpassend apparaat gevonden voor dat doel."
+    },
+    "service_device_not_loaded": {
+      "message": "Dit apparaat is nog niet verbonden. Probeer het opnieuw zodra het is geladen."
     }
   }
 }

docs/investigations/ac-filter-reset.md

@@ -15,6 +15,12 @@ that follows them explains why the reset looked cloud-only for as long as it
 did — a genuine trap worth knowing about before the next reset-adjacent
 mystery on this board family.
 
+Scope: all of the above applies to boards that carry the counter as a
+`FilterTime_<N>` option token on `/mode/vs/0`. Not every AC does. See
+"Boards with no `FilterTime` token" at the end for an `ARTIK051_PRAC_20K`
+that keeps the counter in its own resource, rejects both the token and a
+direct write, and has no local reset at all.
+
 ## What the reset actually is
 
 A **command**, not a value write. Samsung's cloud models it as capability
@@ -92,3 +98,72 @@ on every unit on record).
 The entity key stays `filter_time` rather than `filter_time_elapsed`:
 renaming it would change every existing unit's `entity_id`/`unique_id` for a
 wording improvement only.
+
+## Boards with no `FilterTime` token (`ARTIK051_PRAC_20K`)
+
+Negative result, measured 2026-08-11 on integration v0.21.0 / HA 2026.8.1,
+against one head of a three-head multi-split (`OptionCode_35880`,
+`ExtendOptionCode_199181`). **There is no local reset on this board**, by
+either route. Reset appears to be panel-only.
+
+This generation does not put the counter in `/mode/vs/0` at all. Its
+options blob carries no `FilterTime`, no `FilterAlarmTime` and no
+`FilterCleanAlarm`:
+
+```json
+["Sleep_0", "ArtificialWorking_Off", "ComfortAICooling_Off",
+ "AiTempChanged_Off", "AiTemp_240", "OutdoorTemp_77", "CoolCapa_25",
+ "WarmCapa_32", "Light_Off", "Volume_100", "OptionCode_35880",
+ "ExtendOptionCode_199181", "RacInfo_None", "UpdateAllow_NotAllowed",
+ "DurationOn_0", "WelcomeCoolingState_Off"]
+```
+
+The counter lives in its own resource instead, as a **percentage** of a
+500-hour interval rather than tenths of an hour —
+`/filter/airdustfilter/vs/0`:
+
+```json
+{
+  "x.com.samsung.da.filterUsage": "96",
+  "x.com.samsung.da.filterUsageResolution": "1",
+  "x.com.samsung.da.filterDesiredUsage": "500",
+  "x.com.samsung.da.filterStatus": "normal",
+  "x.com.samsung.da.filterCapacity": "500",
+  "x.com.samsung.da.filterCapacityUnit": "Hour",
+  "x.com.samsung.da.filterResetType": ["replaceable", "washable"]
+}
+```
+
+Three attempts, all against a live unit deliberately put in `fan_only`
+first — writes to a powered-off head on this board are dropped silently
+with no error, which would otherwise be indistinguishable from a rejected
+write:
+
+| Target | Payload | Result |
+|---|---|---|
+| `/mode/vs/0` | `{"x.com.samsung.da.options": ["FilterCleanAlarm_Clear"]}` | 4.00, options blob byte-identical |
+| `/filter/airdustfilter/vs/0` | `{"x.com.samsung.da.filterUsage": "0"}` | 4.00 |
+| `/filter/airdustfilter/vs/0` | `{"x.com.samsung.da.filterUsage": 0}` (integer) | 5.00 |
+
+`filterUsage` stayed at `96` throughout, verified by a live re-read after
+each write rather than by the integration's optimistic state.
+
+The last two rows are the informative pair. They differ only in JSON type
+and return *different* codes, which rules out both boring explanations: an
+unresolved href or an unrecognised field name would fail identically. The
+board parses the field, faults on the wrong type, and still refuses the
+value when typed as the string its own rep uses. The resource is
+**read-only**, not mis-addressed.
+
+One trap worth stating plainly: `filterResetType:
+["replaceable","washable"]` describes what the filter *is*, not a reset
+command that exists. It reads like a hint that a reset write is available
+somewhere. It is not.
+
+Since the integration cannot perform the reset here, it can still observe
+it. The counter only climbs in normal use, so a downward crossing is
+unambiguous: a `numeric_state` trigger with `below: 10` on
+`sensor.<name>_filter_usage`, stamping an `input_datetime`, keeps an
+honest "last cleaned" date without pretending a reset entity exists. The
+blind spot is a reset performed while HA is down or the entry is
+unloaded — no state transition, so that stamp has to be set by hand.

docs/investigations/composite-subdevice-hrefs.md

@@ -0,0 +1,184 @@
+# Composite AC subdevices: where else a sibling's hrefs could live
+
+Open question behind issue #335 (`ARTIK051_FAC_BORA_19K`, a 2-in-1 floor +
+wall AC): the board reports a sibling in `/subdevices/vs/0`'s
+`subdeviceIdList`, but every seed `registry/subdevices.enumerate_subdevices`
+tries comes back 4.04, so `subdevices` and `subdevices_skipped` are both
+empty and the wall unit never becomes an entity.
+
+This file records what that actually rules out (less than it looks like),
+why, and which hrefs are worth reading next.
+
+## `/oic/res` does not enumerate the resource tree on modern firmware
+
+This is the finding that reopens the question. Across every fixture that
+carries a captured `/oic/res`:
+
+| board | links | `sec:true` | lists `/device/0`? |
+| --- | --- | --- | --- |
+| `ARTIK051_DONGLE_FAC_18K` | 91 | 78 | yes |
+| `TP2X_FAC_BORA_21K` (2-in-1) | 17 | 6 | no |
+| `TP2X_FAC_BORA_21K` (#205 flat) | 17 | 6 | no |
+| `TP1X_DA_KS_RANGE_0101X` | 10 | 6 | no |
+| `AWM-WW-AID-26-ONEBODY` | 15 | 9 | no |
+| `ARTIK051_FAC_BORA_19K` (#335) | 18 | 6 | no |
+
+The `ARTIK051_DONGLE_FAC_18K` board — the one Pattern A was built against —
+is the outlier, not the model. Everywhere else `/oic/res` lists the
+onboarding surface and nothing else: `/oic/d`, `/oic/p`, the security and
+EasySetup/WiFiConf/CoapCloudConf/DevConf resources, file transfer, and the
+`sec/*` pair. On issue #335's board the six `sec:true` links are exactly
+doxm, pstat and the four setup URIs; every other listed link is `sec:false`.
+The entire secure operational tree — `/device/0` included, which
+demonstrably answers, since the dump comes from it — is absent.
+
+Two consequences, both load-bearing:
+
+1. **Nothing is learned from an href's absence in `/oic/res`.** On the range
+   board (issue #324) `/oic/res` lists ten onboarding links and no
+   `/device/0`, yet `/device/1` answers a full indexed dual-cavity sibling.
+   It was found only by `_SPECULATIVE_DEVICE_INDICES`, never by enumeration
+   of the links.
+2. **Pattern A's `/oic/res` index scan is dead weight on these boards.** It
+   contributes nothing anywhere except the dongle board, so in practice
+   indexed siblings are found by the speculative `/device/1`, `/device/2`
+   probe alone.
+
+## What issue #335 has actually ruled out
+
+All 26 probes in the report returned false. Twenty-three of them are the
+issue #205 flat fallback walking the master's own href list under the
+sibling's UUID prefix, plus `/<uuid>/device/0`, `/device/1`, `/device/2`
+and `/multidevice/vs/0`. Four more were read by hand from the issue thread
+(`/<uuid>/information/vs/{1,2}`, `/<uuid>/device/{1,2}`), all 4.04.
+
+So what is ruled out is: the UUID-prefixed namespace (Pattern B/C), and the
+indexed **Collection** (`/device/<n>`). What has never been read on this
+board — or on any `FAC_BORA` board — is **a bare indexed leaf**:
+`/mode/vs/1`, `/temperatures/vs/1`, and friends. Every indexed href ever
+probed by this project arrived via a `/device/<n>` batch; none was ever
+GETed directly.
+
+That gap matters because the "leaves exist, their Collection does not" shape
+is already confirmed on this exact product family, just in the other
+namespace: issue #205's `TP2X_FAC_BORA_21K` answers
+`/<uuid>/information/vs/0` while `/<uuid>/device/0` comes back empty. A
+board that mounts sibling leaves without mounting a sibling Collection is
+the documented BORA behavior, so `/device/1`'s 4.04 is evidence about the
+Collection and not about `/mode/vs/1`.
+
+## What the OCF spec says about composite devices
+
+The Core/Device specifications model this as a *Composite Device*: one
+Platform representing the whole appliance, `/oic/d` carrying the Device
+Types of every constituent Device, and — the relevant part — a **Collection
+per distinct Device in the composition**, each Collection's `rt` including
+the Device Type it represents.
+
+Issue #335's `/oic/d` reports `["oic.wk.d", "oic.d.airconditioner"]`, which
+is consistent with a two-indoor-unit composite (both constituents are air
+conditioners, so the type appears once) and equally consistent with a single
+unit. It does not discriminate.
+
+The Collection half does suggest something untried. `x.com.samsung.devcol`
+is Samsung's Collection type, carried by `/device/0` — and on the dongle
+board `/oic/res` advertises a second resource with the same
+`["x.com.samsung.devcol", "oic.wk.col"]` pair: **`/sec/devices`**. A
+collection of devices, sitting alongside `/device/0`, never read by this
+project or by any issue thread. If the composite enumeration is exposed
+anywhere as a first-class resource, that is the shape it would take.
+
+## Results of the second probe round
+
+The reporter ran these live. Three answers, all informative.
+
+**Indexed leaves do not exist.** `/information/vs/1`, `/power/vs/1`,
+`/mode/vs/1` → 4.04. Pattern A is ruled out on this board properly now:
+not just the `/device/1` Collection, but the leaf namespace it would have
+carried.
+
+**The UUID prefix routes, and is empty of operational resources.** The
+control pair settles it:
+
+    /c24e25e9-.../file/list/vs/0  → 2.05, two items
+    /file/list/vs/0              → 2.05, the same two items
+    (/opt/data/energy.db, /opt/data/hass.db)
+
+So the sibling's prefix is a live, routed namespace — the 23 flat-fallback
+4.04s under it are the firmware answering "no such resource", not a dead
+prefix swallowing everything. Pattern B/C is ruled out on this board on
+positive evidence rather than on absence. That the two listings are
+identical is expected either way: one board, one flash, one filesystem.
+
+**`/sec/devices` exists — and this project could not see what's in it.**
+It answered `2.05` with `rep: {}`, which reads as "the resource is there and
+has nothing in it". It is not. `coordinator._raw_read_blocking` decoded the
+CBOR body and then kept it *only if it was a Property map*:
+
+```python
+if isinstance(body, dict):
+    rep = body
+```
+
+A Collection answers a **list** — the `[devcol rep, {href, rep}, ...]` batch
+`parse_device0_batch` reads. `/device/0` itself would have rendered exactly
+the same accepted-but-empty `2.05 {}` through `read_resource`. Fixed: the
+read path now returns the decoded body alongside `rep`, and the service
+response carries it as `body` whenever it isn't the map already in `rep`.
+
+`/sec/devices` therefore remains the one open lead, and needs one re-read on
+a build carrying that fix.
+
+## Still worth reading
+
+**1 — `/sec/devices`, again.** Same `x.com.samsung.devcol` + `oic.wk.col`
+pair as `/device/0`, so its body should be a batch naming its members. If a
+composite enumeration is exposed anywhere, it is here.
+
+**2 — the file-transfer pair.** `/oic/res` advertises
+`/c24e25e9-.../file/transfer/vs/0` alongside the master's, and the prefix is
+now known to route. Issue #301 documents the shape: a baseline GET returns
+one item, `x.com.samsung.name` plus `x.com.samsung.blob`, no write needed to
+see whatever it currently serves. If the prefixed endpoint serves *different
+bytes* than the master's, that is the first hard local evidence the wall
+unit exists as a data producer, and `/opt/data/energy.db` would be where its
+runtime history lives.
+
+    /file/transfer/vs/0
+    /c24e25e9-55dd-ba18-d567-000000000001/file/transfer/vs/0
+
+Mind the blob: #301 measured 2172 B on a `KRAC_18K`, and a raw `bytes` value
+in a service response is not guaranteed to survive rendering in Developer
+Tools. Ask for `x.com.samsung.name` and whether a blob field appears, not
+for the blob pasted into a comment.
+
+## Dead ends, so they aren't re-tried
+
+- `/hass/state/vs/0`, `/hass/command/vs/0` — advertised in `/oic/res` on
+  every board here, and indexed per subdevice on the dongle board
+  (`/hass/state/vs/{0,1,2}`), which makes them look like a subdevice-aware
+  state channel. They are not: 4.04 on every interface on
+  `ARTIK051_KRAC_18K` (see `ac-filter-reset.md`). Cheap enough to retry once
+  on #335's newer build, but expect nothing.
+- `/multidevice/vs/0` — probed, 4.04. Absent on this board; only the dongle
+  family exposes it.
+- `/actions/vs/0` — GET returns `{}` on baseline and `oic.if.a`; publishes
+  no schema (`ac-filter-reset.md`).
+
+## Where this lands if `/sec/devices` is empty too
+
+Then the sibling is named in `subdeviceIdList` for the cloud's benefit and
+has no local operational surface at all on this firmware — every namespace
+it could occupy has now been read directly, and the UUID one was confirmed
+routable first, so the negatives mean what they say. That closes issue #335
+as a firmware limitation rather than leaving it open against a probe
+strategy that was never actually exercised.
+
+Worth keeping in view for the enumeration code either way: both remaining
+patterns hinge on a Collection, and this board answers neither `/device/1`
+nor a prefixed `/device/0`. An indexed flat-probe fallback — the mirror of
+issue #205's prefixed one, gated on a board that claims a sibling but
+materialized nothing — would have cost 8 round trips here and returned the
+same 4.04s the reporter got by hand. It is worth building only if some
+other board turns out to serve indexed leaves without their Collection;
+this one does not.

docs/investigations/download-cycle.md

@@ -0,0 +1,279 @@
+# Laundry cloud "Download" cycles: solved, with one dead end
+
+`registry/capabilities/laundry.py`'s cycle select offers a washer's
+downloaded ("Download" / "Downloaded") programs alongside its ordinary
+courses now, driven by the store in `cloudcourse.py` (issue #342). This file
+records the byte-level work behind it, including a decode that fit one
+device perfectly and collapsed on the second — the reason nothing in the
+shipped code interprets a program payload at all.
+
+Four devices in the corpus carry these tokens (a survey of every laundry
+diagnostics dump attached to an issue turned up 14 devices; the other 10 have
+no cloud tokens at all, so this is a minority feature):
+
+| dump | model | slots advertised | payloads seen | blob width |
+| --- | --- | --- | --- | --- |
+| `washer_ww5000c_cloud` | WW5000C `_B06C`, `DA_WM_TP1_21_COMMON`, Table_02 | 9 | 2 | 20 bytes |
+| `washer_wa55a7700av` | WA55A7700AV, `DA_WM_TP1_21_COMMON`, Table_02 | 2 | 1 | 16 bytes |
+| `dishwasher_dw5000c_cloud` | DW5000C, `DA_DW_TP1_21_COMMON` | 4 (but see below) | **0** | — |
+| (not fixtured) | WW5000C `_B048`, issues #259/#343, Table_02 | 9 | 1 | 20 bytes |
+
+Three things follow immediately from that table:
+
+- **`CloudExtraCourse_` does not mean the same thing on every family.** On
+  the DW5000C all four of its bytes (`8E 8D 8F 02`) are course codes in that
+  dishwasher's *own* course list, three already translated (Plastic, Pots and
+  pans, Baby Care). There it tags which ordinary courses came from the cloud;
+  they select with a plain `Course_` write and need no payload — consistent
+  with it carrying no payload token at all. It also has a
+  `DownloadCourseList_8F` token the washers lack.
+  On both washers the slots share **zero** overlap with the course list and a
+  payload is required. Subtracting the course list is what tells the two
+  apart (`cloudcourse.cloud_slots`), so the feature engages on the washers
+  and correctly does nothing on the dishwasher.
+- **A device can advertise a slot it has never loaded.** True on the washers
+  too — nothing about a program is learnable until its owner runs it, which
+  is what the Repairs issue exists to explain.
+- **Both WW5000C units advertise the byte-identical slot list**
+  (`0A5C286B2D0C55301A`, same nine slots in the same order) despite different
+  firmware builds. Either the set is a factory/regional default rather than
+  something each owner curates, or the two dumps share an owner — unresolved,
+  but worth knowing before assuming a user picked their own programs.
+
+## The three tokens
+
+All on `/course/vs/0`'s `x.com.samsung.da.options` array, same
+prefix-match/replace merge as every other token there.
+
+- `CloudExtraCourse_<slot><slot>…` — the device's own list of downloaded
+  program slots, one byte each. The cloud counterpart of `EditCourseList_`.
+- `CloudCourse_<blob>` — the persisted default program.
+- `OneTimeCloudCourse_<blob>` — a this-run-only override.
+
+### `CloudExtraCourse_` is an enumeration, and byte 2 of a blob is its slot
+
+The WW5000C reports `CloudExtraCourse_0A5C286B2D0C55301A` — nine bytes for
+its nine downloaded programs. Byte 2 of each of the nine blobs its owner
+captured is exactly one of those nine, no repeats, sets equal:
+
+```
+        blob                                       byte2  program
+        00 21 55 04 49 28 4D 13 4A A0 4C 00 …       55    Sports
+        00 20 28 04 49 00 4D 00 4A B8 4C 00 …       28    Spin only
+        00 02 5C 04 49 28 4D 13 4A B0 4C 00 …       5C    Outdoor
+        00 1F 6B 04 49 28 4D 13 4A A0 4C 00 …       6B    Jeans
+        00 2E 2D 04 49 30 4D 12 4A A0 4C 00 …       2D    Super quiet
+        00 2F 0C 04 49 58 4D 14 4A B8 4C 00 …       0C    Baby care intensive
+        00 0D 30 04 49 30 4D 12 4A B8 4C 00 …       30    Cloudy heaven
+        00 30 1A 04 49 28 4D 12 4A A0 4C 00 …       1A    Shirts
+        00 04 0A 04 49 40 4D 13 4A B8 4C 00 …       0A    Towels
+
+CloudExtraCourse_  0A 5C 28 6B 2D 0C 55 30 1A
+```
+
+Confirmed independently on the WA55A7700AV: `CloudExtraCourse_5958`, and its
+`CloudCourse` blob `00 1C 59 05 …` has byte 2 = `59`. Its
+`OneTimeCloudCourse` is `FF FF 01 …` — byte 2 = `01`, which is *not* an
+advertised slot, and the `FFFF` prefix marks it as "nothing loaded" rather
+than naming a program. That sentinel is why `cloudcourse.is_loaded` exists.
+
+This is what makes "3 of 9 discovered" answerable, and it is why no catalog
+of program ids is hardcoded anywhere: the appliance already knows which
+programs it has.
+
+## Writing: the two-token rule
+
+Confirmed on hardware by the issue #342 reporter. Writing
+`OneTimeCloudCourse_<blob>` alone while some other course is selected is
+accepted at the protocol level (no error) and then silently ignored by the
+machine. It takes effect only when the same write also switches `Course_` to
+the Download course — which is what `laundry._cloud_cycle_write` does, and
+the only two-token options write in the codebase:
+
+```yaml
+x.com.samsung.da.options:
+  - Course_87
+  - OneTimeCloudCourse_001F6B0449284D134AA04C0035F004F005F0AC00
+```
+
+`CloudCourse_` was separately confirmed writable on its own: set while on
+Download it changes the running program; set from another course it becomes
+what gets preselected the next time Download is chosen. The integration
+doesn't write it today — a "default download cycle" control is a possible
+follow-up, deliberately left out of the first pass.
+
+### There is no single "Download" course code
+
+The WW5000C's Download is `Course_87`; the WA55A7700AV's is `17`
+("Downloaded" in `washer_cycle_table_02`). **Same course table, different
+code.** Any per-table lookup of "the Download code" would have been wrong on
+one of the only two devices available to check it against, which is why the
+code is learned by observation and confirmed by the user in the options flow
+instead of tabled.
+
+The observation signal is "whatever `Course_` reads at the moment a
+non-sentinel `OneTimeCloudCourse_` *appears or changes*" — a transition that
+was actually watched, not a state. Tokens in this array are replaced by
+prefix and never evicted, so a payload merely sitting there says nothing
+about when it got there; on the first rep after a restart it is equally
+consistent with "just loaded" and "left over from last week". Believing it
+would propose whatever ordinary course the appliance happens to be sitting
+on, and accepting that prefill starts a real wash cycle. Even a genuine
+transition is only ever a *candidate*, confirmed by the user before use.
+
+Both dumps in the corpus taken while off the Download course
+(`washer_wa55a7700av` on `Course_01`, the `_B048` washer on `Course_1C`)
+show the appliance clearing its one-time token to the `FFFF` sentinel, so
+the saved default persists but the one-shot does not. That makes the stale
+case unlikely on these boards — which is a reason to expect it to behave,
+not a reason to depend on it.
+
+## The dead end: bytes 5/7/9 do not decode portably
+
+With the nine WW5000C programs and their app-reported settings side by side,
+three of the varying bytes fit perfectly:
+
+| byte | meaning | formula | fit |
+| --- | --- | --- | --- |
+| 5 | wash temperature | `(b - 0x10) / 0.8` °C, `0x00` = n/a | 9/9 |
+| 7 | rinse count | `b - 0x10`, `0x00` = off | 9/9 |
+| 9 | spin level | `(b - 0x90) / 8` | 9/9 |
+
+Nine for nine, including the internally consistent case: "Spin only" is the
+only program with `0x00` in *both* byte 5 and byte 7, matching a cycle that
+skips washing entirely while still reporting a spin level.
+
+It does not survive the second device. Against the WA55A7700AV's
+`CloudCourse` blob `00 1C 59 05 49 16 4D 11 4A 22 4C 20 37 F0 AC 22`:
+
+- temperature: `(0x16 - 0x10) / 0.8` = **7.5 °C**
+- spin: `(0x22 - 0x90) / 8` = **negative**
+- rinse: `0x11 - 0x10` = 1 — the only plausible one
+
+### What *does* survive is the grammar
+
+The two boards' payloads are different lengths (20 vs 16 bytes) but not a
+different format — same header, same leading fields, two fewer optional
+trailing ones:
+
+```
+WW5000C  00 | 2155 | 04 | 49:28  4D:13  4A:A0  4C:00 | 35:F0  04:F0  05:F0 | AC:00
+WA55     00 | 1C59 | 05 | 49:16  4D:11  4A:22  4C:20 | 37:F0               | AC:22
+```
+
+- `00`, then the 2-byte program id, then one byte (`04` vs `05`) — identical
+  layout on both.
+- Then a tag/value stream whose **first four tags are the same, in the same
+  order, at the same offsets**: `49`, `4D`, `4A`, `4C`. These are exactly the
+  four whose values vary per program.
+- Then a fixed tail, terminated on both by an `AC:<value>` pair. The entire
+  width difference is two trailing pairs the WA55 doesn't carry.
+
+The tail is not program data. Across all nine WW5000C programs bytes 12–19
+are byte-identical — every trailing pair carries value `F0` except the `AC`
+terminator, and `35` vs `37` looks like a board or profile marker rather than
+a field. (It is not a field count either: the board with the *higher* leading
+byte has *fewer* pairs.)
+
+### Byte 3 is not part of a program's identity
+
+Worth its own heading, because it is the single strongest argument against
+ever shipping a table of payloads. The second WW5000C (issues #259/#343,
+firmware `_B048`) has its saved `CloudCourse` set to the same program as the
+first one's "Towels" capture — and the two payloads differ at exactly one
+byte:
+
+```
+_B06C  "Towels"      00 04 0A 04 49 40 4D 13 4A B8 4C 00 35 F0 04 F0 05 F0 AC 00
+_B048  CloudCourse   00 04 0A 06 49 40 4D 13 4A B8 4C 00 35 F0 04 F0 05 F0 AC 00
+                              ^^
+```
+
+Same program id, same slot, same values on all four varying tags, same tail.
+Only byte 3 moves, `04` → `06`. So it is neither a per-board constant (both
+are WW5000C) nor a property of the program (identical in every other
+respect) — most likely a download revision or sequence counter.
+
+A hardcoded catalog keyed on program id would therefore have shipped one
+unit's byte 3 to the other unit. Whether the appliance would reject that, or
+accept it and do something unintended, is untested and does not need to be:
+every payload is learned from the device it will be replayed to.
+
+### Sentinels
+
+The `FFFF` "nothing loaded" payload takes its board's own width (16 bytes on
+the WA55, 20 on the WW5000C `_B048`) and always carries byte 3 = `00`. Its
+byte 2 is *not* reliably meaningful: it equals the currently selected course
+on the WA55 (`01`, on `Course_01`) and does not on the `_B048` (`1B`, on
+`Course_1C`). Nothing keys off it — a sentinel is rejected on its `FFFF`
+prefix, and its byte 2 is not an advertised slot in either dump anyway.
+
+So the payload is tag/value, not fixed offsets — but knowing the grammar
+doesn't recover the values. The same four tags carry non-overlapping ranges
+between the two boards:
+
+| tag | WW5000C (9 programs) | WA55 |
+| --- | --- | --- |
+| `49` | `00, 28, 30, 40, 58` | `16` |
+| `4D` | `00, 12, 13, 14` | `11` |
+| `4A` | `A0, B0, B8` | `22` |
+| `4C` | `00` (all nine) | `20` |
+
+Same field, board-specific encoding. Decoding it properly needs a third
+device; one device's fit is a coincidence-shaped hypothesis, not a format.
+
+**A trap for whoever picks this up:** the WA55's `/washer/vs/0` reads
+Warm / High / 1, which looks like it could confirm a decode of that unit's
+`CloudCourse`. It can't — that appliance is sitting on `Course_01` (Normal),
+not on its cloud course, so those values describe the local cycle it has
+selected, not the saved cloud program. A cross-check like this is only
+evidence when the machine is actually loaded with the program being decoded.
+
+So the shipped code never interprets a payload: a blob is recorded whole and
+replayed byte-for-byte, exactly as the device reported it, and never
+decomposed or rebuilt. The read-only "loaded program's temperature/spin"
+sensors this decode would have enabled were dropped for the same reason.
+
+## What is deliberately not done
+
+- **No hardcoded program catalog.** Blobs are cloud-assigned per
+  account/region. One owner's captured payload is not evidence about anyone
+  else's appliance, and a table of them would offer options that write
+  another household's wash settings.
+- **No invented names.** The appliance reports an opaque slot id and nothing
+  else. Names come from the user in the options flow, the same rule that
+  stops an unrecognized local course code from getting a made-up English
+  label (PR #251 review).
+- **No blob synthesis.** Even with the byte 5/7/9 decode in hand, nothing
+  builds a payload from parts — the device was never tested with one, and a
+  fabricated blob is an untested write to a wash cycle.
+
+## Open questions for the next dump
+
+1. Does `OneTimeCloudCourse_` clear itself when a cycle finishes, or when the
+   course changes? Behavior suggests the appliance falls back to
+   `CloudCourse_` when Download is re-entered, but the token's own lifecycle
+   is unconfirmed. `laundry.cloud_current` is written to be correct either
+   way.
+2. What does byte 1 mean? It is distinct per program and *sometimes*
+   coincides with a plausible local course code for that program (`2E` Baby
+   Care for "Baby care intensive", `30` Cloudy Day for "Cloudy heaven") and
+   sometimes doesn't (`21` Colors for "Sports"). Probably a base-course
+   reference; not reliable enough to use.
+3. What does byte 3 count? It moves between two units holding the identical
+   program (`04` vs `06`) and is `00` on every sentinel. A revision or
+   download counter is the obvious guess; a dump taken before and after
+   re-downloading the same program would confirm it.
+4. **The value encoding is still open, and a third *washer* won't
+   necessarily settle it.** The survey found one, but its saved program is a
+   duplicate of one already captured, so it adds no new tag values. What is
+   actually needed is a dump from a board whose `/washer/vs/0` speaks in
+   named levels (Cold/Warm/Hot, Low/High) *while that unit is sitting on a
+   downloaded program* — then the payload's `49`/`4A` values can be read
+   against settings that describe the same program. The WA55 is such a
+   board but was captured on a local course, which is why it can't be used
+   (see the trap above).
+5. The DW5000C's four slots (`8E 8D 8F 02`) are in the same numeric range as
+   dishwasher course codes (its selected course is `86`), unlike the
+   washers' slots. One payload from that machine would show whether slot ids
+   are drawn from the course-code space on some boards.

docs/investigations/offline-setup.md

@@ -0,0 +1,213 @@
+# Loading a config entry while the appliance is offline
+
+Issue #295 asks for faster recovery when a powered-off appliance comes back,
+instead of waiting out HA's `ConfigEntryNotReady` backoff. PR #303 tried to
+get there by catching the first-refresh failure in `async_setup_entry` and
+loading the entry anyway.
+
+That doesn't work here, and the reason is worth writing down: this
+integration has no static entity list. Every entity comes from discovery,
+and discovery only happens inside a successful poll.
+
+(The issue's "up to 15 minutes" is out of date, incidentally. Current HA
+retries on `2 ** min(tries, 4) * 5` seconds — capped at 80s, not 900. The
+backoff was never the worst part; a device card reading "Retrying setup" with
+no entities behind it is.)
+
+## What PR #303 produces today
+
+Measured on the PR's branch — set up with `_poll_once` raising, then advance
+the clock four summary intervals:
+
+| | |
+| --- | --- |
+| entry state | `LOADED` |
+| `coordinator.bound` | 0 |
+| entities in the state machine | 0 |
+| registry entries | 1 (the disabled connection-mode sensor) |
+| coordinator listeners | 0 |
+| `_unsub_refresh` | `None` |
+| poll attempts over the next 4 intervals | **0** |
+
+The entry loads and then never polls again. `DataUpdateCoordinator._async_refresh`
+reschedules only `if not auth_failed and self._listeners and not
+self.hass.is_stopping`; with no bound entities the only unconditional entity
+is `LocalThingsConnectionModeSensor`, which is
+`entity_registry_enabled_default = False` and so never added and never
+subscribes. Nothing reloads the entry either. The device comes back online to
+an entry that is permanently empty until a manual reload — strictly worse
+than the backoff it replaces, which did recover on its own within 15 minutes.
+
+## Why entities can't just be created offline
+
+Four independent gates, all of which need live device data:
+
+1. `bound` is only ever assigned in `_run_discovery` (`coordinator.py:1081`),
+   which runs on a poll's `resources` dict.
+2. All ten platforms enumerate `coordinator.bound` exactly once, at forward
+   time (`sensor.py:34` and siblings). Nothing adds entities later — the
+   invariant is already documented at `coordinator.py:1283-1286`.
+3. `_is_included` (`entity.py:39`) returns False whenever `last_resources`
+   has no rep for the href. Even a fully reconstructed `bound` filters to
+   nothing while `StateCache` is empty.
+4. `LocalThingsEntity` is a bare `CoordinatorEntity` with no `available`
+   override, no `RestoreEntity`, and no `Store` anywhere in the component. An
+   entity that did exist offline would be `unavailable` with no state.
+
+The issue cites ESPHome, Shelly, LIFX and WLED as precedent for setup that
+never fails. Those integrations can do it because each one has a *persisted
+device description* to build entities from — ESPHome keeps its entity list in
+`.storage`, Shelly caches device info. The pattern is portable; the mechanism
+underneath it is the part PR #303 is missing.
+
+## How the implemented version works
+
+Three pieces, plus a gating rule.
+
+### 1. A persisted discovery snapshot
+
+After each successful first cycle, `_save_snapshot` banks exactly the
+`resources` dict that cycle handed `_run_discovery`, along with the
+pre-narrowing subdevice candidate list and the `DeviceIdentity` read from
+`/oic/*`.
+
+Storing the poll input rather than a rendered entity list is the decision
+that keeps this honest. `BoundEntity` holds live
+`Capability`/`SamsungEntityDescription` objects and isn't serializable, so
+the alternative was a parallel format plus a re-resolution path — a second
+implementation of discovery that could drift from the real one. Replaying the
+input through `_run_discovery` means the same code, the same registry
+resolution, and no second source of truth.
+
+Three things ride along because `_run_discovery` reads them off `self`
+rather than out of `resources`, and getting them wrong would silently resolve
+a *different* registry offline than online — which reconciliation below would
+then see as a real change and reload on every restart:
+
+- `_identity.device_types` routes `resolve_registry`.
+- `self.subdevices` is the candidate list `discover_partitioned` narrows;
+  replaying against the already-narrowed list finds no siblings at all.
+- `_identity.manufacturer`/`model` feed `device_info`.
+
+It lives in `.storage` (`Store`, keyed on entry_id) rather than on the config
+entry: it's device state, not configuration, and runs to tens of kilobytes.
+`async_remove_entry` deletes it with the entry.
+
+The write is awaited, not `async_delay_save`d. A deferred write outlives
+whatever queued it: it lands after `async_remove_entry` has deleted the file
+and recreates it orphaned, and a reload scheduled by the reconcile below
+would read the pre-reload snapshot back off disk. It runs once per entry
+load, so there's nothing worth deferring. A write that fails is logged and
+swallowed — a board reporting something the JSON encoder rejects must not
+break polling.
+
+### 2. Reconcile on reconnect
+
+The snapshot is a claim about a device we haven't talked to yet. When the
+first live poll lands, `_reconcile_rehydrated` compares the live entity set
+against the rehydrated one — as `(subdevice key, _key(bound))` pairs, which
+is the unique_id identity — and calls `async_schedule_reload` if they differ.
+
+Gate 2 above is why this has to be a reload rather than an in-place fixup.
+It's what makes the feature safe against a firmware update, a sibling
+subdevice that starts answering, or a different appliance at the same IP.
+
+### 3. Keep polling with no listeners
+
+`async_setup_entry` holds one listener for the entry's lifetime:
+
+```python
+entry.async_on_unload(coordinator.async_add_listener(lambda: None))
+```
+
+Registered *before* the first refresh, so scheduling survives a refresh that
+fails. This alone fixes the measured "never polls again" bug, and covers a
+rehydrated set whose entities are all registry-disabled. Removing the last
+listener unschedules the timer, and HA runs `async_on_unload` callbacks when
+setup raises, so the setup-retry path doesn't leak a polling coordinator.
+
+### Gating rule: only load offline when there's a snapshot
+
+An entry that has never successfully polled has nothing to restore and keeps
+raising `ConfigEntryNotReady`. This is what answers the objection in the PR
+thread — with a snapshot we *do* have metadata to build a device from, and
+without one HA's backoff is still the right behavior. It also leaves room for
+the #168-style flows that need to interact with the device during setup: a
+device that never completed setup still blocks.
+
+It also means `async_remove_config_entry_device` is no longer reachable with
+an empty `coordinator.subdevices`, so an offline load can't offer to delete a
+real-but-unreachable subdevice.
+
+### The coverage-gap Repair stays live-only
+
+`_run_discovery(..., from_snapshot=True)` skips `_update_coverage_gap_issue`.
+The Repair points the user at a diagnostics download, which is empty until
+the appliance answers, and a device name that drifts between the snapshot and
+the live poll would churn the issue for no reason.
+
+Not a de-duplication measure — HA already handles that. `async_create_issue`
+is keyed on `(domain, issue_id)`, `dataclasses.replace` in
+`async_get_or_create` leaves `dismissed_version` alone, and the registry
+reloads non-persistent issues with their dismissal intact, so one row per
+entry survives restarts and an "Ignore" sticks.
+
+### What a cycle costs while the appliance stays dark (issue #269)
+
+An appliance switched off at the wall isn't a one-cycle blip: it fails the
+same way every 30s for hours, and both halves of that failure were being paid
+twice.
+
+`_poll_once` opens the session itself when there isn't one, so a switched-off
+appliance fails *in the handshake* — 12s (`DtlsCoapSession.HANDSHAKE_TIMEOUT_S`)
+with nothing to show for it. The poll path then treated that like any other
+poll failure and ran its reconnect: close the session, pause
+`_RECONNECT_PAUSE_S`, poll again. There is no session to close and no
+association for the device to clean up, so the "reconnect" was the identical
+handshake five seconds later — 29s of the 30s interval spent proving the
+appliance is off, twice over, and the same again on every `SETUP_RETRY`
+attempt for an entry with no snapshot to load from. `_handshake_failed` marks
+that case in `_poll_once` so the poll path can skip the retry; a session that
+opened and *then* broke still reconnects within the cycle.
+
+The log was the half the reporters actually saw: `poll failed after
+reconnect` at ERROR every cycle, plus a `reconnect_is_frequent` WARNING once
+three piled up, for a state this integration is specifically built to sit
+through. Issue #269's reporter read that repetition as the integration having
+failed. It's one ERROR per outage now, DEBUG for the cycles after it, and one
+INFO when the device answers again — HA's own coordinator already logs the
+transition into and out of a failed update.
+
+## What this still won't do
+
+Entities will be present and `unavailable` — not showing their last values.
+Gate 4 means last-known values require either `RestoreEntity` per platform or
+persisting `StateCache`, and both mean asserting state the integration cannot
+verify: a washer unplugged for a week would read "Running". HA's convention
+is that unreachable means unavailable, and the recorder keeps the history
+either way, so long-term statistics and history graphs are unaffected by this
+choice.
+
+Worth being explicit about, because it is the gap between what PR #303
+promises in the thread ("load their previously recorded states") and what any
+correct version can deliver.
+
+## Rejected: zeroconf
+
+The issue's other suggestion — wire zeroconf so the device's own boot
+announcement triggers a retry, which is the genuinely idiomatic HA answer —
+is a non-starter as things stand: there is no `zeroconf` or `dhcp` key in
+`manifest.json` and the config flow is user-driven only, so HA has no
+discovery signal for this integration to hang a retry on. It would first need
+a confirmed mDNS service on the appliance. Worth revisiting if one turns up;
+it would make recovery near-instant instead of within one poll interval.
+
+## Rejected: the cheap version
+
+Keeping `ConfigEntryNotReady` and adding a probe that calls
+`async_schedule_reload` on first success would have fixed the recovery *time*
+in about twenty lines, with no persistence and no reconcile. It was rejected
+because it leaves the device reading as broken for as long as the appliance
+is off, which is the half of issue #295 that actually bites — an appliance
+switched off at the wall is offline for days, not seconds, and a whole
+integration that looks failed for that entire window is the complaint.

requirements-dev.txt

@@ -6,7 +6,7 @@ pytest-homeassistant-custom-component>=0.13.316
 
 # Integration runtime deps, needed to import the component under test
 # (also declared in custom_components/localthings/manifest.json).
-smartthings-local>=0.1.2
+smartthings-local>=0.1.8
 cbor2>=5.4.6
 pyOpenSSL>=23.0
 cryptography>=41.0

tests/conftest.py

@@ -70,7 +70,7 @@ class FakeCoapSession:
         pass
 
 
-def _discover_full(resources: dict[str, dict], oic_res, seeds: dict[str, list]):
+def _discover_full(resources: dict[str, dict], oic_res, seeds: dict[str, list], device_types=()):
     """Run the *whole* subdevice-aware discovery pipeline against fixture
     data, HA-free -- mirrors exactly what LocalThingsCoordinator does across
     _enumerate_subdevices_blocking + _run_discovery (issue #177), so a test
@@ -78,6 +78,12 @@ def _discover_full(resources: dict[str, dict], oic_res, seeds: dict[str, list]):
     it. See the adding-device-support skill's section 2 for the plain
     (non-subdevice) equivalent this extends.
 
+    `device_types` is the master's own /oic/d `rt` (see
+    discover_partitioned's `oic_device_types` param) -- only needed for a
+    board with no /information/vs/0 at all to route from (issue #324's
+    range, whose modelNum-based fallback has nothing to read), so it
+    defaults to () for every fixture that resolves by board token instead.
+
     Returns `(bound, materialized, skipped, full_resources, device_type_name)`:
     - `bound`: every BoundEntity, main + every materialized subdevice.
     - `materialized`/`skipped`: Subdevice / SkippedSubdevice lists straight from
@@ -101,6 +107,7 @@ def _discover_full(resources: dict[str, dict], oic_res, seeds: dict[str, list]):
         candidates,
         resolve,
         CAPABILITIES,
+        oic_device_types=device_types,
     )
     return bound, materialized, skipped, full_resources, device_type_name
 

tests/fixtures/dishwasher_dw5000c_cloud_device.json

@@ -0,0 +1,297 @@
+{
+  "device0": [
+    {
+      "rt": [
+        "x.com.samsung.devcol",
+        "oic.wk.col"
+      ],
+      "if": [
+        "oic.if.baseline",
+        "oic.if.ll",
+        "oic.if.b"
+      ]
+    },
+    {
+      "href": "/realtimenotiforclient/vs/0",
+      "rep": {
+        "x.com.samsung.da.timeforshortnoti": "0",
+        "x.com.samsung.da.periodicnotisubscription": "true"
+      }
+    },
+    {
+      "href": "/alarms/vs/0",
+      "rep": {
+        "x.com.samsung.da.items": [
+          {
+            "x.com.samsung.da.id": "0",
+            "x.com.samsung.da.description": "Alarm",
+            "x.com.samsung.da.alarmType": "Device",
+            "x.com.samsung.da.code": "DishA_Disable",
+            "x.com.samsung.da.triggeredTime": "2022-07-28T13:45:57",
+            "x.com.samsung.da.state": "Deleted"
+          }
+        ]
+      }
+    },
+    {
+      "href": "/diagnosis/vs/0",
+      "rep": {
+        "x.com.samsung.da.diagnosisStart": "Ready"
+      }
+    },
+    {
+      "href": "/energy/consumption/vs/0",
+      "rep": {
+        "x.com.samsung.da.cumulativeSavedPower": "0"
+      }
+    },
+    {
+      "href": "/energy/consumption/0",
+      "rep": {}
+    },
+    {
+      "href": "/course/vs/0",
+      "rep": {
+        "x.com.samsung.da.supportedModes": [
+          "HOMECARE_WIZARD_V2"
+        ],
+        "x.com.samsung.da.options": [
+          "DeviceType_0812",
+          "UpdateAllow_NotAllowed",
+          "CourseDefaultTimeSet_008B008E009A006D003C000A006600A50059009D",
+          "CourseDefaultTempSet_3C41363F41413737373700003C3C464649493C3C",
+          "CourseDefaultFahrenheitSet_8C95819195958383838300008C8C9E9EA3A38C8C",
+          "Course_86",
+          "DetergentOnce_0",
+          "DetergentLeft_0",
+          "DetergentBase_0",
+          "DetergentAlarm_Off",
+          "DetergentType_0",
+          "DetergentTotal_0",
+          "ProgressTimeSet_420622820456B20384",
+          "SendToDevice_Off",
+          "GMT_F2",
+          "SavingModeCondition_01010207828485868E8D020300",
+          "SavingMode_Off",
+          "DownloadCourseList_8F",
+          "StormWashZone_Off",
+          "AutoDoorRelease_On",
+          "Sound_On",
+          "WaterLevelSet_050404050302010205010400",
+          "CloudExtraCourse_8E8D8F02",
+          "EnergyLevelSet_050403050202010305040300",
+          "UsagesDB_ok",
+          "EnergyKW_396",
+          "DrumCleanLog_Empty",
+          "TimeSync_NotSupported"
+        ],
+        "x.com.samsung.da.supportedOptions": [
+          "482830CB002C002D00283830CB002C002D00284830CB002C002D00285830CB000C000D00086830CB002C002D002908308B000C000D0008E830CB000C000D0008D830CB002C002D0028F8308B000C000D00002830CB002C002D002"
+        ]
+      }
+    },
+    {
+      "href": "/power/vs/0",
+      "rep": {
+        "x.com.samsung.da.power": "On"
+      }
+    },
+    {
+      "href": "/power/0",
+      "rep": {
+        "value": true
+      }
+    },
+    {
+      "href": "/kidslock/vs/0",
+      "rep": {
+        "x.com.samsung.da.kidsLock": "Ready"
+      }
+    },
+    {
+      "href": "/kidslock/0",
+      "rep": {
+        "value": false
+      }
+    },
+    {
+      "href": "/operational/state/vs/0",
+      "rep": {
+        "x.com.samsung.da.state": "Run",
+        "x.com.samsung.da.remainingTime": "00:44:00",
+        "x.com.samsung.da.progressPercentage": "28",
+        "x.com.samsung.da.delayStartTime": "00:00:00",
+        "x.com.samsung.da.progress": "Wash",
+        "x.com.samsung.da.supportedProgress": [
+          "None",
+          "Predrain",
+          "Wash",
+          "Rinse",
+          "Drying",
+          "Finish"
+        ]
+      }
+    },
+    {
+      "href": "/operational/state/0",
+      "rep": {
+        "currentMachineState": "**REDACTED**",
+        "machineStates": "**REDACTED**",
+        "jobStates": [
+          "None",
+          "Predrain",
+          "Wash",
+          "Rinse",
+          "Drying",
+          "Finish"
+        ],
+        "currentJobState": "Wash",
+        "remainingTime": "00:44:00",
+        "progressPercentage": "28"
+      }
+    },
+    {
+      "href": "/information/vs/0",
+      "rep": {
+        "x.com.samsung.da.modelNum": "DA_DW_TP1_21_COMMON|30010741|40000200001711004981000000200000",
+        "x.com.samsung.da.description": "DA_DW_TP1_21_COMMON_DW5000C/DD92-0010741_0001",
+        "x.com.samsung.da.serialNum": "**REDACTED**",
+        "x.com.samsung.da.otnDUID": "**REDACTED**",
+        "x.com.samsung.da.diagProtocolType": "WIFI_HTTPS",
+        "x.com.samsung.da.diagLogType": [
+          "errCode",
+          "dump"
+        ],
+        "x.com.samsung.da.diagDumpType": "file",
+        "x.com.samsung.da.diagEndPoint": "SSM",
+        "x.com.samsung.da.diagMnid": "0AJT",
+        "x.com.samsung.da.diagSetupid": "WD0",
+        "x.com.samsung.da.diagMinVersion": "1.0",
+        "x.com.samsung.da.items": [
+          {
+            "x.com.samsung.da.id": "0",
+            "x.com.samsung.da.description": "DA_DW_TP1_21_COMMON|30010741|40000200001711004981000000200000",
+            "x.com.samsung.da.type": "Software",
+            "x.com.samsung.da.number": "00081A230213(A214)",
+            "x.com.samsung.da.newVersionAvailable": "0"
+          },
+          {
+            "x.com.samsung.da.id": "1",
+            "x.com.samsung.da.description": "Firmware_1_DB_30010741230602142FFFFFFFFFFFFFFFFFFFFFFFFFFE(081230010741FFFFFFFF_30000000)(FileDown:0)(Type:0)",
+            "x.com.samsung.da.type": "Firmware",
+            "x.com.samsung.da.number": "23060214,FFFFFFFF",
+            "x.com.samsung.da.newVersionAvailable": "0"
+          }
+        ]
+      }
+    },
+    {
+      "href": "/file/information/vs/0",
+      "rep": {
+        "x.com.samsung.timeoffset": "+00:00"
+      }
+    },
+    {
+      "href": "/wm/editcourse/vs/0",
+      "rep": {}
+    },
+    {
+      "href": "/wm/setinfo/vs/0",
+      "rep": {
+        "x.com.samsung.da.isModelSettingWithoutSC": "false",
+        "x.com.samsung.da.isModelSettingPowerOnOff": "false"
+      }
+    },
+    {
+      "href": "/dishwasher/vs/0",
+      "rep": {
+        "x.com.samsung.da.highTemperatureDry": "Off",
+        "x.com.samsung.da.sanitize": "Off",
+        "x.com.samsung.da.selectedZone": "ON_ON",
+        "x.com.samsung.da.rinseLevel": "0",
+        "x.com.samsung.da.supportedSelectedZone": [
+          "OFF_ON",
+          "ON_ON"
+        ],
+        "x.com.samsung.da.supportedSanitize": [
+          "Off",
+          "On"
+        ],
+        "x.com.samsung.da.supportedHighTemperatureDry": [
+          "Off",
+          "On"
+        ],
+        "x.com.samsung.da.supportedRinseLevel": [
+          "0",
+          "1",
+          "2",
+          "3",
+          "4",
+          "5",
+          "6"
+        ]
+      }
+    },
+    {
+      "href": "/otninformation/vs/0",
+      "rep": {
+        "x.com.samsung.da.target": "Micom",
+        "x.com.samsung.da.newVersionAvailable": "false"
+      }
+    },
+    {
+      "href": "/remotectrl/vs/0",
+      "rep": {
+        "x.com.samsung.da.remoteControlEnabled": "true"
+      }
+    },
+    {
+      "href": "/remotectrl/0",
+      "rep": {
+        "value": true
+      }
+    },
+    {
+      "href": "/configuration/vs/0",
+      "rep": {
+        "x.com.samsung.da.region": "0000000000",
+        "x.com.samsung.da.countryCode": "CA"
+      }
+    },
+    {
+      "href": "/filter/waterfilter/vs/0",
+      "rep": {}
+    },
+    {
+      "href": "/drlc/0",
+      "rep": {
+        "DRLevel": 0,
+        "start": "0000-00-00T00:00:00Z",
+        "duration": 0,
+        "override": false
+      }
+    },
+    {
+      "href": "/drlc/vs/0",
+      "rep": {
+        "x.com.samsung.da.drlcLevel": "0",
+        "x.com.samsung.da.durationminutes": "0",
+        "x.com.samsung.da.start": "0000-00-00T00:00:00Z",
+        "x.com.samsung.da.override": "Off",
+        "x.com.samsung.da.realSaving": "Off"
+      }
+    },
+    {
+      "href": "/water/consumption/vs/0",
+      "rep": {
+        "x.com.samsung.da.cumulativeWater": "2662000"
+      }
+    },
+    {
+      "href": "/wm/submode/vs/0",
+      "rep": {
+        "setTemperatureUnit": "F"
+      }
+    }
+  ]
+}

tests/fixtures/dryer_dv6800n_device.json

@@ -0,0 +1,244 @@
+{
+  "device0": [
+    {
+      "rt": [
+        "x.com.samsung.devcol",
+        "oic.wk.col"
+      ],
+      "if": [
+        "oic.if.baseline",
+        "oic.if.ll",
+        "oic.if.b"
+      ]
+    },
+    {
+      "href": "/alarms/vs/0",
+      "rep": {}
+    },
+    {
+      "href": "/configuration/vs/0",
+      "rep": {
+        "x.com.samsung.da.region": "0000000000",
+        "x.com.samsung.da.countryCode": "US\u0001"
+      }
+    },
+    {
+      "href": "/course/vs/0",
+      "rep": {
+        "x.com.samsung.da.supportedModes": [
+          "HOMECARE_WIZARD_V2"
+        ],
+        "x.com.samsung.da.options": [
+          "DeviceType_0165",
+          "UpdateAllow_NotAllowed",
+          "Course_9A",
+          "MixedLoadBell_Disable",
+          "MixedLoadBellNoti_Nothing",
+          "LaundryOutTime_0",
+          "SeamlessControl_Disable",
+          "KidsLockBypass_On",
+          "DetergentOnce_0",
+          "DetergentLeft_0",
+          "DetergentBase_0",
+          "DetergentAlarm_Off",
+          "DetergentType_0",
+          "DetergentTotal_0",
+          "SpecialFunction_4",
+          "AvailableDelayTime_188",
+          "LaundryPlannerUserSetTime_0",
+          "ProgressTimeSet_B22D00B4003C",
+          "WrinklePreventRunning_Off",
+          "EnergyLevelSet_050502050503020304010204030203",
+          "MostUsed_9AD20EE000",
+          "MixedLoadBellSet_02FFFF02FFFFFFFFFFFFFFFFFF02",
+          "UsagesDB_ok",
+          "EnergyKW_396",
+          "TimeSync_NotSupported"
+        ],
+        "x.com.samsung.da.supportedOptions": [
+          "29AD20EE000CAD10EE000DBD204E00099D20EE00093D102E000B5D102E000D7D204E000A5D204E00096D000E10E97D000E10E7FD000E33E98D000E000EBD204E000B6D20EE000"
+        ]
+      }
+    },
+    {
+      "href": "/cycleinterface/vs/0",
+      "rep": {}
+    },
+    {
+      "href": "/diagnosis/vs/0",
+      "rep": {
+        "x.com.samsung.da.diagnosisStart": "Ready"
+      }
+    },
+    {
+      "href": "/energy/consumption/0",
+      "rep": {}
+    },
+    {
+      "href": "/energy/consumption/vs/0",
+      "rep": {
+        "x.com.samsung.da.instantaneousPowerUnit": "W",
+        "x.com.samsung.da.instantaneousPower": "-500",
+        "x.com.samsung.da.cumulativePower": "692600",
+        "x.com.samsung.da.cumulativeUnit": "Wh",
+        "x.com.samsung.da.cumulativeDate": "1786964400",
+        "x.com.samsung.da.cumulativeDateUTC": "1786960800"
+      }
+    },
+    {
+      "href": "/file/information/vs/0",
+      "rep": {
+        "x.com.samsung.timeoffset": "+01:00"
+      }
+    },
+    {
+      "href": "/information/vs/0",
+      "rep": {
+        "x.com.samsung.da.modelNum": "DA_WM_A51_20_COMMON|20221341|30010102001211000103000000000000",
+        "x.com.samsung.da.description": "DA_WM_A51_20_COMMON_DV6800N/DC92-01967B_0404",
+        "x.com.samsung.da.serialNum": "**REDACTED**",
+        "x.com.samsung.da.otnDUID": "**REDACTED**",
+        "x.com.samsung.da.items": [
+          {
+            "x.com.samsung.da.id": "0",
+            "x.com.samsung.da.description": "DA_WM_A51_20_COMMON|20221341|30010102001211000103000000000000",
+            "x.com.samsung.da.type": "Software",
+            "x.com.samsung.da.number": "02198A230708(E257)",
+            "x.com.samsung.da.newVersionAvailable": "0"
+          },
+          {
+            "x.com.samsung.da.id": "1",
+            "x.com.samsung.da.description": "DA_WM_A51_20_COMMON",
+            "x.com.samsung.da.type": "Firmware",
+            "x.com.samsung.da.number": "17111305,17122616",
+            "x.com.samsung.da.newVersionAvailable": "0"
+          }
+        ]
+      }
+    },
+    {
+      "href": "/kidslock/0",
+      "rep": {
+        "value": false
+      }
+    },
+    {
+      "href": "/kidslock/vs/0",
+      "rep": {
+        "x.com.samsung.da.kidsLock": "Ready"
+      }
+    },
+    {
+      "href": "/operational/state/0",
+      "rep": {
+        "currentMachineState": "**REDACTED**",
+        "machineStates": "**REDACTED**",
+        "jobStates": [
+          "None",
+          "Drying",
+          "Cooling",
+          "Finish"
+        ],
+        "currentJobState": "None",
+        "remainingTime": "03:08:00",
+        "progressPercentage": "1"
+      }
+    },
+    {
+      "href": "/operational/state/vs/0",
+      "rep": {
+        "x.com.samsung.da.state": "Ready",
+        "x.com.samsung.da.remainingTime": "03:08:00",
+        "x.com.samsung.da.progressPercentage": "1",
+        "x.com.samsung.da.progress": "None",
+        "x.com.samsung.da.delayEndTime": "00:00:00",
+        "x.com.samsung.da.supportedProgress": [
+          "None",
+          "Drying",
+          "Cooling",
+          "Finish"
+        ]
+      }
+    },
+    {
+      "href": "/power/0",
+      "rep": {
+        "value": false
+      }
+    },
+    {
+      "href": "/power/vs/0",
+      "rep": {
+        "x.com.samsung.da.power": "Off"
+      }
+    },
+    {
+      "href": "/realtimenotiforclient/vs/0",
+      "rep": {
+        "x.com.samsung.da.timeforshortnoti": "0",
+        "x.com.samsung.da.periodicnotisubscription": "true"
+      }
+    },
+    {
+      "href": "/remotectrl/0",
+      "rep": {
+        "value": false
+      }
+    },
+    {
+      "href": "/remotectrl/vs/0",
+      "rep": {
+        "x.com.samsung.da.remoteControlEnabled": "false"
+      }
+    },
+    {
+      "href": "/setting/vs/0",
+      "rep": {}
+    },
+    {
+      "href": "/st/dryercourse/vs/0",
+      "rep": {
+        "x.com.samsung.da.st.dryerMode": "Table_00_Course_9A",
+        "x.com.samsung.da.st.courseTable": "Table_00"
+      }
+    },
+    {
+      "href": "/washer/vs/0",
+      "rep": {
+        "x.com.samsung.da.wrinklePrevent": "Off",
+        "x.com.samsung.da.dryLevel": "2",
+        "x.com.samsung.da.supportedDryLevel": [
+          "None",
+          "1",
+          "2",
+          "3"
+        ],
+        "x.com.samsung.da.dryTime": "00:00:00",
+        "x.com.samsung.da.supportedDryTime": [
+          "00:00:00",
+          "00:30:00",
+          "01:00:00",
+          "01:30:00",
+          "02:00:00",
+          "02:30:00"
+        ],
+        "x.com.samsung.da.dryerType": "Electricity"
+      }
+    },
+    {
+      "href": "/wm/editcourse/vs/0",
+      "rep": {}
+    },
+    {
+      "href": "/wm/jobbeginingstatus/vs/0",
+      "rep": {}
+    },
+    {
+      "href": "/wm/setinfo/vs/0",
+      "rep": {
+        "x.com.samsung.da.isModelSettingWithoutSC": "false",
+        "x.com.samsung.da.isModelSettingPowerOnOff": "false"
+      }
+    }
+  ]
+}

tests/fixtures/gas_cooktop_tp2x_ks_device.json

@@ -0,0 +1,138 @@
+{
+  "device0": [
+    {
+      "rt": [
+        "x.com.samsung.devcol",
+        "oic.wk.col"
+      ],
+      "if": [
+        "oic.if.baseline",
+        "oic.if.ll",
+        "oic.if.b"
+      ]
+    },
+    {
+      "href": "/alarms/vs/0",
+      "rep": {
+        "rt": [
+          "x.com.samsung.da.alarms"
+        ],
+        "if": [
+          "oic.if.baseline",
+          "oic.if.a"
+        ],
+        "x.com.samsung.da.items": [
+          {
+            "x.com.samsung.da.id": "0",
+            "x.com.samsung.da.description": "Alarm",
+            "x.com.samsung.da.alarmType": "Device",
+            "x.com.samsung.da.code": "CT_E",
+            "x.com.samsung.da.triggeredTime": "2026-08-06T14:24:02"
+          }
+        ]
+      }
+    },
+    {
+      "href": "/bluetooth/hood/status/vs/0",
+      "rep": {
+        "connectionState": "disconnected",
+        "micomModelId": "",
+        "firmwareVersion": "",
+        "power": "off",
+        "fanSpeed": 0,
+        "lampState": "off",
+        "timer": {},
+        "rt": [
+          "bluetoothHoodStatus"
+        ],
+        "if": [
+          "oic.if.baseline",
+          "oic.if.s"
+        ]
+      }
+    },
+    {
+      "href": "/configuration/vs/0",
+      "rep": {}
+    },
+    {
+      "href": "/connected/vs/0",
+      "rep": {
+        "x.com.samsung.da.connected": "On",
+        "rt": [
+          "x.com.samsung.da.connected"
+        ],
+        "if": [
+          "oic.if.baseline",
+          "oic.if.a"
+        ]
+      }
+    },
+    {
+      "href": "/kidslock/vs/0",
+      "rep": {
+        "x.com.samsung.da.kidsLock": "Ready"
+      }
+    },
+    {
+      "href": "/mode/vs/0",
+      "rep": {
+        "x.com.samsung.da.options": [
+          "DeviceType_NV8000T-/KO0",
+          "Pause_Off",
+          "SyncFlex_Off",
+          "FlexCoil_0",
+          "MainTimerCurrent_0",
+          "MainTimerSet_0",
+          "MainTimerState_Ready",
+          "IndependentTimerCheck_Enable",
+          "OperationState0_Ready",
+          "HotSurface0_Normal",
+          "PowerLevel0_0",
+          "OperationState1_Ready",
+          "HotSurface1_Normal",
+          "PowerLevel1_0",
+          "OperationState2_Ready",
+          "HotSurface2_Normal",
+          "PowerLevel2_0",
+          "OperationState3_Ready",
+          "HotSurface3_Normal",
+          "PowerLevel3_0",
+          "OperationState4_Ready",
+          "HotSurface4_Normal",
+          "PowerLevel4_0",
+          "OperationState5_Ready",
+          "HotSurface5_Normal",
+          "PowerLevel5_0"
+        ],
+        "rt": [
+          "x.com.samsung.da.mode"
+        ],
+        "if": [
+          "oic.if.baseline",
+          "oic.if.a"
+        ]
+      }
+    },
+    {
+      "href": "/otninformation/vs/0",
+      "rep": {
+        "x.com.samsung.da.target": "",
+        "x.com.samsung.da.newVersionAvailable": "false"
+      }
+    },
+    {
+      "href": "/power/vs/0",
+      "rep": {
+        "x.com.samsung.da.power": "Off",
+        "rt": [
+          "x.com.samsung.da.operation"
+        ],
+        "if": [
+          "oic.if.baseline",
+          "oic.if.a"
+        ]
+      }
+    }
+  ]
+}

tests/fixtures/golden/airconditioner.json

@@ -20,6 +20,7 @@
     "fine_dust",
     "humidity",
     "odor",
+    "outdoor_temperature",
     "power_watts",
     "super_fine_dust",
     "tropical_night_mode"

tests/fixtures/golden/airconditioner_ailp_fac.json

@@ -0,0 +1,40 @@
+{
+  "state_keys": [
+    "absence_clean",
+    "ai_energy_level",
+    "air_filter_status",
+    "air_filter_threshold",
+    "air_filter_usage",
+    "air_filter_usage_hours",
+    "air_purify",
+    "alarm_code",
+    "auto_clean",
+    "auto_clean_progress",
+    "auto_clean_running",
+    "beep",
+    "climate",
+    "current_temperature_c",
+    "display",
+    "energy_kwh",
+    "energy_saved_kwh",
+    "energy_saving_mode",
+    "energy_saving_operating_status",
+    "energy_saving_state",
+    "firmware_update",
+    "humidity",
+    "mute_once",
+    "odor_controller_active",
+    "odor_controller_progress",
+    "outdoor_temperature",
+    "power_energy_kwh",
+    "power_watts",
+    "selfcheck_error",
+    "selfcheck_result",
+    "selfcheck_status",
+    "sound_mode",
+    "sound_output",
+    "tropical_night_mode",
+    "uv_led",
+    "ventilation_alarm"
+  ]
+}

tests/fixtures/golden/airconditioner_ara_ww_tp1_22.json

@@ -18,6 +18,7 @@
     "mute_once",
     "odor_controller_active",
     "odor_controller_progress",
+    "outdoor_temperature",
     "power_watts",
     "tropical_night_mode"
   ]

tests/fixtures/golden/airconditioner_cac.json

@@ -1,5 +1,6 @@
 {
   "state_keys": [
+    "absence_clean",
     "absence_power_saving_active",
     "absence_power_saving_mode",
     "air_filter_pm1_status",
@@ -9,6 +10,7 @@
     "air_filter_usage",
     "air_filter_usage_hours",
     "air_purify",
+    "air_sensing_state",
     "alarm_code",
     "auto_clean",
     "auto_clean_progress",
@@ -17,20 +19,37 @@
     "climate",
     "current_temperature_c",
     "dust",
+    "edge_lighting",
+    "edge_lighting_color",
+    "edge_lighting_mode",
     "energy_kwh",
     "energy_saved_kwh",
     "fine_dust",
     "firmware_update",
     "humidity",
+    "indicator_light",
+    "indicator_light_mode",
+    "last_air_sensing_level",
+    "last_air_sensing_time",
     "motion_detect_wind_active",
     "motion_detect_wind_mode",
     "mute_once",
     "odor_controller_active",
     "odor_controller_progress",
+    "outdoor_temperature",
+    "periodic_air_sensing",
+    "periodic_sensing_skip_status",
     "power_watts",
     "selfcheck_error",
     "selfcheck_result",
     "selfcheck_status",
+    "sensing_interval",
+    "sensing_mode",
+    "sensing_skip_end",
+    "sensing_skip_start",
+    "sound_mode",
+    "sound_output",
+    "sound_volume",
     "super_fine_dust",
     "tropical_night_mode",
     "uv_led"

tests/fixtures/golden/airconditioner_caww_tp2.json

@@ -17,6 +17,7 @@
     "firmware_update",
     "humidity",
     "mute_once",
+    "outdoor_temperature",
     "power_watts",
     "tropical_night_mode"
   ]

tests/fixtures/golden/airconditioner_tp1x_da_ac_rac_01011.json

@@ -5,6 +5,7 @@
     "air_filter_usage",
     "air_filter_usage_hours",
     "air_purify",
+    "air_sensing_state",
     "alarm_code",
     "auto_clean",
     "auto_clean_progress",
@@ -19,10 +20,19 @@
     "fine_dust",
     "firmware_update",
     "humidity",
+    "last_air_sensing_level",
+    "last_air_sensing_time",
     "mute_once",
+    "outdoor_temperature",
+    "periodic_air_sensing",
+    "periodic_sensing_skip_status",
     "selfcheck_error",
     "selfcheck_result",
     "selfcheck_status",
+    "sensing_interval",
+    "sensing_mode",
+    "sensing_skip_end",
+    "sensing_skip_start",
     "super_fine_dust",
     "tropical_night_mode"
   ]

tests/fixtures/golden/airconditioner_tp1x_rac.json

@@ -19,6 +19,7 @@
     "energy_saved_kwh",
     "firmware_update",
     "mute_once",
+    "outdoor_temperature",
     "selfcheck_error",
     "selfcheck_result",
     "selfcheck_status",

tests/fixtures/golden/airconditioner_tp1x_rac_01001.json

@@ -18,6 +18,7 @@
     "mute_once",
     "odor_controller_active",
     "odor_controller_progress",
+    "outdoor_temperature",
     "power_watts",
     "tropical_night_mode"
   ]

tests/fixtures/golden/airconditioner_tp1x_rac_coolonly.json

@@ -16,6 +16,7 @@
     "firmware_update",
     "humidity",
     "mute_once",
+    "outdoor_temperature",
     "power_watts",
     "tropical_night_mode"
   ]

tests/fixtures/golden/airconditioner_tp1x_rac_odor_controller.json

@@ -20,6 +20,7 @@
     "mute_once",
     "odor_controller_active",
     "odor_controller_progress",
+    "outdoor_temperature",
     "selfcheck_error",
     "selfcheck_result",
     "selfcheck_status",

tests/fixtures/golden/airconditioner_tp2x_rac_20k.json

@@ -15,6 +15,7 @@
     "firmware_update",
     "humidity",
     "mute_once",
+    "outdoor_temperature",
     "power_watts",
     "tropical_night_mode"
   ]

tests/fixtures/golden/airconditioner_windfree.json

@@ -19,6 +19,7 @@
     "fine_dust",
     "humidity",
     "odor",
+    "outdoor_temperature",
     "power_watts",
     "super_fine_dust",
     "tropical_night_mode"

tests/fixtures/golden/airconditioner_window_ac.json

@@ -16,6 +16,7 @@
     "firmware_update",
     "humidity",
     "mute_once",
+    "outdoor_temperature",
     "power_watts",
     "selfcheck_error",
     "selfcheck_result",

tests/fixtures/golden/dishwasher.json

@@ -8,6 +8,7 @@
     "cycle_active",
     "delay_start_hours",
     "diagnosis_status",
+    "drum_clean_cycles_remaining",
     "energy_kwh",
     "energy_saved_kwh",
     "finish_time",
@@ -40,6 +41,7 @@
     "samsung_dishwasher_delay_start_hours",
     "samsung_dishwasher_diagnosis_start",
     "samsung_dishwasher_diagnosis_status",
+    "samsung_dishwasher_drum_clean_cycles_remaining",
     "samsung_dishwasher_energy_kwh",
     "samsung_dishwasher_energy_saved_kwh",
     "samsung_dishwasher_finish_time",

tests/fixtures/golden/dishwasher_dw5000c_cloud.json

@@ -0,0 +1,26 @@
+{
+  "state_keys": [
+    "alarm_code",
+    "auto_release_dry",
+    "child_lock",
+    "completion_minutes",
+    "cycle",
+    "cycle_active",
+    "delay_start_hours",
+    "diagnosis_status",
+    "energy_saved_kwh",
+    "filter_status",
+    "filter_usage",
+    "finish_time",
+    "firmware_update",
+    "heated_dry",
+    "machine_state",
+    "power_switch",
+    "progress",
+    "progress_percentage",
+    "remote_control",
+    "sanitize",
+    "storm_wash",
+    "water_liters"
+  ]
+}

tests/fixtures/golden/dryer_dv6800n.json

@@ -0,0 +1,23 @@
+{
+  "state_keys": [
+    "alarm_code",
+    "child_lock",
+    "completion_minutes",
+    "cycle",
+    "cycle_active",
+    "delay_start_hours",
+    "diagnosis",
+    "dry_level",
+    "dry_time",
+    "dryer_type",
+    "energy_kwh",
+    "finish_time",
+    "job_beginning_status",
+    "machine_state",
+    "power_switch",
+    "progress",
+    "progress_percentage",
+    "remote_control",
+    "wrinkle_prevent"
+  ]
+}

tests/fixtures/golden/gas_cooktop_tp2x_ks.json

@@ -0,0 +1,24 @@
+{
+  "state_keys": [
+    "alarm_code",
+    "any_burner_active",
+    "burner_0_state",
+    "burner_1_state",
+    "burner_2_state",
+    "burner_3_state",
+    "burner_4_state",
+    "burner_5_state",
+    "child_lock",
+    "cloud_connected",
+    "firmware_update",
+    "main_timer_current",
+    "main_timer_state",
+    "paired_hood_connected",
+    "paired_hood_fan_speed",
+    "paired_hood_firmware",
+    "paired_hood_light",
+    "paired_hood_model",
+    "paired_hood_power",
+    "power_state"
+  ]
+}

tests/fixtures/golden/oven_tp2x_ks_walloven.json

@@ -0,0 +1,24 @@
+{
+  "state_keys": [
+    "alarm_code",
+    "child_lock",
+    "cloud_connected",
+    "cook_time",
+    "current_temp_c",
+    "cycle_active",
+    "diagnosis_status",
+    "door_open",
+    "energy_saving",
+    "finish_time",
+    "firmware_update",
+    "machine_state",
+    "operation_time_minutes",
+    "oven_mode",
+    "oven_setpoint",
+    "oven_state",
+    "power_switch",
+    "progress_percentage",
+    "remote_control",
+    "sound"
+  ]
+}

tests/fixtures/golden/range_tp1x_da_ks_range_0101x.json

@@ -0,0 +1,39 @@
+{
+  "state_keys": [
+    "alarm_code",
+    "child_lock",
+    "cloud_connected",
+    "cook_time",
+    "cooktop_on_alert",
+    "cooktop_running_state",
+    "current_temp_c",
+    "cycle_active",
+    "door_open",
+    "energy_saving",
+    "finish_time",
+    "firmware_update",
+    "lamp",
+    "machine_state",
+    "operation_time_minutes",
+    "oven_mode",
+    "oven_setpoint",
+    "oven_state",
+    "power_switch",
+    "progress_percentage",
+    "remote_control",
+    "sound",
+    "subdevice1_cloud_connected",
+    "subdevice1_cook_time",
+    "subdevice1_current_temp_c",
+    "subdevice1_cycle_active",
+    "subdevice1_finish_time",
+    "subdevice1_machine_state",
+    "subdevice1_operation_time_minutes",
+    "subdevice1_oven_mode",
+    "subdevice1_oven_setpoint",
+    "subdevice1_oven_state",
+    "subdevice1_progress_percentage",
+    "subdevice1_sound",
+    "warming_center_state"
+  ]
+}

tests/fixtures/golden/refrigerator_tp1x_ref_21k_airfilter.json

@@ -0,0 +1,36 @@
+{
+  "state_keys": [
+    "ai_energy_level",
+    "air_filter_status",
+    "air_filter_usage",
+    "alarm_code",
+    "auto_door_opener",
+    "brightness_level",
+    "cabinet_light_dim",
+    "cabinet_light_switch",
+    "cooler_setpoint",
+    "cooler_temperature",
+    "day_brightness",
+    "door_alert",
+    "door_cooler_open",
+    "door_freezer_open",
+    "energy_kwh",
+    "energy_saved_kwh",
+    "firmware_update",
+    "freezer_setpoint",
+    "freezer_temperature",
+    "fridge_sound",
+    "ice_night_mode",
+    "icemaker_one_enabled",
+    "icemaker_one_making_status",
+    "night_end",
+    "night_start",
+    "power_energy_kwh",
+    "power_watts",
+    "rapid_freezing",
+    "rapid_fridge",
+    "selfcheck_error",
+    "selfcheck_result",
+    "selfcheck_status"
+  ]
+}

tests/fixtures/golden/refrigerator_tp1x_ref_21k_autodoor.json

@@ -0,0 +1,24 @@
+{
+  "state_keys": [
+    "ai_energy_level",
+    "alarm_code",
+    "auto_door_opener",
+    "auto_door_timer",
+    "auto_door_voice_control",
+    "defrost_active",
+    "door_onedoorfreezer_open",
+    "energy_kwh",
+    "energy_saved_kwh",
+    "firmware_update",
+    "freezer_setpoint",
+    "freezer_temperature",
+    "fridge_sound",
+    "power_energy_kwh",
+    "power_watts",
+    "rapid_freezing",
+    "rapid_fridge",
+    "selfcheck_error",
+    "selfcheck_result",
+    "selfcheck_status"
+  ]
+}

tests/fixtures/golden/refrigerator_tp1x_ref_21k_kimchi.json

@@ -0,0 +1,22 @@
+{
+  "state_keys": [
+    "alarm_code",
+    "auto_door_opener",
+    "auto_door_timer",
+    "auto_door_voice_control",
+    "door_onedoorkimchi_open",
+    "energy_kwh",
+    "energy_saved_kwh",
+    "firmware_update",
+    "fridge_sound",
+    "onedoor_mode",
+    "onedoor_rack_count",
+    "onedoor_ripening_remaining",
+    "onedoor_ripening_status",
+    "power_energy_kwh",
+    "power_watts",
+    "selfcheck_error",
+    "selfcheck_result",
+    "selfcheck_status"
+  ]
+}

tests/fixtures/golden/refrigerator_winecellar.json

@@ -0,0 +1,26 @@
+{
+  "state_keys": [
+    "alarm_code",
+    "auto_door_opener",
+    "auto_door_sound_control",
+    "auto_door_timer",
+    "auto_door_voice_control",
+    "cabinet_light_dim",
+    "cabinet_light_switch",
+    "deodor_filter_status",
+    "deodor_filter_usage",
+    "door_winecellar_open",
+    "energy_kwh",
+    "energy_saved_kwh",
+    "firmware_update",
+    "fridge_sound",
+    "power_energy_kwh",
+    "power_watts",
+    "selfcheck_error",
+    "selfcheck_result",
+    "selfcheck_status",
+    "winecellar_bottom_setpoint",
+    "winecellar_pantry_zone_mode",
+    "winecellar_top_setpoint"
+  ]
+}

tests/fixtures/golden/washer_dryer_combo.json

@@ -1,5 +1,11 @@
 {
   "state_keys": [
+    "add_wash_alarm",
+    "add_wash_alarm_final_rinse",
+    "add_wash_alarm_rinse",
+    "add_wash_alarm_spin",
+    "add_wash_available",
+    "add_wash_indicator",
     "alarm_code",
     "bubble_soak",
     "child_lock",

tests/fixtures/golden/washer_ww5000c_cloud.json

@@ -0,0 +1,34 @@
+{
+  "state_keys": [
+    "alarm_code",
+    "bubble_soak",
+    "buzzer_sound",
+    "child_lock",
+    "completion_minutes",
+    "cycle",
+    "cycle_active",
+    "delay_start_hours",
+    "detergent_low",
+    "diagnosis_status",
+    "drum_clean_cycles_remaining",
+    "drum_clean_last_cleaned",
+    "energy_kwh",
+    "energy_saved_kwh",
+    "finish_sound",
+    "finish_time",
+    "firmware_update",
+    "intensive",
+    "job_beginning_status",
+    "machine_state",
+    "power_switch",
+    "pre_wash",
+    "progress",
+    "progress_percentage",
+    "remote_control",
+    "rinse_cycles",
+    "softener_low",
+    "spin_speed",
+    "wash_temperature",
+    "water_liters"
+  ]
+}

tests/fixtures/golden/washer_ww6500.json

@@ -0,0 +1,28 @@
+{
+  "state_keys": [
+    "add_wash_alarm",
+    "add_wash_alarm_final_rinse",
+    "add_wash_alarm_rinse",
+    "add_wash_alarm_spin",
+    "add_wash_available",
+    "add_wash_indicator",
+    "alarm_code",
+    "child_lock",
+    "completion_minutes",
+    "cycle",
+    "cycle_active",
+    "delay_start_hours",
+    "diagnosis_status",
+    "energy_kwh",
+    "finish_time",
+    "job_beginning_status",
+    "machine_state",
+    "power_switch",
+    "progress",
+    "progress_percentage",
+    "remote_control",
+    "rinse_cycles",
+    "spin_speed",
+    "wash_temperature"
+  ]
+}

tests/fixtures/oven_tp2x_ks_walloven_device.json

@@ -0,0 +1,260 @@
+{
+  "device0": [
+    {
+      "rt": [
+        "x.com.samsung.devcol",
+        "oic.wk.col"
+      ],
+      "if": [
+        "oic.if.baseline",
+        "oic.if.ll",
+        "oic.if.b"
+      ]
+    },
+    {
+      "href": "/alarms/vs/0",
+      "rep": {
+        "rt": [
+          "x.com.samsung.da.alarms"
+        ],
+        "if": [
+          "oic.if.baseline",
+          "oic.if.s"
+        ],
+        "x.com.samsung.da.items": [
+          {
+            "x.com.samsung.da.id": "0",
+            "x.com.samsung.da.description": "Alarm",
+            "x.com.samsung.da.alarmType": "Device",
+            "x.com.samsung.da.code": "OV_E_OFF",
+            "x.com.samsung.da.triggeredTime": "2026-08-05T14:20:14"
+          }
+        ]
+      }
+    },
+    {
+      "href": "/connected/vs/0",
+      "rep": {
+        "x.com.samsung.da.connected": "On",
+        "rt": [
+          "x.com.samsung.da.connected"
+        ],
+        "if": [
+          "oic.if.baseline",
+          "oic.if.s"
+        ]
+      }
+    },
+    {
+      "href": "/diagnosis/vs/0",
+      "rep": {
+        "x.com.samsung.da.diagnosisStart": "Ready"
+      }
+    },
+    {
+      "href": "/doors/vs/0",
+      "rep": {
+        "x.com.samsung.da.items": [
+          {
+            "x.com.samsung.da.id": "0",
+            "x.com.samsung.da.description": "Door",
+            "x.com.samsung.da.openState": "Close",
+            "x.com.samsung.da.lock": "Unlock"
+          }
+        ],
+        "rt": [
+          "x.com.samsung.da.doors"
+        ],
+        "if": [
+          "oic.if.baseline",
+          "oic.if.s"
+        ]
+      }
+    },
+    {
+      "href": "/information/vs/0",
+      "rep": {
+        "x.com.samsung.da.modelNum": "TP2X_DA-KS-WALLOVEN-000002|40441841|5002011E021011150100000000000000",
+        "x.com.samsung.da.description": "NW9000KD/AA1",
+        "x.com.samsung.da.serialNum": "**REDACTED**",
+        "x.com.samsung.da.otnDUID": "**REDACTED**",
+        "x.com.samsung.da.items": [
+          {
+            "x.com.samsung.da.id": "0",
+            "x.com.samsung.da.description": "Version",
+            "x.com.samsung.da.type": "Software",
+            "x.com.samsung.da.number": "240205",
+            "x.com.samsung.da.newVersionAvailable": "0"
+          },
+          {
+            "x.com.samsung.da.id": "1",
+            "x.com.samsung.da.description": "Version",
+            "x.com.samsung.da.type": "Firmware",
+            "x.com.samsung.da.number": "DE92-04418A_20062500, DE92-04011A_17041300",
+            "x.com.samsung.da.newVersionAvailable": "0"
+          }
+        ],
+        "x.com.samsung.da.diagProtocolType": "WIFI_HTTPS",
+        "x.com.samsung.da.diagLogType": [
+          "errCode",
+          "dump"
+        ],
+        "x.com.samsung.da.diagDumpType": "file",
+        "x.com.samsung.da.diagEndPoint": "SSM",
+        "x.com.samsung.da.diagMnid": "0AJT",
+        "x.com.samsung.da.diagSetupid": "610",
+        "x.com.samsung.da.diagMinVersion": "1.0"
+      }
+    },
+    {
+      "href": "/kidslock/vs/0",
+      "rep": {
+        "x.com.samsung.da.kidsLock": "Ready"
+      }
+    },
+    {
+      "href": "/mode/vs/0",
+      "rep": {
+        "x.com.samsung.da.supportedModes": [
+          "ConvectionBake",
+          "ConvectionRoast",
+          "Bake",
+          "Broil",
+          "SteamBake",
+          "SteamRoast",
+          "Easycook3",
+          "Descale",
+          "PyroFree",
+          "Drain",
+          "SelfClean",
+          "NoOperation"
+        ],
+        "x.com.samsung.da.modes": [
+          "NoOperation"
+        ],
+        "x.com.samsung.da.options": [
+          "DeviceType_NW9000KD/AA1",
+          "keepWarmReservation_Off",
+          "meatprobe_disconnected",
+          "NoPreheat_Off",
+          "waterInlet_Closed",
+          "steamAddLevel_0",
+          "descaleAlarm_Normal",
+          "descaleNewWaterAlarm_Off",
+          "descaleEmptyWaterAlarm_Off",
+          "steamGeneratorLevel_Empty",
+          "steamUsingTime_66",
+          "drainRequired_00",
+          "steamState_Standby",
+          "descaleState_Standby",
+          "waterTankInSwitch_On",
+          "pyroFreeState_Standby",
+          "waterTankOutSwitch_Off",
+          "Sound_On",
+          "AdjustingTemp_0",
+          "Sabbath_Off",
+          "EnergySaving_On"
+        ],
+        "rt": [
+          "x.com.samsung.da.mode"
+        ],
+        "if": [
+          "oic.if.baseline",
+          "oic.if.a"
+        ]
+      }
+    },
+    {
+      "href": "/operational/state/vs/0",
+      "rep": {
+        "x.com.samsung.da.state": "Ready",
+        "x.com.samsung.da.operationTime": "00:00:00",
+        "x.com.samsung.da.remainingTime": "00:00:00",
+        "x.com.samsung.da.progressPercentage": "1",
+        "rt": [
+          "x.com.samsung.da.operation"
+        ],
+        "if": [
+          "oic.if.baseline",
+          "oic.if.a"
+        ]
+      }
+    },
+    {
+      "href": "/otninformation/vs/0",
+      "rep": {
+        "x.com.samsung.da.target": "",
+        "x.com.samsung.da.newVersionAvailable": "false"
+      }
+    },
+    {
+      "href": "/oven/vs/0",
+      "rep": {
+        "x.com.samsung.da.state": "Ready",
+        "rt": [
+          "x.com.samsung.da.oven"
+        ],
+        "if": [
+          "oic.if.baseline",
+          "oic.if.s"
+        ]
+      }
+    },
+    {
+      "href": "/power/vs/0",
+      "rep": {
+        "x.com.samsung.da.power": "On",
+        "rt": [
+          "x.com.samsung.da.operation"
+        ],
+        "if": [
+          "oic.if.baseline",
+          "oic.if.s"
+        ]
+      }
+    },
+    {
+      "href": "/remotectrl/vs/0",
+      "rep": {
+        "x.com.samsung.da.remoteControlEnabled": "false",
+        "rt": [
+          "x.com.samsung.da.configuration"
+        ],
+        "if": [
+          "oic.if.baseline",
+          "oic.if.s"
+        ]
+      }
+    },
+    {
+      "href": "/temperatures/vs/0",
+      "rep": {
+        "x.com.samsung.da.items": [
+          {
+            "x.com.samsung.da.id": "0",
+            "x.com.samsung.da.description": "Temperature",
+            "x.com.samsung.da.desired": "0",
+            "x.com.samsung.da.current": "0",
+            "x.com.samsung.da.increment": "0",
+            "x.com.samsung.da.unit": "Fahrenheit"
+          },
+          {
+            "x.com.samsung.da.id": "1",
+            "x.com.samsung.da.description": "Temperature",
+            "x.com.samsung.da.desired": "0",
+            "x.com.samsung.da.current": "0",
+            "x.com.samsung.da.increment": "0",
+            "x.com.samsung.da.unit": "Fahrenheit"
+          }
+        ],
+        "rt": [
+          "x.com.samsung.da.temperatures"
+        ],
+        "if": [
+          "oic.if.baseline",
+          "oic.if.a"
+        ]
+      }
+    }
+  ]
+}

tests/fixtures/refrigerator_tp1x_ref_21k_airfilter_device.json

@@ -0,0 +1,623 @@
+{
+  "device0": [
+    {
+      "rt": [
+        "x.com.samsung.devcol",
+        "oic.wk.col"
+      ],
+      "if": [
+        "oic.if.baseline",
+        "oic.if.ll",
+        "oic.if.b"
+      ]
+    },
+    {
+      "href": "/alarms/vs/0",
+      "rep": {
+        "href": "/alarms/vs/0",
+        "rt": [
+          "x.com.samsung.da.alarms"
+        ],
+        "if": [
+          "oic.if.baseline",
+          "oic.if.a"
+        ]
+      }
+    },
+    {
+      "href": "/bespoke/vs/0",
+      "rep": {
+        "x.com.samsung.da.BespokeProduct": "On",
+        "href": "/bespoke/vs/0"
+      }
+    },
+    {
+      "href": "/cabinet/light/enhanced/vs/0",
+      "rep": {
+        "light.control.status": "On",
+        "level.brightness.daytime": "100",
+        "level.brightness.nighttime": "33",
+        "night.starttime": "2026-08-07T12:00:00",
+        "night.duration.minute": "540",
+        "timezone.offset": "+09:00",
+        "href": "/cabinet/light/enhanced/vs/0",
+        "rt": [
+          "x.com.samsung.da.light.enhanced"
+        ],
+        "if": [
+          "oic.if.baseline",
+          "oic.if.a"
+        ]
+      }
+    },
+    {
+      "href": "/cabinet/light/total/vs/0",
+      "rep": {
+        "x.com.samsung.da.lightLevel": "100",
+        "x.com.samsung.da.lightResolution": "3",
+        "x.com.samsung.da.lightControl.off.include": "Off",
+        "x.com.samsung.da.lightControl": "Off",
+        "x.com.samsung.da.lightControl.hide": "true",
+        "light.dimming.status": "On",
+        "href": "/cabinet/light/total/vs/0",
+        "rt": [
+          "x.com.samsung.da.cabinetlight"
+        ],
+        "if": [
+          "oic.if.baseline",
+          "oic.if.a"
+        ]
+      }
+    },
+    {
+      "href": "/configuration/vs/0",
+      "rep": {
+        "x.com.samsung.da.region": "",
+        "x.com.samsung.da.countryCode": "",
+        "href": "/configuration/vs/0"
+      }
+    },
+    {
+      "href": "/connectionconfig/vs/0",
+      "rep": {
+        "autoReconnectionMinVersion": "1.0",
+        "autoReconnection": "true",
+        "autoReconnectionProtocolType": [
+          "helper_hotspot",
+          "ble_ocf"
+        ],
+        "supportedWiFiAuthType": [
+          "OPEN",
+          "WEP",
+          "WPA-PSK",
+          "WPA2-PSK",
+          "SAE"
+        ],
+        "supportedWiFiCryptoType": [
+          "TKIP",
+          "AES",
+          "WEP-64",
+          "WEP-128"
+        ],
+        "supportedWiFiFreq": [
+          "2.4G"
+        ],
+        "calmConnectionCare": {
+          "version": "1.0",
+          "role": [
+            "things"
+          ]
+        }
+      }
+    },
+    {
+      "href": "/defrost/prediction/vs/0",
+      "rep": {
+        "ai.cooling.care": "Off",
+        "href": "/defrost/prediction/vs/0"
+      }
+    },
+    {
+      "href": "/dginformation/vs/0",
+      "rep": {
+        "enrolmentstatus": "Unknown",
+        "devicestate": "Unknown",
+        "lockstatus": "Normal",
+        "nextduedate": "",
+        "workingminutes": 0,
+        "paymentinfo": {
+          "emiplan": "Unknown",
+          "currency": "Unknown",
+          "totalemi": 0,
+          "totalemipaid": 0
+        }
+      }
+    },
+    {
+      "href": "/door/cooler/0",
+      "rep": {
+        "openState": "Close",
+        "href": "/door/cooler/0",
+        "rt": [
+          "oic.r.door"
+        ],
+        "if": [
+          "oic.if.baseline",
+          "oic.if.s"
+        ]
+      }
+    },
+    {
+      "href": "/door/freezer/0",
+      "rep": {
+        "openState": "Close",
+        "href": "/door/freezer/0",
+        "rt": [
+          "oic.r.door"
+        ],
+        "if": [
+          "oic.if.baseline",
+          "oic.if.s"
+        ]
+      }
+    },
+    {
+      "href": "/doors/vs/0",
+      "rep": {
+        "x.com.samsung.da.items": [
+          {
+            "x.com.samsung.da.openState": "Close",
+            "x.com.samsung.da.id": "0",
+            "x.com.samsung.da.description": "Door"
+          },
+          {
+            "x.com.samsung.da.openState": "Close",
+            "x.com.samsung.da.id": "1",
+            "x.com.samsung.da.description": "Door"
+          }
+        ],
+        "href": "/doors/vs/0"
+      }
+    },
+    {
+      "href": "/drlc/vs/0",
+      "rep": {
+        "x.com.samsung.da.drlcLevel": "2",
+        "x.com.samsung.da.override": "Not_Supported",
+        "x.com.samsung.da.durationminutes": "1441",
+        "x.com.samsung.da.start": "2026-08-07T00:00:41Z",
+        "x.com.samsung.da.realSaving": "On",
+        "href": "/drlc/vs/0"
+      }
+    },
+    {
+      "href": "/energy/ailevel/vs/0",
+      "rep": {
+        "aiLevel": "1",
+        "supportedAiLevel": [
+          "1",
+          "2"
+        ],
+        "href": "/energy/ailevel/vs/0"
+      }
+    },
+    {
+      "href": "/energy/consumption/vs/0",
+      "rep": {
+        "x.com.samsung.da.cumulativeConsumption": "25344",
+        "x.com.samsung.da.instantaneousPower": "48",
+        "x.com.samsung.da.cumulativePower": "413385",
+        "x.com.samsung.da.cumulativeSavedPower": "50694",
+        "x.com.samsung.da.cumulativeUnit": "Wh",
+        "x.com.samsung.da.instantaneousPowerUnit": "W",
+        "href": "/energy/consumption/vs/0",
+        "x.com.samsung.da.cumulativeDateUTC": "1786020360"
+      }
+    },
+    {
+      "href": "/file/information/vs/0",
+      "rep": {
+        "x.com.samsung.timeoffset": "+09:00",
+        "x.com.samsung.supprtedtype": 1,
+        "href": "/file/information/vs/0"
+      }
+    },
+    {
+      "href": "/filter/airdustfilter/vs/0",
+      "rep": {
+        "x.com.samsung.da.filterUsage": "100",
+        "x.com.samsung.da.filterUsageResolution": "1",
+        "x.com.samsung.da.filterResetType": [
+          "washable"
+        ],
+        "x.com.samsung.da.filterStatus": "wash",
+        "href": "/filter/airdustfilter/vs/0"
+      }
+    },
+    {
+      "href": "/icemaker/nighttime/vs/0",
+      "rep": {
+        "ice.night.status": "On",
+        "ice.night.starttime": "2026-08-07T12:00:00",
+        "ice.night.duration": "540",
+        "ice.night.timezone": "+09:00",
+        "href": "/icemaker/nighttime/vs/0",
+        "rt": [
+          "x.com.samsung.da.ice.night"
+        ],
+        "if": [
+          "oic.if.baseline",
+          "oic.if.a"
+        ]
+      }
+    },
+    {
+      "href": "/icemaker/one/vs/0",
+      "rep": {
+        "x.com.samsung.da.iceMaker.name": "ICE_MAKER",
+        "x.com.samsung.da.iceMaker.state": "On",
+        "x.com.samsung.da.iceType.desired": "NORMAL",
+        "x.com.samsung.da.iceMaker.iceMakingStatus": "ICESTATUS_STOP",
+        "x.com.samsung.da.iceMaker.type": "toggle",
+        "href": "/icemaker/one/vs/0",
+        "rt": [
+          "x.com.samsung.da.icemaker"
+        ],
+        "if": [
+          "oic.if.baseline",
+          "oic.if.a"
+        ]
+      }
+    },
+    {
+      "href": "/icemaker/status/vs/0",
+      "rep": {
+        "x.com.samsung.da.iceMaker": "On",
+        "href": "/icemaker/status/vs/0"
+      }
+    },
+    {
+      "href": "/information/vs/0",
+      "rep": {
+        "x.com.samsung.da.modelNum": "TP1X_REF_21K|70664141|0000033C011913114100000041FB5F00",
+        "x.com.samsung.da.description": "TP1X_REF_21K",
+        "x.com.samsung.da.serialNum": "**REDACTED**",
+        "x.com.samsung.da.otnDUID": "**REDACTED**",
+        "x.com.samsung.da.diagDumpType": "file",
+        "x.com.samsung.da.diagEndPoint": "SSM",
+        "x.com.samsung.da.diagLogType": [
+          "errCode",
+          "dump"
+        ],
+        "x.com.samsung.da.diagMnid": "0AJT",
+        "x.com.samsung.da.diagSetupid": "RR7",
+        "x.com.samsung.da.diagProtocolType": "BLE_OCF",
+        "x.com.samsung.da.diagMinVersion": "3.0",
+        "x.com.samsung.da.diagTsId": "DA01",
+        "x.com.samsung.da.items": [
+          {
+            "x.com.samsung.da.id": "0",
+            "x.com.samsung.da.description": "WiFi Module",
+            "x.com.samsung.da.type": "Software",
+            "x.com.samsung.da.number": "260618",
+            "x.com.samsung.da.newVersionAvailable": "0"
+          },
+          {
+            "x.com.samsung.da.id": "1",
+            "x.com.samsung.da.description": "Micom",
+            "x.com.samsung.da.type": "Firmware",
+            "x.com.samsung.da.number": "2605071D, 24120906, 26040701, FFFFFFFF, 25082208, FFFFFFFF",
+            "x.com.samsung.da.newVersionAvailable": "0"
+          }
+        ],
+        "href": "/information/vs/0"
+      }
+    },
+    {
+      "href": "/mode/vs/0",
+      "rep": {
+        "x.com.samsung.da.supportedModes": [
+          "HOMECARE_WIZARD_V2",
+          "ENERGY_REPORT_MODEL",
+          "18K_REF_OUTDOOR_CONTROL_V2"
+        ],
+        "href": "/mode/vs/0",
+        "rt": [
+          "x.com.samsung.da.mode"
+        ],
+        "if": [
+          "oic.if.baseline",
+          "oic.if.a"
+        ]
+      }
+    },
+    {
+      "href": "/otninformation/vs/0",
+      "rep": {
+        "x.com.samsung.da.target": "Micom",
+        "x.com.samsung.da.newVersionAvailable": "false",
+        "x.com.samsung.da.newVersionNo": "26040701",
+        "x.com.samsung.da.currentVersionInfo": "10000000",
+        "otnStatus": "None",
+        "flashingProgress": "0",
+        "otnTarget": "inverter",
+        "otnCompleteDate": "noHistory",
+        "scheduledTime": "None",
+        "swVersionInfo": {
+          "platform": "Tizen Lite",
+          "oneUiVersion": "7.0 Refrigerator",
+          "osVersion": "4.0"
+        },
+        "otnList": [
+          {
+            "type": "WIFI",
+            "modelId": "A-RFWW-TP1-24-T4-RE1",
+            "versions": [
+              "20260618"
+            ],
+            "visVersion": "260618"
+          },
+          {
+            "type": "Micom",
+            "modelId": "823070664141FFFFFFFF",
+            "versions": [
+              "2605071D",
+              "FFFFFFFF"
+            ],
+            "visVersion": "260507"
+          },
+          {
+            "type": "Micom",
+            "modelId": "823070664041FFFFFFFF",
+            "versions": [
+              "24120906",
+              "FFFFFFFF"
+            ],
+            "visVersion": "241209"
+          },
+          {
+            "type": "Micom",
+            "modelId": "02307066414170664041",
+            "versions": [
+              "2605071D",
+              "24120906"
+            ],
+            "visVersion": "260507"
+          },
+          {
+            "type": "Micom",
+            "modelId": "023070680641FFFFFFFF",
+            "versions": [
+              "26040701",
+              "FFFFFFFF"
+            ],
+            "visVersion": "260407"
+          },
+          {
+            "type": "Micom",
+            "modelId": "023070668841FFFFFFFF",
+            "versions": [
+              "25082208",
+              "FFFFFFFF"
+            ],
+            "visVersion": "250822"
+          }
+        ]
+      }
+    },
+    {
+      "href": "/quickcontrol/info/vs/0",
+      "rep": {
+        "supportedVersion": "1.0"
+      }
+    },
+    {
+      "href": "/realtimenotiforclient/vs/0",
+      "rep": {
+        "x.com.samsung.da.timeforshortnoti": "0",
+        "x.com.samsung.da.periodicnotisubscription": "true",
+        "href": "/realtimenotiforclient/vs/0"
+      }
+    },
+    {
+      "href": "/refrigeration/vs/0",
+      "rep": {
+        "x.com.samsung.da.rapidFridge": "Off",
+        "x.com.samsung.da.rapidFreezing": "Off",
+        "href": "/refrigeration/vs/0",
+        "rt": [
+          "x.com.samsung.da.fridge"
+        ],
+        "if": [
+          "oic.if.baseline",
+          "oic.if.a"
+        ]
+      }
+    },
+    {
+      "href": "/rm/control/vs/0",
+      "rep": {
+        "minPeriod": "9000",
+        "href": "/rm/control/vs/0"
+      }
+    },
+    {
+      "href": "/runningmode/vs/0",
+      "rep": {
+        "x.com.samsung.da.runningMode": 0,
+        "href": "/runningmode/vs/0"
+      }
+    },
+    {
+      "href": "/selfcheck/vs/0",
+      "rep": {
+        "x.com.samsung.da.supportedActions": [
+          "Start"
+        ],
+        "x.com.samsung.da.status": "Ready",
+        "x.com.samsung.da.result": "Success",
+        "x.com.samsung.da.error": [
+          "ErrorCode_None"
+        ],
+        "href": "/selfcheck/vs/0"
+      }
+    },
+    {
+      "href": "/settings/sound/alert/door/vs/0",
+      "rep": {
+        "alert.door": "1",
+        "supportedAlert.door": [
+          "1",
+          "2",
+          "3",
+          "4"
+        ],
+        "href": "/settings/sound/alert/door/vs/0",
+        "rt": [
+          "x.com.samsung.alert.door"
+        ],
+        "if": [
+          "oic.if.baseline",
+          "oic.if.a"
+        ]
+      }
+    },
+    {
+      "href": "/status/lock/vs/0",
+      "rep": {
+        "x.com.samsung.da.device.sound": "On",
+        "x.com.samsung.da.preciseCooling": "On",
+        "x.com.samsung.da.doorAlarmSound": "On",
+        "cleaning.status": "On",
+        "cleaning.type": "SPI_AND_UV",
+        "href": "/status/lock/vs/0",
+        "rt": [
+          "x.com.samsung.da.lockstatus"
+        ],
+        "if": [
+          "oic.if.baseline",
+          "oic.if.a"
+        ]
+      }
+    },
+    {
+      "href": "/temperature/current/cooler/0",
+      "rep": {
+        "temperature": 2.0,
+        "range": [
+          1.0,
+          7.0
+        ],
+        "units": "C",
+        "href": "/temperature/current/cooler/0",
+        "rt": [
+          "oic.r.temperature"
+        ],
+        "if": [
+          "oic.if.baseline",
+          "oic.if.a"
+        ]
+      }
+    },
+    {
+      "href": "/temperature/current/freezer/0",
+      "rep": {
+        "temperature": -19.0,
+        "range": [
+          -23.0,
+          -15.0
+        ],
+        "units": "C",
+        "href": "/temperature/current/freezer/0",
+        "rt": [
+          "oic.r.temperature"
+        ],
+        "if": [
+          "oic.if.baseline",
+          "oic.if.a"
+        ]
+      }
+    },
+    {
+      "href": "/temperature/desired/cooler/0",
+      "rep": {
+        "temperature": 2.0,
+        "range": [
+          1.0,
+          7.0
+        ],
+        "units": "C",
+        "href": "/temperature/desired/cooler/0",
+        "rt": [
+          "oic.r.temperature"
+        ],
+        "if": [
+          "oic.if.baseline",
+          "oic.if.a"
+        ]
+      }
+    },
+    {
+      "href": "/temperature/desired/freezer/0",
+      "rep": {
+        "temperature": -19.0,
+        "range": [
+          -23.0,
+          -15.0
+        ],
+        "units": "C",
+        "href": "/temperature/desired/freezer/0",
+        "rt": [
+          "oic.r.temperature"
+        ],
+        "if": [
+          "oic.if.baseline",
+          "oic.if.a"
+        ]
+      }
+    },
+    {
+      "href": "/temperatures/vs/0",
+      "rep": {
+        "temperature.unit.control": "true",
+        "x.com.samsung.da.items": [
+          {
+            "x.com.samsung.da.id": "0",
+            "x.com.samsung.da.description": "Freezer",
+            "x.com.samsung.da.desired": "-19",
+            "x.com.samsung.da.current": "-19",
+            "x.com.samsung.da.maximum": "-15",
+            "x.com.samsung.da.minimum": "-23",
+            "x.com.samsung.da.unit": "Celsius"
+          },
+          {
+            "x.com.samsung.da.id": "1",
+            "x.com.samsung.da.description": "Fridge",
+            "x.com.samsung.da.desired": "2",
+            "x.com.samsung.da.current": "2",
+            "x.com.samsung.da.maximum": "7",
+            "x.com.samsung.da.minimum": "1",
+            "x.com.samsung.da.unit": "Celsius"
+          }
+        ],
+        "href": "/temperatures/vs/0"
+      }
+    },
+    {
+      "href": "/timezone/vs/0",
+      "rep": {
+        "timezoneid": "Asia/Seoul",
+        "offset": "+09:00",
+        "DST": "OFF"
+      }
+    },
+    {
+      "href": "/wirelessinfo/vs/0",
+      "rep": {
+        "macaddressWiFi": "**REDACTED**",
+        "macaddressBLE": "**REDACTED**",
+        "connectedApSsid": "eomkim_IoT"
+      }
+    }
+  ]
+}

tests/fixtures/refrigerator_tp1x_ref_21k_autodoor_device.json

@@ -0,0 +1,343 @@
+{
+  "device0": [
+    {
+      "rt": [
+        "x.com.samsung.devcol",
+        "oic.wk.col"
+      ],
+      "if": [
+        "oic.if.baseline",
+        "oic.if.ll",
+        "oic.if.b"
+      ]
+    },
+    {
+      "href": "/alarms/vs/0",
+      "rep": {}
+    },
+    {
+      "href": "/temperatures/vs/0",
+      "rep": {
+        "x.com.samsung.da.items": [
+          {
+            "x.com.samsung.da.id": "0",
+            "x.com.samsung.da.description": "Freezer",
+            "x.com.samsung.da.desired": "-19",
+            "x.com.samsung.da.current": "-19",
+            "x.com.samsung.da.maximum": "-17",
+            "x.com.samsung.da.minimum": "-23",
+            "x.com.samsung.da.unit": "Celsius"
+          }
+        ]
+      }
+    },
+    {
+      "href": "/temperature/current/freezer/0",
+      "rep": {
+        "range": [
+          -23.0,
+          -17.0
+        ],
+        "units": "C",
+        "temperature": -19.0
+      }
+    },
+    {
+      "href": "/temperature/desired/freezer/0",
+      "rep": {
+        "range": [
+          -23.0,
+          -17.0
+        ],
+        "units": "C",
+        "temperature": -19.0
+      }
+    },
+    {
+      "href": "/selfcheck/vs/0",
+      "rep": {
+        "x.com.samsung.da.status": "Ready",
+        "x.com.samsung.da.result": "Success",
+        "x.com.samsung.da.error": [
+          "DA_ERROR_NONE"
+        ],
+        "x.com.samsung.da.supportedActions": [
+          "Start"
+        ]
+      }
+    },
+    {
+      "href": "/energy/consumption/vs/0",
+      "rep": {
+        "x.com.samsung.da.cumulativeConsumption": "41042",
+        "x.com.samsung.da.cumulativePower": "466708",
+        "x.com.samsung.da.cumulativeUnit": "Wh",
+        "x.com.samsung.da.instantaneousPower": "4",
+        "x.com.samsung.da.instantaneousPowerUnit": "W",
+        "x.com.samsung.da.cumulativeSavedPower": "15759"
+      }
+    },
+    {
+      "href": "/mode/vs/0",
+      "rep": {
+        "x.com.samsung.da.supportedModes": [
+          "HOMECARE_WIZARD_V2",
+          "ENERGY_REPORT_MODEL",
+          "18K_REF_OUTDOOR_CONTROL_V2"
+        ]
+      }
+    },
+    {
+      "href": "/mode/0",
+      "rep": {
+        "supportedModes": [
+          "HOMECARE_WIZARD_V2",
+          "ENERGY_REPORT_MODEL",
+          "18K_REF_OUTDOOR_CONTROL_V2"
+        ]
+      }
+    },
+    {
+      "href": "/realtimenotiforclient/vs/0",
+      "rep": {
+        "x.com.samsung.da.timeforshortnoti": "0",
+        "x.com.samsung.da.periodicnotisubscription": "true"
+      }
+    },
+    {
+      "href": "/information/vs/0",
+      "rep": {
+        "x.com.samsung.da.modelNum": "TP1X_REF_21K|00168541|00080023001713104100000041010000",
+        "x.com.samsung.da.description": "TP1X_REF_21K",
+        "x.com.samsung.da.serialNum": "**REDACTED**",
+        "x.com.samsung.da.otnDUID": "**REDACTED**",
+        "x.com.samsung.da.diagProtocolType": "BLE_OCF",
+        "x.com.samsung.da.diagLogType": [
+          "errCode",
+          "dump"
+        ],
+        "x.com.samsung.da.diagDumpType": "file",
+        "x.com.samsung.da.diagEndPoint": "SSM",
+        "x.com.samsung.da.diagMnid": "0AJT",
+        "x.com.samsung.da.diagSetupid": "RO6",
+        "x.com.samsung.da.diagMinVersion": "3.0",
+        "x.com.samsung.da.diagTsId": "DA01",
+        "x.com.samsung.da.items": [
+          {
+            "x.com.samsung.da.id": "0",
+            "x.com.samsung.da.description": "WiFi Module",
+            "x.com.samsung.da.type": "Software",
+            "x.com.samsung.da.number": "250422",
+            "x.com.samsung.da.newVersionAvailable": "0"
+          },
+          {
+            "x.com.samsung.da.id": "1",
+            "x.com.samsung.da.description": "Micom",
+            "x.com.samsung.da.type": "Firmware",
+            "x.com.samsung.da.number": "24101709, 23031302, 24062000, FFFFFFFF",
+            "x.com.samsung.da.newVersionAvailable": "0"
+          }
+        ]
+      }
+    },
+    {
+      "href": "/file/information/vs/0",
+      "rep": {
+        "x.com.samsung.timeoffset": "+09:00",
+        "x.com.samsung.supprtedtype": 1
+      }
+    },
+    {
+      "href": "/doors/vs/0",
+      "rep": {
+        "x.com.samsung.da.items": [
+          {
+            "x.com.samsung.da.id": "3",
+            "x.com.samsung.da.description": "Door",
+            "x.com.samsung.da.openState": "Close"
+          }
+        ]
+      }
+    },
+    {
+      "href": "/door/onedoorfreezer/vs/0",
+      "rep": {
+        "x.com.samsung.da.openState": "Close"
+      }
+    },
+    {
+      "href": "/configuration/vs/0",
+      "rep": {
+        "x.com.samsung.da.countryCode": "",
+        "x.com.samsung.da.region": ""
+      }
+    },
+    {
+      "href": "/refrigeration/0",
+      "rep": {
+        "defrost": false,
+        "rapidFreeze": false,
+        "rapidCool": false
+      }
+    },
+    {
+      "href": "/refrigeration/vs/0",
+      "rep": {
+        "x.com.samsung.da.rapidFreezing": "Off"
+      }
+    },
+    {
+      "href": "/drlc/0",
+      "rep": {
+        "DRLevel": 2,
+        "override": false
+      }
+    },
+    {
+      "href": "/drlc/vs/0",
+      "rep": {
+        "x.com.samsung.da.drlcLevel": "2",
+        "x.com.samsung.da.override": "Not_Supported",
+        "x.com.samsung.da.durationminutes": "1441",
+        "x.com.samsung.da.start": "2026-08-06T00:34:47Z",
+        "x.com.samsung.da.realSaving": "On"
+      }
+    },
+    {
+      "href": "/bespoke/vs/0",
+      "rep": {
+        "x.com.samsung.da.BespokeProduct": "On"
+      }
+    },
+    {
+      "href": "/otninformation/vs/0",
+      "rep": {
+        "x.com.samsung.da.target": "",
+        "x.com.samsung.da.newVersionAvailable": "false",
+        "otnStatus": "None",
+        "flashingProgress": "",
+        "otnList": [
+          {
+            "type": "WIFI",
+            "modelId": "A-RFWW-TP1-23-COMMON",
+            "versions": [
+              "20250422"
+            ],
+            "visVersion": "250422"
+          },
+          {
+            "type": "Micom",
+            "modelId": "02800016854100168441",
+            "versions": [
+              "24101709",
+              "23031302"
+            ],
+            "visVersion": "241017"
+          },
+          {
+            "type": "Micom",
+            "modelId": "028070655341FFFFFFFF",
+            "versions": [
+              "24062000",
+              "FFFFFFFF"
+            ],
+            "visVersion": "240620"
+          }
+        ]
+      }
+    },
+    {
+      "href": "/status/lock/vs/0",
+      "rep": {
+        "x.com.samsung.da.ado.voicecontrol": "Off",
+        "x.com.samsung.da.device.sound": "On"
+      }
+    },
+    {
+      "href": "/energy/ailevel/vs/0",
+      "rep": {
+        "aiLevel": "1",
+        "supportedAiLevel": [
+          "1",
+          "2"
+        ]
+      }
+    },
+    {
+      "href": "/autodoor/timer/vs/0",
+      "rep": {
+        "x.com.samsung.da.time.desired": "1",
+        "x.com.samsung.da.time.supportedOptions": [
+          "1",
+          "2",
+          "3",
+          "4",
+          "5",
+          "6"
+        ]
+      }
+    },
+    {
+      "href": "/autodoor/single/vs/0",
+      "rep": {
+        "x.com.samsung.da.ado.openOptions": [
+          "Single"
+        ]
+      }
+    },
+    {
+      "href": "/connectionconfig/vs/0",
+      "rep": {
+        "autoReconnectionMinVersion": "1.0",
+        "autoReconnection": "true",
+        "autoReconnectionProtocolType": [
+          "ble_ocf",
+          null
+        ],
+        "supportedWiFiAuthType": [
+          "OPEN",
+          "WEP",
+          "WPA-PSK",
+          "WPA2-PSK",
+          "SAE"
+        ],
+        "supportedWiFiCryptoType": [
+          "TKIP",
+          "AES",
+          "WEP-64",
+          "WEP-128"
+        ],
+        "supportedWiFiFreq": [
+          "2.4G"
+        ],
+        "calmConnectionCare": {
+          "version": "1.0",
+          "role": [
+            "things"
+          ]
+        }
+      }
+    },
+    {
+      "href": "/timezone/vs/0",
+      "rep": {
+        "timezoneid": "Asia/Seoul",
+        "offset": "+09:00",
+        "DST": "OFF"
+      }
+    },
+    {
+      "href": "/wirelessinfo/vs/0",
+      "rep": {
+        "macaddressWiFi": "**REDACTED**",
+        "macaddressBLE": "**REDACTED**"
+      }
+    },
+    {
+      "href": "/quickcontrol/info/vs/0",
+      "rep": {
+        "supportedVersion": "1.0"
+      }
+    }
+  ]
+}

tests/fixtures/refrigerator_tp1x_ref_21k_kimchi_device.json

@@ -0,0 +1,332 @@
+{
+  "device0": [
+    {
+      "rt": [
+        "x.com.samsung.devcol",
+        "oic.wk.col"
+      ],
+      "if": [
+        "oic.if.baseline",
+        "oic.if.ll",
+        "oic.if.b"
+      ]
+    },
+    {
+      "href": "/alarms/vs/0",
+      "rep": {}
+    },
+    {
+      "href": "/selfcheck/vs/0",
+      "rep": {
+        "x.com.samsung.da.status": "Ready",
+        "x.com.samsung.da.result": "Success",
+        "x.com.samsung.da.error": [
+          "DA_ERROR_NONE"
+        ],
+        "x.com.samsung.da.supportedActions": [
+          "Start"
+        ]
+      }
+    },
+    {
+      "href": "/energy/consumption/vs/0",
+      "rep": {
+        "x.com.samsung.da.cumulativeConsumption": "53539",
+        "x.com.samsung.da.cumulativePower": "174590",
+        "x.com.samsung.da.cumulativeUnit": "Wh",
+        "x.com.samsung.da.instantaneousPower": "4",
+        "x.com.samsung.da.instantaneousPowerUnit": "W",
+        "x.com.samsung.da.cumulativeSavedPower": "0"
+      }
+    },
+    {
+      "href": "/mode/vs/0",
+      "rep": {
+        "x.com.samsung.da.supportedModes": [
+          "HOMECARE_WIZARD_V2",
+          "ENERGY_REPORT_MODEL",
+          "18K_KIMCHI_OUTDOOR_CONTROL"
+        ],
+        "x.com.samsung.da.modes": [
+          "KIMCHI_KIMCHI_STORAGE_NORMAL",
+          "KIMCHI_RIPE_REMAIN_[0]:[0]",
+          "KIMCHIT_BOX_COUNT_[0]",
+          "KIMCHIM_BOX_COUNT_[0]",
+          "KIMCHIB_BOX_COUNT_[0]",
+          "KIMCHI_BOX_COUNT_[8]"
+        ],
+        "x.com.samsung.da.supportedOptions": [
+          "KIMCHI_KIMCHI_STORAGE_NORMAL_[0]:[0]",
+          "KIMCHI_KIMCHI_STORAGE_COLD_[0]:[0]",
+          "KIMCHI_KIMCHI_STORAGE_WARM_[0]:[0]",
+          "KIMCHI_KIMCHI_STORAGE_CRUNFCH_[0]:[0]",
+          "KIMCHI_KIMCHI_STORAGE_BUY_[0]:[0]",
+          "KIMCHI_STORAGE_FRIDGE_[0]:[0]",
+          "KIMCHI_STORAGE_FREEZER_[0]:[0]",
+          "KIMCHI_KIMCHI_RIPE_NORMAL_TEMP_[2]:[12]",
+          "KIMCHI_KIMCHI_RIPE_LOW_TEMP_[5]:[17]"
+        ]
+      }
+    },
+    {
+      "href": "/mode/0",
+      "rep": {
+        "supportedModes": [
+          "HOMECARE_WIZARD_V2",
+          "ENERGY_REPORT_MODEL",
+          "18K_KIMCHI_OUTDOOR_CONTROL"
+        ],
+        "modes": [
+          "KIMCHI_KIMCHI_STORAGE_NORMAL",
+          "KIMCHI_RIPE_REMAIN_[0]:[0]",
+          "KIMCHIT_BOX_COUNT_[0]",
+          "KIMCHIM_BOX_COUNT_[0]",
+          "KIMCHIB_BOX_COUNT_[0]",
+          "KIMCHI_BOX_COUNT_[8]"
+        ]
+      }
+    },
+    {
+      "href": "/realtimenotiforclient/vs/0",
+      "rep": {
+        "x.com.samsung.da.timeforshortnoti": "0",
+        "x.com.samsung.da.periodicnotisubscription": "true"
+      }
+    },
+    {
+      "href": "/information/vs/0",
+      "rep": {
+        "x.com.samsung.da.modelNum": "TP1X_REF_21K|00168041|10010022011713004101800031010000",
+        "x.com.samsung.da.description": "TP1X_REF_21K",
+        "x.com.samsung.da.serialNum": "**REDACTED**",
+        "x.com.samsung.da.otnDUID": "**REDACTED**",
+        "x.com.samsung.da.diagProtocolType": "BLE_OCF",
+        "x.com.samsung.da.diagLogType": [
+          "errCode",
+          "dump"
+        ],
+        "x.com.samsung.da.diagDumpType": "file",
+        "x.com.samsung.da.diagEndPoint": "SSM",
+        "x.com.samsung.da.diagMnid": "0AJT",
+        "x.com.samsung.da.diagSetupid": "CO0",
+        "x.com.samsung.da.diagMinVersion": "3.0",
+        "x.com.samsung.da.diagTsId": "DA01",
+        "x.com.samsung.da.items": [
+          {
+            "x.com.samsung.da.id": "0",
+            "x.com.samsung.da.description": "WiFi Module",
+            "x.com.samsung.da.type": "Software",
+            "x.com.samsung.da.number": "250422",
+            "x.com.samsung.da.newVersionAvailable": "0"
+          },
+          {
+            "x.com.samsung.da.id": "1",
+            "x.com.samsung.da.description": "Micom",
+            "x.com.samsung.da.type": "Firmware",
+            "x.com.samsung.da.number": "24101006, 23031302, 24102200, FFFFFFFF",
+            "x.com.samsung.da.newVersionAvailable": "0"
+          }
+        ]
+      }
+    },
+    {
+      "href": "/file/information/vs/0",
+      "rep": {
+        "x.com.samsung.timeoffset": "+00:00",
+        "x.com.samsung.supprtedtype": 1
+      }
+    },
+    {
+      "href": "/doors/vs/0",
+      "rep": {
+        "x.com.samsung.da.items": [
+          {
+            "x.com.samsung.da.id": "8",
+            "x.com.samsung.da.description": "Door",
+            "x.com.samsung.da.openState": "Close"
+          }
+        ]
+      }
+    },
+    {
+      "href": "/door/onedoorkimchi/vs/0",
+      "rep": {
+        "x.com.samsung.da.openState": "Close"
+      }
+    },
+    {
+      "href": "/configuration/vs/0",
+      "rep": {
+        "x.com.samsung.da.countryCode": "",
+        "x.com.samsung.da.region": ""
+      }
+    },
+    {
+      "href": "/drlc/0",
+      "rep": {
+        "DRLevel": 2,
+        "override": false
+      }
+    },
+    {
+      "href": "/drlc/vs/0",
+      "rep": {
+        "x.com.samsung.da.drlcLevel": "2",
+        "x.com.samsung.da.override": "Not_Supported",
+        "x.com.samsung.da.durationminutes": "1441",
+        "x.com.samsung.da.start": "2026-08-06T00:34:47Z",
+        "x.com.samsung.da.realSaving": "Off"
+      }
+    },
+    {
+      "href": "/bespoke/vs/0",
+      "rep": {
+        "x.com.samsung.da.BespokeProduct": "On"
+      }
+    },
+    {
+      "href": "/otninformation/vs/0",
+      "rep": {
+        "x.com.samsung.da.target": "",
+        "x.com.samsung.da.newVersionAvailable": "false",
+        "otnStatus": "None",
+        "flashingProgress": "",
+        "otnList": [
+          {
+            "type": "WIFI",
+            "modelId": "A-RFWW-TP1-23-COMMON",
+            "versions": [
+              "20250422"
+            ],
+            "visVersion": "250422"
+          },
+          {
+            "type": "Micom",
+            "modelId": "02120016804100168441",
+            "versions": [
+              "24101006",
+              "23031302"
+            ],
+            "visVersion": "241010"
+          },
+          {
+            "type": "Micom",
+            "modelId": "021270659241FFFFFFFF",
+            "versions": [
+              "24102200",
+              "FFFFFFFF"
+            ],
+            "visVersion": "241022"
+          }
+        ]
+      }
+    },
+    {
+      "href": "/status/lock/vs/0",
+      "rep": {
+        "x.com.samsung.da.ado.voicecontrol": "Off",
+        "x.com.samsung.da.device.sound": "On"
+      }
+    },
+    {
+      "href": "/status/kimchi/onedoor/vs/0",
+      "rep": {
+        "x.com.samsung.da.currentMode": "KIMCHI_STORAGE_NORMAL",
+        "x.com.samsung.da.ripeStatus": "Off",
+        "x.com.samsung.da.ripeRemaintime": "0",
+        "x.com.samsung.da.rackCount": "8",
+        "x.com.samsung.da.ripeTotaltime": "0",
+        "x.com.samsung.da.supportMode": [
+          "KIMCHI_STORAGE_NORMAL",
+          "KIMCHI_STORAGE_COLD",
+          "KIMCHI_STORAGE_WARM",
+          "KIMCHI_STORAGE_CRUNFCH",
+          "KIMCHI_STORAGE_BUY",
+          "STORAGE_FRIDGE",
+          "STORAGE_FREEZER",
+          "KIMCHI_RIPE_NORMAL_TEMP",
+          "KIMCHI_RIPE_LOW_TEMP",
+          "NEWMODE_KIMCHI_0000",
+          "NEWMODE_KIMCHI_0000",
+          "NEWMODE_KIMCHI_0000"
+        ]
+      }
+    },
+    {
+      "href": "/autodoor/timer/vs/0",
+      "rep": {
+        "x.com.samsung.da.time.desired": "1",
+        "x.com.samsung.da.time.supportedOptions": [
+          "1",
+          "2",
+          "3",
+          "4",
+          "5",
+          "6"
+        ]
+      }
+    },
+    {
+      "href": "/autodoor/kimchi/vs/0",
+      "rep": {
+        "x.com.samsung.da.ado.openOptions": [
+          "Single"
+        ]
+      }
+    },
+    {
+      "href": "/connectionconfig/vs/0",
+      "rep": {
+        "autoReconnectionMinVersion": "1.0",
+        "autoReconnection": "true",
+        "autoReconnectionProtocolType": [
+          "ble_ocf",
+          null
+        ],
+        "supportedWiFiAuthType": [
+          "OPEN",
+          "WEP",
+          "WPA-PSK",
+          "WPA2-PSK",
+          "SAE"
+        ],
+        "supportedWiFiCryptoType": [
+          "TKIP",
+          "AES",
+          "WEP-64",
+          "WEP-128"
+        ],
+        "supportedWiFiFreq": [
+          "2.4G"
+        ],
+        "calmConnectionCare": {
+          "version": "1.0",
+          "role": [
+            "things"
+          ]
+        }
+      }
+    },
+    {
+      "href": "/timezone/vs/0",
+      "rep": {
+        "timezoneid": "Asia/Seoul",
+        "offset": "+09:00",
+        "DST": "OFF"
+      }
+    },
+    {
+      "href": "/wirelessinfo/vs/0",
+      "rep": {
+        "macaddressWiFi": "**REDACTED**",
+        "macaddressBLE": "**REDACTED**"
+      }
+    },
+    {
+      "href": "/quickcontrol/info/vs/0",
+      "rep": {
+        "supportedVersion": "1.0"
+      }
+    }
+  ]
+}

tests/fixtures/refrigerator_winecellar_device.json

@@ -0,0 +1,466 @@
+{
+  "device0": [
+    {
+      "rt": [
+        "x.com.samsung.devcol",
+        "oic.wk.col"
+      ],
+      "if": [
+        "oic.if.baseline",
+        "oic.if.ll",
+        "oic.if.b"
+      ]
+    },
+    {
+      "href": "/alarms/vs/0",
+      "rep": {
+        "href": "/alarms/vs/0",
+        "rt": [
+          "x.com.samsung.da.alarms"
+        ],
+        "if": [
+          "oic.if.baseline",
+          "oic.if.a"
+        ]
+      }
+    },
+    {
+      "href": "/autodoor/winecellar/vs/0",
+      "rep": {
+        "x.com.samsung.da.ado.openOptions": [
+          "Single"
+        ],
+        "href": "/autodoor/winecellar/vs/0"
+      }
+    },
+    {
+      "href": "/autodoor/timer/vs/0",
+      "rep": {
+        "x.com.samsung.da.time.desired": "1",
+        "x.com.samsung.da.time.supportedOptions": [
+          "1",
+          "2",
+          "3",
+          "4",
+          "5",
+          "6"
+        ],
+        "href": "/autodoor/timer/vs/0"
+      }
+    },
+    {
+      "href": "/bespoke/vs/0",
+      "rep": {
+        "x.com.samsung.da.BespokeProduct": "On",
+        "href": "/bespoke/vs/0"
+      }
+    },
+    {
+      "href": "/cabinet/light/total/vs/0",
+      "rep": {
+        "x.com.samsung.da.lightLevel": "100",
+        "x.com.samsung.da.lightResolution": "1",
+        "x.com.samsung.da.lightControl.off.include": "Off",
+        "x.com.samsung.da.lightControl": "Off",
+        "x.com.samsung.da.timeout.desired": "0",
+        "x.com.samsung.da.timeout.supportedList": [
+          "0",
+          "15",
+          "30",
+          "60"
+        ],
+        "href": "/cabinet/light/total/vs/0",
+        "rt": [
+          "x.com.samsung.da.cabinetlight"
+        ],
+        "if": [
+          "oic.if.baseline",
+          "oic.if.a"
+        ]
+      }
+    },
+    {
+      "href": "/configuration/vs/0",
+      "rep": {
+        "x.com.samsung.da.region": "",
+        "x.com.samsung.da.countryCode": "",
+        "href": "/configuration/vs/0"
+      }
+    },
+    {
+      "href": "/door/winecellar/vs/0",
+      "rep": {
+        "x.com.samsung.da.openState": "Close",
+        "href": "/door/winecellar/vs/0",
+        "rt": [
+          "x.com.samsung.da.doorwinecellar"
+        ],
+        "if": [
+          "oic.if.baseline",
+          "oic.if.s"
+        ]
+      }
+    },
+    {
+      "href": "/doors/vs/0",
+      "rep": {
+        "x.com.samsung.da.items": [
+          {
+            "x.com.samsung.da.openState": "Close",
+            "x.com.samsung.da.id": "9",
+            "x.com.samsung.da.description": "Door"
+          }
+        ],
+        "href": "/doors/vs/0"
+      }
+    },
+    {
+      "href": "/drlc/vs/0",
+      "rep": {
+        "x.com.samsung.da.drlcLevel": "2",
+        "x.com.samsung.da.override": "Not_Supported",
+        "x.com.samsung.da.durationminutes": "1345",
+        "x.com.samsung.da.start": "2026-08-06T02:08:48Z",
+        "x.com.samsung.da.realSaving": "On",
+        "href": "/drlc/vs/0"
+      }
+    },
+    {
+      "href": "/energy/consumption/vs/0",
+      "rep": {
+        "x.com.samsung.da.cumulativeConsumption": "19073",
+        "x.com.samsung.da.instantaneousPower": "5",
+        "x.com.samsung.da.cumulativePower": "210483",
+        "x.com.samsung.da.cumulativeSavedPower": "15696",
+        "x.com.samsung.da.cumulativeUnit": "Wh",
+        "x.com.samsung.da.instantaneousPowerUnit": "W",
+        "href": "/energy/consumption/vs/0"
+      }
+    },
+    {
+      "href": "/file/information/vs/0",
+      "rep": {
+        "x.com.samsung.timeoffset": "+00:00",
+        "x.com.samsung.supprtedtype": 1,
+        "href": "/file/information/vs/0"
+      }
+    },
+    {
+      "href": "/filter/deodorfilter/vs/0",
+      "rep": {
+        "x.com.samsung.da.filterUsage": "-1",
+        "x.com.samsung.da.filterUsageResolution": "1",
+        "x.com.samsung.da.filterResetType": [
+          "replaceable"
+        ],
+        "x.com.samsung.da.filterStatus": "normal",
+        "href": "/filter/deodorfilter/vs/0"
+      }
+    },
+    {
+      "href": "/information/vs/0",
+      "rep": {
+        "x.com.samsung.da.modelNum": "TP1X_REF_21K|00146141|000B0020001513924100000011000000",
+        "x.com.samsung.da.description": "TP1X_REF_21K",
+        "x.com.samsung.da.serialNum": "**REDACTED**",
+        "x.com.samsung.da.otnDUID": "**REDACTED**",
+        "x.com.samsung.da.diagDumpType": "file",
+        "x.com.samsung.da.diagEndPoint": "SSM",
+        "x.com.samsung.da.diagLogType": [
+          "errCode",
+          "dump"
+        ],
+        "x.com.samsung.da.diagMnid": "0AJT",
+        "x.com.samsung.da.diagSetupid": "531",
+        "x.com.samsung.da.diagProtocolType": "WIFI_HTTPS",
+        "x.com.samsung.da.diagMinVersion": "1.0",
+        "x.com.samsung.da.items": [
+          {
+            "x.com.samsung.da.id": "0",
+            "x.com.samsung.da.description": "WiFi Module",
+            "x.com.samsung.da.type": "Software",
+            "x.com.samsung.da.number": "260619",
+            "x.com.samsung.da.newVersionAvailable": "0"
+          },
+          {
+            "x.com.samsung.da.id": "1",
+            "x.com.samsung.da.description": "Micom",
+            "x.com.samsung.da.type": "Firmware",
+            "x.com.samsung.da.number": "24102313, 2201030E",
+            "x.com.samsung.da.newVersionAvailable": "0"
+          }
+        ],
+        "href": "/information/vs/0"
+      }
+    },
+    {
+      "href": "/status/lock/vs/0",
+      "rep": {
+        "x.com.samsung.da.ado.voicecontrol": "Off",
+        "x.com.samsung.da.ado.soundcontrol": "On",
+        "href": "/status/lock/vs/0",
+        "rt": [
+          "x.com.samsung.da.lockstatus"
+        ],
+        "if": [
+          "oic.if.baseline",
+          "oic.if.a"
+        ]
+      }
+    },
+    {
+      "href": "/mode/vs/0",
+      "rep": {
+        "x.com.samsung.da.modes": [
+          "AIRFILTER_DISABLE"
+        ],
+        "x.com.samsung.da.supportedModes": [
+          "HOMECARE_WIZARD_V2",
+          "ENERGY_REPORT_MODEL",
+          "WINE_T_TOTRACK_[6]",
+          "WINE_T_BOTTLE_RACK_[7]",
+          "WINE_B_TOTRACK_[4]",
+          "WINE_B_BOTTLE_RACK_[7]",
+          "WINE_PRESENTATION_[6]",
+          "WINE_BTM_BOTTLE_[20]",
+          "WINE_PANTRY_BOTTLE_[5]"
+        ],
+        "href": "/mode/vs/0",
+        "rt": [
+          "x.com.samsung.da.mode"
+        ],
+        "if": [
+          "oic.if.baseline",
+          "oic.if.a"
+        ]
+      }
+    },
+    {
+      "href": "/realtimenotiforclient/vs/0",
+      "rep": {
+        "x.com.samsung.da.timeforshortnoti": "0",
+        "x.com.samsung.da.periodicnotisubscription": "true",
+        "href": "/realtimenotiforclient/vs/0"
+      }
+    },
+    {
+      "href": "/runningmode/vs/0",
+      "rep": {
+        "x.com.samsung.da.runningMode": 0,
+        "href": "/runningmode/vs/0"
+      }
+    },
+    {
+      "href": "/selfcheck/vs/0",
+      "rep": {
+        "x.com.samsung.da.supportedActions": [
+          "Start"
+        ],
+        "x.com.samsung.da.status": "Ready",
+        "x.com.samsung.da.result": "Success",
+        "x.com.samsung.da.error": [
+          "ErrorCode_None"
+        ],
+        "href": "/selfcheck/vs/0"
+      }
+    },
+    {
+      "href": "/temperature/desired/winecellar/top/vs/0",
+      "rep": {
+        "temperature": 13.0,
+        "range": [
+          4.0,
+          18.0
+        ],
+        "units": "C",
+        "href": "/temperature/desired/winecellar/top/vs/0",
+        "rt": [
+          "oic.r.temperature"
+        ],
+        "if": [
+          "oic.if.baseline",
+          "oic.if.a"
+        ]
+      }
+    },
+    {
+      "href": "/temperature/desired/winecellar/bottom/vs/0",
+      "rep": {
+        "temperature": 7.0,
+        "range": [
+          4.0,
+          18.0
+        ],
+        "units": "C",
+        "href": "/temperature/desired/winecellar/bottom/vs/0",
+        "rt": [
+          "oic.r.temperature"
+        ],
+        "if": [
+          "oic.if.baseline",
+          "oic.if.a"
+        ]
+      }
+    },
+    {
+      "href": "/temperatures/vs/0",
+      "rep": {
+        "x.com.samsung.da.items": [
+          {
+            "x.com.samsung.da.id": "2",
+            "x.com.samsung.da.description": "WineCellar-top",
+            "x.com.samsung.da.desired": "13",
+            "x.com.samsung.da.current": "13",
+            "x.com.samsung.da.maximum": "18",
+            "x.com.samsung.da.minimum": "4",
+            "x.com.samsung.da.unit": "Celsius"
+          },
+          {
+            "x.com.samsung.da.id": "3",
+            "x.com.samsung.da.description": "WineCellar-bottom",
+            "x.com.samsung.da.desired": "7",
+            "x.com.samsung.da.current": "7",
+            "x.com.samsung.da.maximum": "18",
+            "x.com.samsung.da.minimum": "4",
+            "x.com.samsung.da.unit": "Celsius"
+          }
+        ],
+        "href": "/temperatures/vs/0"
+      }
+    },
+    {
+      "href": "/information/winecellar/vs/0",
+      "rep": {
+        "x.com.samsung.da.tbl.revision": "1",
+        "href": "/information/winecellar/vs/0"
+      }
+    },
+    {
+      "href": "/status/winecellar/pantry/one/vs/0",
+      "rep": {
+        "x.com.samsung.da.mode": "Fruit",
+        "x.com.samsung.range": [
+          "4",
+          "13"
+        ],
+        "x.com.samsung.da.room": "0x10",
+        "x.com.samsung.da.name": "MULTI_PANTRY",
+        "x.com.samsung.da.unit": "Celsius",
+        "x.com.samsung.da.supportedOptions": [
+          "Processed_Meat",
+          "Cheese",
+          "Nuts",
+          "Fruit",
+          "Wine"
+        ],
+        "href": "/status/winecellar/pantry/one/vs/0"
+      }
+    },
+    {
+      "href": "/otninformation/vs/0",
+      "rep": {
+        "x.com.samsung.da.target": "",
+        "x.com.samsung.da.newVersionAvailable": "false",
+        "otnStatus": "None",
+        "flashingProgress": "0",
+        "otnCompleteDate": "noHistory",
+        "scheduledTime": "None",
+        "swVersionInfo": {
+          "platform": "Tizen Lite",
+          "oneUiVersion": "7.0 Refrigerator",
+          "osVersion": "4.0"
+        },
+        "otnList": [
+          {
+            "type": "WIFI",
+            "modelId": "A-RFWW-TP1-24-T4-RE2",
+            "versions": [
+              "20260619"
+            ],
+            "visVersion": "260619"
+          },
+          {
+            "type": "Micom",
+            "modelId": "02900014614100146441",
+            "versions": [
+              "24102313",
+              "2201030E"
+            ],
+            "visVersion": "241023"
+          }
+        ]
+      }
+    },
+    {
+      "href": "/timezone/vs/0",
+      "rep": {
+        "timezoneid": "Asia/Seoul",
+        "offset": "+09:00",
+        "DST": "OFF"
+      }
+    },
+    {
+      "href": "/connectionconfig/vs/0",
+      "rep": {
+        "autoReconnectionMinVersion": "1.0",
+        "autoReconnection": "true",
+        "autoReconnectionProtocolType": [
+          "helper_hotspot",
+          "ble_ocf"
+        ],
+        "supportedWiFiAuthType": [
+          "OPEN",
+          "WEP",
+          "WPA-PSK",
+          "WPA2-PSK",
+          "SAE"
+        ],
+        "supportedWiFiCryptoType": [
+          "TKIP",
+          "AES",
+          "WEP-64",
+          "WEP-128"
+        ],
+        "supportedWiFiFreq": [
+          "2.4G"
+        ],
+        "calmConnectionCare": {
+          "version": "1.0",
+          "role": [
+            "things"
+          ]
+        }
+      }
+    },
+    {
+      "href": "/wirelessinfo/vs/0",
+      "rep": {
+        "macaddressWiFi": "**REDACTED**",
+        "macaddressBLE": "**REDACTED**",
+        "connectedApSsid": "Home_IoT"
+      }
+    },
+    {
+      "href": "/quickcontrol/info/vs/0",
+      "rep": {
+        "supportedVersion": "1.0"
+      }
+    },
+    {
+      "href": "/dginformation/vs/0",
+      "rep": {
+        "enrolmentstatus": "Unknown",
+        "devicestate": "Unknown",
+        "lockstatus": "Unknown",
+        "nextduedate": "",
+        "workingminutes": 0,
+        "paymentinfo": {
+          "emiplan": "Unknown",
+          "currency": "Unknown",
+          "totalemi": 0,
+          "totalemipaid": 0
+        }
+      }
+    }
+  ]
+}

tests/fixtures/washer_ww5000c_cloud_device.json

@@ -0,0 +1,452 @@
+{
+  "device0": [
+    {
+      "rt": [
+        "x.com.samsung.devcol",
+        "oic.wk.col"
+      ],
+      "if": [
+        "oic.if.baseline",
+        "oic.if.ll",
+        "oic.if.b"
+      ]
+    },
+    {
+      "href": "/realtimenotiforclient/vs/0",
+      "rep": {
+        "x.com.samsung.da.timeforshortnoti": "10",
+        "x.com.samsung.da.periodicnotisubscription": "true"
+      }
+    },
+    {
+      "href": "/alarms/vs/0",
+      "rep": {}
+    },
+    {
+      "href": "/diagnosis/vs/0",
+      "rep": {
+        "x.com.samsung.da.diagnosisStart": "Ready"
+      }
+    },
+    {
+      "href": "/energy/consumption/vs/0",
+      "rep": {
+        "x.com.samsung.da.instantaneousPower": "-500",
+        "x.com.samsung.da.instantaneousPowerUnit": "W",
+        "x.com.samsung.da.cumulativePower": "74800",
+        "x.com.samsung.da.cumulativeUnit": "Wh",
+        "x.com.samsung.da.cumulativeDate": "1786287600",
+        "x.com.samsung.da.cumulativeDateUTC": "1786280400",
+        "x.com.samsung.da.cumulativeSavedPower": "0"
+      }
+    },
+    {
+      "href": "/energy/consumption/0",
+      "rep": {}
+    },
+    {
+      "href": "/course/vs/0",
+      "rep": {
+        "x.com.samsung.da.supportedModes": [
+          "HOMECARE_WIZARD_V2"
+        ],
+        "x.com.samsung.da.options": [
+          "DeviceType_0167",
+          "UpdateAllow_NotAllowed",
+          "Course_87",
+          "LaundryOutTime_0",
+          "SeamlessControl_Enable",
+          "KidsLockBypass_On",
+          "WashingTimes_0",
+          "DrumCleanProposal_40",
+          "DetergentOnce_0",
+          "DetergentLeft_0",
+          "DetergentBase_0",
+          "DetergentAlarm_Off",
+          "DetergentType_0",
+          "DetergentTotal_0",
+          "SoftenerOnce_0",
+          "SoftenerLeft_0",
+          "SoftenerBase_0",
+          "SoftenerAlarm_Off",
+          "SoftenerType_0",
+          "SoftenerTotal_0",
+          "SpecialFunction_4",
+          "AvailableDelayTime_74",
+          "BubbleSoak_Off",
+          "LaundryPlannerUserSetTime_0",
+          "ProgressTimeSet_421C20820437A2042C",
+          "SendToDevice_On",
+          "GMT_04",
+          "PreWashSetting_Off",
+          "IntensiveSetting_Off",
+          "CloudCourse_0021550449284D134AA04C0035F004F005F0AC00",
+          "CloudExtraCourse_0A5C286B2D0C55301A",
+          "OneTimeCloudCourse_001F6B0449284D134AA04C0035F004F005F0AC00",
+          "BubbleSoakSet_00F0F0F00000F0F000000000F000",
+          "EnergyLevelSet_050304040501050404030201020401",
+          "MostUsed_1B841E923FA67F00000000000000",
+          "PreWashAvailableSet_F0F0F0F00000F0F000F0F000F000",
+          "IntensiveAvailableSet_F0F0F0F00000F0F000F0F000F000",
+          "TextureLevel_None",
+          "SavingModeCondition_010102151C1BA0961C8F251C0A061A207F5C55656B0C2D3034030149035E2830",
+          "SavingMode_Off",
+          "WelcomeLighting_1",
+          "SupportedWelcomeLighting_000102",
+          "GeoFenceAlarm",
+          "UsagesDB_ok",
+          "EnergyKW_396",
+          "DrumCleanLog_2025-08-18T14:56:34|2025-11-02T21:08:39|2026-01-19T13:00:50|2026-03-23T12:10:12|2026-06-27T11:07:22|2026-08-09T10:13:44",
+          "TimeSync_NotSupported"
+        ],
+        "x.com.samsung.da.supportedOptions": [
+          "31C8410923FA67F1B847E923FA67F25843E933FA57F20857E943FA67F088000913FA67F7485209204A5208780009000A00006841E930FA30F7F841E920FA30F65841E943FA57F8F8102923FA57F96841E920FA37F34841E923FA67FA0811E933FA33F"
+        ]
+      }
+    },
+    {
+      "href": "/power/vs/0",
+      "rep": {
+        "x.com.samsung.da.power": "On"
+      }
+    },
+    {
+      "href": "/power/0",
+      "rep": {
+        "value": true
+      }
+    },
+    {
+      "href": "/cycleinterface/vs/0",
+      "rep": {}
+    },
+    {
+      "href": "/kidslock/vs/0",
+      "rep": {
+        "x.com.samsung.da.kidsLock": "Ready"
+      }
+    },
+    {
+      "href": "/kidslock/0",
+      "rep": {
+        "value": false
+      }
+    },
+    {
+      "href": "/operational/state/vs/0",
+      "rep": {
+        "x.com.samsung.da.state": "Ready",
+        "x.com.samsung.da.remainingTime": "01:14:00",
+        "x.com.samsung.da.progressPercentage": "1",
+        "x.com.samsung.da.progress": "None",
+        "x.com.samsung.da.delayEndTime": "00:00:00",
+        "x.com.samsung.da.supportedProgress": [
+          "None",
+          "Wash",
+          "Rinse",
+          "Spin",
+          "Finish"
+        ]
+      }
+    },
+    {
+      "href": "/operational/state/0",
+      "rep": {
+        "currentMachineState": "**REDACTED**",
+        "machineStates": "**REDACTED**",
+        "jobStates": [
+          "None",
+          "Wash",
+          "Rinse",
+          "Spin",
+          "Finish"
+        ],
+        "currentJobState": "None",
+        "remainingTime": "01:14:00",
+        "progressPercentage": "1"
+      }
+    },
+    {
+      "href": "/information/vs/0",
+      "rep": {
+        "x.com.samsung.da.modelNum": "DA_WM_TP1_21_COMMON|20348141|20010002001711124ACB020200080000",
+        "x.com.samsung.da.description": "DA_WM_TP1_21_COMMON_WW5000C/DC92-03495A_B06C",
+        "x.com.samsung.da.serialNum": "**REDACTED**",
+        "x.com.samsung.da.otnDUID": "**REDACTED**",
+        "x.com.samsung.da.diagProtocolType": "BLE_OCF",
+        "x.com.samsung.da.diagLogType": [
+          "errCode",
+          "dump"
+        ],
+        "x.com.samsung.da.diagDumpType": "file",
+        "x.com.samsung.da.diagEndPoint": "SSM",
+        "x.com.samsung.da.diagMnid": "0AJT",
+        "x.com.samsung.da.diagSetupid": "WF1",
+        "x.com.samsung.da.diagMinVersion": "3.0",
+        "x.com.samsung.da.diagTsId": "DA01",
+        "x.com.samsung.da.items": [
+          {
+            "x.com.samsung.da.id": "0",
+            "x.com.samsung.da.description": "DA_WM_TP1_21_COMMON|20348141|20010002001711124ACB020200080000",
+            "x.com.samsung.da.type": "Software",
+            "x.com.samsung.da.number": "02986A260118(A182)",
+            "x.com.samsung.da.newVersionAvailable": "0"
+          },
+          {
+            "x.com.samsung.da.id": "1",
+            "x.com.samsung.da.description": "Firmware_1_DB_20348141240110090FFFFF203495412406195503FFFF(01672034814120349541_30000000)(FileDown:0)(Type:0)",
+            "x.com.samsung.da.type": "Firmware",
+            "x.com.samsung.da.number": "03481A24011009,03495A24061955",
+            "x.com.samsung.da.newVersionAvailable": "0"
+          },
+          {
+            "x.com.samsung.da.id": "2",
+            "x.com.samsung.da.description": "Firmware_2_DB_2025984624053003032FFFFFFFFFFFFFFFFFFFFFFFFE(016720259846FFFFFFFF_30000000)(FileDown:0)(Type:0)",
+            "x.com.samsung.da.type": "Firmware",
+            "x.com.samsung.da.number": "02598F24053003,FFFFFFFFFFFFFF"
+          }
+        ]
+      }
+    },
+    {
+      "href": "/file/information/vs/0",
+      "rep": {
+        "x.com.samsung.timeoffset": "+02:00"
+      }
+    },
+    {
+      "href": "/washer/vs/0",
+      "rep": {
+        "x.com.samsung.da.waterTemperature": "30",
+        "x.com.samsung.da.supportedWaterTemperature": [
+          "None",
+          "Cold",
+          "20",
+          "30",
+          "40",
+          "60",
+          "90"
+        ],
+        "x.com.samsung.da.spinLevel": "800",
+        "x.com.samsung.da.supportedSpinLevel": [
+          "RinseHold",
+          "NoSpin",
+          "400",
+          "800",
+          "1000",
+          "1200",
+          "1400"
+        ],
+        "x.com.samsung.da.rinseCycles": "3",
+        "x.com.samsung.da.supportedRinseCycles": [
+          "0",
+          "1",
+          "2",
+          "3",
+          "4",
+          "5"
+        ]
+      }
+    },
+    {
+      "href": "/st/washercourse/vs/0",
+      "rep": {
+        "x.com.samsung.da.st.washerMode": "Table_02_Course_87",
+        "x.com.samsung.da.st.courseTable": "Table_02"
+      }
+    },
+    {
+      "href": "/water/consumption/vs/0",
+      "rep": {
+        "x.com.samsung.da.cumulativeWater": "7512800"
+      }
+    },
+    {
+      "href": "/setting/vs/0",
+      "rep": {
+        "x.com.samsung.da.supportedSetLanguage": [
+          "ko_KR",
+          "en_US"
+        ]
+      }
+    },
+    {
+      "href": "/wm/editcourse/vs/0",
+      "rep": {}
+    },
+    {
+      "href": "/wm/setinfo/vs/0",
+      "rep": {
+        "x.com.samsung.da.isModelSettingWithoutSC": "true",
+        "x.com.samsung.da.isModelSettingPowerOnOff": "false",
+        "x.com.samsung.da.modelCode": "M(None),W(WW8XCGC04AAEEG)"
+      }
+    },
+    {
+      "href": "/wm/jobbeginingstatus/vs/0",
+      "rep": {
+        "x.com.samsung.da.currentStatus": "None"
+      }
+    },
+    {
+      "href": "/otninformation/vs/0",
+      "rep": {
+        "x.com.samsung.da.target": "",
+        "x.com.samsung.da.newVersionAvailable": "false",
+        "x.com.samsung.da.newVersionNo": "00000000",
+        "x.com.samsung.da.currentVersionInfo": "00000000",
+        "otnStatus": "None",
+        "flashingProgress": "",
+        "otnTarget": "main",
+        "otnCompleteDate": "2026-03-04",
+        "otnList": [
+          {
+            "type": "WIFI",
+            "modelId": "DA_WM_TP1_21_COMMON",
+            "versions": [
+              "30260118"
+            ],
+            "visVersion": "260118"
+          },
+          {
+            "type": "Micom",
+            "modelId": "01672034814120349541",
+            "versions": [
+              "24011009",
+              "24061955"
+            ],
+            "visVersion": "240619"
+          },
+          {
+            "type": "Micom",
+            "modelId": "016720259846FFFFFFFF",
+            "versions": [
+              "24053003",
+              "FFFFFFFF"
+            ],
+            "visVersion": "240530"
+          },
+          {
+            "type": "Micom",
+            "modelId": "016720259846FFFFFFFF",
+            "versions": [
+              "24053003",
+              "FFFFFFFF"
+            ],
+            "visVersion": "240530"
+          }
+        ]
+      }
+    },
+    {
+      "href": "/buzzersound/vs/0",
+      "rep": {
+        "supportedBuzzerSound": [
+          "Volume_Off",
+          "Volume_Low",
+          "Volume_Med",
+          "Volume_High"
+        ],
+        "setBuzzerSound": "Volume_Low",
+        "supportedFinishSound": [
+          "FinishSound_1",
+          "FinishSound_2",
+          "FinishSound_3"
+        ],
+        "setFinishSound": "FinishSound_2"
+      }
+    },
+    {
+      "href": "/remotectrl/vs/0",
+      "rep": {
+        "x.com.samsung.da.remoteControlEnabled": "false"
+      }
+    },
+    {
+      "href": "/remotectrl/0",
+      "rep": {
+        "value": false
+      }
+    },
+    {
+      "href": "/configuration/vs/0",
+      "rep": {
+        "x.com.samsung.da.region": "0000000000",
+        "x.com.samsung.da.countryCode": "DE"
+      }
+    },
+    {
+      "href": "/drlc/0",
+      "rep": {
+        "DRLevel": 0,
+        "start": "0000-00-00T00:00:00Z",
+        "duration": 0,
+        "override": false
+      }
+    },
+    {
+      "href": "/drlc/vs/0",
+      "rep": {
+        "x.com.samsung.da.drlcLevel": "0",
+        "x.com.samsung.da.durationminutes": "0",
+        "x.com.samsung.da.start": "0000-00-00T00:00:00Z",
+        "x.com.samsung.da.override": "Off",
+        "x.com.samsung.da.realSaving": "Off"
+      }
+    },
+    {
+      "href": "/timezone/vs/0",
+      "rep": {
+        "timezoneid": "Europe/Berlin",
+        "offset": "+02:00",
+        "DST": "ON"
+      }
+    },
+    {
+      "href": "/connectionconfig/vs/0",
+      "rep": {
+        "autoReconnectionMinVersion": "1.0",
+        "autoReconnection": "true",
+        "autoReconnectionProtocolType": [
+          "helper_hotspot",
+          "ble_ocf"
+        ],
+        "supportedWiFiAuthType": [
+          "OPEN",
+          "WEP",
+          "WPA-PSK",
+          "WPA2-PSK",
+          "SAE"
+        ],
+        "supportedWiFiCryptoType": [
+          "TKIP",
+          "AES",
+          "WEP-64",
+          "WEP-128"
+        ],
+        "supportedWiFiFreq": [
+          "2.4G"
+        ],
+        "calmConnectionCare": {
+          "version": "1.0",
+          "role": [
+            "things"
+          ]
+        }
+      }
+    },
+    {
+      "href": "/wirelessinfo/vs/0",
+      "rep": {
+        "macaddressWiFi": "**REDACTED**",
+        "macaddressBLE": "**REDACTED**"
+      }
+    },
+    {
+      "href": "/quickcontrol/info/vs/0",
+      "rep": {
+        "supportedVersion": "1.0"
+      }
+    }
+  ]
+}

tests/fixtures/washer_ww6500_device.json

@@ -0,0 +1,233 @@
+{
+  "device0": [
+    {},
+    {
+      "href": "/realtimenotiforclient/vs/0",
+      "rep": {
+        "x.com.samsung.da.timeforshortnoti": "0",
+        "x.com.samsung.da.periodicnotisubscription": "true"
+      }
+    },
+    {
+      "href": "/alarms/vs/0",
+      "rep": {}
+    },
+    {
+      "href": "/diagnosis/vs/0",
+      "rep": {
+        "x.com.samsung.da.diagnosisStart": "Ready"
+      }
+    },
+    {
+      "href": "/energy/consumption/vs/0",
+      "rep": {
+        "x.com.samsung.da.instantaneousPowerUnit": "W",
+        "x.com.samsung.da.instantaneousPower": "-500",
+        "x.com.samsung.da.cumulativePower": "2016700",
+        "x.com.samsung.da.cumulativeUnit": "Wh",
+        "x.com.samsung.da.cumulativeDate": "1787050800",
+        "x.com.samsung.da.cumulativeDateUTC": "1787050800"
+      }
+    },
+    {
+      "href": "/energy/consumption/0",
+      "rep": {}
+    },
+    {
+      "href": "/course/vs/0",
+      "rep": {
+        "x.com.samsung.da.options": [
+          "DeviceType_0167",
+          "Course_5C",
+          "LaundryOutTime_0",
+          "AddWashSet_0",
+          "AddWashAvailable_7",
+          "AddWashIndicator_Off",
+          "QuickWash_Not_Used",
+          "QuickWashSet_5B847E933FA53F",
+          "UsagesDB_ok",
+          "EnergyKW_396",
+          "DrumCleanLog_Empty",
+          "TimeSync_NotSupported"
+        ],
+        "x.com.samsung.da.supportedOptions": [
+          "35B847E933FA53F5C841E923FA53F5D8102923FA43F66841E930FA30F5E831E920FA2075F867E943FA53F60831E930FA43F61841E943FA43F6385209204A204648000913FA53F6B80009000A53E65841E920FA30F67843E923FA43F688430923FA53F"
+        ]
+      }
+    },
+    {
+      "href": "/power/vs/0",
+      "rep": {
+        "x.com.samsung.da.power": "On"
+      }
+    },
+    {
+      "href": "/power/0",
+      "rep": {
+        "value": true
+      }
+    },
+    {
+      "href": "/cycleinterface/vs/0",
+      "rep": {}
+    },
+    {
+      "href": "/kidslock/vs/0",
+      "rep": {
+        "x.com.samsung.da.kidsLock": "Ready"
+      }
+    },
+    {
+      "href": "/kidslock/0",
+      "rep": {
+        "value": false
+      }
+    },
+    {
+      "href": "/operational/state/vs/0",
+      "rep": {
+        "x.com.samsung.da.state": "Ready",
+        "x.com.samsung.da.remainingTime": "01:07:00",
+        "x.com.samsung.da.progressPercentage": "1",
+        "x.com.samsung.da.progress": "None",
+        "x.com.samsung.da.supportedProgress": [
+          "None",
+          "Wash",
+          "Rinse",
+          "Spin",
+          "Finish"
+        ]
+      }
+    },
+    {
+      "href": "/operational/state/0",
+      "rep": {
+        "currentMachineState": "idle",
+        "machineStates": [
+          "pause",
+          "active",
+          "idle"
+        ],
+        "jobStates": [
+          "None",
+          "Wash",
+          "Rinse",
+          "Spin",
+          "Finish"
+        ],
+        "currentJobState": "None",
+        "remainingTime": "01:07:00",
+        "progressPercentage": "1"
+      }
+    },
+    {
+      "href": "/information/vs/0",
+      "rep": {
+        "x.com.samsung.da.modelNum": "DA_WM_A51_20_COMMON|FFFFFFFF|20010102001011070000000000000000",
+        "x.com.samsung.da.description": "DA_WM_A51_20_COMMON_WW6500",
+        "x.com.samsung.da.serialNum": "**REDACTED**",
+        "x.com.samsung.da.otnDUID": "**REDACTED**",
+        "x.com.samsung.da.items": [
+          {
+            "x.com.samsung.da.id": "0",
+            "x.com.samsung.da.description": "DA_WM_A51_20_COMMON|FFFFFFFF|20010102001011070000000000000000",
+            "x.com.samsung.da.type": "Software",
+            "x.com.samsung.da.number": "02198A230708(E257)",
+            "x.com.samsung.da.newVersionAvailable": "0"
+          },
+          {
+            "x.com.samsung.da.id": "1",
+            "x.com.samsung.da.description": "DA_WM_A51_20_COMMON",
+            "x.com.samsung.da.type": "Firmware",
+            "x.com.samsung.da.number": "Unknown",
+            "x.com.samsung.da.newVersionAvailable": "0"
+          }
+        ]
+      }
+    },
+    {
+      "href": "/file/information/vs/0",
+      "rep": {
+        "x.com.samsung.timeoffset": "+00:00"
+      }
+    },
+    {
+      "href": "/washer/vs/0",
+      "rep": {
+        "x.com.samsung.da.waterTemperature": "30",
+        "x.com.samsung.da.supportedWaterTemperature": [
+          "None",
+          "Cold",
+          "20",
+          "30",
+          "40",
+          "60",
+          "95"
+        ],
+        "x.com.samsung.da.spinLevel": "1400",
+        "x.com.samsung.da.supportedSpinLevel": [
+          "RinseHold",
+          "NoSpin",
+          "400",
+          "800",
+          "1200",
+          "1400"
+        ],
+        "x.com.samsung.da.rinseCycles": "3",
+        "x.com.samsung.da.supportedRinseCycles": [
+          "0",
+          "1",
+          "2",
+          "3",
+          "4",
+          "5"
+        ]
+      }
+    },
+    {
+      "href": "/st/washercourse/vs/0",
+      "rep": {
+        "x.com.samsung.da.st.washerMode": "Table_00_Course_5C",
+        "x.com.samsung.da.st.courseTable": "Table_00"
+      }
+    },
+    {
+      "href": "/setting/vs/0",
+      "rep": {}
+    },
+    {
+      "href": "/wm/editcourse/vs/0",
+      "rep": {}
+    },
+    {
+      "href": "/wm/setinfo/vs/0",
+      "rep": {
+        "x.com.samsung.da.isModelSettingWithoutSC": "false",
+        "x.com.samsung.da.isModelSettingPowerOnOff": "false"
+      }
+    },
+    {
+      "href": "/wm/jobbeginingstatus/vs/0",
+      "rep": {}
+    },
+    {
+      "href": "/remotectrl/vs/0",
+      "rep": {
+        "x.com.samsung.da.remoteControlEnabled": "true"
+      }
+    },
+    {
+      "href": "/remotectrl/0",
+      "rep": {
+        "value": true
+      }
+    },
+    {
+      "href": "/configuration/vs/0",
+      "rep": {
+        "x.com.samsung.da.region": "0000000000",
+        "x.com.samsung.da.countryCode": "CZ"
+      }
+    }
+  ]
+}

tests/localthings/conftest.py

@@ -14,6 +14,7 @@ from pytest_homeassistant_custom_component.common import MockConfigEntry
 from custom_components.localthings.const import (
     CONF_CA_CERT_PEM,
     CONF_CA_KEY_PEM,
+    CONF_DEVICE_KEY,
     CONF_DEVICE_TYPE,
     CONF_HOST,
     CONF_LEAF_CERT_PEM,
@@ -82,6 +83,10 @@ MOCK_PORT = 49154
 # what mock_coordinator_session polls -- so an entry built from ENTRY_DATA and
 # the device it "reaches" agree on who they are, the same as in production.
 MOCK_SERIAL = "TEST-SERIAL-0000"
+# The OCF device UUID (/oic/d's `di`) the probe resolves the entry's key from
+# (issue #381). Distinct from MOCK_SERIAL so a test that confuses the two
+# fails rather than passing by coincidence.
+MOCK_DEVICE_KEY = "7b1f0c9e-2a44-4d6b-9f10-4c8e2b5a0d31"
 MOCK_MODEL = "TEST-MODEL"
 MOCK_DEVICE_TYPE = "refrigerator"
 MOCK_CA_CERT_PEM = "-----BEGIN CERTIFICATE-----\nTEST-CA\n-----END CERTIFICATE-----"
@@ -98,6 +103,7 @@ ENTRY_DATA = {
     CONF_LEAF_KEY_PEM: MOCK_LEAF_KEY_PEM,
     # Identity the config flow's probe resolved (issue #236) -- what the
     # coordinator keys its devices and entities on from construction.
+    CONF_DEVICE_KEY: MOCK_DEVICE_KEY,
     CONF_SERIAL: MOCK_SERIAL,
     CONF_MODEL: MOCK_MODEL,
     CONF_MANUFACTURER: "Samsung",
@@ -131,6 +137,7 @@ def fridge_resources():
 def _probe_result(*, recognized: bool) -> dict:
     return {
         "port": MOCK_PORT,
+        "device_key": MOCK_DEVICE_KEY,
         "serial": MOCK_SERIAL,
         "model": MOCK_MODEL,
         "manufacturer": "Samsung",
@@ -244,8 +251,8 @@ def mock_entry(hass):
     entry = MockConfigEntry(
         domain=DOMAIN,
         data=ENTRY_DATA,
-        unique_id=f"localthings_{MOCK_SERIAL}",
-        version=2,
+        unique_id=f"localthings_{MOCK_DEVICE_KEY}",
+        version=4,
     )
     entry.add_to_hass(hass)
     return entry

tests/localthings/test_config_flow.py

@@ -15,9 +15,14 @@ from custom_components.localthings.const import (
     CONF_BYPASS_REMOTE_CONTROL,
     CONF_CA_CERT_PEM,
     CONF_CA_KEY_PEM,
+    CONF_CLOUD_COURSES_ENABLED,
+    CONF_DEVICE_KEY,
     CONF_HOST,
     CONF_LEAF_CERT_PEM,
+    CONF_LEARN_MODES,
+    CONF_LEARNED_MODES,
     CONF_PORT,
+    CONF_SERIAL,
     DOMAIN,
 )
 
@@ -25,11 +30,13 @@ from .conftest import (
     ENTRY_DATA,
     MOCK_CA_CERT_PEM,
     MOCK_CA_KEY_PEM,
+    MOCK_DEVICE_KEY,
     MOCK_HOST,
     MOCK_LEAF_CERT_PEM,
     MOCK_MODEL,
     MOCK_PORT,
     MOCK_SERIAL,
+    _probe_result,
 )
 
 
@@ -75,6 +82,41 @@ async def test_successful_setup(hass: HomeAssistant, mock_probe) -> None:
     assert result["data"][CONF_CA_CERT_PEM] == MOCK_CA_CERT_PEM
 
 
+async def test_setup_normalizes_messy_pasted_pem(hass: HomeAssistant, mock_probe) -> None:
+    """A PEM with a leading UTF-8 BOM, CRLF line endings, and a stray blank
+    line -- the kind a Windows text editor's copy produces, as opposed to a
+    `type` dump (issue #291) -- must still be accepted and stored in its
+    normalized form, not rejected with an opaque InvalidHeader."""
+    messy_cert = "\ufeff" + MOCK_CA_CERT_PEM.replace("\n", "\r\n") + "\r\n\r\n"
+    messy_key = "\ufeff" + MOCK_CA_KEY_PEM.replace("\n", "\r\n")
+
+    result = await hass.config_entries.flow.async_init(DOMAIN, context={"source": "user"})
+    result = await hass.config_entries.flow.async_configure(
+        result["flow_id"],
+        {
+            CONF_HOST: MOCK_HOST,
+            CONF_CA_CERT_PEM: messy_cert,
+            CONF_CA_KEY_PEM: messy_key,
+        },
+    )
+    assert result["type"] == FlowResultType.CREATE_ENTRY
+    assert result["data"][CONF_CA_CERT_PEM] == MOCK_CA_CERT_PEM
+    assert result["data"][CONF_CA_KEY_PEM] == MOCK_CA_KEY_PEM
+
+
+def test_normalize_pem_strips_bom_crlf_and_blank_lines() -> None:
+    """Unit-level check of the helper itself, isolated from the flow."""
+    from custom_components.localthings.config_flow import _normalize_pem
+
+    messy = "\ufeff-----BEGIN CERTIFICATE-----\r\nTEST-CA\r\n\r\n-----END CERTIFICATE-----\r\n"
+    assert _normalize_pem(messy) == (
+        "-----BEGIN CERTIFICATE-----\nTEST-CA\n-----END CERTIFICATE-----"
+    )
+    # A clean PEM (the `type`-dump case) passes through unchanged.
+    clean = "-----BEGIN CERTIFICATE-----\nTEST-CA\n-----END CERTIFICATE-----"
+    assert _normalize_pem(clean) == clean
+
+
 def test_order_candidates_prefers_known_ports() -> None:
     """Live ports are ordered with the historically known DTLS ports first,
     then the rest ascending."""
@@ -201,6 +243,11 @@ class FakeSession:
 
     instances: ClassVar[list[FakeSession]] = []
     reject_certs: ClassVar[set[str]] = set()
+    # smartthings-local >= 0.1.3 ("redacted typed failures") no longer puts
+    # the alert in connect()'s exception text -- set True to model that, so
+    # a test can check the diagnostic-handshake fallback (_resolve_alert)
+    # instead of the legacy _alert_name text-parsing path.
+    redact_rejection: ClassVar[bool] = False
 
     def __init__(self, host, port, cert_pem=None, key_pem=None, **kwargs):
         self.host, self.port, self.cert_pem = host, port, cert_pem
@@ -208,6 +255,10 @@ class FakeSession:
 
     def connect(self):
         if self.cert_pem in FakeSession.reject_certs:
+            if FakeSession.redact_rejection:
+                from smartthings_local.errors import SessionError
+
+                raise SessionError()
             raise ConnectionError(
                 "DTLS handshake error: [('SSL routines', '', 'sslv3 alert bad certificate')]"
             )
@@ -231,6 +282,7 @@ def fake_dtls(monkeypatch):
 
     FakeSession.instances = []
     FakeSession.reject_certs = set()
+    FakeSession.redact_rejection = False
     monkeypatch.setattr(config_flow, "_fetch_samsung_uuid", lambda: "test-uuid")
     monkeypatch.setattr(
         config_flow,
@@ -443,6 +495,77 @@ async def test_rejected_reused_leaf_is_reminted(
     assert [s.cert_pem for s in FakeSession.instances] == [MOCK_LEAF_CERT_PEM, "FULLCHAIN"]
 
 
+async def test_rejected_reused_leaf_is_reminted_against_a_redacted_library(
+    hass: HomeAssistant, monkeypatch, fake_dtls
+) -> None:
+    """Same flow as test_rejected_reused_leaf_is_reminted, but against a
+    connect() failure shaped like smartthings-local >= 0.1.3 -- a fixed,
+    redacted exception with no alert text at all (see errors.py's
+    "Classified errors"). The re-mint decision has to come from
+    _resolve_alert's diagnostic-handshake fallback instead of _alert_name."""
+    from custom_components.localthings import config_flow
+
+    existing = MockConfigEntry(domain=DOMAIN, data=ENTRY_DATA, unique_id="localthings_other")
+    existing.add_to_hass(hass)
+    _patch_clienthello(monkeypatch, {49154})
+    FakeSession.reject_certs = {MOCK_LEAF_CERT_PEM}
+    FakeSession.redact_rejection = True
+
+    class _DiagnosticResult:
+        alert = (2, "bad_certificate")
+
+    diagnosed: list[int] = []
+
+    def _diagnostic_alert(host, port, cert_pem, key_pem):
+        diagnosed.append(port)
+        return _DiagnosticResult()
+
+    monkeypatch.setattr(config_flow, "_diagnostic_alert", _diagnostic_alert)
+
+    result = await hass.config_entries.flow.async_init(DOMAIN, context={"source": "user"})
+    result = await hass.config_entries.flow.async_configure(
+        result["flow_id"], {CONF_HOST: MOCK_HOST}
+    )
+
+    assert result["type"] == FlowResultType.CREATE_ENTRY
+    assert result["data"][CONF_LEAF_CERT_PEM] == "FULLCHAIN"
+    assert [s.cert_pem for s in FakeSession.instances] == [MOCK_LEAF_CERT_PEM, "FULLCHAIN"]
+    assert diagnosed == [49154]
+
+
+def test_diagnostic_handshake_runs_once_not_once_per_failing_port(monkeypatch) -> None:
+    """_diagnostic_alert commits association state on the device (see its
+    own docstring) -- running it once per failing candidate instead of once
+    overall would both add latency (each is its own bounded handshake) and
+    multiply that pollution right before _probe_and_validate might retry a
+    real handshake against these very same ports. Three candidates fail
+    here; the diagnostic must run exactly once, against the confirmed-live
+    port, not three times against every candidate in scan order."""
+    from custom_components.localthings import config_flow
+
+    FakeSession.instances = []
+    FakeSession.reject_certs = {MOCK_LEAF_CERT_PEM}
+    FakeSession.redact_rejection = True
+    monkeypatch.setattr("smartthings_local.protocol.dtls_session.DtlsCoapSession", FakeSession)
+
+    diagnosed: list[int] = []
+
+    class _DiagnosticResult:
+        alert = (2, "bad_certificate")
+
+    def _diagnostic_alert(host, port, cert_pem, key_pem):
+        diagnosed.append(port)
+        return _DiagnosticResult()
+
+    monkeypatch.setattr(config_flow, "_diagnostic_alert", _diagnostic_alert)
+
+    scan = _scan(confirmed=[49153, 49154], candidates=[49153, 49154, 49155])
+    with pytest.raises(config_flow.CertRejected):
+        config_flow._handshake_and_read(MOCK_HOST, scan, MOCK_LEAF_CERT_PEM, "KEY")
+
+    assert diagnosed == [49153]  # confirmed-live, and only once
+
+
 async def test_unconfirmed_port_failure_is_not_reminted(
     hass: HomeAssistant, monkeypatch, fake_dtls
 ) -> None:
@@ -517,6 +640,92 @@ def test_cert_alert_is_reported_as_a_certificate_problem() -> None:
         assert err.error_key == "cert_rejected"
 
 
+def test_classify_handshake_failure_uses_a_resolved_alert_over_exception_text() -> None:
+    """_handshake_and_read passes its own resolved `alerts` mapping (built
+    via _resolve_alert, which is what actually classifies a failure against
+    smartthings-local >= 0.1.3's redacted exceptions) -- it must win even
+    when the exception text itself says nothing."""
+    from custom_components.localthings.config_flow import (
+        CertRejected,
+        _classify_handshake_failure,
+    )
+
+    err = _classify_handshake_failure(
+        MOCK_HOST,
+        _scan(confirmed=[49154]),
+        [(49154, RuntimeError("session operation failed"))],
+        {49154: "bad_certificate"},
+    )
+    assert isinstance(err, CertRejected)
+    assert err.error_key == "cert_rejected"
+
+
+def test_resolve_alert_prefers_exception_text_over_the_diagnostic_handshake() -> None:
+    """A library still stamping the alert into its exception text (< 0.1.3)
+    answers for free; the diagnostic handshake must not run at all then."""
+    from custom_components.localthings.config_flow import _resolve_alert
+
+    def _must_not_run(*args, **kwargs):
+        raise AssertionError("must not run the diagnostic handshake")
+
+    with patch("custom_components.localthings.config_flow._diagnostic_alert", _must_not_run):
+        name = _resolve_alert(
+            _openssl_alert("tlsv1 alert unknown ca"), MOCK_HOST, 49154, "CERT", "KEY"
+        )
+    assert name == "unknown_ca"
+
+
+def test_resolve_alert_falls_back_to_the_diagnostic_handshake() -> None:
+    """smartthings-local >= 0.1.3 redacts the exception text (see errors.py's
+    "Classified errors"), so the only way left to learn *why* a handshake
+    failed is the library's own classification of the raw alert record."""
+    from smartthings_local.errors import SessionError
+
+    from custom_components.localthings import config_flow
+
+    class _Result:
+        alert = (2, "bad_certificate")
+
+    with patch.object(config_flow, "_diagnostic_alert", lambda *a, **k: _Result()):
+        name = config_flow._resolve_alert(SessionError(), MOCK_HOST, 49154, "CERT", "KEY")
+    assert name == "bad_certificate"
+
+
+def test_resolve_alert_ignores_a_non_fatal_alert() -> None:
+    """ProbeResult.alert is set for a *received* alert of either level, but
+    only a fatal one (2) means the appliance actually broke off the
+    handshake over it -- a warning-level alert (e.g. close_notify on an
+    otherwise ordinary close) is not evidence of a rejection. The old
+    exception-text path never had this ambiguity: OpenSSL's exception only
+    ever rendered for a fatal alert, so nothing pre-0.1.3 could confuse the
+    two -- the diagnostic-handshake fallback must not introduce the mix-up."""
+    from smartthings_local.errors import SessionError
+
+    from custom_components.localthings import config_flow
+
+    class _Result:
+        alert = (1, "close_notify")  # warning level, not fatal
+
+    with patch.object(config_flow, "_diagnostic_alert", lambda *a, **k: _Result()):
+        name = config_flow._resolve_alert(SessionError(), MOCK_HOST, 49154, "CERT", "KEY")
+    assert name is None
+
+
+def test_resolve_alert_is_none_when_the_diagnostic_handshake_also_fails() -> None:
+    """A best-effort extra probe: its own failure must not raise out of
+    _resolve_alert, it just leaves the caller with no alert to report."""
+    from smartthings_local.errors import SessionError, SessionTimeoutError
+
+    from custom_components.localthings import config_flow
+
+    def _boom(*args, **kwargs):
+        raise SessionTimeoutError()
+
+    with patch.object(config_flow, "_diagnostic_alert", _boom):
+        name = config_flow._resolve_alert(SessionError(), MOCK_HOST, 49154, "CERT", "KEY")
+    assert name is None
+
+
 def test_non_cert_alert_is_kept_distinct_from_a_cert_problem() -> None:
     """A cipher or version mismatch is also a deliberate refusal, but no
     amount of fiddling with CA credentials will fix it."""
@@ -842,7 +1051,11 @@ async def test_unknown_type_step_description_makes_no_version_claim(
 
 
 async def test_duplicate_device_aborted(hass: HomeAssistant, mock_probe) -> None:
-    """Second add of same serial: flow aborts.
+    """Second add of the same *device key*: flow aborts.
+
+    Keyed on the OCF device UUID rather than the serialNum (issue #381), so
+    this is now the check that two genuinely distinct units can no longer
+    trip -- see test_same_serial_on_two_units_is_not_a_duplicate.
 
     When a device already exists the form only asks for host (CA creds are
     reused), so we only submit CONF_HOST in the second configure call.
@@ -850,7 +1063,7 @@ async def test_duplicate_device_aborted(hass: HomeAssistant, mock_probe) -> None
     existing = MockConfigEntry(
         domain=DOMAIN,
         data=ENTRY_DATA,
-        unique_id=f"localthings_{MOCK_SERIAL}",
+        unique_id=f"localthings_{MOCK_DEVICE_KEY}",
     )
     existing.add_to_hass(hass)
 
@@ -864,6 +1077,154 @@ async def test_duplicate_device_aborted(hass: HomeAssistant, mock_probe) -> None
     assert result["reason"] == "already_configured"
 
 
+async def test_same_serial_on_two_units_is_not_a_duplicate(hass: HomeAssistant, mock_probe) -> None:
+    """Issue #381: two Samsung air purifiers of one model ship the identical,
+    well-formed serialNum, so keying the entry on it turned the second one
+    away as already configured. The OCF device UUID differs between them,
+    and it is what the entry is keyed on now, so both can be added.
+
+    Deliberately holds the serial *constant* across the two probes and varies
+    only the device key -- the exact shape of the bug report.
+    """
+    first = MockConfigEntry(
+        domain=DOMAIN,
+        data={**ENTRY_DATA, CONF_HOST: "192.168.0.3"},
+        unique_id=f"localthings_{MOCK_DEVICE_KEY}",
+    )
+    first.add_to_hass(hass)
+
+    second_probe = {
+        **_probe_result(recognized=True),
+        "device_key": "3771f8bf-c184-3a2d-d885-e4c9818736d2",
+        "serial": MOCK_SERIAL,
+    }
+    with patch(
+        "custom_components.localthings.config_flow._probe_and_validate",
+        return_value=second_probe,
+    ):
+        result = await hass.config_entries.flow.async_init(DOMAIN, context={"source": "user"})
+        result = await hass.config_entries.flow.async_configure(
+            result["flow_id"], {CONF_HOST: "192.168.0.14"}
+        )
+
+    assert result["type"] == FlowResultType.CREATE_ENTRY
+    assert result["data"][CONF_DEVICE_KEY] == "3771f8bf-c184-3a2d-d885-e4c9818736d2"
+    # Both entries exist, and the shared serial is still recorded on each --
+    # it is what corroborates a later change of key.
+    assert len(hass.config_entries.async_entries(DOMAIN)) == 2
+    assert result["data"][CONF_SERIAL] == first.data[CONF_SERIAL]
+
+
+async def test_re_adding_during_the_migration_window_is_still_a_duplicate(
+    hass: HomeAssistant, mock_probe
+) -> None:
+    """An entry created before v4 keeps its serial-keyed unique_id until its
+    first *live* poll adopts the UUID, which can be a long while for an
+    appliance that is off (it loads from its snapshot meanwhile, issue
+    #295). The UUID check can't see such an entry, so without a second
+    check on the legacy key, re-adding this very appliance in that window
+    would be waved through -- and the two entries would collide the moment
+    the older one re-keyed, with rekey_entry resolving the collision by
+    deleting the duplicate rows and taking the original's entity_ids,
+    history and automations with them.
+    """
+    existing = MockConfigEntry(
+        domain=DOMAIN,
+        data={k: v for k, v in ENTRY_DATA.items() if k != CONF_DEVICE_KEY},
+        unique_id=f"localthings_{MOCK_SERIAL}",
+        version=3,
+    )
+    existing.add_to_hass(hass)
+
+    result = await hass.config_entries.flow.async_init(DOMAIN, context={"source": "user"})
+    result = await hass.config_entries.flow.async_configure(
+        result["flow_id"], {CONF_HOST: ENTRY_DATA[CONF_HOST]}
+    )
+
+    assert result["type"] == FlowResultType.ABORT
+    assert result["reason"] == "already_configured"
+
+
+async def test_the_migration_window_check_still_separates_two_same_serial_units(
+    hass: HomeAssistant, mock_probe
+) -> None:
+    """The legacy-key check above matches on the host as well as the serial,
+    so it cannot undo the fix: issue #381's two units share a serial but sit
+    at different addresses, and the second must still be addable while the
+    first is mid-migration."""
+    existing = MockConfigEntry(
+        domain=DOMAIN,
+        data={
+            **{k: v for k, v in ENTRY_DATA.items() if k != CONF_DEVICE_KEY},
+            CONF_HOST: "192.168.0.3",
+        },
+        unique_id=f"localthings_{MOCK_SERIAL}",
+        version=3,
+    )
+    existing.add_to_hass(hass)
+
+    second_probe = {
+        **_probe_result(recognized=True),
+        "device_key": "3771f8bf-c184-3a2d-d885-e4c9818736d2",
+        "serial": MOCK_SERIAL,
+    }
+    with patch(
+        "custom_components.localthings.config_flow._probe_and_validate",
+        return_value=second_probe,
+    ):
+        result = await hass.config_entries.flow.async_init(DOMAIN, context={"source": "user"})
+        result = await hass.config_entries.flow.async_configure(
+            result["flow_id"], {CONF_HOST: "192.168.0.14"}
+        )
+
+    assert result["type"] == FlowResultType.CREATE_ENTRY
+    assert result["data"][CONF_DEVICE_KEY] == "3771f8bf-c184-3a2d-d885-e4c9818736d2"
+
+
+def test_probe_reads_the_device_key_from_oic_d_without_an_extra_round_trip(monkeypatch):
+    """`_read_device` already fetches /oic/p and /oic/d for the device-type
+    signal, so keying on the OCF UUID costs no additional GET -- it reads
+    the identity that call already returned."""
+    from custom_components.localthings.config_flow import _read_device
+
+    device0 = [
+        {"rt": ["x.com.samsung.devcol"]},
+        {
+            "href": "/information/vs/0",
+            "rep": {
+                "x.com.samsung.da.modelNum": "AVT-WW-TP1-23-AXX500|10251941",
+                "x.com.samsung.da.serialNum": "BS7SP9AW400114A",
+            },
+        },
+    ]
+
+    class _Session:
+        def __init__(self):
+            self.paths = []
+
+        def get(self, path, timeout=10.0):
+            self.paths.append(tuple(path))
+            table = {
+                ("oic", "p"): {"mnmn": "Samsung Electronics", "pi": "PLATFORM-UUID"},
+                ("oic", "d"): {"di": "CCFD73B3-AEB4-792A-1100-68F06F5D603B"},
+                ("device", "0"): device0,
+            }
+            body = table.get(tuple(path))
+            if body is None:
+                return 0x84, b""
+            import cbor2
+
+            return 0x45, cbor2.dumps(body)
+
+    sess = _Session()
+    info = _read_device(sess, "192.168.0.3", MOCK_PORT)
+
+    assert info["device_key"] == "ccfd73b3-aeb4-792a-1100-68f06f5d603b"
+    assert info["serial"] == "BS7SP9AW400114A"
+    # Exactly the three reads the probe already made before this change.
+    assert sess.paths == [("oic", "p"), ("oic", "d"), ("oic", "res"), ("device", "0")]
+
+
 def test_probe_marks_washer_as_recognized(monkeypatch):
     """A washer reports no oneUiVersion at all -- its consumer-model code
     must still resolve so setup doesn't warn about an unrecognized type."""
@@ -900,7 +1261,11 @@ async def test_options_flow_init_shows_menu(hass: HomeAssistant) -> None:
 
     assert result["type"] == FlowResultType.MENU
     assert result["step_id"] == "init"
-    assert set(cast(Iterable[str], result["menu_options"])) == {"settings", "debug_write"}
+    assert set(cast(Iterable[str], result["menu_options"])) == {
+        "settings",
+        "forget_learned_modes",
+        "debug_write",
+    }
 
 
 async def test_options_flow_default_is_off(hass: HomeAssistant) -> None:
@@ -939,6 +1304,109 @@ async def test_options_flow_can_enable_bypass(hass: HomeAssistant) -> None:
     assert entry.options[CONF_BYPASS_REMOTE_CONTROL] is True
 
 
+async def test_learned_modes_option_defaults_to_on(hass: HomeAssistant) -> None:
+    """Issue #327's remembering is on by default -- a device that hides a
+    mode it's in should just work, not need the option found first."""
+    entry = MockConfigEntry(domain=DOMAIN, data=ENTRY_DATA, unique_id=f"localthings_{MOCK_SERIAL}")
+    entry.add_to_hass(hass)
+
+    result = await hass.config_entries.options.async_init(entry.entry_id)
+    result = await hass.config_entries.options.async_configure(
+        result["flow_id"], user_input={"next_step_id": "settings"}
+    )
+
+    data_schema = result["data_schema"]
+    assert data_schema is not None
+    assert data_schema({})[CONF_LEARN_MODES] is True
+
+
+async def test_learned_modes_option_can_be_turned_off(hass: HomeAssistant) -> None:
+    entry = MockConfigEntry(domain=DOMAIN, data=ENTRY_DATA, unique_id=f"localthings_{MOCK_SERIAL}")
+    entry.add_to_hass(hass)
+
+    result = await hass.config_entries.options.async_init(entry.entry_id)
+    result = await hass.config_entries.options.async_configure(
+        result["flow_id"], user_input={"next_step_id": "settings"}
+    )
+    result = await hass.config_entries.options.async_configure(
+        result["flow_id"],
+        user_input={CONF_BYPASS_REMOTE_CONTROL: False, CONF_LEARN_MODES: False},
+    )
+
+    assert result["type"] == FlowResultType.CREATE_ENTRY
+    assert entry.options[CONF_LEARN_MODES] is False
+
+
+async def test_cloud_courses_enabled_option_defaults_to_on(hass: HomeAssistant) -> None:
+    """Issue #364's toggle starts on -- devices that already have a working
+    downloaded-cycle setup keep it without having to find the option first."""
+    entry = MockConfigEntry(domain=DOMAIN, data=ENTRY_DATA, unique_id=f"localthings_{MOCK_SERIAL}")
+    entry.add_to_hass(hass)
+
+    result = await hass.config_entries.options.async_init(entry.entry_id)
+    result = await hass.config_entries.options.async_configure(
+        result["flow_id"], user_input={"next_step_id": "settings"}
+    )
+
+    data_schema = result["data_schema"]
+    assert data_schema is not None
+    assert data_schema({})[CONF_CLOUD_COURSES_ENABLED] is True
+
+
+async def test_cloud_courses_enabled_option_can_be_turned_off(hass: HomeAssistant) -> None:
+    entry = MockConfigEntry(domain=DOMAIN, data=ENTRY_DATA, unique_id=f"localthings_{MOCK_SERIAL}")
+    entry.add_to_hass(hass)
+
+    result = await hass.config_entries.options.async_init(entry.entry_id)
+    result = await hass.config_entries.options.async_configure(
+        result["flow_id"], user_input={"next_step_id": "settings"}
+    )
+    result = await hass.config_entries.options.async_configure(
+        result["flow_id"],
+        user_input={
+            CONF_BYPASS_REMOTE_CONTROL: False,
+            CONF_LEARN_MODES: True,
+            CONF_CLOUD_COURSES_ENABLED: False,
+        },
+    )
+
+    assert result["type"] == FlowResultType.CREATE_ENTRY
+    assert entry.options[CONF_CLOUD_COURSES_ENABLED] is False
+
+
+@pytest.mark.parametrize(
+    ("stored", "listed"),
+    [
+        ({"/mode/convenient/vs/0": ["Quiet"]}, "Quiet"),
+        # Malformed -- nothing writes this shape, but a hand-edited
+        # .storage can hold it, and this step is the one screen that can
+        # clear it, so it must not be the one screen that trips over it.
+        ({"/mode/convenient/vs/0": None}, "(none)"),
+    ],
+)
+async def test_forget_learned_modes_clears_the_entry(hass: HomeAssistant, stored, listed) -> None:
+    """The reset step works on an unloaded entry too, by dropping the
+    persisted copy directly -- that's all a reload would restore from."""
+    entry = MockConfigEntry(
+        domain=DOMAIN,
+        data={**ENTRY_DATA, CONF_LEARNED_MODES: stored},
+        unique_id=f"localthings_{MOCK_SERIAL}",
+    )
+    entry.add_to_hass(hass)
+
+    result = await hass.config_entries.options.async_init(entry.entry_id)
+    result = await hass.config_entries.options.async_configure(
+        result["flow_id"], user_input={"next_step_id": "forget_learned_modes"}
+    )
+    assert result["type"] == FlowResultType.FORM
+    assert result["description_placeholders"] == {"codes": listed}
+
+    result = await hass.config_entries.options.async_configure(result["flow_id"], user_input={})
+
+    assert result["type"] == FlowResultType.CREATE_ENTRY
+    assert entry.data[CONF_LEARNED_MODES] == {}
+
+
 async def test_options_flow_reflects_previously_saved_value(hass: HomeAssistant) -> None:
     """Reopening the form shows the currently-saved choice as the default,
     not always False."""
@@ -1001,9 +1469,10 @@ async def test_options_flow_debug_edit_writes_and_shows_result(
     hass: HomeAssistant,
     mock_coordinator_session,
 ) -> None:
-    """Picking an href, then submitting a payload, drives
-    coordinator.async_raw_write and lands on the result menu with the
-    device's response."""
+    """Picking an href, then submitting a payload, calls the write_resource
+    service (issue #300) -- which drives
+    coordinator.async_raw_write_sequence -- and lands on the result menu
+    with the device's response."""
     entry = MockConfigEntry(domain=DOMAIN, data=ENTRY_DATA, unique_id=f"localthings_{MOCK_SERIAL}")
     entry.add_to_hass(hass)
     await hass.config_entries.async_setup(entry.entry_id)
@@ -1021,8 +1490,20 @@ async def test_options_flow_debug_edit_writes_and_shows_result(
     assert result["step_id"] == "debug_edit"
 
     with patch(
-        "custom_components.localthings.coordinator.LocalThingsCoordinator.async_raw_write",
-        return_value=(0x44, {"a": 1}),
+        "custom_components.localthings.coordinator.LocalThingsCoordinator.async_raw_write_sequence",
+        return_value={
+            "results": [
+                {
+                    "href": "/washer/vs/0",
+                    "code": "2.04",
+                    "raw_code": 0x44,
+                    "accepted": True,
+                    "before": {},
+                    "after": {"a": 1},
+                    "changed": True,
+                }
+            ]
+        },
     ):
         result = await hass.config_entries.options.async_configure(
             result["flow_id"],
@@ -1088,8 +1569,20 @@ async def test_options_flow_finish_preserves_existing_options(
         user_input={"href": "/washer/vs/0"},
     )
     with patch(
-        "custom_components.localthings.coordinator.LocalThingsCoordinator.async_raw_write",
-        return_value=(0x44, {"a": 1}),
+        "custom_components.localthings.coordinator.LocalThingsCoordinator.async_raw_write_sequence",
+        return_value={
+            "results": [
+                {
+                    "href": "/washer/vs/0",
+                    "code": "2.04",
+                    "raw_code": 0x44,
+                    "accepted": True,
+                    "before": {},
+                    "after": {"a": 1},
+                    "changed": True,
+                }
+            ]
+        },
     ):
         result = await hass.config_entries.options.async_configure(
             result["flow_id"],

tests/localthings/test_coordinator.py

@@ -2,6 +2,9 @@
 
 from __future__ import annotations
 
+import asyncio
+import contextlib
+import time
 from datetime import timedelta
 from unittest.mock import AsyncMock, patch
 
@@ -12,6 +15,7 @@ from homeassistant.const import EVENT_HOMEASSISTANT_STOP
 from homeassistant.core import HomeAssistant
 from homeassistant.exceptions import ServiceValidationError
 from homeassistant.helpers import issue_registry as ir
+from smartthings_local.errors import SessionClosedError, SessionError, SessionTimeoutError
 
 from custom_components.localthings.const import (
     CONF_BYPASS_REMOTE_CONTROL,
@@ -21,6 +25,7 @@ from custom_components.localthings.const import (
     SUMMARY_INTERVAL_S,
 )
 from custom_components.localthings.coordinator import (
+    _RECOVERY_RETRY_S,
     LocalThingsCoordinator,
     _local_source_port,
 )
@@ -30,7 +35,13 @@ from custom_components.localthings.registry.capabilities.common import (
     remote_control_required_for_write,
 )
 
-from .conftest import ENTRY_DATA, MOCK_MODEL, MOCK_SERIAL
+from .conftest import (
+    ENTRY_DATA,
+    MOCK_DEVICE_KEY,
+    MOCK_MODEL,
+    MOCK_SERIAL,
+    FakeObserveSession,
+)
 from .conftest import _load_fridge_resources as _load_fridge
 
 
@@ -68,7 +79,12 @@ async def test_summary_interval(hass: HomeAssistant, mock_entry, mock_coordinato
 
 
 async def test_update_failed_on_persistent_poll_error(hass: HomeAssistant, mock_entry) -> None:
-    """ConfigEntryNotReady raised when poll fails even after reconnect."""
+    """ConfigEntryNotReady raised when poll fails even after reconnect.
+
+    An entry with no stored discovery snapshot has never reached this device,
+    so there is nothing to load offline from (issue #295) -- it stays on HA's
+    backoff rather than loading empty.
+    """
 
     with (
         patch("custom_components.localthings.coordinator.LocalThingsCoordinator._connect_session"),
@@ -142,7 +158,7 @@ def test_run_discovery_falls_back_to_host_for_placeholder_serial(
 ) -> None:
     """Issue #83: the ARTIK051_DONGLE_REF firmware family reports the
     literal string 'Nothing(SVC)' as serialNum on every unit. Left as-is,
-    two such units get the same device_serial (which feeds both the HA
+    two such units get the same device_key (which feeds both the HA
     device-registry identifier and every entity's unique_id), so the
     second one's entities silently collide and get dropped. It must be
     treated the same as an empty serial and fall back to the host."""
@@ -156,7 +172,7 @@ def test_run_discovery_falls_back_to_host_for_placeholder_serial(
     }
     coordinator = LocalThingsCoordinator(hass, legacy_entry)
     coordinator._run_discovery(resources)
-    assert coordinator.device_serial == legacy_entry.data[CONF_HOST]
+    assert coordinator.device_key == legacy_entry.data[CONF_HOST]
 
 
 def test_run_discovery_falls_back_to_host_for_all_f_placeholder_serial(
@@ -167,7 +183,7 @@ def test_run_discovery_falls_back_to_host_for_all_f_placeholder_serial(
     character the same repeated hex digit. A washer and a dryer, two
     different physical units, both reported the literal serialNum
     'FFFFFFFFFFFFFFF', so without this fallback they'd collide on
-    device_serial exactly like the #83 case above."""
+    device_key exactly like the #83 case above."""
     resources = {
         "/information/vs/0": {
             "x.com.samsung.da.modelNum": "DA_WM_A51_20_COMMON|20221341|30010102001211000103000000000000",  # noqa: E501
@@ -178,7 +194,7 @@ def test_run_discovery_falls_back_to_host_for_all_f_placeholder_serial(
     }
     coordinator = LocalThingsCoordinator(hass, legacy_entry)
     coordinator._run_discovery(resources)
-    assert coordinator.device_serial == legacy_entry.data[CONF_HOST]
+    assert coordinator.device_key == legacy_entry.data[CONF_HOST]
 
 
 # ---------------------------------------------------------------------------
@@ -190,7 +206,7 @@ def test_identity_is_resolved_before_any_poll(hass: HomeAssistant, mock_entry) -
     """The coordinator mints registry keys from the entry's stored identity at
     construction time.
 
-    `device_serial` is what entity unique_ids and device identifiers are built
+    `device_key` is what entity unique_ids and device identifiers are built
     from, and those are permanent. Seeding it with the host meant anything that
     registered before the first poll returned -- the connection-mode sensor
     especially, added unconditionally rather than from `bound` -- was written
@@ -199,8 +215,8 @@ def test_identity_is_resolved_before_any_poll(hass: HomeAssistant, mock_entry) -
     """
     coordinator = LocalThingsCoordinator(hass, mock_entry)
 
-    assert coordinator.device_serial == MOCK_SERIAL
-    assert coordinator.device_info["identifiers"] == {(DOMAIN, MOCK_SERIAL)}
+    assert coordinator.device_key == MOCK_DEVICE_KEY
+    assert coordinator.device_info["identifiers"] == {(DOMAIN, MOCK_DEVICE_KEY)}
     assert coordinator.device_info["model"] == MOCK_MODEL
     assert coordinator.device_info["name"] == f"Samsung Refrigerator ({MOCK_MODEL})"
     assert mock_entry.data[CONF_HOST] not in str(coordinator.device_info["identifiers"])
@@ -231,7 +247,7 @@ def test_discovery_keeps_the_registered_identity(hass: HomeAssistant, mock_entry
     coordinator = LocalThingsCoordinator(hass, mock_entry)
     coordinator._run_discovery(resources)
 
-    assert coordinator.device_serial == MOCK_SERIAL
+    assert coordinator.device_key == MOCK_DEVICE_KEY
 
 
 def test_discovery_backfills_a_legacy_entry_identity(hass: HomeAssistant, legacy_entry) -> None:
@@ -478,6 +494,87 @@ async def test_reconnect_while_observe_mode_downgrades_to_poll(
     assert coordinator._observe.mode == MODE_POLL
 
 
+async def test_total_poll_failure_downgrades_observe_mode_to_poll(
+    hass: HomeAssistant, mock_entry, mock_coordinator_observe_session, fridge_resources
+) -> None:
+    """A device that drops off the network entirely -- both the poll and its
+    reconnect retry fail -- must not leave the connection-mode sensor
+    reporting 'Push' forever (issue #287). Only the *successful* reconnect
+    branch used to touch observe mode (see
+    test_reconnect_while_observe_mode_downgrades_to_poll); this covers the
+    branch where the device stays unreachable."""
+    fake = mock_coordinator_observe_session
+    await hass.config_entries.async_setup(mock_entry.entry_id)
+    await hass.async_block_till_done()
+
+    coordinator: LocalThingsCoordinator = hass.data[DOMAIN][mock_entry.entry_id]
+    hrefs = coordinator._hot_hrefs + coordinator._warm_hrefs
+
+    fake.notify_on_subscribe = {"notified": True}
+    entered = await hass.async_add_executor_job(
+        coordinator._observe.try_enter_observe_mode,
+        fake,
+        hrefs,
+        0.02,
+        0.8,
+    )
+    assert entered is True
+    assert coordinator.observe_mode == MODE_OBSERVE
+
+    last_notify_ts = coordinator._observe._last_notify_ts
+    assert last_notify_ts is not None
+    coordinator._observe._last_notify_ts = last_notify_ts - (PUSH_HEALTH_WINDOW_S + 1)
+
+    with (
+        patch(
+            "custom_components.localthings.coordinator.LocalThingsCoordinator._poll_once",
+            side_effect=[RuntimeError("connection lost"), RuntimeError("still lost")],
+        ),
+        patch(
+            "custom_components.localthings.coordinator.asyncio.sleep",
+            new=AsyncMock(),
+        ),
+    ):
+        await coordinator.async_request_refresh()
+        await hass.async_block_till_done()
+
+    # The update still "succeeds" with the last-known snapshot (issue #254's
+    # degraded-data path) -- but the connection mode must reflect reality
+    # now, not the stale OBSERVE state from before the outage.
+    assert coordinator.observe_mode == MODE_POLL
+    assert coordinator.last_update_success is True
+
+
+def test_defer_reconnect_for_reconnects_immediately_on_a_confirmed_dead_session(
+    hass: HomeAssistant, mock_entry
+) -> None:
+    """smartthings-local >= 0.1.6 raises SessionClosedError -- a
+    ConnectionError, not a TimeoutError -- the moment a dead reader thread
+    is confirmed, instead of the old behavior of letting the request hang
+    out to its own timeout and surface as an ambiguous TimeoutError.
+    _defer_reconnect_for must never extend the block-ACK tolerance to a
+    failure this unambiguous; see its docstring for the full reasoning."""
+    coordinator = LocalThingsCoordinator(hass, mock_entry)
+    coordinator._discovered = True
+
+    assert coordinator._defer_reconnect_for(SessionClosedError()) is False
+
+
+def test_defer_reconnect_for_still_tolerates_an_ambiguous_timeout(
+    hass: HomeAssistant, mock_entry
+) -> None:
+    """The other half of the same distinction: a plain block-ACK timeout --
+    still a TimeoutError, including smartthings-local's own
+    SessionTimeoutError subclass -- keeps its multi-cycle tolerance rather
+    than being swept into the immediate-reconnect path above."""
+    coordinator = LocalThingsCoordinator(hass, mock_entry)
+    coordinator._discovered = True
+
+    for _ in range(coordinator._POLL_TIMEOUT_LIMIT - 1):
+        assert coordinator._defer_reconnect_for(SessionTimeoutError()) is True
+    assert coordinator._defer_reconnect_for(SessionTimeoutError()) is False
+
+
 async def test_poll_timeout_skips_reconnect_when_push_is_healthy(
     hass: HomeAssistant, mock_entry, mock_coordinator_observe_session
 ) -> None:
@@ -691,6 +788,181 @@ async def test_reconnect_from_observe_mode_resubscribes_immediately(
     assert coordinator.observe_mode == MODE_OBSERVE
 
 
+async def test_attempt_observe_mode_discards_stale_commit_after_session_swap(
+    hass: HomeAssistant, mock_entry, mock_coordinator_observe_session
+) -> None:
+    """A reconnect (the poll path's own, or a command's retry) can swap
+    self._session while this attempt's grace wait is in flight -- it runs
+    without holding _session_lock precisely so a write isn't blocked behind
+    it (issue #294). Committing observe mode against the now-stale local
+    `sess` reference would claim "Push" on a session that's already gone,
+    with nothing left to notice -- the identity re-check under the lock
+    right before committing must catch this and abandon instead.
+
+    The new session is never-tried, though, not just abandoned: it must
+    flag an immediate resubscribe rather than let _last_observe_attempt_ts
+    (stamped for the now-abandoned attempt) throttle it for up to
+    _RECOVERY_RETRY_S.
+
+    Simulates the swap from inside await_observe_notifies itself rather
+    than via real concurrency: subscribe_hrefs (and its lock) has already
+    returned by the time that call runs, so this lands exactly in the
+    window the identity check exists to cover, deterministically."""
+    await hass.config_entries.async_setup(mock_entry.entry_id)
+    await hass.async_block_till_done()
+    coordinator: LocalThingsCoordinator = hass.data[DOMAIN][mock_entry.entry_id]
+    assert coordinator._resubscribe_due is False
+
+    other = FakeObserveSession()
+
+    def _swap_session_mid_wait(subscribed, grace_period_s, success_fraction=None):
+        coordinator._session = other  # ty: ignore[invalid-assignment]
+        return True
+
+    with patch.object(
+        coordinator._observe, "await_observe_notifies", side_effect=_swap_session_mid_wait
+    ):
+        await coordinator._attempt_observe_mode()
+
+    assert coordinator.observe_mode == MODE_POLL
+    assert coordinator._observe.subscribed_hrefs == set()
+    assert coordinator._observe._refresh_thread is None
+    assert coordinator._resubscribe_due is True
+
+
+async def test_attempt_observe_mode_survives_a_failed_reconnect(
+    hass: HomeAssistant, mock_entry, mock_coordinator_observe_session
+) -> None:
+    """The session was closed out from under this attempt concurrently
+    (rare, but real -- see the docstring above), and the reconnect it tries
+    on the way back in fails too (smartthings-local >= 0.1.3's redacted
+    SessionError, or any other exception). That must not escape
+    _async_update_data uncaught: it should land in the same "give up on
+    push this cycle" state the subscribe-failed and stale-session branches
+    already produce, not skip this integration's own logging/state handling
+    entirely."""
+    await hass.config_entries.async_setup(mock_entry.entry_id)
+    await hass.async_block_till_done()
+    coordinator: LocalThingsCoordinator = hass.data[DOMAIN][mock_entry.entry_id]
+    coordinator._session = None
+    coordinator._reconnect_times = []
+
+    with patch.object(
+        coordinator,
+        "_connect_session",
+        side_effect=SessionError(),
+    ):
+        await coordinator._attempt_observe_mode()  # must not raise
+
+    assert coordinator.observe_mode == MODE_POLL
+    assert coordinator._observe.subscribed_hrefs == set()
+    assert coordinator._resubscribe_due is False
+    # Not the poll path's own reconnect-frequency window (see the fix's
+    # comment) -- this failure must not count toward it.
+    assert coordinator._reconnect_times == []
+
+
+async def test_maybe_retry_observe_mode_uses_most_recent_attempt_not_just_mode_change(
+    hass: HomeAssistant, mock_entry, mock_coordinator_observe_session
+) -> None:
+    """_set_mode only stamps last_mode_change_ts on an actual transition,
+    so a device that never successfully enters observe mode leaves that
+    timestamp stuck at construction time forever -- a failed attempt keeps
+    calling _set_mode(MODE_POLL) while already in MODE_POLL, a no-op.
+    Gating solely on that timestamp would make the 600s throttle open once
+    and then never close again, re-attempting (and paying the subscribe
+    burst) on every single poll cycle instead of every _RECOVERY_RETRY_S."""
+    fake = mock_coordinator_observe_session
+    await hass.config_entries.async_setup(mock_entry.entry_id)
+    await hass.async_block_till_done()
+    coordinator: LocalThingsCoordinator = hass.data[DOMAIN][mock_entry.entry_id]
+    assert coordinator.observe_mode == MODE_POLL  # never notified during setup
+
+    # Simulate exactly the scenario above: mode_change_ts is old (as it
+    # would be forever, for a device that never gets push), but an attempt
+    # really did just run.
+    coordinator._observe.last_mode_change_ts = time.monotonic() - _RECOVERY_RETRY_S - 1
+    coordinator._last_observe_attempt_ts = time.monotonic()
+
+    with patch.object(fake, "subscribe") as mock_subscribe:
+        await coordinator._maybe_retry_observe_mode()
+
+    mock_subscribe.assert_not_called()
+
+
+async def test_maybe_retry_observe_mode_also_respects_a_mode_change_outside_an_attempt(
+    hass: HomeAssistant, mock_entry, mock_coordinator_observe_session
+) -> None:
+    """The mirror of the case above: last_mode_change_ts can be the more
+    recent of the two as well, e.g. right after the poll or command path's
+    own downgrade (neither goes through _attempt_observe_mode, so neither
+    stamps _last_observe_attempt_ts). Dropping last_mode_change_ts from the
+    max() would let a device that was *just* downgraded get re-attempted
+    immediately instead of respecting _RECOVERY_RETRY_S."""
+    fake = mock_coordinator_observe_session
+    await hass.config_entries.async_setup(mock_entry.entry_id)
+    await hass.async_block_till_done()
+    coordinator: LocalThingsCoordinator = hass.data[DOMAIN][mock_entry.entry_id]
+    assert coordinator.observe_mode == MODE_POLL
+
+    coordinator._last_observe_attempt_ts = time.monotonic() - _RECOVERY_RETRY_S - 1
+    coordinator._observe.last_mode_change_ts = time.monotonic()
+
+    with patch.object(fake, "subscribe") as mock_subscribe:
+        await coordinator._maybe_retry_observe_mode()
+
+    mock_subscribe.assert_not_called()
+
+
+async def test_attempt_observe_mode_releases_lock_before_the_grace_wait(
+    hass: HomeAssistant, mock_entry, mock_coordinator_observe_session
+) -> None:
+    """The subscribe burst holds _session_lock (it touches the session);
+    the grace wait after it must not, or a command write could stall
+    behind up to _OBSERVE_GRACE_PERIOD_S of an unrelated observe-mode-entry
+    attempt (issue #294). By construction, subscribe_hrefs's own
+    `async with self._session_lock:` has already exited by the time
+    await_observe_notifies is even called -- checked here rather than
+    inferred from timing."""
+    await hass.config_entries.async_setup(mock_entry.entry_id)
+    await hass.async_block_till_done()
+    coordinator: LocalThingsCoordinator = hass.data[DOMAIN][mock_entry.entry_id]
+
+    locked_during_wait = {"value": None}
+
+    def _check_lock(subscribed, grace_period_s, success_fraction=None):
+        locked_during_wait["value"] = coordinator._session_lock.locked()
+        return True
+
+    with patch.object(coordinator._observe, "await_observe_notifies", side_effect=_check_lock):
+        await coordinator._attempt_observe_mode()
+
+    assert locked_during_wait["value"] is False
+
+
+async def test_attempt_observe_mode_holds_lock_during_the_subscribe_burst(
+    hass: HomeAssistant, mock_entry, mock_coordinator_observe_session
+) -> None:
+    """The other half of the split above: the subscribe burst does touch
+    the session, so it must hold _session_lock -- that's what actually
+    stops a concurrent close from landing mid-subscribe (issue #294)."""
+    await hass.config_entries.async_setup(mock_entry.entry_id)
+    await hass.async_block_till_done()
+    coordinator: LocalThingsCoordinator = hass.data[DOMAIN][mock_entry.entry_id]
+
+    locked_during_subscribe = {"value": None}
+    real_subscribe_hrefs = coordinator._observe.subscribe_hrefs
+
+    def _check_lock(session, hrefs):
+        locked_during_subscribe["value"] = coordinator._session_lock.locked()
+        return real_subscribe_hrefs(session, hrefs)
+
+    with patch.object(coordinator._observe, "subscribe_hrefs", side_effect=_check_lock):
+        await coordinator._attempt_observe_mode()
+
+    assert locked_during_subscribe["value"] is True
+
+
 async def test_sweep_mismatch_never_downgrades_a_live_observe_session(
     hass: HomeAssistant, mock_entry, mock_coordinator_observe_session
 ) -> None:
@@ -780,6 +1052,110 @@ async def test_sweep_mismatch_forces_subpolls_on_a_live_observe_session(
     mock_subpolls.assert_called_once_with(force=True)
 
 
+async def _cancel_background_subpolls(coordinator: LocalThingsCoordinator) -> None:
+    """Setup starts `_run_subpolls` as a background task. Tests that drive
+    it directly have to cancel that one first, or a patched
+    `_poll_hrefs_blocking` also captures its batches."""
+    task = coordinator._subpoll_task
+    if task is None:
+        return
+    task.cancel()
+    coordinator._subpoll_task = None
+    with contextlib.suppress(asyncio.CancelledError):
+        await task
+
+
+async def test_observe_mode_subpolls_only_silent_hrefs(
+    hass: HomeAssistant, mock_entry, mock_coordinator_observe_session
+) -> None:
+    """Issue #92: subscribed-but-silent hrefs keep the hot/warm cadence
+    instead of waiting for the 30s sweep."""
+    await hass.config_entries.async_setup(mock_entry.entry_id)
+    await hass.async_block_till_done()
+    coordinator: LocalThingsCoordinator = hass.data[DOMAIN][mock_entry.entry_id]
+    await _cancel_background_subpolls(coordinator)
+    assert coordinator._hot_hrefs
+    silent = coordinator._hot_hrefs[0]
+    coordinator._observe.mode = MODE_OBSERVE
+    coordinator._observe.fallback_hrefs = {silent}
+
+    polled: list[list[str]] = []
+
+    def _capture(hrefs):
+        polled.append(list(hrefs))
+
+    with (
+        patch.object(coordinator, "_poll_hrefs_blocking", side_effect=_capture),
+        patch(
+            "custom_components.localthings.coordinator.asyncio.sleep",
+            new_callable=AsyncMock,
+        ),
+    ):
+        await coordinator._run_subpolls()
+
+    assert polled
+    for batch in polled:
+        assert set(batch) == {silent}
+
+
+async def test_observe_mode_skips_subpolls_when_nothing_is_silent(
+    hass: HomeAssistant, mock_entry, mock_coordinator_observe_session
+) -> None:
+    """The observe-mode no-op stays in place when every subscribed href
+    actually notified -- issue #92 only keeps the silent ones on poll."""
+    await hass.config_entries.async_setup(mock_entry.entry_id)
+    await hass.async_block_till_done()
+    coordinator: LocalThingsCoordinator = hass.data[DOMAIN][mock_entry.entry_id]
+    await _cancel_background_subpolls(coordinator)
+    coordinator._observe.mode = MODE_OBSERVE
+    coordinator._observe.fallback_hrefs = set()
+
+    with (
+        patch.object(coordinator, "_poll_hrefs_blocking") as mock_poll,
+        patch(
+            "custom_components.localthings.coordinator.asyncio.sleep",
+            new_callable=AsyncMock,
+        ) as mock_sleep,
+    ):
+        await coordinator._run_subpolls()
+
+    mock_poll.assert_not_called()
+    mock_sleep.assert_not_called()
+
+
+async def test_observe_mode_skips_empty_subpoll_slots(
+    hass: HomeAssistant, mock_entry, mock_coordinator_observe_session
+) -> None:
+    """Once hot is empty, odd slots would otherwise take the session lock
+    and dispatch a no-op executor job. Skip those."""
+    await hass.config_entries.async_setup(mock_entry.entry_id)
+    await hass.async_block_till_done()
+    coordinator: LocalThingsCoordinator = hass.data[DOMAIN][mock_entry.entry_id]
+    await _cancel_background_subpolls(coordinator)
+    coordinator._observe.mode = MODE_OBSERVE
+    coordinator._hot_hrefs = []
+    coordinator._warm_hrefs = ["/warm/vs/0"]
+    coordinator._observe.fallback_hrefs = {"/warm/vs/0"}
+
+    polled: list[list[str]] = []
+
+    def _capture(hrefs):
+        polled.append(list(hrefs))
+
+    with (
+        patch.object(coordinator, "_poll_hrefs_blocking", side_effect=_capture),
+        patch(
+            "custom_components.localthings.coordinator.asyncio.sleep",
+            new_callable=AsyncMock,
+        ),
+    ):
+        await coordinator._run_subpolls()
+
+    assert polled
+    for batch in polled:
+        assert batch == ["/warm/vs/0"]
+
+
 async def test_write_marks_href_pending_before_post(
     hass: HomeAssistant, mock_entry, mock_coordinator_observe_session
 ) -> None:
@@ -956,6 +1332,192 @@ async def test_send_command_survives_stale_confirm_poll(
     assert coordinator._cache.get("/test/vs/0") == {"value": 5}
 
 
+async def test_send_command_reconnects_and_retries_after_socket_closed(
+    hass: HomeAssistant,
+    mock_entry,
+    mock_coordinator_observe_session,
+) -> None:
+    """A command lost to a session Samsung's firmware closed between polls
+    must not just vanish (issue #294): `_do_put` failing once is now
+    followed by a reconnect and a single retry, mirroring the poll path's
+    own recovery in `_async_update_data`.
+
+    `mock_coordinator_observe_session` patches `_close_session` to a no-op,
+    which would leave `self._session` never actually going `None` -- and
+    with it, `_do_put`'s own `if self._session is None: self._connect_session()`
+    guard never exercised, so a broken reconnect could still pass. Overridden
+    here to actually drop the session, so the retry only succeeds if that
+    guard really rebuilds it."""
+    from custom_components.localthings.registry.discovery import BoundEntity
+    from custom_components.localthings.registry.entities import NumberDesc
+
+    fake = mock_coordinator_observe_session
+    await hass.config_entries.async_setup(mock_entry.entry_id)
+    await hass.async_block_till_done()
+    coordinator: LocalThingsCoordinator = hass.data[DOMAIN][mock_entry.entry_id]
+
+    def _write_fn(payload, rep, href=None):
+        return (["test", "vs", "0"], {"value": payload})
+
+    desc = NumberDesc(key="test", field="value", write_fn=_write_fn)
+    bound = BoundEntity(href="/test/vs/0", capability=coordinator.bound[0].capability, desc=desc)
+
+    calls = {"n": 0}
+
+    def _post(*args, **kwargs):
+        calls["n"] += 1
+        if calls["n"] == 1:
+            raise ConnectionError("socket closed")
+        return (0x44, b"")
+
+    def _drop_session():
+        coordinator._session = None
+
+    reconnects = {"n": 0}
+
+    def _reconnect():
+        reconnects["n"] += 1
+        coordinator._session = fake
+
+    with (
+        patch.object(fake, "subscribe"),
+        patch.object(coordinator, "_close_session", side_effect=_drop_session),
+        patch.object(coordinator, "_connect_session", side_effect=_reconnect),
+        patch(
+            "custom_components.localthings.coordinator.asyncio.sleep",
+            new=AsyncMock(),
+        ),
+    ):
+        fake.post = _post
+        await coordinator.async_send_command(bound, 5)
+
+    assert reconnects["n"] == 1
+
+    assert calls["n"] == 2
+    assert coordinator._cache.get("/test/vs/0") == {"value": 5}
+
+
+async def test_send_command_raises_after_reconnect_retry_also_fails(
+    hass: HomeAssistant,
+    mock_entry,
+    mock_coordinator_observe_session,
+) -> None:
+    """If the command still fails on the reconnected session, the user must
+    see it -- previously this was swallowed into a log line with no
+    feedback at all (issue #294).
+
+    Also covers a sibling bug the fix for that same issue introduced: the
+    session is closed the moment the first attempt fails, so any OBSERVE
+    subscriptions on it are already dead regardless of whether the retry
+    that follows succeeds -- a failed retry must still downgrade mode, or
+    it's left claiming "Push" on a session that no longer exists."""
+    from homeassistant.exceptions import HomeAssistantError
+
+    from custom_components.localthings.registry.discovery import BoundEntity
+    from custom_components.localthings.registry.entities import NumberDesc
+
+    fake = mock_coordinator_observe_session
+    await hass.config_entries.async_setup(mock_entry.entry_id)
+    await hass.async_block_till_done()
+    coordinator: LocalThingsCoordinator = hass.data[DOMAIN][mock_entry.entry_id]
+    hrefs = coordinator._hot_hrefs + coordinator._warm_hrefs
+
+    fake.notify_on_subscribe = {"notified": True}
+    entered = await hass.async_add_executor_job(
+        coordinator._observe.try_enter_observe_mode,
+        fake,
+        hrefs,
+        0.02,
+        0.8,
+    )
+    assert entered is True
+    assert coordinator.observe_mode == MODE_OBSERVE
+
+    def _write_fn(payload, rep, href=None):
+        return (["test", "vs", "0"], {"value": payload})
+
+    desc = NumberDesc(key="test", field="value", write_fn=_write_fn)
+    bound = BoundEntity(href="/test/vs/0", capability=coordinator.bound[0].capability, desc=desc)
+
+    def _post(*args, **kwargs):
+        raise ConnectionError("socket closed")
+
+    with (
+        patch(
+            "custom_components.localthings.coordinator.asyncio.sleep",
+            new=AsyncMock(),
+        ),
+        pytest.raises(HomeAssistantError),
+    ):
+        fake.post = _post
+        await coordinator.async_send_command(bound, 5)
+
+    assert coordinator.observe_mode == MODE_POLL
+
+
+async def test_send_command_reconnect_downgrades_observe_mode(
+    hass: HomeAssistant,
+    mock_entry,
+    mock_coordinator_observe_session,
+) -> None:
+    """A command's own successful reconnect hands back a session with zero
+    OBSERVE registrations too, same as the poll path's reconnect -- must
+    downgrade the same way and flag a resubscribe, or observe mode stays
+    claimed against a session the write just replaced underneath it
+    (issue #294)."""
+    from custom_components.localthings.registry.discovery import BoundEntity
+    from custom_components.localthings.registry.entities import NumberDesc
+
+    fake = mock_coordinator_observe_session
+    await hass.config_entries.async_setup(mock_entry.entry_id)
+    await hass.async_block_till_done()
+    coordinator: LocalThingsCoordinator = hass.data[DOMAIN][mock_entry.entry_id]
+    hrefs = coordinator._hot_hrefs + coordinator._warm_hrefs
+
+    fake.notify_on_subscribe = {"notified": True}
+    entered = await hass.async_add_executor_job(
+        coordinator._observe.try_enter_observe_mode,
+        fake,
+        hrefs,
+        0.02,
+        0.8,
+    )
+    assert entered is True
+    assert coordinator.observe_mode == MODE_OBSERVE
+
+    def _write_fn(payload, rep, href=None):
+        return (["test", "vs", "0"], {"value": payload})
+
+    desc = NumberDesc(key="test", field="value", write_fn=_write_fn)
+    bound = BoundEntity(href="/test/vs/0", capability=coordinator.bound[0].capability, desc=desc)
+
+    calls = {"n": 0}
+
+    def _post(*args, **kwargs):
+        calls["n"] += 1
+        if calls["n"] == 1:
+            raise ConnectionError("socket closed")
+        return (0x44, b"")
+
+    with (
+        patch.object(fake, "subscribe") as mock_subscribe,
+        patch(
+            "custom_components.localthings.coordinator.asyncio.sleep",
+            new=AsyncMock(),
+        ),
+    ):
+        fake.post = _post
+        await coordinator.async_send_command(bound, 5)
+
+        # _resubscribe_due is consumed by this same call's own trailing
+        # refresh (async_request_refresh is awaited, not fire-and-forget),
+        # so the visible effect is a resubscribe attempt, not a lingering
+        # flag value to assert on afterward.
+        assert mock_subscribe.called
+
+    assert coordinator.observe_mode == MODE_POLL
+
+
 async def test_second_write_to_same_href_lands_during_first_writes_settle_window(
     hass: HomeAssistant,
     mock_entry,
@@ -1379,10 +1941,11 @@ async def test_first_refresh_timeout_recovers_via_reconnect(
 async def test_first_refresh_persistent_timeout_fails_setup(
     hass: HomeAssistant, mock_entry
 ) -> None:
-    """When the reconnect times out too, the first refresh must fail so HA
-    retries on its backoff -- not load an entity-less entry. The session it
-    left open is closed on the way out (`_poll_once` keeps it up on a
-    `TimeoutError`, and the source port is fixed per device)."""
+    """With no snapshot to load from, a reconnect that times out too must
+    fail the first refresh so HA retries on its backoff -- not load an
+    entity-less entry. The session it left open is closed on the way out
+    (`_poll_once` keeps it up on a `TimeoutError`, and the source port is
+    fixed per device)."""
     with (
         patch("custom_components.localthings.coordinator.LocalThingsCoordinator._connect_session"),
         patch(

tests/localthings/test_device_removal.py

@@ -39,7 +39,7 @@ async def test_stale_device_can_be_removed(
     stale = _device(
         hass,
         mock_entry,
-        {(DOMAIN, f"{coordinator.device_serial}_1")},
+        {(DOMAIN, f"{coordinator.device_key}_1")},
     )
 
     assert await async_remove_config_entry_device(hass, mock_entry, stale) is True

tests/localthings/test_diagnostics.py

@@ -76,8 +76,11 @@ async def test_diagnostics_include_ocf_identity(
     # fields identify a device type, so nothing is dropped up front beyond
     # what redaction takes out.
     assert identity["resources"]["/oic/p"]["mnmn"] == "Samsung Electronics"
-    assert identity["resources"]["/oic/d"]["di"] == REDACTED
-    assert identity["resources"]["/oic/p"]["pi"] == REDACTED
+    # The OCF UUIDs are reported rather than redacted: they are what this
+    # entry is keyed on (issue #381), and blanking them is what made the
+    # first duplicate-serial report unanswerable.
+    assert identity["resources"]["/oic/d"]["di"] == "ab-cd-ef"
+    assert identity["resources"]["/oic/p"]["pi"] == "12-34-56"
     # The owner-settable device name is redacted; `rt` -- the reason this
     # block exists -- is not.
     assert identity["resources"]["/oic/d"]["n"] == REDACTED
@@ -125,9 +128,9 @@ async def test_diagnostics_include_oic_res_links(
 
     links = diag["identity"]["resources"]["/oic/res"]
     assert len(links) == 2
-    assert links[0]["di"] == REDACTED
+    assert links[0]["di"] == "aaaa-1111"
     assert links[0]["href"] == "/device/0"
-    assert links[1]["di"] == REDACTED
+    assert links[1]["di"] == "bbbb-2222"
     assert links[1]["href"] == "/device/1"
     assert links[1]["rt"] == ["x.com.samsung.devcol", "oic.wk.col"]
 

tests/localthings/test_identity_migration.py

@@ -0,0 +1,773 @@
+"""Moving an existing install onto the OCF device UUID (issue #381).
+
+This migration can't finish inside `async_migrate_entry` -- the UUID is
+only readable from the appliance, and an entry can load from its snapshot
+while that appliance is off (issue #295) -- so the coordinator adopts it
+on the first live poll, rewriting both registries and the entry's
+unique_id together.
+
+That makes it the riskiest migration here: it rewrites the identity of
+rows a user's automations, history and areas hang off. These tests are
+organised around what must not break rather than around the functions
+involved. Statistics are covered separately, against a real recorder, in
+tests/test_rekey_statistics_end_to_end.py.
+"""
+
+from __future__ import annotations
+
+from contextlib import contextmanager
+from unittest.mock import patch
+
+from homeassistant.core import HomeAssistant
+from homeassistant.helpers import device_registry as dr
+from homeassistant.helpers import entity_registry as er
+from pytest_homeassistant_custom_component.common import MockConfigEntry
+
+from custom_components.localthings.const import (
+    CONF_DEVICE_KEY,
+    CONF_HOST,
+    CONF_SERIAL,
+    DOMAIN,
+)
+from custom_components.localthings.registry.identity import DeviceIdentity
+
+from .conftest import LEGACY_ENTRY_DATA, MOCK_HOST, MOCK_SERIAL
+
+_COORD = "custom_components.localthings.coordinator.LocalThingsCoordinator"
+
+# The two purifiers from issue #381: one serialNum, two device UUIDs.
+SHARED_SERIAL = "BS7SP9AW400114A"
+UUID_A = "ccfd73b3-aeb4-792a-1100-68f06f5d603b"
+UUID_B = "3771f8bf-c184-3a2d-d885-e4c9818736d2"
+
+
+@contextmanager
+def _reachable(resources: dict, device_id: str | None):
+    """A device that answers a poll, reporting `device_id` as its /oic/d
+    `di` -- which `_connect_session` is what normally reads, so a test that
+    patches it out otherwise leaves `_identity` None (indistinguishable
+    from firmware that reports no UUID at all)."""
+
+    def _connect(self) -> None:
+        self._identity = (
+            None
+            if device_id is None
+            else DeviceIdentity(
+                manufacturer="Samsung Electronics",
+                model="AVT-WW-TP1-23-AXX500",
+                name="Samsung AirPurifier",
+                serial=None,
+                device_id=device_id,
+            )
+        )
+
+    with (
+        patch(f"{_COORD}._connect_session", _connect),
+        patch(f"{_COORD}._poll_once", return_value=resources),
+        patch(f"{_COORD}._close_session"),
+    ):
+        yield
+
+
+@contextmanager
+def _unreachable():
+    with (
+        patch(f"{_COORD}._connect_session"),
+        patch(f"{_COORD}._poll_once", side_effect=OSError("device offline")),
+        patch(f"{_COORD}._close_session"),
+    ):
+        yield
+
+
+def _entry(
+    hass: HomeAssistant,
+    *,
+    version: int,
+    key: str,
+    serial: str | None = None,
+    device_key: str | None = None,
+    host: str = MOCK_HOST,
+) -> MockConfigEntry:
+    """An entry as it sits on disk at `version`. Pre-v4 entries carry no
+    CONF_DEVICE_KEY at all -- that absence is what tells the coordinator it
+    is looking at an entry that has never adopted a UUID."""
+    data = {**LEGACY_ENTRY_DATA, CONF_HOST: host}
+    if version >= 2:
+        data[CONF_SERIAL] = serial if serial is not None else key
+    if device_key is not None:
+        data[CONF_DEVICE_KEY] = device_key
+    entry = MockConfigEntry(
+        domain=DOMAIN,
+        data=data,
+        unique_id=f"{DOMAIN}_{key}",
+        version=version,
+    )
+    entry.add_to_hass(hass)
+    return entry
+
+
+def _reporting_serial(resources: dict, serial: str) -> dict:
+    """`resources` with the serialNum the device reports swapped out, so a
+    test can pair a fixture with the identity its scenario implies."""
+    info = dict(resources["/information/vs/0"])
+    info["x.com.samsung.da.serialNum"] = serial
+    return {**resources, "/information/vs/0": info}
+
+
+def _device_identifiers(hass: HomeAssistant, device_id: str) -> set[tuple[str, str]]:
+    """This device row's identifiers, asserting the row still exists.
+
+    `dev_reg.async_get` returns `DeviceEntry | None`, so reading through it
+    directly would crash with an AttributeError on a row the re-key
+    wrongly removed instead of failing the assertion that says so.
+    """
+    row = dr.async_get(hass).async_get(device_id)
+    assert row is not None
+    return row.identifiers
+
+
+def _entity_unique_id(hass: HomeAssistant, entity_id: str) -> str:
+    """This entity row's unique_id, asserting the row still exists."""
+    row = er.async_get(hass).async_get(entity_id)
+    assert row is not None
+    return row.unique_id
+
+
+def _seed_registry(hass: HomeAssistant, entry: MockConfigEntry, key: str, **entity_kwargs):
+    """A device and one entity keyed on `key`, as a running install has."""
+    dev_reg = dr.async_get(hass)
+    ent_reg = er.async_get(hass)
+    device = dev_reg.async_get_or_create(
+        config_entry_id=entry.entry_id,
+        identifiers={(DOMAIN, key)},
+        name=f"Samsung Air Purifier ({key})",
+    )
+    entity = ent_reg.async_get_or_create(
+        "sensor",
+        DOMAIN,
+        f"{DOMAIN}_{key}_connection_mode",
+        config_entry=entry,
+        device_id=device.id,
+        **entity_kwargs,
+    )
+    return device, entity
+
+
+# ---------------------------------------------------------------------------
+# The upgrade itself
+# ---------------------------------------------------------------------------
+
+
+async def test_v3_entry_moves_onto_the_device_uuid_keeping_its_entity_ids(
+    hass: HomeAssistant, fridge_resources
+) -> None:
+    """The migration promise for an existing user, asserted end to end: all
+    three permanent places move together, and the entity_id doesn't."""
+    entry = _entry(hass, version=3, key=MOCK_SERIAL)
+    device, existing = _seed_registry(
+        hass, entry, MOCK_SERIAL, suggested_object_id="kitchen_purifier_connection"
+    )
+
+    with _reachable(fridge_resources, UUID_A):
+        await hass.config_entries.async_setup(entry.entry_id)
+        await hass.async_block_till_done()
+
+    assert entry.version == 4
+    assert entry.data[CONF_DEVICE_KEY] == UUID_A
+    # The serial is kept alongside the key, not replaced by it: it is what
+    # corroborates a later change of UUID.
+    assert entry.data[CONF_SERIAL] == MOCK_SERIAL
+    assert entry.unique_id == f"{DOMAIN}_{UUID_A}"
+
+    rekeyed_device = dr.async_get(hass).async_get(device.id)
+    assert rekeyed_device is not None
+    assert rekeyed_device.identifiers == {(DOMAIN, UUID_A)}
+    kept = er.async_get(hass).async_get(existing.entity_id)
+    assert kept is not None
+    assert kept.entity_id == "sensor.kitchen_purifier_connection"
+    assert kept.unique_id == f"{DOMAIN}_{UUID_A}_connection_mode"
+    # Nothing left behind on the old key.
+    assert dr.async_get(hass).async_get_device(identifiers={(DOMAIN, MOCK_SERIAL)}) is None
+
+
+async def test_the_oldest_install_walks_all_the_way_from_v1(
+    hass: HomeAssistant, fridge_resources
+) -> None:
+    """A v1 entry -- no stored identity at all, from before issue #236 --
+    walks v1 -> v2 -> v3 -> v4 and then adopts the UUID on its first poll.
+
+    The oldest installs take the longest path, and each step rewrites what
+    the next one reads, so the chain is worth pinning as one journey rather
+    than trusting the individual steps to compose.
+    """
+    entry = _entry(hass, version=1, key=MOCK_SERIAL)
+    device, existing = _seed_registry(
+        hass, entry, MOCK_SERIAL, suggested_object_id="old_install_connection"
+    )
+
+    with _reachable(fridge_resources, UUID_A):
+        await hass.config_entries.async_setup(entry.entry_id)
+        await hass.async_block_till_done()
+
+    assert entry.version == 4
+    assert entry.data[CONF_DEVICE_KEY] == UUID_A
+    assert entry.unique_id == f"{DOMAIN}_{UUID_A}"
+    kept = er.async_get(hass).async_get(existing.entity_id)
+    assert kept is not None
+    assert kept.entity_id == "sensor.old_install_connection"
+    assert kept.unique_id == f"{DOMAIN}_{UUID_A}_connection_mode"
+    assert _device_identifiers(hass, device.id) == {(DOMAIN, UUID_A)}
+
+
+async def test_a_host_keyed_entry_adopts_a_real_identity(
+    hass: HomeAssistant, fridge_resources
+) -> None:
+    """A placeholder-serial board (issues #83/#189) was keyed on its IP,
+    which is an address rather than an identity -- a new DHCP lease silently
+    makes it someone else's. Such an entry never made an identity claim to
+    defend, so a real UUID is adopted without needing the serial to
+    corroborate it; requiring corroboration would strand exactly these
+    boards, since their serial resolves to the host and can never match."""
+    entry = _entry(hass, version=3, key=MOCK_HOST)
+    device, _ = _seed_registry(hass, entry, MOCK_HOST)
+
+    with _reachable(fridge_resources, UUID_B):
+        await hass.config_entries.async_setup(entry.entry_id)
+        await hass.async_block_till_done()
+
+    assert entry.data[CONF_DEVICE_KEY] == UUID_B
+    assert _device_identifiers(hass, device.id) == {(DOMAIN, UUID_B)}
+
+
+async def test_the_two_units_from_the_issue_migrate_to_separate_identities(
+    hass: HomeAssistant, fridge_resources
+) -> None:
+    """Issue #381's actual install: two entries whose stored identity is the
+    same shared serial. Before this, they could not both exist. Migrating
+    them must give each its own key rather than collapsing them again --
+    including their entity unique_ids, which is where issue #83's Bug 4
+    silently dropped the second unit's entities even once its entry existed.
+    """
+    # Both units report the shared serial, as the real ones do -- so the
+    # entry's stored identity still matches what the device says, and only
+    # the UUID separates them.
+    resources = _reporting_serial(fridge_resources, SHARED_SERIAL)
+    first = _entry(hass, version=3, key=SHARED_SERIAL, host="192.168.0.3")
+    _, first_entity = _seed_registry(hass, first, SHARED_SERIAL, suggested_object_id="purifier_a")
+
+    with _reachable(resources, UUID_A):
+        await hass.config_entries.async_setup(first.entry_id)
+        await hass.async_block_till_done()
+
+    # Added only now: setting up the first entry loads the integration, which
+    # brings up every entry already registered -- so a second one created up
+    # front would come up inside the first one's patched identity and adopt
+    # its UUID, which is the collision this test exists to disprove.
+    second = _entry(hass, version=3, key=SHARED_SERIAL, host="192.168.0.14")
+    _, second_entity = _seed_registry(hass, second, SHARED_SERIAL, suggested_object_id="purifier_b")
+
+    with _reachable(resources, UUID_B):
+        await hass.config_entries.async_setup(second.entry_id)
+        await hass.async_block_till_done()
+
+    assert first.data[CONF_DEVICE_KEY] == UUID_A
+    assert second.data[CONF_DEVICE_KEY] == UUID_B
+    assert first.unique_id != second.unique_id
+
+    assert _entity_unique_id(hass, first_entity.entity_id) == (f"{DOMAIN}_{UUID_A}_connection_mode")
+    assert _entity_unique_id(hass, second_entity.entity_id) == (
+        f"{DOMAIN}_{UUID_B}_connection_mode"
+    )
+
+
+# ---------------------------------------------------------------------------
+# What the user must not lose
+# ---------------------------------------------------------------------------
+
+
+async def test_every_user_customization_on_the_row_survives(
+    hass: HomeAssistant, fridge_resources
+) -> None:
+    """Re-keying rewrites the registry row in place rather than replacing
+    it, which is the whole reason to do it this way -- so everything the
+    user attached to that row rides along. A rename, an area, an icon
+    override and a deliberate hide are each things they would have to redo
+    by hand if the row were recreated instead.
+    """
+    entry = _entry(hass, version=3, key=MOCK_SERIAL)
+    ent_reg = er.async_get(hass)
+    device, existing = _seed_registry(
+        hass, entry, MOCK_SERIAL, suggested_object_id="kitchen_purifier_connection"
+    )
+    dr.async_get(hass).async_update_device(device.id, area_id="kitchen")
+    ent_reg.async_update_entity(
+        existing.entity_id,
+        name="Purifier link",
+        icon="mdi:air-filter",
+        area_id="kitchen",
+        hidden_by=er.RegistryEntryHider.USER,
+    )
+
+    with _reachable(fridge_resources, UUID_A):
+        await hass.config_entries.async_setup(entry.entry_id)
+        await hass.async_block_till_done()
+
+    kept = ent_reg.async_get(existing.entity_id)
+    assert kept is not None
+    assert kept.unique_id == f"{DOMAIN}_{UUID_A}_connection_mode"
+    assert kept.name == "Purifier link"
+    assert kept.icon == "mdi:air-filter"
+    assert kept.area_id == "kitchen"
+    assert kept.hidden_by is er.RegistryEntryHider.USER
+    rekeyed_device = dr.async_get(hass).async_get(device.id)
+    assert rekeyed_device is not None
+    assert rekeyed_device.area_id == "kitchen"
+
+
+async def test_a_composite_appliance_keeps_its_subdevice_links(
+    hass: HomeAssistant, fridge_resources
+) -> None:
+    """A composite appliance (issue #177) registers one device per logical
+    subdevice, keyed f"{key}_{subdevice}" and linked via_device to the
+    master's bare key. Rewriting only the exact-match identifier would
+    strand every sibling under a via_device pointing at a device that no
+    longer exists, collapsing the user's device tree."""
+    entry = _entry(hass, version=3, key=MOCK_SERIAL)
+    dev_reg = dr.async_get(hass)
+    master, _ = _seed_registry(hass, entry, MOCK_SERIAL)
+    sub = dev_reg.async_get_or_create(
+        config_entry_id=entry.entry_id,
+        identifiers={(DOMAIN, f"{MOCK_SERIAL}_subdevice_1")},
+        via_device=(DOMAIN, MOCK_SERIAL),
+    )
+    assert sub.via_device_id == master.id
+
+    with _reachable(fridge_resources, UUID_A):
+        await hass.config_entries.async_setup(entry.entry_id)
+        await hass.async_block_till_done()
+
+    assert _device_identifiers(hass, master.id) == {(DOMAIN, UUID_A)}
+    rekeyed_sub = dev_reg.async_get(sub.id)
+    assert rekeyed_sub is not None
+    assert rekeyed_sub.identifiers == {(DOMAIN, f"{UUID_A}_subdevice_1")}
+    # Still the same parent row, so the device tree the user sees is intact.
+    assert rekeyed_sub.via_device_id == master.id
+
+
+async def test_a_re_key_never_touches_another_entrys_rows(hass: HomeAssistant) -> None:
+    """The rewrite is scoped to one config entry's own registry rows.
+
+    Issue #381's install is the case that makes this sharp: *both* entries
+    are keyed on the same shared serial, so both have registry rows under
+    the identical old key, and they migrate one at a time. An unscoped
+    rewrite -- matching on the key prefix alone -- would sweep up the other
+    appliance's device and entities and hand them to the first one to
+    migrate, which is the worst outcome this change could have.
+
+    The two entries hold *different* entities under that one shared prefix
+    (HA's registry won't let two rows share a unique_id, which is issue
+    #83's Bug 4 in the first place), so only the config-entry scoping can
+    tell them apart -- prefix matching alone cannot.
+
+    Calls rekey_entry directly so the scoping is what's under test, rather
+    than the coordinator's decision about whether to call it at all.
+    """
+    from custom_components.localthings.rekey import rekey_entry
+
+    migrating = _entry(hass, version=3, key=SHARED_SERIAL, host="192.168.0.3")
+    bystander = _entry(hass, version=3, key=SHARED_SERIAL, host="192.168.0.14")
+    ent_reg = er.async_get(hass)
+    moved = ent_reg.async_get_or_create(
+        "sensor", DOMAIN, f"{DOMAIN}_{SHARED_SERIAL}_connection_mode", config_entry=migrating
+    )
+    stays = ent_reg.async_get_or_create(
+        "sensor", DOMAIN, f"{DOMAIN}_{SHARED_SERIAL}_power", config_entry=bystander
+    )
+
+    rekey_entry(hass, migrating, SHARED_SERIAL, UUID_A)
+
+    assert _entity_unique_id(hass, moved.entity_id) == f"{DOMAIN}_{UUID_A}_connection_mode"
+    # The other appliance is still on the shared serial, waiting its turn.
+    assert _entity_unique_id(hass, stays.entity_id) == f"{DOMAIN}_{SHARED_SERIAL}_power"
+    assert bystander.unique_id == f"{DOMAIN}_{SHARED_SERIAL}"
+
+
+async def test_a_re_key_stops_at_the_key_boundary(hass: HomeAssistant) -> None:
+    """Matching is on the whole key or the key plus a separator, never a
+    bare prefix. Serial numbers of one model are routinely prefixes of each
+    other, so a naive startswith would drag a *different* appliance's rows
+    along -- and the identifiers it would rewrite them to are nonsense."""
+    from custom_components.localthings.rekey import rekey_entry
+
+    entry = _entry(hass, version=3, key="TEST-SERIAL")
+    dev_reg = dr.async_get(hass)
+    ent_reg = er.async_get(hass)
+    target = dev_reg.async_get_or_create(
+        config_entry_id=entry.entry_id, identifiers={(DOMAIN, "TEST-SERIAL")}
+    )
+    # Same config entry, so scoping can't save this one -- only the boundary.
+    neighbour = dev_reg.async_get_or_create(
+        config_entry_id=entry.entry_id, identifiers={(DOMAIN, "TEST-SERIAL-0000")}
+    )
+    neighbour_entity = ent_reg.async_get_or_create(
+        "sensor", DOMAIN, f"{DOMAIN}_TEST-SERIAL-0000_connection_mode", config_entry=entry
+    )
+
+    rekey_entry(hass, entry, "TEST-SERIAL", UUID_A)
+
+    assert _device_identifiers(hass, target.id) == {(DOMAIN, UUID_A)}
+    assert _device_identifiers(hass, neighbour.id) == {(DOMAIN, "TEST-SERIAL-0000")}
+    assert _entity_unique_id(hass, neighbour_entity.entity_id) == (
+        f"{DOMAIN}_TEST-SERIAL-0000_connection_mode"
+    )
+
+
+# ---------------------------------------------------------------------------
+# Stability: upgrading twice, or offline, must not churn
+# ---------------------------------------------------------------------------
+
+
+async def test_upgrading_while_the_appliance_is_off_changes_nothing(
+    hass: HomeAssistant, fridge_resources, hass_storage
+) -> None:
+    """The case a large share of users will actually hit: HA restarts onto
+    the new release while the appliance is unplugged or asleep.
+
+    The entry comes up from its snapshot (issue #295), which never reached
+    the device -- so it has no standing to claim an identity. It must load
+    under the key its registry rows already carry and write nothing, or the
+    real UUID would later look like a *changed* identity to defend against
+    rather than the one-time adoption it is.
+    """
+    entry = _entry(hass, version=3, key=MOCK_SERIAL)
+    _, existing = _seed_registry(hass, entry, MOCK_SERIAL)
+
+    # Bank a snapshot from a run on the old release, then take it down.
+    with _reachable(fridge_resources, None):
+        await hass.config_entries.async_setup(entry.entry_id)
+        await hass.async_block_till_done()
+        await hass.config_entries.async_unload(entry.entry_id)
+        await hass.async_block_till_done()
+    assert entry.data[CONF_DEVICE_KEY] == MOCK_SERIAL
+
+    # Now the appliance is off. Simulate the pre-v4 shape the upgrade finds.
+    hass.config_entries.async_update_entry(
+        entry, data={k: v for k, v in entry.data.items() if k != CONF_DEVICE_KEY}, version=3
+    )
+
+    with _unreachable():
+        await hass.config_entries.async_setup(entry.entry_id)
+        await hass.async_block_till_done()
+
+    coordinator = hass.data[DOMAIN][entry.entry_id]
+    assert coordinator.device_key == MOCK_SERIAL
+    # No key claimed, and the registry is exactly as it was.
+    assert CONF_DEVICE_KEY not in entry.data
+    assert entry.unique_id == f"{DOMAIN}_{MOCK_SERIAL}"
+    assert _entity_unique_id(hass, existing.entity_id) == (
+        f"{DOMAIN}_{MOCK_SERIAL}_connection_mode"
+    )
+
+
+async def test_an_offline_load_never_rewrites_the_registry(
+    hass: HomeAssistant, fridge_resources, hass_storage
+) -> None:
+    """A snapshot replay must not re-key on the strength of what the
+    snapshot says, because that is last run's answer rather than the
+    device's.
+
+    Modelled on a placeholder-serial board (issues #83/#189), which is
+    where the two can genuinely disagree: the entry is keyed on its address
+    because the board reports no usable serial, while the snapshot banked
+    whatever serial the polled resources carried. A replay that trusted the
+    snapshot would rewrite every registry row onto that serial -- without
+    the appliance having been reachable at any point -- and would then
+    freeze the answer into CONF_DEVICE_KEY, so the real UUID could never be
+    adopted afterwards.
+    """
+    entry = _entry(hass, version=3, key=MOCK_HOST)
+
+    with _reachable(fridge_resources, None):
+        await hass.config_entries.async_setup(entry.entry_id)
+        await hass.async_block_till_done()
+        await hass.config_entries.async_unload(entry.entry_id)
+        await hass.async_block_till_done()
+
+    # Back to the pre-v4 shape the upgrade finds, still keyed on the address.
+    hass.config_entries.async_update_entry(
+        entry,
+        data={
+            **{k: v for k, v in entry.data.items() if k != CONF_DEVICE_KEY},
+            CONF_SERIAL: MOCK_HOST,
+        },
+        unique_id=f"{DOMAIN}_{MOCK_HOST}",
+        version=3,
+    )
+    device, existing = _seed_registry(hass, entry, MOCK_HOST)
+
+    with _unreachable():
+        await hass.config_entries.async_setup(entry.entry_id)
+        await hass.async_block_till_done()
+
+    coordinator = hass.data[DOMAIN][entry.entry_id]
+    assert coordinator.device_key == MOCK_HOST
+    assert CONF_DEVICE_KEY not in entry.data
+    assert entry.unique_id == f"{DOMAIN}_{MOCK_HOST}"
+    assert _device_identifiers(hass, device.id) == {(DOMAIN, MOCK_HOST)}
+    assert _entity_unique_id(hass, existing.entity_id) == (f"{DOMAIN}_{MOCK_HOST}_connection_mode")
+
+    # And the deferred adoption still works once the appliance answers --
+    # the offline load left nothing frozen behind it.
+    with _reachable(fridge_resources, UUID_A):
+        coordinator._connect_session()
+        coordinator._run_discovery(fridge_resources)
+
+    assert coordinator.device_key == UUID_A
+    assert entry.data[CONF_DEVICE_KEY] == UUID_A
+    assert _entity_unique_id(hass, existing.entity_id) == (f"{DOMAIN}_{UUID_A}_connection_mode")
+
+
+async def test_the_appliance_coming_back_completes_the_upgrade(
+    hass: HomeAssistant, fridge_resources
+) -> None:
+    """The other half of the offline case: the deferred adoption is not
+    abandoned, it just waits. Once the device answers, the same re-key runs
+    and the entry finishes its upgrade."""
+    entry = _entry(hass, version=3, key=MOCK_SERIAL)
+    _, existing = _seed_registry(hass, entry, MOCK_SERIAL)
+
+    with _reachable(fridge_resources, None):
+        await hass.config_entries.async_setup(entry.entry_id)
+        await hass.async_block_till_done()
+    assert entry.data[CONF_DEVICE_KEY] == MOCK_SERIAL
+
+    # The device is reachable again, now reporting its UUID.
+    coordinator = hass.data[DOMAIN][entry.entry_id]
+    with _reachable(fridge_resources, UUID_A):
+        coordinator._connect_session()
+        coordinator._run_discovery(fridge_resources)
+
+    assert coordinator.device_key == UUID_A
+    assert entry.data[CONF_DEVICE_KEY] == UUID_A
+    assert entry.unique_id == f"{DOMAIN}_{UUID_A}"
+    assert _entity_unique_id(hass, existing.entity_id) == (f"{DOMAIN}_{UUID_A}_connection_mode")
+
+
+async def test_restarting_after_the_upgrade_is_a_no_op(
+    hass: HomeAssistant, fridge_resources
+) -> None:
+    """Every restart re-runs discovery, so the adoption path runs again on
+    an entry that has already moved. It must recognise its own work and do
+    nothing -- a re-key that fired every boot would churn the registry
+    forever."""
+    entry = _entry(hass, version=3, key=MOCK_SERIAL)
+    _, existing = _seed_registry(hass, entry, MOCK_SERIAL)
+
+    with _reachable(fridge_resources, UUID_A):
+        await hass.config_entries.async_setup(entry.entry_id)
+        await hass.async_block_till_done()
+        after_first = dict(entry.data)
+        await hass.config_entries.async_unload(entry.entry_id)
+        await hass.async_block_till_done()
+
+        await hass.config_entries.async_setup(entry.entry_id)
+        await hass.async_block_till_done()
+
+    assert dict(entry.data) == after_first
+    assert entry.unique_id == f"{DOMAIN}_{UUID_A}"
+    kept = er.async_get(hass).async_get(existing.entity_id)
+    assert kept is not None
+    assert kept.unique_id == f"{DOMAIN}_{UUID_A}_connection_mode"
+    # Exactly one device, not a duplicate alongside it.
+    assert len(dr.async_entries_for_config_entry(dr.async_get(hass), entry.entry_id)) == 1
+
+
+async def test_an_already_migrated_entry_is_left_alone(
+    hass: HomeAssistant, fridge_resources
+) -> None:
+    """A v4 entry created by the current config flow has nothing to migrate
+    and nothing to re-key -- it was minted on its UUID."""
+    entry = _entry(hass, version=4, key=UUID_A, serial=MOCK_SERIAL, device_key=UUID_A)
+    device, existing = _seed_registry(hass, entry, UUID_A)
+
+    with _reachable(fridge_resources, UUID_A):
+        await hass.config_entries.async_setup(entry.entry_id)
+        await hass.async_block_till_done()
+
+    assert entry.version == 4
+    assert entry.data[CONF_DEVICE_KEY] == UUID_A
+    assert _device_identifiers(hass, device.id) == {(DOMAIN, UUID_A)}
+    assert _entity_unique_id(hass, existing.entity_id) == (f"{DOMAIN}_{UUID_A}_connection_mode")
+
+
+# ---------------------------------------------------------------------------
+# Guarding the identity once it has moved
+# ---------------------------------------------------------------------------
+
+
+async def test_a_poll_that_reads_no_uuid_does_not_demote_a_keyed_entry(
+    hass: HomeAssistant, fridge_resources
+) -> None:
+    """The device saying nothing is not the device saying something
+    different. A reconnect that can't read /oic/d (a timeout, a firmware
+    hiccup) must leave the key alone -- demoting back onto the serial would
+    re-key every entity the user has for the duration of an outage, and
+    re-key them all back afterwards."""
+    entry = _entry(hass, version=4, key=UUID_A, serial=MOCK_SERIAL, device_key=UUID_A)
+
+    with _reachable(fridge_resources, None):
+        await hass.config_entries.async_setup(entry.entry_id)
+        await hass.async_block_till_done()
+
+    coordinator = hass.data[DOMAIN][entry.entry_id]
+    assert coordinator.device_key == UUID_A
+    assert entry.data[CONF_DEVICE_KEY] == UUID_A
+
+
+async def test_a_rotated_uuid_on_the_same_serial_is_followed(
+    hass: HomeAssistant, fridge_resources
+) -> None:
+    """OCF permits a hard factory reset to regenerate `di`. The serialNum is
+    what tells that apart from a different appliance moving onto the
+    address, and following it keeps the user's history rather than stranding
+    it on a UUID the device will never report again."""
+    entry = _entry(hass, version=4, key=UUID_A, serial=MOCK_SERIAL, device_key=UUID_A)
+    device, existing = _seed_registry(hass, entry, UUID_A)
+
+    # fridge_resources reports MOCK_SERIAL, matching what the entry stored.
+    with _reachable(fridge_resources, UUID_B):
+        await hass.config_entries.async_setup(entry.entry_id)
+        await hass.async_block_till_done()
+
+    assert entry.data[CONF_DEVICE_KEY] == UUID_B
+    assert _device_identifiers(hass, device.id) == {(DOMAIN, UUID_B)}
+    assert _entity_unique_id(hass, existing.entity_id) == (f"{DOMAIN}_{UUID_B}_connection_mode")
+
+
+async def test_a_different_appliance_on_the_same_address_keeps_the_registered_identity(
+    hass: HomeAssistant, fridge_resources
+) -> None:
+    """Neither the UUID nor the serial matches what this entry was
+    registered with, so this is a different appliance answering at this
+    address -- not a reset of the registered one. Re-keying here would hand
+    one appliance's entities, history and automations to another; re-adding
+    is the user's call."""
+    entry = _entry(hass, version=4, key=UUID_A, serial="SOME-OTHER-APPLIANCE", device_key=UUID_A)
+    device, _ = _seed_registry(hass, entry, UUID_A)
+
+    with _reachable(fridge_resources, UUID_B):
+        await hass.config_entries.async_setup(entry.entry_id)
+        await hass.async_block_till_done()
+
+        assert entry.data[CONF_DEVICE_KEY] == UUID_A
+        assert _device_identifiers(hass, device.id) == {(DOMAIN, UUID_A)}
+        # The rejected appliance's serial is not written either. The serial
+        # is what corroborates a later change of key, so adopting it here
+        # would hand the intruder exactly the corroboration it needs to win
+        # the *next* poll -- defending the identity once and then
+        # surrendering it on the following cycle.
+        assert entry.data[CONF_SERIAL] == "SOME-OTHER-APPLIANCE"
+
+        coordinator = hass.data[DOMAIN][entry.entry_id]
+        coordinator._run_discovery(fridge_resources)
+
+        assert coordinator.device_key == UUID_A
+        assert entry.data[CONF_DEVICE_KEY] == UUID_A
+        assert entry.data[CONF_SERIAL] == "SOME-OTHER-APPLIANCE"
+
+
+async def test_a_pre_v4_entry_defends_itself_against_a_different_appliance(
+    hass: HomeAssistant, fridge_resources
+) -> None:
+    """The "same IP, different appliance" guard applies to an entry that has
+    not migrated yet, exactly as it does to one that has.
+
+    A pre-v4 entry is the population this change exists to move, but it is
+    also the population that has been running longest -- so it is the last
+    one that should hand its entity_ids, history and automations to an
+    appliance that merely happens to have taken over its address. Adoption
+    is the migration's job only when the identity is corroborated.
+    """
+    entry = _entry(hass, version=3, key=MOCK_SERIAL)
+    device, existing = _seed_registry(hass, entry, MOCK_SERIAL)
+
+    # Neither the serial nor (therefore) the UUID belongs to the registered
+    # appliance.
+    resources = _reporting_serial(fridge_resources, "SOME-OTHER-APPLIANCE")
+    with _reachable(resources, UUID_B):
+        await hass.config_entries.async_setup(entry.entry_id)
+        await hass.async_block_till_done()
+
+    coordinator = hass.data[DOMAIN][entry.entry_id]
+    assert coordinator.device_key == MOCK_SERIAL
+    assert entry.data[CONF_DEVICE_KEY] == MOCK_SERIAL
+    assert entry.data[CONF_SERIAL] == MOCK_SERIAL
+    assert entry.unique_id == f"{DOMAIN}_{MOCK_SERIAL}"
+    assert _device_identifiers(hass, device.id) == {(DOMAIN, MOCK_SERIAL)}
+    assert _entity_unique_id(hass, existing.entity_id) == (
+        f"{DOMAIN}_{MOCK_SERIAL}_connection_mode"
+    )
+
+
+# ---------------------------------------------------------------------------
+# rekey_entry's own contract
+# ---------------------------------------------------------------------------
+
+
+async def test_rekey_is_idempotent(hass: HomeAssistant) -> None:
+    """Safe to attempt on every poll rather than having to track whether it
+    has already run -- a second call finds nothing under the old key.
+
+    Calls rekey_entry directly: what it leaves behind is the contract, and
+    going through a setup would let the platforms re-adding their entities
+    hide a row that had in fact been orphaned.
+    """
+    from custom_components.localthings.rekey import rekey_entry
+
+    entry = _entry(hass, version=3, key=MOCK_SERIAL)
+    _, existing = _seed_registry(hass, entry, MOCK_SERIAL)
+
+    rekey_entry(hass, entry, MOCK_SERIAL, UUID_A)
+    rekey_entry(hass, entry, MOCK_SERIAL, UUID_A)
+
+    kept = er.async_get(hass).async_get(existing.entity_id)
+    assert kept is not None
+    assert kept.unique_id == f"{DOMAIN}_{UUID_A}_connection_mode"
+    assert entry.unique_id == f"{DOMAIN}_{UUID_A}"
+
+
+async def test_rekey_removes_a_stale_row_rather_than_colliding(hass: HomeAssistant) -> None:
+    """Where the destination key is already taken, the old-key row is the
+    dead one -- unavailable since whichever restart created the split -- so
+    it goes rather than being rewritten onto a key that exists. Same rule
+    the #236 repair has always applied, now on the identity move."""
+    from custom_components.localthings.rekey import rekey_entry
+
+    entry = _entry(hass, version=3, key=MOCK_SERIAL)
+    ent_reg = er.async_get(hass)
+    live = ent_reg.async_get_or_create(
+        "sensor", DOMAIN, f"{DOMAIN}_{UUID_A}_connection_mode", config_entry=entry
+    )
+    stale = ent_reg.async_get_or_create(
+        "sensor", DOMAIN, f"{DOMAIN}_{MOCK_SERIAL}_connection_mode", config_entry=entry
+    )
+    assert stale.entity_id != live.entity_id
+
+    rekey_entry(hass, entry, MOCK_SERIAL, UUID_A)
+
+    assert ent_reg.async_get(stale.entity_id) is None
+    assert ent_reg.async_get(live.entity_id) is not None
+
+
+async def test_rekey_to_the_same_key_does_nothing(hass: HomeAssistant) -> None:
+    """The no-op guard that lets callers pass whatever they resolved without
+    checking first."""
+    from custom_components.localthings.rekey import rekey_entry
+
+    entry = _entry(hass, version=4, key=UUID_A, device_key=UUID_A)
+    _, existing = _seed_registry(hass, entry, UUID_A)
+
+    rekey_entry(hass, entry, UUID_A, UUID_A)
+
+    assert _entity_unique_id(hass, existing.entity_id) == (f"{DOMAIN}_{UUID_A}_connection_mode")
+    assert entry.unique_id == f"{DOMAIN}_{UUID_A}"

tests/localthings/test_migration.py

@@ -1,4 +1,9 @@
-"""Config-entry migration and the placeholder-identity repair (issue #236)."""
+"""Config-entry migration and the placeholder-identity repair (issue #236).
+
+The move onto the OCF device UUID (issue #381) has its own suite in
+test_identity_migration.py -- it is the one migration step that can't
+finish inside async_migrate_entry, so it needs a device to talk to.
+"""
 
 from __future__ import annotations
 
@@ -38,35 +43,38 @@ async def test_migration_recovers_serial_from_unique_id(
     await hass.config_entries.async_setup(entry.entry_id)
     await hass.async_block_till_done()
 
-    assert entry.version == 2
+    # Straight through to the current version: v2 -> v3 is a statistics
+    # relabel that no-ops for a family without particulate sensors, and
+    # v3 -> v4 only records the legacy key for the coordinator to re-key
+    # from once a poll produces an OCF device id.
+    assert entry.version == 4
     assert entry.data[CONF_SERIAL] == MOCK_SERIAL
 
 
-async def test_migration_collapses_the_host_port_unique_id(
-    hass: HomeAssistant, mock_coordinator_session
-) -> None:
+async def test_migration_collapses_the_host_port_unique_id(hass: HomeAssistant) -> None:
     """A board with no usable serial (issues #83/#189) used to be keyed two
     different ways at once: `host:port` on the config entry, `host` in the
     device and entity registries. Migration collapses the entry onto the
     registry's form, so the two finally name the same thing."""
+    from custom_components.localthings import async_migrate_entry
+
     entry = _legacy_entry(hass, f"{DOMAIN}_{MOCK_HOST}:{MOCK_PORT}")
 
-    await hass.config_entries.async_setup(entry.entry_id)
-    await hass.async_block_till_done()
+    assert await async_migrate_entry(hass, entry) is True
 
     assert entry.data[CONF_SERIAL] == MOCK_HOST
     assert entry.unique_id == f"{DOMAIN}_{MOCK_HOST}"
 
 
-async def test_migration_resolves_a_placeholder_serial_unique_id(
-    hass: HomeAssistant, mock_coordinator_session
-) -> None:
+async def test_migration_resolves_a_placeholder_serial_unique_id(hass: HomeAssistant) -> None:
     """An entry created before the placeholder rules landed was keyed on the
     placeholder itself (issues #83/#189), while the coordinator has been
     resolving those boards to the host ever since. The unique_id records what
     the flow believed then, not what the registry holds -- taking it at face
     value would re-key working devices back onto a string every unit of the
     family reports, which is the collision those issues are about."""
+    from custom_components.localthings import async_migrate_entry
+
     entry = _legacy_entry(hass, f"{DOMAIN}_Nothing(SVC)")
     dev_reg = dr.async_get(hass)
     device = dev_reg.async_get_or_create(
@@ -74,8 +82,7 @@ async def test_migration_resolves_a_placeholder_serial_unique_id(
         identifiers={(DOMAIN, MOCK_HOST)},
     )
 
-    await hass.config_entries.async_setup(entry.entry_id)
-    await hass.async_block_till_done()
+    assert await async_migrate_entry(hass, entry) is True
 
     assert entry.data[CONF_SERIAL] == MOCK_HOST
     assert entry.unique_id == f"{DOMAIN}_{MOCK_HOST}"
@@ -84,14 +91,13 @@ async def test_migration_resolves_a_placeholder_serial_unique_id(
     assert unchanged.identifiers == {(DOMAIN, MOCK_HOST)}
 
 
-async def test_migration_resolves_an_all_hex_placeholder_unique_id(
-    hass: HomeAssistant, mock_coordinator_session
-) -> None:
+async def test_migration_resolves_an_all_hex_placeholder_unique_id(hass: HomeAssistant) -> None:
     """The issue #189 flash-unset sentinel, same reasoning."""
+    from custom_components.localthings import async_migrate_entry
+
     entry = _legacy_entry(hass, f"{DOMAIN}_FFFFFFFFFFFFFFF")
 
-    await hass.config_entries.async_setup(entry.entry_id)
-    await hass.async_block_till_done()
+    assert await async_migrate_entry(hass, entry) is True
 
     assert entry.data[CONF_SERIAL] == MOCK_HOST
 
@@ -229,13 +235,13 @@ async def test_migration_removes_an_orphan_that_is_already_duplicated(
     assert dev_reg.async_get(real_device.id) is not None
 
 
-async def test_migration_leaves_a_host_identity_device_alone(
-    hass: HomeAssistant, mock_coordinator_session
-) -> None:
+async def test_migration_leaves_a_host_identity_device_alone(hass: HomeAssistant) -> None:
     """A board whose serial resolves *to* the host was never keyed on a
     placeholder -- its host-keyed device is the real one, and re-keying or
     removing it would orphan a working device to fix a problem it doesn't
     have."""
+    from custom_components.localthings import async_migrate_entry
+
     entry = _legacy_entry(hass, f"{DOMAIN}_{MOCK_HOST}")
     dev_reg = dr.async_get(hass)
     device = dev_reg.async_get_or_create(
@@ -243,8 +249,7 @@ async def test_migration_leaves_a_host_identity_device_alone(
         identifiers={(DOMAIN, MOCK_HOST)},
     )
 
-    await hass.config_entries.async_setup(entry.entry_id)
-    await hass.async_block_till_done()
+    assert await async_migrate_entry(hass, entry) is True
 
     assert entry.data[CONF_SERIAL] == MOCK_HOST
     unchanged = dev_reg.async_get(device.id)
@@ -257,7 +262,7 @@ async def test_migration_rejects_a_future_entry_version(hass: HomeAssistant) ->
     written by a newer release."""
     from custom_components.localthings import async_migrate_entry
 
-    entry = MockConfigEntry(domain=DOMAIN, data=LEGACY_ENTRY_DATA, version=3)
+    entry = MockConfigEntry(domain=DOMAIN, data=LEGACY_ENTRY_DATA, version=5)
     entry.add_to_hass(hass)
 
     assert await async_migrate_entry(hass, entry) is False