Merge pull request #15 from mbillow/claude/device-port-detection-vp0q8d

feat: auto-detect DTLS port across the full 49152-49160 range

README.md

@@ -2,31 +2,27 @@
 
 **A native Home Assistant custom integration for local control of newer-generation Samsung connected appliances.** No cloud round-trip. Add a device through HA's normal *Settings > Devices & Services* flow and it talks CoAP-over-DTLS straight to the appliance on your LAN.
 
-> ### Where things live
->
-> This project split into two repos partway through development.
->
-> - **[`smartthings-local`](https://github.com/QuiteYellow/SmartThings-Local)** (PyPI package): the reusable protocol layer. DTLS session handling, CoAP wire encoding, Block2 reads, bounded retry/retransmit, inter-request rate limiting, cert-chain validation. No HA dependency; usable from any Python project.
-> - **This repo**: the Home Assistant integration built on top of it. Config flow, a per-device-type capability registry, the polling coordinator, and all the HA entity classes.
->
-> `custom_components/localthings/manifest.json` pulls in `smartthings-local` from PyPI like any other HA integration dependency.
+This integration uses the [`smartthings-local`](https://github.com/QuiteYellow/SmartThings-Local) library to handle the low-level DTLS/CoAP communication with devices.
 
 ### What you get
 
-Adding a device just needs a host IP and your CA credentials in the UI. The integration reads the appliance's `oneUiVersion` and picks the matching capability registry (dryer, oven, dishwasher, refrigerator) on its own, so there's no per-model descriptor to write for a new unit of a type that's already supported.
+Adding a device just needs a host IP and your CA credentials in the UI. The integration reads the appliance's identity and picks the matching capability registry on its own, so there's no per-model descriptor to write for a new unit of a type that's already supported.
 
-Credential setup is one-time. The first device you add asks for the AC14K_M CA cert and key (see Part 2); every device after that reuses the same stored CA and only asks for the host IP, minting its own per-device leaf cert automatically.
+Credential setup is one-time. The first device you add asks for a CA certificate and key (see Part 2); every device after that reuses the same stored CA and only asks for the host IP, minting its own per-device leaf cert automatically.
 
 Your state stays on your LAN: HA talks to the appliance over a direct DTLS session, and Samsung's cloud sees nothing from this integration. (The appliance itself still maintains its own connection to Samsung; that's firmware behavior on the device side, not something this integration controls.)
 
 ### Supported appliance types
 
-| Type | Registry | Notable capabilities |
-|---|---|---|
-| Dryer | `by_type/dryer.py` | Power, kids lock, remote control, alarms, energy meter, operational state, door LED, sound mode, dryer settings/course, job-beginning status, diagnosis, firmware-update sensor |
-| Oven | `by_type/oven.py` | Power, kids lock, remote control, alarms, cavity state, setpoint, mode, operational state, door, connectivity, firmware-update sensor |
-| Dishwasher | `by_type/dishwasher.py` | Power, kids lock, remote control, alarms, energy + water meters, water filter, operational state, cycle options/settings, door LED, sound mode/volume, firmware-update sensor |
-| Refrigerator | `by_type/refrigerator.py` | Power, kids lock, remote control, alarms, energy meter, water filter, status lock, door alert, icemaker (nighttime + generic per-compartment), flex zone, refrigeration mode, autofill, welcome/cabinet lighting, Sabbath mode, beverage zone, plus pattern-matched per-compartment temperature/setpoint/icemaker/door capabilities for multi-cavity fridges, firmware-update sensor |
+| Type | Registry |
+|---|---|
+| Dryer | `by_type/dryer.py` |
+| Oven | `by_type/oven.py` |
+| Dishwasher | `by_type/dishwasher.py` |
+| Refrigerator | `by_type/refrigerator.py` |
+| Washer | `by_type/washer.py` |
+
+Each registry composes shared and family-specific `Capability` objects from `registry/capabilities/`; those modules document the individual resources/entities in more depth than a README table can stay current with.
 
 Other Tizen RT / DAWIT-family appliances almost certainly speak the same protocol underneath, since the auth path and CoAP primitives are shared across the fleet. Adding a new type means writing a new `by_type/<name>.py` registry file; it doesn't require reverse-engineering the protocol again. See **Adding a new appliance type** below.
 
@@ -39,23 +35,17 @@ Other Tizen RT / DAWIT-family appliances almost certainly speak the same protoco
 nmap -Pn -sU -p 49152-49160 "$APPLIANCE_IP"
 ```
 
-- `49154/udp` or `49155/udp` open|filtered with a DTLS handshake responding: newer firmware (Tizen RT 3.x, DAWIT 3.0+). This is what the integration talks to. The config flow probes both ports automatically, so you don't need to know which one your device uses.
+- Any UDP port in `49152-49160` open|filtered with a DTLS handshake responding: newer firmware (Tizen RT 3.x, DAWIT 3.0+). This is what the integration talks to. Most devices answer on `49154`/`49155`, but some builds bind lower (e.g. `49153`). The config flow sweeps the whole range and auto-detects the live port, so you don't need to know which one your device uses.
 - Only `8888/tcp` open (token-based HTTPS): older firmware (roughly 2018-2022). **Not supported here.**
 
 ---
 
 ## Part 2: One-time setup, get the AC14K_M CA credentials
 
-The config flow (Part 3) needs a **CA certificate and CA private key** to mint each device's leaf cert itself. Specifically, it needs the `AC14K_M` intermediate CA: a cert chain that's been public for years and still ships in current Samsung firmware trust stores. It's required because every Samsung Tizen/RT-OCF appliance's factory ACL grants full CRUDN access (`perm=31` on `href=*`) to whatever identity is chained to that CA, so a cert signed by it is the one thing that lets HA talk to your appliance without Samsung's cloud in the loop. HA doesn't need the *device's* original cert or key, only something `AC14K_M` has signed, and it mints that itself once you give it the CA.
+The config flow (Part 3) needs a **CA certificate and CA private key** to mint each device's leaf cert itself. Specifically, it needs the `AC14K_M` intermediate CA — a cert chain that's been public for years and still ships in current Samsung firmware trust stores. Every Samsung Tizen/RT-OCF appliance trusts identities chained to that CA with full access by default, so a cert signed by it is what lets HA talk to your appliance without Samsung's cloud in the loop. HA doesn't need the *device's* original cert or key, only something `AC14K_M` has signed, and it mints that itself once you give it the CA.
 
 This repo doesn't include the needed CA bundle. For an example of how to obtain it, including fetching the AC14K_M cert and key and verifying they pair, see the `smartthings-local` protocol project's [`setup_cert.py`](https://github.com/QuiteYellow/SmartThings-Local/blob/main/setup_cert.py). However you obtain the CA cert and key, paste their PEM contents into the HA config flow's "CA Certificate (PEM)" and "CA Private Key (PEM)" fields in Part 3. You only need to do this once, since every appliance you add afterward reuses the same stored CA.
 
-### Why this works
-
-- Every Samsung Tizen/RT-OCF appliance has a factory-baked ACE in `/oic/sec/acl` granting the AC14K_M-chained identity `perm=31` on `href=*`.
-- TizenRT iotivity derives the peer ID via `memmem(subject_dn, "uuid:")`, which is RDN-agnostic, so a cert with the UUID in any RDN authenticates the same way.
-- You don't need the original keyholder's private key. The config flow mints its own key and has `AC14K_M` sign the leaf: different key, same identity, same access.
-
 ---
 
 ## Part 3: Add the integration in Home Assistant
@@ -64,7 +54,7 @@ This repo doesn't include the needed CA bundle. For an example of how to obtain
 2. Restart HA.
 3. **Settings > Devices & Services > Add Integration > LocalThings.**
 4. First device: paste the appliance's IP, plus the contents of the CA private and public key from Part 2.
-5. The flow fetches the current UUID from Samsung's cloud gateway, mints a leaf cert signed by your CA, probes ports `49154`/`49155`, and confirms the device answers `/device/0`. On success it creates the config entry and detects the device type automatically.
+5. The flow fetches the current UUID from Samsung's cloud gateway, mints a leaf cert signed by your CA, sweeps the `49152-49160` range to find the live DTLS port, and confirms the device answers `/device/0`. On success it creates the config entry and detects the device type automatically.
 6. Every subsequent device only asks for the host IP; the stored CA credentials are reused to mint that device's leaf cert.
 
 Entities appear under one HA device per appliance, named `Samsung Appliance (<ip>)` initially. Rename freely: the config entry is keyed on the device's serial, not the name.
@@ -80,7 +70,7 @@ docker compose up -d --build
 docker compose logs -f
 ```
 
-The `Dockerfile` builds on the official `home-assistant/home-assistant:stable` image and pre-installs `smartthings-local`, so the dependency is present at container start instead of depending on HA's own runtime pip-install step (which needs outbound network access at exactly the moment the integration loads, and repeats on every container recreate). Re-run with `--build` whenever the pinned `smartthings-local` version changes.
+The `Dockerfile` builds on the official `home-assistant/home-assistant:stable` image and pre-installs `smartthings-local`, so the dependency is present at container start instead of depending on HA's own runtime pip-install step. Re-run with `--build` whenever the pinned `smartthings-local` version changes.
 
 `docker-compose.yml` sets `network_mode: host`, which is required since DTLS is UDP and won't traverse Docker's bridge NAT to reach LAN appliances, and bind-mounts `custom_components/localthings/` read-only into `ha_config/custom_components/`. Bump `custom_components.localthings` to `debug` in `ha_config/configuration.yaml` for verbose protocol logging.
 
@@ -93,7 +83,7 @@ python3 -m venv .venv
 .venv/bin/pytest tests/ -q
 ```
 
-`requirements-dev.txt` pins `smartthings-local` the same way `manifest.json` does, so tests exercise the real published protocol layer rather than a vendored copy.
+A large suite covering registry composition, discovery, entity descriptors, and golden-file regression against captured device dumps. `requirements-dev.txt` pins `smartthings-local` the same way `manifest.json` does, so tests exercise the real published protocol layer rather than a vendored copy.
 
 ---
 
@@ -101,29 +91,32 @@ python3 -m venv .venv
 
 ```
 custom_components/localthings/
-  manifest.json                  Requirements (incl. the smartthings-local PyPI dep), version, domain
-  __init__.py                    async_setup_entry / async_unload_entry
-  config_flow.py                 UUID fetch, leaf cert minting, port probing, config entry creation
-  coordinator.py                 DataUpdateCoordinator: polling, stale-state fallback, write dispatch
-  const.py                       Domain, config keys, probe ports
-  entity.py                      Base entity wiring capability registry -> HA entity
+  manifest.json         Requirements (incl. the smartthings-local PyPI dep), version, domain
+  __init__.py            async_setup_entry / async_unload_entry
+  config_flow.py          UUID fetch, leaf cert minting, port probing, config entry creation
+  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)
+  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
-                                  One module per HA platform
+                            One module per HA platform
   strings.json / translations/   Config-flow copy + entity state translations
   registry/
-    batch.py                     /device/0 batch response parsing
-    capability.py                Capability dataclass (href, entities, transforms)
-    entities.py                  Per-platform entity descriptor dataclasses
-    discovery.py                  Binds a device's live resources to registered capabilities
-    adapter.py                    Flattens bound entities into HA-ready state
-    identity.py                   Reads device identity (serial, oneUiVersion) for type detection
-    capabilities/                 Shared + per-family Capability definitions (common, dryer, oven,
-                                   dishwasher, fridge, laundry, operational)
-    by_type/                      One DeviceRegistry per appliance type, composed from capabilities/
-tests/                            80+ tests: registry composition, discovery, entity descriptors,
-                                   golden-file regression against captured device dumps
-requirements-dev.txt               Test deps, including the smartthings-local package
-docker-compose.yml / ha_config/    Local HA dev environment
+    registry.py             Builds the global capability registry, validates href collisions
+    capability.py           Capability dataclass (href, entities, transforms)
+    entities.py             Per-platform entity descriptor dataclasses
+    discovery.py            Binds a device's live resources to registered capabilities
+    adapter.py               Flattens bound entities into HA-ready state
+    identity.py              Reads device identity for type detection
+    redact.py                 Strips account/identity data before diagnostics leave HA
+    capabilities/             Shared + per-family Capability definitions (common, dryer, oven,
+                               dishwasher, fridge, washer, laundry, operational, ignored)
+    by_type/                  One DeviceRegistry per appliance type, composed from capabilities/
+tests/                    Registry composition, discovery, entity descriptors, coordinator/observe
+                            behavior, and golden-file regression against captured device dumps
+requirements-dev.txt        Test deps, including the smartthings-local package
+docker-compose.yml / ha_config/   Local HA dev environment
 ```
 
 ---
@@ -141,21 +134,21 @@ support for hardware the maintainers don't have.
 
 ## Adding a new appliance type
 
-1. Capture the appliance's `/device/0` response to see what resources/fields it exposes. An authenticated `DtlsCoapSession` from `smartthings_local.protocol.dtls_session` GET is enough; `local-tools/probe_device.py` wraps this.
+1. Get a capture of the appliance's `/device/0` response. The easiest way: add the device to HA (type detection failing is fine) and pull its Diagnostics download from Settings > Devices & Services > the device > the menu > Download diagnostics — it already contains a redacted dump of the device's resources.
 2. Reuse existing `Capability` objects from `registry/capabilities/` wherever the resource matches one already declared. Most `common.py` capabilities (power, kids lock, remote control, alarms, energy/water meters) are shared verbatim across families; add new ones only for resources unique to the new type.
 3. Create `registry/by_type/<name>.py` with a `DeviceRegistry(name=..., capabilities=_build([...]))`. Use `pattern_capabilities` instead of `capabilities` for any resource whose `href` isn't fixed (for example per-compartment fridge resources); see `refrigerator.py` for the pattern.
-4. Register it in `_REGISTRY_BY_KEY` in `registry/by_type/__init__.py`, keyed on the lowercased, space/hyphen-to-underscore-converted suffix of the device's `oneUiVersion` string (see `_type_key()` in that file for the exact transform).
+4. Register it in `_REGISTRY_BY_KEY` in `registry/by_type/__init__.py`, keyed on the lowercased, space/hyphen-to-underscore-converted suffix of the device's `oneUiVersion` string (see `_type_key()` in that file for the exact transform). If the device never reports `oneUiVersion` — confirmed true for washers — add its consumer-model prefix to `_CONSUMER_PREFIX_TO_KEY` instead, so `for_device_by_model()` can route it.
 5. Add golden-file coverage in `tests/` against a captured `/device/0` dump for the new type.
 
-No config-flow or coordinator changes are needed. Device-type detection and entity wiring are fully driven by the registry.
+No config-flow changes are needed. Device-type detection and entity wiring are fully driven by the registry.
 
 ---
 
-## Known DTLS behavior
+## Known device behavior
 
-Samsung's RT-OCF DTLS stack occasionally closes sessions actively, usually right after a Block2 GET or in the seconds after a POST. Retry/retransmit bounds and inter-request pacing live in the `smartthings-local` protocol layer (tuned against measured per-firmware request-rate ceilings); reconnect-with-backoff and stale-state fallback live in this repo's `coordinator.py`. From HA's perspective a brief reconnect looks like an entity holding its last value for one poll cycle rather than going `unavailable`.
+Samsung's firmware occasionally drops the DTLS session briefly — this is normal appliance-side behavior, not a bug. The integration reconnects automatically, and from HA's perspective a brief reconnect looks like an entity holding its last value for one poll cycle rather than going `unavailable`. When an appliance supports it, the integration prefers push-based updates (instant, via `observe.py`) over polling, falling back to polling otherwise.
 
-If reconnects become persistent (more than a handful per minute), something's actually wrong. Check the appliance's Wi-Fi link first, then look for a competing DTLS client on the LAN: Samsung's RT-OCF DTLS allows only one active session per peer.
+If reconnects become persistent (more than a handful per minute), something's actually wrong. Check the appliance's Wi-Fi link first, then look for a competing DTLS client on the LAN — only one active session per appliance is allowed at a time.
 
 ---
 
@@ -163,7 +156,7 @@ If reconnects become persistent (more than a handful per minute), something's ac
 
 Patches are welcome, especially:
 
-- New `by_type/` registries for appliance families not yet covered (washer, AC, microwave, etc.) on the same Tizen RT 3.x firmware family.
+- New `by_type/` registries for appliance families not yet covered (AC, microwave, etc.) on the same Tizen RT 3.x firmware family.
 - Confirmation or refutation of compatibility on additional models within an already-supported type.
 - Protocol-level fixes, which belong upstream in [`smartthings-local`](https://github.com/QuiteYellow/SmartThings-Local) rather than here. HA-side fixes (entities, config flow, coordinator, registry) belong in this repo.
 

custom_components/localthings/config_flow.py

@@ -4,8 +4,10 @@ from __future__ import annotations
 import datetime
 import logging
 import re
+import selectors
 import socket
 import ssl
+import time
 from typing import Any
 
 import voluptuous as vol
@@ -22,7 +24,8 @@ from .const import (
     CONF_HOST, CONF_PORT,
     CONF_CA_CERT_PEM, CONF_CA_KEY_PEM,
     CONF_LEAF_CERT_PEM, CONF_LEAF_KEY_PEM,
-    PROBE_PORTS,
+    PROBE_PORT_RANGE, PREFERRED_PROBE_PORTS, LIVENESS_PROBE_TIMEOUT_S,
+    PROBE_GET_TIMEOUT_S,
 )
 
 _TEXT = TextSelector(TextSelectorConfig(type=TextSelectorType.TEXT))
@@ -120,6 +123,73 @@ def _mint_leaf_cert(ca_cert_pem: str, ca_key_pem: str, uuid: str) -> tuple[str,
     return fullchain_pem, leaf_key_pem
 
 
+def _order_candidates(ports: list[int]) -> list[int]:
+    """Order live ports so the historically known DTLS ports are tried first."""
+    preferred = [p for p in PREFERRED_PROBE_PORTS if p in ports]
+    rest = sorted(p for p in ports if p not in PREFERRED_PROBE_PORTS)
+    return preferred + rest
+
+
+def _find_live_ports(host: str, ports: list[int], timeout: float) -> list[int]:
+    """Fast UDP liveness sweep to narrow the range before the DTLS handshake.
+
+    UDP is connectionless, but a *connected* UDP socket surfaces the ICMP
+    port-unreachable that a closed port returns as ECONNREFUSED on its next
+    recv. So we send one probe datagram per port and watch for that error:
+
+      * ECONNREFUSED       -> port is closed (device actively rejected it)
+      * silence / any data -> port may be live (open|filtered); a candidate
+
+    This is the in-process equivalent of ``nmap -sU``: it lets us take a
+    nine-port range down to the one or two ports actually worth a full DTLS
+    handshake + /device/0 GET, and bounds the total wait to ``timeout``
+    instead of stalling on every dead port when a firewall swallows the ICMP
+    replies.
+    """
+    sockets: dict[int, socket.socket] = {}
+    sel = selectors.DefaultSelector()
+    # A single byte is enough to provoke an ICMP port-unreach from a closed
+    # port; a real DTLS ClientHello is unnecessary just to test for life.
+    probe = b"\x00"
+    try:
+        for port in ports:
+            sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+            sock.setblocking(False)
+            try:
+                sock.connect((host, port))
+                sock.send(probe)
+            except OSError:
+                sock.close()
+                continue
+            sockets[port] = sock
+            sel.register(sock, selectors.EVENT_READ, port)
+
+        # Ports drop out of the selector as they refuse; whatever is still
+        # registered when the deadline passes is silent-but-live (a candidate).
+        deadline = time.monotonic() + timeout
+        while sel.get_map():
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                break
+            for key, _ in sel.select(timeout=remaining):
+                try:
+                    # Data back means live; ECONNREFUSED (or any other socket
+                    # error) means the port is closed/unusable — rule it out.
+                    key.fileobj.recv(1)
+                except OSError:
+                    sel.unregister(key.fileobj)
+        live = [key.data for key in sel.get_map().values()]
+    finally:
+        sel.close()
+        for sock in sockets.values():
+            try:
+                sock.close()
+            except OSError:
+                pass
+
+    return _order_candidates(live)
+
+
 def _probe_and_validate(host: str, ca_cert_pem: str, ca_key_pem: str) -> dict:
     """Fetch UUID, mint leaf cert, probe each port. Returns config entry data dict."""
     import cbor2
@@ -146,8 +216,21 @@ def _probe_and_validate(host: str, ca_cert_pem: str, ca_key_pem: str) -> dict:
         raise CannotConnect(f"Failed to mint leaf cert: {exc}") from exc
     _LOGGER.debug("Leaf cert minted successfully")
 
+    candidates = _find_live_ports(
+        host, PROBE_PORT_RANGE, LIVENESS_PROBE_TIMEOUT_S
+    )
+    if not candidates:
+        # Every port in the range actively refused: there is no DTLS/CoAP
+        # listener on this host, so a handshake can't succeed. Fail now with a
+        # clear message instead of retrying doomed ports.
+        raise CannotConnect(
+            f"no live DTLS port found on {host} "
+            f"in {PROBE_PORT_RANGE[0]}-{PROBE_PORT_RANGE[-1]}"
+        )
+    _LOGGER.debug("Live DTLS port candidates on %s: %s", host, candidates)
+
     last_exc = None
-    for port in PROBE_PORTS:
+    for port in candidates:
         sess = None
         try:
             sess = DtlsCoapSession(
@@ -157,7 +240,7 @@ def _probe_and_validate(host: str, ca_cert_pem: str, ca_key_pem: str) -> dict:
             )
             sess.connect()
             sess.start_reader()
-            code, payload = sess.get(['device', '0'], timeout=15.0)
+            code, payload = sess.get(['device', '0'], timeout=PROBE_GET_TIMEOUT_S)
             if code != 0x45 or not payload:
                 raise CannotConnect(f"port {port}: unexpected code {code:#04x}")
             body = cbor2.loads(payload)

custom_components/localthings/const.py

@@ -9,7 +9,25 @@ CONF_CA_KEY_PEM   = "ca_key_pem"
 CONF_LEAF_CERT_PEM = "leaf_cert_pem"
 CONF_LEAF_KEY_PEM  = "leaf_key_pem"
 
-PROBE_PORTS = [49154, 49155]
+# The DTLS/CoAP local API binds somewhere in this ephemeral range; which port
+# depends on firmware. Newer builds answer on 49154/49155, but older ones have
+# been seen as low as 49153, so we sweep the whole range for a live UDP port
+# before attempting the (expensive) DTLS handshake.
+PROBE_PORT_RANGE = list(range(49152, 49161))
+
+# Ports we've historically seen complete a DTLS handshake. When more than one
+# port in the range looks live, these are tried first.
+PREFERRED_PROBE_PORTS = [49154, 49155]
+
+# Per-port timeout for the cheap UDP liveness sweep. Closed ports return an
+# ICMP port-unreachable almost immediately; a live-but-silent port is only
+# detected by this timeout elapsing, so keep it short.
+LIVENESS_PROBE_TIMEOUT_S = 1.5
+
+# Deadline for the blockwise /device/0 GET during the config-flow probe. The
+# slowest device observed returns a full dump in ~8s, so 10s leaves headroom
+# without stalling setup; it matches the per-resource read timeout elsewhere.
+PROBE_GET_TIMEOUT_S = 10.0
 
 SUMMARY_INTERVAL_S = 30.0
 

custom_components/localthings/manifest.json

@@ -5,12 +5,12 @@
   "config_flow": true,
   "dependencies": [],
   "documentation": "https://github.com/mbillow/localthings",
-  "iot_class": "local_polling",
+  "iot_class": "local_push",
   "issue_tracker": "https://github.com/mbillow/localthings/issues",
   "requirements": [
     "cbor2>=5.4.6",
     "pyOpenSSL>=23.0",
     "smartthings-local>=0.1.0"
   ],
-  "version": "0.4.0"
+  "version": "0.5.0"
 }

custom_components/localthings/registry/capabilities/operational.py

@@ -75,7 +75,9 @@ OPERATIONAL_STATE = Capability(
     poll_tier='hot',
     entities=(
         SensorDesc(key='machine_state', field='x.com.samsung.da.state',
-                   name='Machine state', value_fn=_to_ocf),
+                   name='Machine state', device_class='enum',
+                   options=('idle', 'active', 'pause'),
+                   translation_key='machine_state', value_fn=_to_ocf),
         # cycle_active is a bool derived from machine_state; used by the
         # adapter to gate oven writes (cycle_active_field='cycle_active').
         # Harmless for non-oven appliances — just an extra bool in state.

custom_components/localthings/registry/capabilities/oven.py

@@ -223,7 +223,9 @@ OVEN_OPERATIONAL_STATE = Capability(
     poll_tier='hot',
     entities=(
         SensorDesc(key='machine_state', field='x.com.samsung.da.state',
-                   name='Machine state', icon='mdi:stove', value_fn=_to_ocf),
+                   name='Machine state', icon='mdi:stove',
+                   device_class='enum', options=('idle', 'active', 'pause'),
+                   translation_key='machine_state', value_fn=_to_ocf),
         BinarySensorDesc(key='cycle_active', field='x.com.samsung.da.state',
                          name='Cycle active', device_class='running',
                          value_fn=lambda v: _SAMSUNG_STATE_TO_OCF.get(v) == 'active'),

custom_components/localthings/strings.json

@@ -18,6 +18,7 @@
       },
       "ice_type": {
         "state": {
+          "off": "Off",
           "whiskey_iceball_3": "3 Balls/Day",
           "whiskey_iceball_6": "6 Balls/Day",
           "whiskey_iceball_9": "9 Balls/Day"
@@ -114,6 +115,13 @@
           "observe": "Push (observe)",
           "poll": "Polling"
         }
+      },
+      "machine_state": {
+        "state": {
+          "idle": "Idle",
+          "active": "Active",
+          "pause": "Paused"
+        }
       }
     }
   },

custom_components/localthings/translations/en.json

@@ -18,6 +18,7 @@
       },
       "ice_type": {
         "state": {
+          "off": "Off",
           "whiskey_iceball_3": "3 Balls/Day",
           "whiskey_iceball_6": "6 Balls/Day",
           "whiskey_iceball_9": "9 Balls/Day"
@@ -114,6 +115,13 @@
           "observe": "Push (observe)",
           "poll": "Polling"
         }
+      },
+      "machine_state": {
+        "state": {
+          "idle": "Idle",
+          "active": "Active",
+          "pause": "Paused"
+        }
       }
     }
   },

tests/localthings/test_config_flow.py

@@ -56,6 +56,109 @@ async def test_successful_setup(hass: HomeAssistant, mock_probe) -> None:
     assert result['data'][CONF_CA_CERT_PEM] == MOCK_CA_CERT_PEM
 
 
+def test_order_candidates_prefers_known_ports() -> None:
+    """Live ports are ordered with the historically known DTLS ports first,
+    then the rest ascending."""
+    from custom_components.localthings.config_flow import _order_candidates
+
+    assert _order_candidates([49160, 49153, 49155, 49154]) == [
+        49154, 49155, 49153, 49160,
+    ]
+    assert _order_candidates([49153]) == [49153]
+
+
+def test_find_live_ports_detects_silent_port() -> None:
+    """The UDP liveness sweep flags a bound-but-silent port as live and drops
+    ports that refuse with ICMP port-unreachable.
+
+    A bound, never-recv'd UDP socket stands in for a device that listens but
+    stays silent (open|filtered), like the dishwasher in issue #13 on 49153.
+    Two sibling ports are reserved then closed so loopback refuses datagrams
+    to them, standing in for the closed ports the scan should discard.
+    """
+    import socket
+
+    from custom_components.localthings.config_flow import _find_live_ports
+
+    reserve = [socket.socket(socket.AF_INET, socket.SOCK_DGRAM) for _ in range(3)]
+    for s in reserve:
+        s.bind(('127.0.0.1', 0))
+    ports = [s.getsockname()[1] for s in reserve]
+    live_sock, live_port = reserve[0], ports[0]
+    reserve[1].close()
+    reserve[2].close()
+    closed_ports = ports[1:]
+
+    try:
+        result = _find_live_ports(
+            '127.0.0.1', [closed_ports[0], live_port, closed_ports[1]], 0.8,
+        )
+    finally:
+        live_sock.close()
+
+    assert result == [live_port]
+
+
+async def test_probe_uses_discovered_low_port(hass: HomeAssistant, monkeypatch) -> None:
+    """A device that only answers on 49153 — outside the historical
+    49154/49155 pair — is found by the liveness sweep and its port is stored
+    on the config entry (issue #13)."""
+    import cbor2
+
+    from custom_components.localthings import config_flow
+
+    device0 = [
+        {'rt': ['x.com.samsung.devcol']},
+        {'href': '/information/vs/0', 'rep': {
+            'x.com.samsung.da.modelNum':
+                'DA_WM_TP1_21_COMMON|20375141|20010002001811424AA30217008A0000',
+            'x.com.samsung.da.description':
+                'DA_WM_TP1_21_COMMON_WW5000C/DC92-03495A_B048',
+            'x.com.samsung.da.serialNum': 'DISHWASHER-49153',
+        }},
+        {'href': '/otninformation/vs/0', 'rep': {'otnStatus': 'None'}},
+    ]
+
+    class _FakeSession:
+        def __init__(self, host, port, cert_pem=None, key_pem=None):
+            self.host, self.port = host, port
+
+        def connect(self):
+            pass
+
+        def start_reader(self):
+            pass
+
+        def get(self, path, timeout=15.0):
+            return 0x45, cbor2.dumps(device0)
+
+        def close(self):
+            pass
+
+    monkeypatch.setattr(config_flow, '_fetch_samsung_uuid', lambda: 'test-uuid')
+    monkeypatch.setattr(
+        config_flow, '_mint_leaf_cert',
+        lambda ca_cert, ca_key, uuid: ('FULLCHAIN', 'LEAFKEY'),
+    )
+    monkeypatch.setattr(
+        config_flow, '_find_live_ports',
+        lambda host, ports, timeout: [49153],
+    )
+    monkeypatch.setattr(
+        'smartthings_local.protocol.dtls_session.DtlsCoapSession', _FakeSession,
+    )
+
+    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: MOCK_CA_CERT_PEM, CONF_CA_KEY_PEM: MOCK_CA_KEY_PEM},
+    )
+    assert result['type'] == FlowResultType.CREATE_ENTRY
+    assert result['data'][CONF_PORT] == 49153
+
+
 async def test_cannot_connect(hass: HomeAssistant) -> None:
     """Failed probe: form re-shown with cannot_connect error."""
     from custom_components.localthings.config_flow import CannotConnect