Compare commits

..
Author SHA1 Message Date
Claude eb07af3c9a Warn against hard-coding device-specific values in adding-device-support skill
Dumps capture one unit's snapshot, not the field's universe. Add a
dedicated section pointing at the existing options_field/range_field/
native_min_fn machinery for deriving select options and number
ranges/steps live from the device rep instead of transcribing values
from a single dump into Python literals.
2026-07-26 23:48:20 +00:00
5 changed files with 69 additions and 37 deletions

No files matched your search

+35 -4
View File
@@ -103,7 +103,38 @@ sub-polled between summary polls. Pick descriptor types from `entities.py`
as a gap for a human, or ignore it with a documented reason — never invent an as a gap for a human, or ignore it with a documented reason — never invent an
entity on a hunch (`ignored.py`'s rule). entity on a hunch (`ignored.py`'s rule).
## 5. Names and enum labels live in translations, never in Python ## 5. Never hard-code the one dump's values
A single `/device/0` dump is **one device on one firmware** — its select options,
temperature range/increment, and any other "what values are valid here" data are
**that unit's snapshot**, not the field's universe. Other units of the same model
(different region, firmware, board revision) can support more, fewer, or
differently-stepped values. If the dump reports the live option/range list, wire
the descriptor to read it live — don't transcribe what you saw into a Python
literal:
- **Selects**: use `options_field` (a resource field holding the live options
list, e.g. `supportedWaterTemperature`, `iceType.supported`) so `select.py`
reads the current device's real options every time, not `options=(...)` typed
from the dump. Reach for a callable `options` only when the values require
cross-resource computation the field alone can't give you — a static tuple is
right only for genuinely fixed, spec-defined enums (e.g. an OCF-standard field
with a closed value set), never for vendor `supported*` lists.
- **Number ranges/steps**: use `range_field` (a `[min, max]`-shaped field) or
`native_min_fn`/`native_max_fn`/`step_fn` to read bounds from the live rep —
see `oven.py`'s `_setpoint_bounds`. Only fall back to static `native_min`/
`native_max`/`step` when the dump has no such field and the bound is genuinely
fixed by spec, not just "the only value this one unit happened to report."
- **Anywhere else** a field's presence, count, or shape looks like it could vary
by model/config (course lists, capability flags, supported-mode arrays):
check whether the resource carries its own `supported*` companion field before
assuming the observed value is exhaustive.
When you do hard-code something (a genuinely fixed enum, a spec constant), that's
a judgement call worth a one-line comment saying why it's safe — the default
assumption should be "derive it," not "copy it."
## 6. Names and enum labels live in translations, never in Python
Descriptors have **no `name` field**. Every entity is named from the shipped Descriptors have **no `name` field**. Every entity is named from the shipped
catalog, keyed by `translation_key` — which defaults to the descriptor's own catalog, keyed by `translation_key` — which defaults to the descriptor's own
@@ -142,7 +173,7 @@ no `[%key:...%]` resolution (that's Core build tooling). Every other language
must mirror `en.json` key for key — also enforced by must mirror `en.json` key for key — also enforced by
`tests/test_translations.py`. `tests/test_translations.py`.
## 6. Coverage discipline: bound or ignored ## 7. Coverage discipline: bound or ignored
Every href in the dump must resolve, or the repair fires. If a resource isn't Every href in the dump must resolve, or the repair fires. If a resource isn't
worth an entity, add it to `capabilities/ignored.py` (a no-entity `Capability`) worth an entity, add it to `capabilities/ignored.py` (a no-entity `Capability`)
@@ -156,7 +187,7 @@ friendlier href**.
ignored because washers bind it. When only one family should ignore an href ignored because washers bind it. When only one family should ignore an href
that another binds, scope the ignore to that family's registry. that another binds, scope the ignore to that family's registry.
## 7. Reuse before writing new code ## 8. Reuse before writing new code
Check `common.py` (generic OCF: power, energy, alarms, water) and `laundry.py` Check `common.py` (generic OCF: power, energy, alarms, water) and `laundry.py`
(shared washer/dryer/dishwasher: buzzer, job status, `cycle_select` + course (shared washer/dryer/dishwasher: buzzer, job status, `cycle_select` + course
@@ -165,7 +196,7 @@ registry uses `fridge.FIRMWARE_UPDATE`; all three laundry families share
`laundry.cycle_select`. If two families hand-roll the same helper, hoist it to a `laundry.cycle_select`. If two families hand-roll the same helper, hoist it to a
shared module rather than copying. shared module rather than copying.
## 8. Lock it in ## 9. Lock it in
1. Add a **scrubbed** fixture `tests/fixtures/<type>_device.json` 1. Add a **scrubbed** fixture `tests/fixtures/<type>_device.json`
(`{"device0": [ {devcol rep}, {href, rep}, ... ]}`) — replace serials, MACs, (`{"device0": [ {devcol rep}, {href, rep}, ... ]}`) — replace serials, MACs,
@@ -237,33 +237,32 @@ _DEAD_INSTANTANEOUS_POWER = '-500'
ENERGY_METER = Capability( ENERGY_METER = Capability(
href='/energy/consumption/vs/0', href='/energy/consumption/vs/0',
entities=( entities=(
# No `not rep` stub carve-out (issue #78: a fridge whose # `not rep` keeps the empty-{} stub carve-out (see entity._is_included):
# /energy/consumption/vs/0 is permanently {} -- it just doesn't # an explicit exists_fn otherwise bypasses it, which would drop the
# report energy data -- got all five sensors created anyway and # entity when /device/0 returns a not-yet-fetched stub. On a populated
# stuck at "Unknown" forever, since an empty {} rep and a # rep, hide power only for the dead sentinel or an absent field.
# not-yet-fetched stub are indistinguishable from content alone).
# Same tradeoff AI_ENERGY_LEVEL below already makes deliberately:
# an entity that's unlucky on first-poll timing stays absent until
# a reload sees real data, rather than every genuinely-unsupported
# resource showing a permanent phantom sensor.
SensorDesc(key='power_watts', field='x.com.samsung.da.instantaneousPower', SensorDesc(key='power_watts', field='x.com.samsung.da.instantaneousPower',
device_class='power', state_class='measurement', device_class='power', state_class='measurement',
unit='W', value_fn=clamp_power, unit='W', value_fn=clamp_power,
exists_fn=lambda rep, resources: ( exists_fn=lambda rep, resources: not rep or (
rep.get('x.com.samsung.da.instantaneousPower') rep.get('x.com.samsung.da.instantaneousPower')
not in (None, _DEAD_INSTANTANEOUS_POWER))), not in (None, _DEAD_INSTANTANEOUS_POWER))),
SensorDesc(key='energy_kwh', field='x.com.samsung.da.cumulativePower', SensorDesc(key='energy_kwh', field='x.com.samsung.da.cumulativePower',
device_class='energy', device_class='energy',
state_class='total_increasing', unit='kWh', value_fn=wh_to_kwh, state_class='total_increasing', unit='kWh', value_fn=wh_to_kwh,
exists_fn=lambda rep, resources: 'x.com.samsung.da.cumulativePower' in rep), exists_fn=lambda rep, resources: (
not rep or 'x.com.samsung.da.cumulativePower' in rep)),
# cumulativeConsumption is a second, independently-varying running # cumulativeConsumption is a second, independently-varying running
# total alongside cumulativePower -- some fridges (issue #26) report # total alongside cumulativePower -- some fridges (issue #26) report
# both. Self-gates off where only cumulativePower is present. # both. Self-gates off where only cumulativePower is present. `not
# rep or` keeps the same empty-{} stub carve-out as power_watts/
# energy_kwh above -- without it, an exists_fn permanently drops the
# entity if setup happens to land on a not-yet-fetched stub.
SensorDesc(key='power_energy_kwh', field='x.com.samsung.da.cumulativeConsumption', SensorDesc(key='power_energy_kwh', field='x.com.samsung.da.cumulativeConsumption',
device_class='energy', device_class='energy',
state_class='total_increasing', unit='kWh', value_fn=wh_to_kwh, state_class='total_increasing', unit='kWh', value_fn=wh_to_kwh,
exists_fn=lambda rep, resources: ( exists_fn=lambda rep, resources: (
'x.com.samsung.da.cumulativeConsumption' in rep)), not rep or 'x.com.samsung.da.cumulativeConsumption' in rep)),
# AI Energy Mode's lifetime savings estimate vs. an unoptimized # AI Energy Mode's lifetime savings estimate vs. an unoptimized
# baseline -- present on some models (e.g. TP1X_REF_21K, issue #21/ # baseline -- present on some models (e.g. TP1X_REF_21K, issue #21/
# #27) and absent on others (issue #20/#26), unlike cumulativePower. # #27) and absent on others (issue #20/#26), unlike cumulativePower.
@@ -271,7 +270,7 @@ ENERGY_METER = Capability(
device_class='energy', device_class='energy',
state_class='total_increasing', unit='kWh', value_fn=wh_to_kwh, state_class='total_increasing', unit='kWh', value_fn=wh_to_kwh,
exists_fn=lambda rep, resources: ( exists_fn=lambda rep, resources: (
'x.com.samsung.da.cumulativeSavedPower' in rep)), not rep or 'x.com.samsung.da.cumulativeSavedPower' in rep)),
# Monthly billing-cycle totals -- the completed prior month and the # Monthly billing-cycle totals -- the completed prior month and the
# in-progress current month. Not ever-increasing (each resets at # in-progress current month. Not ever-increasing (each resets at
# month boundary), so no state_class. # month boundary), so no state_class.
@@ -279,12 +278,12 @@ ENERGY_METER = Capability(
device_class='energy', device_class='energy',
unit='kWh', value_fn=wh_to_kwh, unit='kWh', value_fn=wh_to_kwh,
exists_fn=lambda rep, resources: ( exists_fn=lambda rep, resources: (
'x.com.samsung.da.monthlyConsumption' in rep)), not rep or 'x.com.samsung.da.monthlyConsumption' in rep)),
SensorDesc(key='energy_this_month_kwh', field='x.com.samsung.da.thismonthlyConsumption', SensorDesc(key='energy_this_month_kwh', field='x.com.samsung.da.thismonthlyConsumption',
device_class='energy', device_class='energy',
unit='kWh', value_fn=wh_to_kwh, unit='kWh', value_fn=wh_to_kwh,
exists_fn=lambda rep, resources: ( exists_fn=lambda rep, resources: (
'x.com.samsung.da.thismonthlyConsumption' in rep)), not rep or 'x.com.samsung.da.thismonthlyConsumption' in rep)),
), ),
) )
@@ -415,12 +414,12 @@ SELF_CHECK = Capability(
icon='mdi:clipboard-check-outline', icon='mdi:clipboard-check-outline',
entity_category='diagnostic'), entity_category='diagnostic'),
# List of error codes from the last self-check; joined for display. # List of error codes from the last self-check; joined for display.
# Not every fridge reports the field, hence the exists_fn (no stub # Not every fridge reports the field, hence the exists_fn.
# carve-out -- see ENERGY_METER above).
SensorDesc(key='selfcheck_error', field='x.com.samsung.da.error', SensorDesc(key='selfcheck_error', field='x.com.samsung.da.error',
icon='mdi:alert-circle-outline', icon='mdi:alert-circle-outline',
entity_category='diagnostic', entity_category='diagnostic',
exists_fn=lambda rep, resources: 'x.com.samsung.da.error' in rep, exists_fn=lambda rep, resources: (
not rep or 'x.com.samsung.da.error' in rep),
value_fn=lambda v: (', '.join(v) if v else None) if isinstance(v, list) else v), value_fn=lambda v: (', '.join(v) if v else None) if isinstance(v, list) else v),
ButtonDesc(key='selfcheck_start', field='', payload='Start', ButtonDesc(key='selfcheck_start', field='', payload='Start',
icon='mdi:play-circle-outline', icon='mdi:play-circle-outline',
@@ -97,7 +97,7 @@ COOKTOP_MODE = Capability(
options, f'OperationState{slot}' options, f'OperationState{slot}'
), ),
exists_fn=lambda rep, resources, slot=slot: ( exists_fn=lambda rep, resources, slot=slot: (
_option_value( not rep or _option_value(
rep.get('x.com.samsung.da.options'), rep.get('x.com.samsung.da.options'),
f'OperationState{slot}', f'OperationState{slot}',
) is not None ) is not None
+6
View File
@@ -6,13 +6,19 @@
"diagnosis_status", "diagnosis_status",
"display_light", "display_light",
"dust", "dust",
"energy_kwh",
"energy_last_month_kwh",
"energy_saved_kwh",
"energy_this_month_kwh",
"fan_direction", "fan_direction",
"fan_speed_level", "fan_speed_level",
"filter_progress", "filter_progress",
"fine_dust", "fine_dust",
"odor", "odor",
"operating_mode", "operating_mode",
"power_energy_kwh",
"power_switch", "power_switch",
"power_watts",
"super_fine_dust" "super_fine_dust"
] ]
} }
+9 -13
View File
@@ -156,17 +156,13 @@ class TestEnergyMeter:
kwh = next(e for e in common.ENERGY_METER.entities if e.key == 'energy_kwh') kwh = next(e for e in common.ENERGY_METER.entities if e.key == 'energy_kwh')
assert kwh.exists_fn({'x.com.samsung.da.cumulativePower': '58900'}, {}) is True assert kwh.exists_fn({'x.com.samsung.da.cumulativePower': '58900'}, {}) is True
def test_both_entities_hidden_on_empty_rep(self): def test_both_entities_included_on_empty_stub(self):
"""Issue #78: a permanently-{} rep (a fridge that just doesn't report """An empty {} rep means the resource exists but data isn't fetched yet
energy data) must not spawn a phantom sensor stuck at "Unknown" (see entity._is_included) -- include both so sub-polls populate them."""
forever -- an empty {} rep and a not-yet-fetched stub are
indistinguishable from content alone, so this deliberately drops the
old stub carve-out (same tradeoff AI_ENERGY_LEVEL already makes,
see TestAiEnergyLevelStubDoesNotDecideThePlatform)."""
pw = next(e for e in common.ENERGY_METER.entities if e.key == 'power_watts') pw = next(e for e in common.ENERGY_METER.entities if e.key == 'power_watts')
kwh = next(e for e in common.ENERGY_METER.entities if e.key == 'energy_kwh') kwh = next(e for e in common.ENERGY_METER.entities if e.key == 'energy_kwh')
assert pw.exists_fn({}, {}) is False assert pw.exists_fn({}, {}) is True
assert kwh.exists_fn({}, {}) is False assert kwh.exists_fn({}, {}) is True
def test_power_watts_hidden_when_field_absent_in_populated_rep(self): def test_power_watts_hidden_when_field_absent_in_populated_rep(self):
"""A populated rep that lacks instantaneousPower must not spawn a """A populated rep that lacks instantaneousPower must not spawn a
@@ -323,11 +319,11 @@ class TestSelfCheckError:
desc = self._desc() desc = self._desc()
assert desc.exists_fn({'x.com.samsung.da.status': 'Ready'}, {}) is False assert desc.exists_fn({'x.com.samsung.da.status': 'Ready'}, {}) is False
def test_hidden_for_empty_rep(self): def test_exists_for_empty_stub_rep(self):
"""Issue #78: no stub carve-out -- see ENERGY_METER's """An empty {} rep is /device/0's not-yet-fetched-stub carve-out --
test_both_entities_hidden_on_empty_rep for why.""" must be included-for-now, same as ENERGY_METER's fields."""
desc = self._desc() desc = self._desc()
assert desc.exists_fn({}, {}) is False assert desc.exists_fn({}, {}) is True
def test_value_joins_list(self): def test_value_joins_list(self):
desc = self._desc() desc = self._desc()