walkingpad-controller 0.2.0__tar.gz → 0.3.0__tar.gz

{walkingpad_controller-0.2.0 → walkingpad_controller-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: walkingpad-controller
-Version: 0.2.0
+Version: 0.3.0
 Summary: Python library for controlling KingSmith WalkingPad treadmills over BLE (FTMS and legacy WiLink protocols)
 Project-URL: Homepage, https://github.com/mcdax/walkingpad-controller
 Project-URL: Repository, https://github.com/mcdax/walkingpad-controller

{walkingpad_controller-0.2.0 → walkingpad_controller-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "walkingpad-controller"
-version = "0.2.0"
+version = "0.3.0"
 description = "Python library for controlling KingSmith WalkingPad treadmills over BLE (FTMS and legacy WiLink protocols)"
 readme = "README.md"
 license = "MIT"

{walkingpad_controller-0.2.0 → walkingpad_controller-0.3.0}/src/walkingpad_controller/controller.py

@@ -13,8 +13,11 @@ Example usage:
     controller = WalkingPadController(ble_device=device)
     await controller.connect()
 
-    # Start at 3.0 km/h
-    await controller.start(target_speed=3.0)
+    # Start the belt (runs at minimum speed)
+    await controller.start()
+
+    # Set desired speed via the speed slider / set_speed()
+    await controller.set_speed(3.0)
 
     # Get status
     print(controller.status)
@@ -40,7 +43,6 @@ from .const import (
     MAX_CONNECT_RETRIES,
     RETRY_DELAY_SECONDS,
     WILINK_SERVICE_UUID,
-    BeltState,
     OperatingMode,
     ProtocolType,
 )
@@ -76,15 +78,6 @@ class WalkingPadController:
         self._status_callbacks: list[Callable[[TreadmillStatus], None]] = []
         self._disconnect_callbacks: list[Callable[[], None]] = []
 
-        # Pending target speed for FTMS cold-start recovery.
-        # When a cold START_OR_RESUME causes a BLE drop, we store the desired
-        # speed here so it can be re-sent after reconnection.
-        self._pending_target_speed: float | None = None
-        self._pending_speed_task_active: bool = False
-        # Suppresses Layer 2 pending speed during an active start() call,
-        # since ftms.start() already handles the speed command internally.
-        self._start_in_progress: bool = False
-
         # Eagerly detect protocol from BLE name
         name_protocol = self._detect_protocol_from_name()
         if name_protocol is not None:
@@ -172,73 +165,6 @@ class WalkingPadController:
             except Exception:
                 _LOGGER.exception("Error in status callback")
 
-        # FTMS cold-start recovery: if the belt is running at min speed
-        # but we have a pending target speed, re-send it after a delay.
-        # IMPORTANT: We must NOT send SET_TARGET_SPEED too early after a
-        # reconnect — the BLE connection is fragile during motor startup.
-        # Also suppress during an active start() call to avoid duplicate
-        # speed commands (ftms.start() already handles this internally).
-        if (
-            self._pending_target_speed is not None
-            and self._ftms
-            and self._ftms.connected
-            and not self._start_in_progress
-        ):
-            if status.speed > 0 and status.speed < self._pending_target_speed - 0.15:
-                # Only fire once — check if we already have a pending task
-                if not self._pending_speed_task_active:
-                    pending = self._pending_target_speed
-                    self._pending_target_speed = None
-                    _LOGGER.info(
-                        "Belt at %.1f km/h after reconnect, will apply "
-                        "pending target %.1f km/h after stabilization delay",
-                        status.speed,
-                        pending,
-                    )
-                    self._pending_speed_task_active = True
-                    asyncio.ensure_future(self._apply_pending_speed(pending))
-            elif abs(status.speed - self._pending_target_speed) <= 0.15:
-                _LOGGER.debug(
-                    "Pending target speed %.1f reached, clearing",
-                    self._pending_target_speed,
-                )
-                self._pending_target_speed = None
-
-    async def _apply_pending_speed(self, speed: float) -> None:
-        """Apply a pending target speed after reconnection.
-
-        Waits for the BLE connection and motor to stabilize before sending
-        SET_TARGET_SPEED. This prevents the disconnect that occurs when
-        speed commands are sent too early after a cold start.
-        """
-        stabilize_delay = 5.0
-        try:
-            _LOGGER.info(
-                "Waiting %.1fs for motor to stabilize before SET_TARGET_SPEED(%.1f)",
-                stabilize_delay,
-                speed,
-            )
-            await asyncio.sleep(stabilize_delay)
-
-            if self._ftms and self._ftms.connected:
-                _LOGGER.info("Re-sending SET_TARGET_SPEED(%.1f) after reconnect", speed)
-                result = await self._ftms.set_target_speed(speed)
-                if result:
-                    _LOGGER.info("SET_TARGET_SPEED(%.1f) applied successfully", speed)
-                else:
-                    _LOGGER.warning(
-                        "SET_TARGET_SPEED(%.1f) failed after reconnect", speed
-                    )
-            else:
-                _LOGGER.warning(
-                    "Connection lost during stabilization, cannot apply speed %.1f",
-                    speed,
-                )
-        except BleakError as err:
-            _LOGGER.warning("BLE error applying pending speed: %s", err)
-        finally:
-            self._pending_speed_task_active = False
-
     def _on_disconnect(self) -> None:
         """Internal handler for disconnect events from either backend."""
         _LOGGER.warning("Device disconnected")
@@ -379,49 +305,25 @@ class WalkingPadController:
 
     # --- Commands ---
 
-    async def start(self, target_speed: float | None = None) -> bool:
-        """Start the treadmill.
-
-        For FTMS devices, this uses START_OR_RESUME (cold start) followed by
-        SET_TARGET_SPEED with retry logic. For WiLink devices, this sends the
-        standard start command.
+    async def start(self) -> bool:
+        """Start the treadmill belt.
 
-        If the BLE connection drops during a cold start (common on KingSmith
-        FTMS devices), the target speed is stored as "pending" and will be
-        automatically re-applied after reconnection.
+        For FTMS devices, sends START_OR_RESUME and waits for the belt
+        to begin moving.  Does NOT send SET_TARGET_SPEED — the user
+        must set speed explicitly via set_speed() (e.g. the HA speed
+        slider).  Sending a speed command during motor spin-up crashes
+        the BLE connection on KingSmith firmware.
 
-        Args:
-            target_speed: Target speed in km/h. If None, uses min speed.
+        For WiLink devices, sends the standard start command.
 
         Returns:
             True if the belt is running. False if the connection was lost.
         """
         if self._ftms:
-            # Store pending speed BEFORE calling start (BLE may drop)
-            if target_speed is not None and target_speed > self._ftms.min_speed:
-                self._pending_target_speed = target_speed
-
-            # Suppress Layer 2 pending speed during start() to avoid duplicate
-            # SET_TARGET_SPEED commands — ftms.start() handles it internally.
-            self._start_in_progress = True
-            try:
-                result = await self._ftms.start(target_speed=target_speed)
-            finally:
-                self._start_in_progress = False
-
-            if result and self._ftms.connected:
-                if target_speed and abs(self._ftms.status.speed - target_speed) > 0.15:
-                    _LOGGER.info(
-                        "start() completed but speed is %.1f (target %.1f), keeping pending",
-                        self._ftms.status.speed,
-                        target_speed,
-                    )
-                else:
-                    self._pending_target_speed = None
-            return result
+            return await self._ftms.start()
 
         elif self._wilink:
-            return await self._wilink.start(target_speed=target_speed)
+            return await self._wilink.start()
 
         _LOGGER.warning("No protocol backend available")
         return False
@@ -432,8 +334,6 @@ class WalkingPadController:
         Returns:
             True if the command was sent successfully.
         """
-        self._pending_target_speed = None
-
         if self._ftms:
             return await self._ftms.stop()
         elif self._wilink:
@@ -445,7 +345,9 @@ class WalkingPadController:
     async def set_speed(self, speed_kmh: float) -> bool:
         """Set the treadmill speed.
 
-        If the belt is stopped, this will start it first (FTMS only).
+        If the belt is already running, sends SET_TARGET_SPEED directly.
+        If the belt is stopped, starts it first (the belt will run at
+        minimum speed until the user adjusts the speed slider).
 
         Args:
             speed_kmh: Target speed in km/h.
@@ -455,19 +357,20 @@ class WalkingPadController:
         """
         if self._ftms:
             if self._ftms.status.speed > 0:
+                # Belt already running — safe to send speed directly
                 return await self._ftms.set_target_speed(speed_kmh)
             else:
-                # Belt is stopped, need full start sequence
-                if speed_kmh > self._ftms.min_speed:
-                    self._pending_target_speed = speed_kmh
-                self._start_in_progress = True
-                try:
-                    result = await self._ftms.start(target_speed=speed_kmh)
-                finally:
-                    self._start_in_progress = False
-                if result and self._ftms.connected:
-                    self._pending_target_speed = None
-                return result
+                # Belt is stopped — start it first.  The user will need
+                # to set the desired speed once the belt is running.
+                _LOGGER.info(
+                    "Belt is stopped — starting first, then setting speed %.1f",
+                    speed_kmh,
+                )
+                started = await self._ftms.start()
+                if not started:
+                    return False
+                # Belt is now running; send the speed command
+                return await self._ftms.set_target_speed(speed_kmh)
 
         elif self._wilink:
             return await self._wilink.set_target_speed(speed_kmh)

{walkingpad_controller-0.2.0 → walkingpad_controller-0.3.0}/src/walkingpad_controller/ftms.py

@@ -476,25 +476,18 @@ class FTMSController:
             _LOGGER.warning("FTMS: Failed to acquire control")
         return result
 
-    async def start(self, target_speed: float | None = None) -> bool:
-        """Start or resume the treadmill.
+    async def start(self) -> bool:
+        """Start or resume the treadmill belt.
 
-        On KingSmith devices, a cold START_OR_RESUME is required for a stopped
-        belt. SET_TARGET_SPEED alone gets ACKed but ignored.
-
-        IMPORTANT: After a cold start, sending SET_TARGET_SPEED too early
-        destabilizes the BLE connection and causes a disconnect. This method
-        waits for the belt to actually start moving (speed > 0 reported via
-        treadmill data notifications) before sending any speed command.
-
-        Args:
-            target_speed: Target speed in km/h. If None, uses min speed.
+        Sends START_OR_RESUME and, on a cold start, waits for the belt to
+        report speed > 0.  Does NOT send SET_TARGET_SPEED — the user sets
+        the speed explicitly via set_target_speed() (e.g. the HA speed
+        slider).  Sending a speed command during motor spin-up crashes the
+        BLE connection on KingSmith firmware.
 
         Returns:
             True if the belt is running. False if the connection was lost.
         """
-        speed = target_speed if target_speed is not None else self.min_speed
-
         if not self._has_control:
             await self._request_control()
 
@@ -502,15 +495,12 @@ class FTMSController:
         if cold_start:
             _LOGGER.info("FTMS: START_OR_RESUME succeeded (cold start)")
         else:
-            _LOGGER.debug("FTMS: START_OR_RESUME failed (expected if already started)")
+            _LOGGER.debug("FTMS: START_OR_RESUME not needed (belt already running)")
 
         if not self.connected:
             _LOGGER.warning("FTMS: Connection lost after START_OR_RESUME")
             return False
 
-        # After a cold start, wait for the belt to actually start moving before
-        # sending SET_TARGET_SPEED. Sending speed commands during motor startup
-        # destabilizes the BLE connection on KingSmith devices (tested on KS-Z1D).
         if cold_start:
             belt_running = await self._wait_for_belt_moving(timeout=15.0)
             if not belt_running:
@@ -519,76 +509,24 @@ class FTMSController:
                     return False
                 _LOGGER.warning("FTMS: Belt did not start moving within timeout")
                 return False
-
-        if not self.connected:
-            _LOGGER.warning("FTMS: Connection lost before SET_TARGET_SPEED")
-            return False
-
-        # Now it's safe to set the target speed. After a cold start the device
-        # may still need a moment to accept speed changes, so retry if needed.
-        max_attempts = 3 if cold_start else 1
-        for attempt in range(max_attempts):
-            if attempt > 0:
-                await asyncio.sleep(2.0)
-                if not self.connected:
-                    return False
-
-            result = await self.set_target_speed(speed)
-            if not result:
-                _LOGGER.warning(
-                    "FTMS: SET_TARGET_SPEED(%.1f) failed on attempt %d/%d",
-                    speed,
-                    attempt + 1,
-                    max_attempts,
-                )
-                continue
-
-            # For min speed, no need to verify (belt already runs at min)
-            if speed <= self.min_speed + 0.05:
-                return True
-
-            # Verify the speed actually changed
-            verified = await self._verify_speed(speed, timeout=5.0)
-            if verified:
-                _LOGGER.info(
-                    "FTMS: Speed verified at %.1f km/h (attempt %d/%d)",
-                    speed,
-                    attempt + 1,
-                    max_attempts,
-                )
-                return True
-
             _LOGGER.info(
-                "FTMS: Speed still %.2f after attempt %d/%d (target %.1f)",
+                "FTMS: Cold start complete — belt running at %.1f km/h",
                 self._status.speed,
-                attempt + 1,
-                max_attempts,
-                speed,
             )
 
-        _LOGGER.warning(
-            "FTMS: Could not reach %.1f km/h after %d attempts (current: %.2f)",
-            speed,
-            max_attempts,
-            self._status.speed,
-        )
-        return True  # Belt IS running, just not at desired speed
+        return True
 
-    async def _wait_for_belt_moving(
-        self, timeout: float = 15.0, stabilize: float = 5.0
-    ) -> bool:
-        """Wait for the belt to start and stabilize before sending speed commands.
+    async def _wait_for_belt_moving(self, timeout: float = 15.0) -> bool:
+        """Wait for the belt to report speed > 0 after a cold start.
 
-        After a cold start on KingSmith devices, the BLE connection is fragile
-        while the motor is spinning up. This waits for two conditions:
-        1. Belt reports speed > 0 via treadmill data notifications.
-        2. An additional stabilization period after speed is first reported.
+        Polls treadmill-data notifications until the belt is physically
+        moving.  No stabilisation delay is applied here — we deliberately
+        avoid sending any speed command while the connection is fragile.
 
         Args:
             timeout: Maximum time to wait for speed > 0 (seconds).
-            stabilize: Additional delay after speed detected (seconds).
 
-        Returns True if the belt started and stabilized, False on timeout/disconnect.
+        Returns True if the belt is moving, False on timeout/disconnect.
         """
         _LOGGER.debug(
             "FTMS: Waiting for belt to start moving (timeout=%.0fs)...", timeout
@@ -600,38 +538,14 @@ class FTMSController:
             if self._status.speed > 0:
                 wait_elapsed = timeout - (deadline - time.time())
                 _LOGGER.info(
-                    "FTMS: Belt moving at %.1f km/h (waited %.1fs), "
-                    "stabilizing %.1fs before speed command...",
+                    "FTMS: Belt moving at %.1f km/h (waited %.1fs)",
                     self._status.speed,
                     wait_elapsed,
-                    stabilize,
-                )
-                # Additional stabilization delay — the motor/firmware needs
-                # time to settle before it can handle SET_TARGET_SPEED
-                # without dropping the BLE connection.
-                await asyncio.sleep(stabilize)
-                if not self.connected:
-                    return False
-                _LOGGER.info(
-                    "FTMS: Stabilization complete (belt at %.1f km/h)",
-                    self._status.speed,
                 )
                 return True
             await asyncio.sleep(0.5)
         return False
 
-    async def _verify_speed(self, target: float, timeout: float = 3.0) -> bool:
-        """Wait for the reported speed to match the target."""
-        tolerance = max(self._capabilities.speed_range.increment, 0.15)
-        deadline = time.time() + timeout
-        while time.time() < deadline:
-            if not self.connected:
-                return False
-            if abs(self._status.speed - target) <= tolerance:
-                return True
-            await asyncio.sleep(0.5)
-        return False
-
     async def stop(self) -> bool:
         """Stop the treadmill."""
         if not self._has_control:

{walkingpad_controller-0.2.0 → walkingpad_controller-0.3.0}/tests/test_real_device.py

@@ -1,6 +1,8 @@
 """Test walkingpad-controller library against real KS-HD-Z1D device.
 
-Tests: scan -> connect -> read status -> start at 2.0 km/h -> observe -> stop -> disconnect
+Tests the cold-start flow WITHOUT automatic SET_TARGET_SPEED:
+  scan -> connect -> start (no speed) -> observe belt at min speed ->
+  set_speed (user action) -> observe -> stop -> disconnect
 """
 
 import asyncio
@@ -18,8 +20,8 @@ logging.basicConfig(
 _LOGGER = logging.getLogger("test")
 
 DEVICE_NAME = "KS-HD-Z1D"
-TARGET_SPEED = 2.0  # km/h
-RUN_DURATION = 25  # seconds
+TARGET_SPEED = 2.0  # km/h — sent AFTER belt is running (simulates user slider)
+RUN_DURATION = 20  # seconds to observe after setting speed
 
 
 async def main():
@@ -90,27 +92,48 @@ async def main():
         s.steps,
     )
 
-    # --- Step 5: Start at target speed ---
-    _LOGGER.info("Starting at %.1f km/h...", TARGET_SPEED)
-    result = await controller.start(target_speed=TARGET_SPEED)
+    # --- Step 5: Start (no target speed — belt runs at minimum) ---
+    _LOGGER.info("Starting belt (no target speed)...")
+    result = await controller.start()
     _LOGGER.info("start() returned: %s", result)
 
     if not controller.connected:
-        _LOGGER.warning(
-            "Connection lost during start! Waiting 10s for reconnect possibility..."
-        )
-        await asyncio.sleep(10)
-        if not controller.connected:
-            _LOGGER.error("Still disconnected. Test cannot continue.")
-            return
+        _LOGGER.error("Connection lost during start! TEST FAILED.")
+        return
+
+    s = controller.status
+    _LOGGER.info(
+        "After start: speed=%.2f km/h (should be ~%.1f min speed)",
+        s.speed,
+        controller.min_speed,
+    )
+
+    # --- Step 6: Wait a moment, then set speed (simulates user slider) ---
+    _LOGGER.info(
+        "Belt running at min speed. Waiting 5s before setting speed to %.1f...",
+        TARGET_SPEED,
+    )
+    await asyncio.sleep(5)
+
+    if not controller.connected:
+        _LOGGER.error("Connection lost while waiting! TEST FAILED.")
+        return
 
-    # --- Step 6: Run and observe ---
-    _LOGGER.info("Belt should be running. Observing for %ds...", RUN_DURATION)
+    _LOGGER.info("Setting speed to %.1f km/h (simulates user slider)...", TARGET_SPEED)
+    result = await controller.set_speed(TARGET_SPEED)
+    _LOGGER.info("set_speed() returned: %s", result)
+
+    if not controller.connected:
+        _LOGGER.error("Connection lost after set_speed! TEST FAILED.")
+        return
+
+    # --- Step 7: Run and observe ---
+    _LOGGER.info("Observing for %ds...", RUN_DURATION)
     start_time = time.time()
     while time.time() - start_time < RUN_DURATION:
         if disconnected.is_set():
-            _LOGGER.warning("Disconnected during run!")
-            break
+            _LOGGER.error("Disconnected during run! TEST FAILED.")
+            return
         await asyncio.sleep(1)
 
     s = controller.status
@@ -123,7 +146,7 @@ async def main():
         s.steps,
     )
 
-    # --- Step 7: Stop ---
+    # --- Step 8: Stop ---
     if controller.connected:
         _LOGGER.info("Stopping belt...")
         result = await controller.stop()
@@ -132,11 +155,11 @@ async def main():
         s = controller.status
         _LOGGER.info("After stop: speed=%.2f, belt=%s", s.speed, s.belt_state)
 
-    # --- Step 8: Disconnect ---
+    # --- Step 9: Disconnect ---
     _LOGGER.info("Disconnecting...")
     await controller.disconnect()
     _LOGGER.info("Disconnected. Total status updates received: %d", status_count)
-    _LOGGER.info("TEST PASSED!")
+    _LOGGER.info("TEST PASSED — no BLE disconnect during cold start!")
 
 
 if __name__ == "__main__":