Skip to content

Commit 3aa9657

Browse files
author
NOisi-X
committed
docs(zeo): clarify start/_force_load/query_values docstrings
1 parent 49901eb commit 3aa9657

1 file changed

Lines changed: 21 additions & 6 deletions

File tree

‎roborock/devices/traits/a01/__init__.py‎

Lines changed: 21 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -380,8 +380,10 @@ async def start(self) -> None:
380380
Subscribes to the DPS MQTT topic, then performs a two-stage
381381
force-load: first the base DP list (including FEATURE_BITS),
382382
then a second query for the DPs gated behind each enabled feature.
383-
The device responds with a complete state dump;
384-
subsequent changes arrive via incremental MQTT push.
383+
Each ID_QUERY returns the state of the queried DPs only (the base DP
384+
list in stage one); feature-gated DPs are fetched separately in the
385+
second-stage ``_load_feature_dps``. Subsequent changes arrive via
386+
incremental MQTT push.
385387
"""
386388
await self._ensure_subscribed()
387389
await self._force_load()
@@ -400,10 +402,13 @@ async def _ensure_subscribed(self) -> None:
400402
self._dps_unsub = await self._channel.subscribe(self._on_dps_message)
401403

402404
async def _force_load(self) -> None:
403-
"""Send ID_QUERY with the base DP list to trigger a full state push.
405+
"""Send ID_QUERY with the base DP list to fetch the base state.
404406
405-
For devices known to lack FEATURE_BITS, the DP is excluded
406-
from the query list and ``_feature_bits`` stays at 0.
407+
The device replies with the state of the *queried* DPs only — it is
408+
not a full dump — so feature-gated DPs are fetched separately by
409+
:meth:`_load_feature_dps`. For devices known to lack FEATURE_BITS,
410+
the DP is excluded from the query list and ``_feature_bits`` stays at
411+
0.
407412
"""
408413
dp_list = build_force_load_dp_list(self._model)
409414
result = await self.query_values(dp_list)
@@ -429,6 +434,9 @@ async def _load_feature_dps(self) -> None:
429434
if not feature_dps:
430435
return
431436
try:
437+
# Pre-warm the DPS cache: the converted return value is unused,
438+
# but query_values() backfills the raw values into _dps_cache,
439+
# which the lazily-built traits read on first access.
432440
await self.query_values(feature_dps)
433441
except RoborockException as exc:
434442
_LOGGER.warning("Feature DPS load failed (non-fatal): %s", exc)
@@ -447,7 +455,14 @@ def _on_dps_message(self, message: RoborockMessage) -> None:
447455
self._notify_update()
448456

449457
async def query_values(self, protocols: list[RoborockZeoProtocol]) -> dict[RoborockZeoProtocol, Any]:
450-
"""Query the device for the values of the given protocols."""
458+
"""Query the device for the values of the given protocols.
459+
460+
Side effect: raw responses are written into ``_dps_cache`` so that
461+
lazily-built traits can backfill state on first access. The return
462+
value is the converted form; both are provided because some callers
463+
want the converted values (e.g. :meth:`get_custom_mode`) while the
464+
cache holds the raw values the traits expect.
465+
"""
451466
response = await send_decoded_command(
452467
self._channel,
453468
{RoborockZeoProtocol.ID_QUERY: protocols},

0 commit comments

Comments
 (0)