From 27480dcb1df110f433cf33d08874d09352bc743a Mon Sep 17 00:00:00 2001
From: Marc Billow <mbillow@me.com>
Date: Sat, 4 Jul 2026 17:10:56 -0500
Subject: [PATCH] fix: pace inter-tier polling; fix stale package-rename
 references in docs

---
 mqtt_demo/logger.py           | 4 ++--
 mqtt_demo/samples/__init__.py | 8 ++++----
 ocf/poll_scheduler.py         | 8 +++++---
 3 files changed, 11 insertions(+), 9 deletions(-)

diff --git a/mqtt_demo/logger.py b/mqtt_demo/logger.py
index 55d6439..f287c9c 100644
--- a/mqtt_demo/logger.py
+++ b/mqtt_demo/logger.py
@@ -1,7 +1,7 @@
 """Stdout logging — works correctly under Docker's PYTHONUNBUFFERED=1.
 
 Two logger families share the root handler:
-  * `samsung_appliance` (and its children) for module-level lines —
+  * `mqtt_demo` (and its children) for module-level lines —
     DTLS warnings, generic startup chatter, MQTT plumbing.
   * `<class>.<serial>` for per-appliance bridge lines — e.g.
     `dryer.<serial>`. Each PushBridge gets its own such logger
@@ -58,7 +58,7 @@ _handler.setFormatter(_LevelColourFormatter(
 
 logging.basicConfig(level=logging.INFO, handlers=[_handler], force=True)
 
-logger = logging.getLogger("samsung_appliance")
+logger = logging.getLogger("mqtt_demo")
 
 
 def bridge_logger(klass: str, serial: str | None = None) -> logging.Logger:
diff --git a/mqtt_demo/samples/__init__.py b/mqtt_demo/samples/__init__.py
index 8cfbcc8..ec8c8ee 100644
--- a/mqtt_demo/samples/__init__.py
+++ b/mqtt_demo/samples/__init__.py
@@ -1,13 +1,13 @@
 """Appliance descriptors registry.
 
 Adding a new appliance class:
-  1. Write `appliances/<class>.py` with an ApplianceDescriptor named
-     after the class (uppercase, e.g. OVEN).
+  1. Write `mqtt_demo/samples/<class>.py` with an ApplianceDescriptor
+     named after the class (uppercase, e.g. OVEN).
   2. Add it to DESCRIPTORS below.
   3. Set DEVICE_CLASS=<class> in the per-device .env.
 
-main.py imports get_descriptor(name) to look up the descriptor at
-startup; the bridge itself stays class-agnostic.
+mqtt_demo/__main__.py imports get_descriptor(name) to look up the
+descriptor at startup; the bridge itself stays class-agnostic.
 """
 from ..descriptor import ApplianceDescriptor
 from .dryer import DRYER
diff --git a/ocf/poll_scheduler.py b/ocf/poll_scheduler.py
index 0ba2773..6634957 100644
--- a/ocf/poll_scheduler.py
+++ b/ocf/poll_scheduler.py
@@ -3,8 +3,8 @@
 Tiers are descriptor-declared (hot/warm/cold + sweep). Per tick:
 each tier whose deadline has passed polls all its paths sequentially
 on the shared session, writing into the StateCache. The sweep tier
-issues one Block2 GET of /device/0 and uses index_links to fan its
-result into many href reps.
+issues one Block2 GET of /device/0 and uses
+StateCache.index_device_tree to fan its result into many href reps.
 
 Adaptive cadence: when descriptor.is_active(cache.links) returns True
 and tier.active_interval_s is set, that tier uses the tighter cadence.
@@ -218,11 +218,13 @@ class PollScheduler:
     def _do_tier(self, tier: PollTier) -> None:
         timeout = self._tier_timeout(tier)
         cooldown = self._cooldown_for(tier)
-        for path in tier.paths:
+        for i, path in enumerate(tier.paths):
             href = '/' + '/'.join(path)
             with self._defer_lock:
                 if self._defer_until.get(href, 0) > time.monotonic():
                     continue
+            if i > 0:
+                self.session.pace()
             self._poll_count += 1
             t0 = time.monotonic()
             try: