walkingpad-controller 0.4.0__tar.gz → 0.4.2__tar.gz

{walkingpad_controller-0.4.0 → walkingpad_controller-0.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: walkingpad-controller
-Version: 0.4.0
+Version: 0.4.2
 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.4.0 → walkingpad_controller-0.4.2}/pyproject.toml

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

{walkingpad_controller-0.4.0 → walkingpad_controller-0.4.2}/src/walkingpad_controller/const.py

@@ -22,6 +22,13 @@ SUPPLEMENT_SERVICE_UUID = "24e2521c-f63b-48ed-85be-c5330a00fdf7"
 SUPPLEMENT_NOTIFY_UUID = "24e2521c-f63b-48ed-85be-c5330b00fdf7"
 SUPPLEMENT_WRITE_UUID = "24e2521c-f63b-48ed-85be-c5330d00fdf7"
 
+# KingSmith MC-21 vendor pre-amble. KS Fit writes a fixed 8-byte payload to
+# this characteristic (located inside the FTMS service) before every Control
+# Point command. Without it, MC-21 firmware rejects SET_TARGET_SPEED with
+# CONTROL_NOT_PERMITTED. See issue #1.
+KINGSMITH_VENDOR_PREAMBLE_UUID = "d18d2c10-c44c-11e8-a355-529269fb1459"
+KINGSMITH_VENDOR_PREAMBLE_PAYLOAD = bytes.fromhex("01000d00060b0f0d")
+
 # Legacy WiLink Service (for older devices)
 WILINK_SERVICE_UUID = "0000fe00-0000-1000-8000-00805f9b34fb"
 
@@ -125,6 +132,11 @@ class TreadmillDataFlags:
 # These devices have service 0x1826 but NOT 0xFE00.
 FTMS_NAME_PREFIXES = ("KS-HD-",)
 
-# Default connection parameters
-MAX_CONNECT_RETRIES = 3
-RETRY_DELAY_SECONDS = 2.0
+# Default connection parameters.
+# KingSmith FTMS firmware can be left in a bad state for several seconds
+# after a previous abrupt disconnect — Bleak/BlueZ then accepts the next
+# connect() call but the device closes the link before service discovery
+# completes. A handful of retries with a few seconds between them rides
+# this out reliably.
+MAX_CONNECT_RETRIES = 5
+RETRY_DELAY_SECONDS = 3.0

{walkingpad_controller-0.4.0 → walkingpad_controller-0.4.2}/src/walkingpad_controller/controller.py

@@ -102,7 +102,16 @@ class WalkingPadController:
 
     @property
     def connected(self) -> bool:
-        """Whether the device is currently connected."""
+        """Whether the device is currently connected.
+
+        Defers to the active backend so the result reflects the live BLE
+        state, not just a cached bool that can drift if the firmware
+        unilaterally drops the link before the disconnect callback fires.
+        """
+        if self._ftms is not None:
+            return self._ftms.connected
+        if self._wilink is not None:
+            return self._wilink.connected
         return self._connected
 
     @property

{walkingpad_controller-0.4.0 → walkingpad_controller-0.4.2}/src/walkingpad_controller/ftms.py

@@ -36,6 +36,8 @@ from .const import (
     FITNESS_MACHINE_STATUS_UUID,
     FTMS_CONTROL_POINT_UUID,
     FTMS_FEATURE_UUID,
+    KINGSMITH_VENDOR_PREAMBLE_PAYLOAD,
+    KINGSMITH_VENDOR_PREAMBLE_UUID,
     SUPPLEMENT_SERVICE_UUID,
     SUPPORTED_SPEED_RANGE_UUID,
     TREADMILL_DATA_UUID,
@@ -126,6 +128,12 @@ class FTMSController:
 
         Args:
             ble_device: The BLE device to connect to.
+
+        Raises:
+            BleakError: If the underlying BLE link drops before setup
+                finishes (e.g. shortly after a previous disconnect, the
+                firmware sometimes accepts the connection and then closes
+                it again before service discovery completes).
         """
         _LOGGER.info("FTMS: Connecting to %s", ble_device.address)
 
@@ -149,6 +157,18 @@ class FTMSController:
         # Request control
         await self._request_control()
 
+        # Sanity check: if the link dropped at any point during setup
+        # (Bleak's is_connected goes False, our _connected bit is flipped
+        # by the disconnect callback), surface that as a failed connect
+        # rather than silently claiming success — otherwise callers see
+        # `connected == False` immediately after `connect()` "succeeds"
+        # and have no clean signal that they should retry.
+        if not self.connected:
+            raise BleakError(
+                "FTMS: BLE link dropped during connection setup; treating "
+                "as a failed connect."
+            )
+
     async def disconnect(self) -> None:
         """Disconnect from the device."""
         if self._client and self._client.is_connected:
@@ -196,6 +216,20 @@ class FTMSController:
         except Exception:
             self._capabilities.has_supplement = False
 
+        # Check for the KingSmith MC-21 vendor pre-amble characteristic.
+        # If present, we'll write the magic payload before every Control
+        # Point command — that's what KS Fit does, and without it the
+        # firmware refuses SET_TARGET_SPEED.
+        try:
+            char = self._client.services.get_characteristic(
+                KINGSMITH_VENDOR_PREAMBLE_UUID
+            )
+            if char is not None:
+                self._capabilities.has_vendor_preamble = True
+                _LOGGER.info("FTMS: KingSmith vendor pre-amble characteristic detected")
+        except Exception:
+            self._capabilities.has_vendor_preamble = False
+
     async def _read_capabilities(self) -> None:
         """Read device capabilities from FTMS characteristics."""
         if not self._client:
@@ -424,6 +458,16 @@ class FTMSController:
             _LOGGER.warning("FTMS: Not connected, cannot send command")
             return False
 
+        if self._capabilities.has_vendor_preamble:
+            try:
+                await self._client.write_gatt_char(
+                    KINGSMITH_VENDOR_PREAMBLE_UUID,
+                    KINGSMITH_VENDOR_PREAMBLE_PAYLOAD,
+                    response=True,
+                )
+            except BleakError as err:
+                _LOGGER.debug("FTMS: Vendor pre-amble write error: %s", err)
+
         command = bytes([opcode]) + params
         _LOGGER.debug("FTMS: Sending control point command: %s", command.hex())
 
@@ -437,10 +481,24 @@ class FTMSController:
             _LOGGER.warning("FTMS: Write error: %s", err)
             return False
 
-        # Wait for indication response
+        # Wait for indication response. On firmware that uses the vendor
+        # pre-amble (MC-21), the device silently accepts most commands
+        # without sending an indication — the snoop shows only the very
+        # first REQUEST_CONTROL gets one. Treat timeout as success in that
+        # case, with a shorter wait so we don't stall the caller.
+        effective_timeout = (
+            1.0 if self._capabilities.has_vendor_preamble else timeout
+        )
         try:
-            await asyncio.wait_for(self._cp_response_event.wait(), timeout)
+            await asyncio.wait_for(self._cp_response_event.wait(), effective_timeout)
         except asyncio.TimeoutError:
+            if self._capabilities.has_vendor_preamble:
+                _LOGGER.debug(
+                    "FTMS: No indication for opcode 0x%02x — assuming success "
+                    "(vendor pre-amble path)",
+                    opcode,
+                )
+                return True
             _LOGGER.warning(
                 "FTMS: Control point response timeout for opcode 0x%02x", opcode
             )
@@ -467,13 +525,25 @@ class FTMSController:
         return False
 
     async def _request_control(self) -> bool:
-        """Request control of the fitness machine."""
+        """Request control of the fitness machine.
+
+        Some KingSmith firmware (e.g. MC-21) rejects REQUEST_CONTROL with
+        OPERATION_FAILED / CONTROL_NOT_PERMITTED but still accepts the
+        commands that follow. KS Fit ignores the failure and proceeds; we
+        do the same — `_has_control` is set regardless of the response so
+        every subsequent command doesn't keep retrying a call we know will
+        fail. See issue #1.
+        """
         result = await self._write_control_point(FTMSOpcode.REQUEST_CONTROL)
+        self._has_control = True
         if result:
-            self._has_control = True
             _LOGGER.info("FTMS: Control acquired")
         else:
-            _LOGGER.warning("FTMS: Failed to acquire control")
+            _LOGGER.warning(
+                "FTMS: REQUEST_CONTROL was rejected — proceeding anyway "
+                "(some KingSmith firmware refuses this command but still "
+                "accepts START_OR_RESUME / STOP_OR_PAUSE)"
+            )
         return result
 
     async def start(self) -> bool:
@@ -491,17 +561,18 @@ class FTMSController:
         if not self._has_control:
             await self._request_control()
 
-        cold_start = await self._write_control_point(FTMSOpcode.START_OR_RESUME)
-        if cold_start:
-            _LOGGER.info("FTMS: START_OR_RESUME succeeded (cold start)")
-        else:
-            _LOGGER.debug("FTMS: START_OR_RESUME not needed (belt already running)")
+        if not self.connected:
+            _LOGGER.warning("FTMS: Not connected; cannot start")
+            return False
+
+        accepted = await self._write_control_point(FTMSOpcode.START_OR_RESUME)
 
         if not self.connected:
-            _LOGGER.warning("FTMS: Connection lost after START_OR_RESUME")
+            _LOGGER.warning("FTMS: Connection lost during START_OR_RESUME")
             return False
 
-        if cold_start:
+        if accepted:
+            _LOGGER.info("FTMS: START_OR_RESUME accepted (cold start)")
             belt_running = await self._wait_for_belt_moving(timeout=15.0)
             if not belt_running:
                 if not self.connected:
@@ -513,8 +584,26 @@ class FTMSController:
                 "FTMS: Cold start complete — belt running at %.1f km/h",
                 self._status.speed,
             )
+            return True
+
+        # The device rejected START_OR_RESUME (non-success indication).
+        # That can mean either (a) belt is already running, or (b) the
+        # device is in a state that doesn't accept start right now —
+        # e.g. just transitioned through stop and isn't fully settled.
+        # Disambiguate by looking at the live speed.
+        if self._status.speed > 0:
+            _LOGGER.info(
+                "FTMS: START_OR_RESUME rejected but belt is running at "
+                "%.1f km/h — treating as success",
+                self._status.speed,
+            )
+            return True
 
-        return True
+        _LOGGER.warning(
+            "FTMS: START_OR_RESUME rejected and belt is not moving "
+            "(device may need a moment after stop)"
+        )
+        return False
 
     async def _wait_for_belt_moving(self, timeout: float = 15.0) -> bool:
         """Wait for the belt to report speed > 0 after a cold start.

{walkingpad_controller-0.4.0 → walkingpad_controller-0.4.2}/src/walkingpad_controller/models.py

@@ -73,3 +73,6 @@ class DeviceCapabilities:
 
     has_supplement: bool = False
     """Whether the KingSmith supplement service is available."""
+
+    has_vendor_preamble: bool = False
+    """Whether the KingSmith MC-21 vendor pre-amble characteristic is present."""