Move the on/off interpretation into a single remote_control_enabled()
in registry/capabilities/common.py so the write-guard added in the
previous commit can't silently drift from the Smart Control binary
sensor's own reading of the same hrefs. Also promotes both
/remotectrl hrefs to poll_tier='warm' so the coordinator's cached
state backing that write guard doesn't lag up to a full 30s cold
summary poll behind the device's actual toggle state.
Devices with a /remotectrl href already surface it as a read-only
"Smart Control" binary sensor, but writes weren't checking it before
now. async_send_command now blocks every write (any platform) with a
ServiceValidationError telling the user to enable remote control via
the appliance's manual, ahead of any per-description validate_fn.
/simplify pass on the issue #27 fix: extract a shared _snake_to_title
between entity.py and discovery.py, factor discover()'s two binding
loops through one _bind() helper, and close a TOCTOU race the cache
merge introduced -- apply() is the sole path StateCache mutations flow
through, so the read-then-write is now serialized under one lock
instead of two independently-locked calls.
Issue #27: the flex-zone/cooler-drawer select vanished after a device
stopped including supportedOptions on an update for /mode/vs/0.
ObserveManager.apply() handed reps straight to StateCache.apply_rep,
which fully replaces the cached rep -- so a partial update (missing a
field the select's exists_fn/options_field gate on) silently erased
data a fuller update had previously supplied. apply() now merges
incoming reps onto whatever's already cached instead.
Also give ice-maker entities (and any future pattern-cap instance) a
device-given display name instead of the href-derived "Icemaker
One"/"Icemaker Two": Capability.name_field lets a pattern capability
read and normalize an instance name (e.g. iceMaker.name's "CUBED_ICE")
for use as the entity name prefix, independent of the stable
key/unique_id.
CLIMATE_CONSUMED_HREFS (power, current/target temp, fan, swing, preset)
were bound as no-entity coverage capabilities with the Capability
default poll_tier='cold'. The coordinator only OBSERVE-subscribes and
sub-polls 'hot'/'warm' hrefs, so cold-tier state only refreshed on the
~30s full /device/0 summary sweep -- matching the 20-30s HA lag reported
on issue #17 despite commands landing on the device instantly. Pin them
to 'warm', same as CLIMATE's own primary href, so they get push
notifications (or warm-tier sub-polling as a poll-only fallback).
The switch and select shared a stub-time asymmetry: only the select had a
`not rep` carve-out, so an unfetched-stub rep at the moment platforms are
set up (entity creation runs once, ever) would instantiate a Select, while
flatten() re-evaluates exists_fn every poll against live data -- once the
resource populated to a single-level list, the switch's exists_fn would win
instead and feed the already-created Select a bool through their shared
'ai_energy_level' key, which isn't a valid select option.
Dropped the stub carve-out from the select's exists_fn so both sides
require real, populated data to decide the platform -- on a device that
stubs this cold-tier href on its very first poll, the entity now simply
doesn't appear until a reload, instead of appearing as the wrong widget
type. Added tests for the missing/empty-list supportedAiLevel shapes on
both widgets and a regression test locking in the stub behavior.
Consolidate the AC/power-exclusion rationale (previously spelled out nearly
verbatim in three places) down to one canonical explanation next to
common.POWER, with one-line pointers elsewhere. Dedupe the switch/select
test classes' identical _desc() lookup into one shared helper.
FIRMWARE_UPDATE and ALARMS were already copy-pasted into all 6 device-type
registries by hand; POWER/KIDS_LOCK/REMOTE_CONTROL into 5 of 6. Consolidate
into two bundles in common.py, unpacked via *common.UNIVERSAL / *common.POWER
the same way ignored.IGNORED already is:
- UNIVERSAL: ALARMS, ENERGY_METER, FIRMWARE_UPDATE (moved from fridge.py),
SELF_CHECK (moved from fridge.py), AI_ENERGY_LEVEL, and the kids-lock/
remote-control pairs. Safe everywhere -- discover() only binds a href
actually present in a device's dump, so a capability with no known
conflicting family is a no-op where the href is absent and a real,
wanted entity where it's present. This also broadens AI_ENERGY_LEVEL,
ENERGY_METER, and SELF_CHECK to device types they weren't confirmed on
before, on the same reasoning.
- POWER: just POWER_GENERIC/POWER_VS_FALLBACK, applied to the 5 non-AC
registries. Airconditioner keeps its own opt-out: its climate entity
already owns /power/0 and /power/vs/0 via a bare, no-entity claim
(airconditioner.COVERAGE), and a real power capability on the same
href would make _build() raise (a href with multiple caps requires
every cap to have rt_filter or match_fn; the bare COVERAGE cap has
neither).
Full test suite (327 tests, all 6 device-type golden fixtures) passes
unchanged -- none of the newly-broadened capabilities bind on any existing
fixture, confirming the no-op reasoning held in practice, not just theory.
Issue #40: /energy/ailevel/vs/0 was unbound on a plain washer. The
capability already existed for fridges but was gated off entirely on
single-level hardware (the common case), so it's moved to common.py
(cross-family, like fridge + washer now) and split into two entities:
a switch when supportedAiLevel has exactly one entry (aiLevel is really
just an on/off toggle there), and a select otherwise, with '0' (off)
synthesized back into the select's options since supportedAiLevel never
lists it but it's a real observed value.
Also drops the translation_key/strings.json entries -- aiLevel's raw
digit values already render fine untranslated, and translating a
handful of levels can't cover devices with more.
Addresses the reuse finding skipped in the previous /simplify pass:
washer's bubble soak/pre-wash/intensive switches and dishwasher's storm
wash/auto release dry switches were two separate implementations of the
same '<prefix>_On'/'<prefix>_Off' read-modify-write-on-options[] contract.
Moved bool_option_write/bool_option_value/bool_option_exists/
bool_option_switch into laundry.py (same module that already owns
cycle_write/cycle_select for the identical 'Course' token), and pointed
both washer.py and dishwasher.py at it. washer.py keeps only its
washer-specific per-course validate_fn, passed into the shared factory
as a prebuilt callable -- the factory itself has no opinion on validation.
No behavior change; re-verified every existing assertion (washer toggles,
dishwasher storm_wash/auto_release_dry, dosing alarms) plus all golden
state-key sets by hand against the refactored code.
/simplify pass on the bubble soak/pre-wash/intensive switches:
- Move validate_fn dispatch from switch.py into coordinator.async_send_command,
next to the existing write_fn getattr -- every platform gets validation for
free instead of switch.py hand-rolling it alone, and it avoids building the
full resources snapshot twice per write (switch.py was calling
coordinator.last_resources twice; the coordinator now snapshots once, and
only when a validate_fn is actually present).
- Collapse the four per-switch factories (write/value/exists/validate) plus
the _AVAILABILITY_FIELD side-table into one _bool_option_switch() that
builds the SwitchDesc directly, so the three call sites read as one line
each instead of six, and a typo'd prefix can no longer silently KeyError
against a separate lookup table.
- Rename _dosing_alarm_exists to _option_exists and reuse it for the new
switches too -- it was already the exact same "is this token present"
check the toggles need.
No behavior change; re-verified write_fn/rep_fn/exists_fn/validate_fn against
the same fixtures and golden state-key sets as before.
Add a validate_fn hook to SwitchDesc, checked in switch.py before dispatch
and surfaced as a ServiceValidationError so an unsupported write shows a
real error in the UI instead of the coordinator's silent log-only rejection.
Wired it into the three course-gated washer switches using their
availability bitmaps (BubbleSoakSet/PreWashAvailableSet/IntensiveAvailableSet),
which line up positionally with editCourseList. Turning a toggle off is
never blocked, and the check fails open whenever the course or bitmap can't
be resolved.
Also fixes a bug in _bool_option_write: it took a `p and 'On' or 'Off'`-style
truthy check, but switch.py always calls it with the string 'On' or 'Off' --
both truthy, so every write landed as 'On' regardless of intent.
A follow-up dump confirmed these ride as plain BubbleSoak_On/Off,
PreWashSetting_On/Off, and IntensiveSetting_On/Off tokens in the same
/course/vs/0 options array as the cycle select, so they're exposed as
self-gating config switches the same way other options-array fields are.
Per-cycle availability (BubbleSoakSet/PreWashAvailableSet/IntensiveAvailableSet)
lines up positionally with editCourseList but isn't used for gating, since
exists_fn only runs once at setup against whatever course happened to be
active then.
A washer/dryer combo user's editCourseList carries five Course_XX codes
that weren't named in washer_cycle: 36 (Wash+Dry), 37 (Air Wash),
38 (Cotton Dry), 39 (Synthetics Dry), and 1F (Intense Cold, distinct
from the existing 8F code used by non-combo models).
Rebased onto PR #36's merge (temperature fallback for /temperatures/vs/0,
display-light switch). Reconciliation, per Opus review:
- Dropped our duplicate LIGHT capability in favor of PR #36's DISPLAY_LIGHT
(same href/entity, cosmetic differences only).
- Dropped /option/muteonce/vs/0 and /selfcheck/vs/0 from the ignore list
PR #36 added -- both have confirmed, cleanly modelable contracts (a plain
On/Off field, and a documented Start/Cancel self-check action already
covered by the existing fridge.SELF_CHECK pattern), so keeping our bound
versions instead of ignoring them. This also picks up mute_once/selfcheck_*
on PR #36's own TP1X_DA-AC-RAC-01011 fixture -- regenerated its golden.
- Deduped the ~10 housekeeping hrefs both branches independently ignored.
- Added a unit test for climate.py's _temps_vs_item (the temperature-
fallback selection logic), which had no coverage -- climate.py isn't
importable in the registry-level AC tests, and the existing "no unbound
hrefs" tests only exercise binding, not the fallback itself.
Closes the coverage-gap repair for two more room-AC boards (issues #37,
- TP2X_RAC_20K reports no oneUiVersion and no '_PRAC_' modelNum token, so
its device type went unrecognized -- add a '_RAC_' fallback token to
for_device_by_model.
- Bind the resources both dumps actually populate: mute-once (switch),
display light (switch), self-check (reused from fridge.SELF_CHECK), and
the circuit-breaker current-limit setting (read-only diagnostic sensors,
since its write contract isn't confirmed from the dump).
- Ignore the rest as plumbing/opaque/unconfirmed: control-set descriptor,
keepnormalstate flag, software-reset trigger, AI Sleep handshake,
absence-monitoring stubs, remote-data-control, remote-temperature,
reservation ruleset, and the welcome-temperature tracker.
Adds scrubbed fixtures + goldens for both dumps and extends the AC
capability/golden-regression tests to assert zero unbound hrefs.
Adds two small, additive fridge capabilities:
- AI_ENERGY_LEVEL: a select on /energy/ailevel/vs/0 exposing the AI
energy-saving level, gated behind supportedAiLevel actually offering
more than one choice (previously globally ignored since every dump
seen only reported a single supported level).
- selfcheck_error: a diagnostic sensor on the existing SELF_CHECK
capability surfacing x.com.samsung.da.error from the last self-check,
for hardware that reports it.
This does not touch FLEX_ZONE, /mode/vs/0, or /icemaker/status/0.
- Parameterize FakeObserveSession.notify_on_subscribe as dict[str, Any] | None
to match the surrounding fully-typed attributes (the dict is delivered as
the OBSERVE rep to on_notification); add the typing.Any import.
- Reword the test_coordinator comment: subscribe() delivers a notification
for every href it subscribes to (when notify_on_subscribe is set), not one.
Covers the #19-#27 fridge/washer coverage-gap batch: FlexWash (WV) and
washer/dryer combo detection, the CV_FDR_ flex-zone fix (also closes#32),
the Cool Select Zone pantry select, and the new energy sensors.
The observe tests raced a background thread (5 ms wall-clock sleep)
against the coordinator reaching its resubscribe. try_enter_observe_mode
clears _notified before subscribing, so a notify only counts if it lands
between that clear and the end of the grace sleep. When the intervening
update cycle (reconnect, cache sweep, executor hops) took longer than
5 ms, every notify was cleared and the mode stayed 'poll' —
test_reconnect_from_observe_mode_resubscribes_immediately failed roughly
1 in 7 runs.
Replace the threads with FakeObserveSession.notify_on_subscribe, which
delivers the rep synchronously from subscribe() the way a real device
answers a subscription. That puts the notify inside the grace window by
construction rather than by timing. Tests that require the resubscribe to
fail now set it to None explicitly instead of relying on the absence of a
racing thread.
No production code changed; no assertion weakened, and no sleeps, retries
or timeouts added.
Claude-Session: https://claude.ai/code/session_01PUSU6tDjHjtbExtyXDPT3N
Review follow-up (Opus + /simplify) on the previous commit:
- power_energy_kwh/energy_saved_kwh/energy_last_month_kwh/
energy_this_month_kwh used a plain `field in rep` exists_fn, unlike their
siblings power_watts/energy_kwh in the same capability. Per
entity._is_included, an explicit exists_fn bypasses the stub carve-out
entirely -- an empty {} rep at platform setup (device/0 returned a
not-yet-fetched stub) would permanently drop these entities for the
session instead of picking them up once a sub-poll populates the
resource. Restore the same `not rep or ...` guard used above.
- fridge._flex_zone_current/_flex_zone_write independently rebuilt the same
supportedOptions set; factor into _flex_zone_supported.
- note in a comment that the flex-zone match assumes at most one
modes/supportedOptions overlap (true on every dump seen); add the
missing negative assertion that dry_level self-gates off on a plain
washer (was only positively asserted on the combo fixture).
Six new diagnostics dumps, six gaps closed:
- refrigerator: bind /diagnosis/vs/0 (reuse dishwasher.DIAGNOSIS -- same
shape) into the refrigerator registry; it was never wired up there,
tripping the coverage repair on any fridge that reports it (#20, #26).
- refrigerator: add PANTRY_ZONE for the Cool Select Zone pantry compartment
(/status/pantry/one/vs/0, x.com.samsung.da.mode/supportedOptions) -- same
shape as BEVERAGE_ZONE but a distinct resource/field set (#20).
- refrigerator: generalize FLEX_ZONE to identify the current mode by list
membership in supportedOptions instead of a hardcoded
CV_TTYPE_RF9000A_ prefix check. TP1X/Bespoke-class fridges use a
CV_FDR_ prefix instead, which the old code didn't recognize -- the
select existed but always read as unknown, and writing to it would have
appended a duplicate CV_FDR_ flag rather than replacing the existing one
(#26, #27; also closes#32).
- common: add energy_saved_kwh (x.com.samsung.da.cumulativeSavedPower) and
power_energy_kwh (x.com.samsung.da.cumulativeConsumption) to the shared
energy meter, plus fridge-only energy_last_month_kwh/energy_this_month_kwh
(monthlyConsumption/thismonthlyConsumption) -- all self-gating on field
presence (#26).
- by_type: add the WV consumer-model prefix (FlexWash twin washers, e.g.
WV55M9600AW) to the by-model fallback map. These report no oneUiVersion
and previously matched no prefix at all, so they fell all the way
through to the unrecognized-device registry with zero capabilities
bound (#19).
- washer: add a self-gating dry_level select to WASHER_SETTINGS for
washer/dryer combo units, which carry a writable dryLevel field
directly on /washer/vs/0 with no separate dryer resource or course
(#22).
The reset-water-filter button and "ice type vs. two named icemakers"
requests from #26/#27 are left alone -- no write contract or exclusivity
behavior is evidenced in either dump, and both icemakers report On
simultaneously on the Bespoke unit, so synthesizing a single-select would
be a guess rather than a fix.
Adds scrubbed fixtures + goldens for FlexWash, a washer/dryer combo,
ARTIK051_REF_17K, and TP2X_REF_20K, plus unit tests for the new/changed
capabilities.
- WV consumer-model prefix (FlexWash twin washers, e.g. WV55M9600AW)
wasn't in the by-model fallback map, so these units fell through to
the unknown-device registry with zero capabilities bound (#19).
- Washer/dryer combo units carry a writable dryLevel field directly on
/washer/vs/0 with no separate dryer resource; add a self-gating
select for it, off supportedDryLevel presence, so plain washers are
unaffected (#22).
Covers the air-conditioner support (#17) and the washer dosing-select /
diagnostics fixes (#9). main was still advertising 0.6.0 despite the AC work
already merging, so this moves it for the next release.
Quality-only cleanups on the air-conditioner support, no behavior change:
- climate.py: reuse common.normalize_temp_unit for the C/F unit read (also
handles the "Celsius"/"Fahrenheit" long forms); collapse the three
fan/swing/preset read properties into _read_mode/_read_modes and the three
write setters into _set_mapped, removing the copy-paste.
- Single source of truth for the climate-consumed hrefs: they lived both as
constants in climate.py and as a list in airconditioner.py. Declare them
once in airconditioner.py (HREF_* + CLIMATE_CONSUMED_HREFS, which also builds
the COVERAGE caps) and import them into climate.py, so a new sibling read
can't drift out of sync with its coverage entry.
Two fixes for issue #9 (WW90T634DHE washer):
- washer dosing selects: the four detergent/softener dosing selects read their
current value from `<Prefix>LevelCtrl_<code>` (un-padded, e.g. "3") but their
options from `Supported<Prefix>LevelCtrl_<hexpairs>` (zero-padded, e.g. "03").
HA's SelectEntity renders a select "unknown" whenever current_option is not in
options, so all four sat "unknown" (idle and running) even though every other
select worked -- which is why it was only those four. Normalize the current
value to the supported code with the same integer value so it matches an
option (and its translation); convert back to the device's native un-padded
format on write.
- diagnostics: pkg_version("smartthings-local") reads package metadata off disk
(listdir + open + read_text), tripping HA's event-loop blocking-call detector.
Offload it to the executor. Audited the rest of the package: config_flow's
socket/crypto and every coordinator DTLS call are already offloaded via
async_add_executor_job -- this was the only blocking call left on the loop.
Also documents air-conditioner support in the README (device table, capability
module list, platform list), missed when that support landed.
Updates the washer dosing tests to the corrected value/write format and adds a
current-option-is-a-valid-option regression; adds a diagnostics test asserting
the version lookup runs off the event loop.
Add support for Samsung room air conditioners (ARTIK051_PRAC-class), the
first device whose core controls map onto a single Home Assistant `climate`
entity rather than a scatter of switches/selects/numbers.
- New `climate` platform + `ClimateDesc`: one composite entity that reads
power, HVAC mode, current/target temperature, fan (wind) strength, swing
(wind direction) and the convenient-mode preset across several OCF
resources and writes back to each. On/off folds into HVACMode.OFF /
TURN_ON/OFF; convenient mode folds into preset_mode. The entity binds one
primary resource (/mode/vs/0) and reads its siblings from the coordinator
snapshot, reusing the cross-resource read pattern from number/select.
- New `airconditioner` capability module + by_type registry, routed via the
`_PRAC_` modelNum token. Reuses common ALARMS/ENERGY_METER,
fridge.FIRMWARE_UPDATE and dishwasher.DIAGNOSIS; air purify and auto clean
as config switches; air dust filter status/usage as diagnostics (usage
normalized to a percentage of rated capacity).
- Climate-consumed and all-zero/ambiguous resources (temperature/wind,
/sensors, /humidity) are declared as AC-scoped coverage so every href in
the dump binds or is covered -- no coverage-gap repair.
- Fan/swing modes map onto HA standard constants (auto-localized); the
custom fan `turbo`, presets `quiet/smart/speed`, and the filter-status
enum get translations in strings.json + translations/en.json.
- Scrubbed fixture, golden, and tests: registry routing, zero unbound
hrefs, the climate write contract, and filter-% normalization.
Clears the 'Node 20 is being deprecated' warnings by moving the actions
we pin to their current Node 24 majors (both released 2026-07-20).
hassfest@master and hacs/action@main are third-party and float on their
own branches.
Marc Billow