walkingpad-controller 0.4.3__tar.gz → 0.4.4__tar.gz

{walkingpad_controller-0.4.3 → walkingpad_controller-0.4.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: walkingpad-controller
-Version: 0.4.3
+Version: 0.4.4
 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
@@ -39,7 +39,7 @@ Supports both **FTMS** (Fitness Machine Service) and legacy **WiLink** protocols
 - **Real-time status** — speed, distance, duration, calories, steps via BLE notifications
 - **Cold-start handling** — waits for belt to start moving and stabilize before sending speed commands, avoiding BLE disconnects on KingSmith devices
 - **Reconnect recovery** — pending target speed is automatically re-applied after BLE reconnection
-- **KingSmith extensions** — step counter via proprietary FTMS extension (bit 13), MC-21 vendor pre-amble for `SET_TARGET_SPEED`, supplement service detection (KS-HD-*)
+- **KingSmith vendor extensions** — step counter (FTMS bit 13), MC-21 vendor pre-amble, supplement service detection
 - **Firmware version** — exposed via `controller.firmware_version` (FTMS only)
 
 ## Installation
@@ -175,15 +175,13 @@ For advanced use, you can use the protocol controllers directly:
 KingSmith FTMS devices require a `START_OR_RESUME` command before the belt will accept speed commands. The library handles this automatically: it sends START, waits for the belt to report speed > 0 via treadmill data notifications, then waits an additional stabilization period before sending `SET_TARGET_SPEED`. This avoids the BLE disconnects that occur when speed commands are sent too early during motor startup.
 
 ### BLE Connection Drops
-KingSmith FTMS devices may occasionally drop the BLE connection after a cold start due to firmware limitations. The library stores the pending target speed and automatically re-applies it after reconnection (with appropriate stabilization delay). When used with the Home Assistant integration's "Stay Connected" mode, this provides seamless recovery.
+KingSmith FTMS devices may occasionally drop the connection after a cold start. The library stores the pending target speed and re-applies it after reconnection.
 
 ### Connection Exclusivity
-Only one BLE client can connect to the treadmill at a time. If Home Assistant holds the connection, the KS Fit app cannot connect, and vice versa.
+Only one BLE client can connect to the treadmill at a time — KS Fit and any client of this library are mutually exclusive.
 
 ### MC-21 Vendor Pre-amble
-The KingSmith MC-21 family (`KS-MC21-*`, `KS-SMC21C-*`, `ZP-ZEALR1-*`) refuses standard FTMS `REQUEST_CONTROL` and rejects `SET_TARGET_SPEED` unless a fixed 8-byte payload is first written to a vendor characteristic (`d18d2c10-…`) embedded in the FTMS service. This library detects the characteristic on connect and replays the pre-amble before each Control Point command — matching what the official KS Fit app does. On these devices, command success is signalled via Fitness Machine Status (`0x2ADA`) events rather than Control Point indications; the library races both signals and accepts whichever arrives first.
-
-For the full reverse-engineering analysis, see [docs/ftms-protocol-reference.md](docs/ftms-protocol-reference.md) and [docs/ks-fit-reverse-engineering.md](docs/ks-fit-reverse-engineering.md).
+The MC-21 family (`KS-MC21-*`, `KS-SMC21C-*`, `ZP-ZEALR1-*`) requires a vendor pre-amble before each FTMS Control Point command, and acks via Fitness Machine Status events rather than Control Point indications. The library detects this and handles it transparently. See [docs/ftms-protocol-reference.md](docs/ftms-protocol-reference.md) for the protocol details and [docs/ks-fit-reverse-engineering.md](docs/ks-fit-reverse-engineering.md) for the analysis.
 
 ## Requirements
 

{walkingpad_controller-0.4.3 → walkingpad_controller-0.4.4}/README.md

@@ -11,7 +11,7 @@ Supports both **FTMS** (Fitness Machine Service) and legacy **WiLink** protocols
 - **Real-time status** — speed, distance, duration, calories, steps via BLE notifications
 - **Cold-start handling** — waits for belt to start moving and stabilize before sending speed commands, avoiding BLE disconnects on KingSmith devices
 - **Reconnect recovery** — pending target speed is automatically re-applied after BLE reconnection
-- **KingSmith extensions** — step counter via proprietary FTMS extension (bit 13), MC-21 vendor pre-amble for `SET_TARGET_SPEED`, supplement service detection (KS-HD-*)
+- **KingSmith vendor extensions** — step counter (FTMS bit 13), MC-21 vendor pre-amble, supplement service detection
 - **Firmware version** — exposed via `controller.firmware_version` (FTMS only)
 
 ## Installation
@@ -147,15 +147,13 @@ For advanced use, you can use the protocol controllers directly:
 KingSmith FTMS devices require a `START_OR_RESUME` command before the belt will accept speed commands. The library handles this automatically: it sends START, waits for the belt to report speed > 0 via treadmill data notifications, then waits an additional stabilization period before sending `SET_TARGET_SPEED`. This avoids the BLE disconnects that occur when speed commands are sent too early during motor startup.
 
 ### BLE Connection Drops
-KingSmith FTMS devices may occasionally drop the BLE connection after a cold start due to firmware limitations. The library stores the pending target speed and automatically re-applies it after reconnection (with appropriate stabilization delay). When used with the Home Assistant integration's "Stay Connected" mode, this provides seamless recovery.
+KingSmith FTMS devices may occasionally drop the connection after a cold start. The library stores the pending target speed and re-applies it after reconnection.
 
 ### Connection Exclusivity
-Only one BLE client can connect to the treadmill at a time. If Home Assistant holds the connection, the KS Fit app cannot connect, and vice versa.
+Only one BLE client can connect to the treadmill at a time — KS Fit and any client of this library are mutually exclusive.
 
 ### MC-21 Vendor Pre-amble
-The KingSmith MC-21 family (`KS-MC21-*`, `KS-SMC21C-*`, `ZP-ZEALR1-*`) refuses standard FTMS `REQUEST_CONTROL` and rejects `SET_TARGET_SPEED` unless a fixed 8-byte payload is first written to a vendor characteristic (`d18d2c10-…`) embedded in the FTMS service. This library detects the characteristic on connect and replays the pre-amble before each Control Point command — matching what the official KS Fit app does. On these devices, command success is signalled via Fitness Machine Status (`0x2ADA`) events rather than Control Point indications; the library races both signals and accepts whichever arrives first.
-
-For the full reverse-engineering analysis, see [docs/ftms-protocol-reference.md](docs/ftms-protocol-reference.md) and [docs/ks-fit-reverse-engineering.md](docs/ks-fit-reverse-engineering.md).
+The MC-21 family (`KS-MC21-*`, `KS-SMC21C-*`, `ZP-ZEALR1-*`) requires a vendor pre-amble before each FTMS Control Point command, and acks via Fitness Machine Status events rather than Control Point indications. The library detects this and handles it transparently. See [docs/ftms-protocol-reference.md](docs/ftms-protocol-reference.md) for the protocol details and [docs/ks-fit-reverse-engineering.md](docs/ks-fit-reverse-engineering.md) for the analysis.
 
 ## Requirements
 

{walkingpad_controller-0.4.3 → walkingpad_controller-0.4.4}/pyproject.toml

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

{walkingpad_controller-0.4.3 → walkingpad_controller-0.4.4}/src/walkingpad_controller/const.py

@@ -101,6 +101,31 @@ class FTMSStopPauseParam(IntEnum):
     PAUSE = 0x02
 
 
+@unique
+class FTMSTrainingStatus(IntEnum):
+    """Training Status (0x2AD3) status codes — Bluetooth SIG FTMS standard.
+
+    KingSmith firmware emits a subset of these. The first byte of the 2AD3
+    payload is the flags byte; the second byte is one of these codes.
+    """
+
+    OTHER = 0x00
+    IDLE = 0x01
+    WARMING_UP = 0x02
+    LOW_INTENSITY_INTERVAL = 0x03
+    HIGH_INTENSITY_INTERVAL = 0x04
+    RECOVERY_INTERVAL = 0x05
+    ISO_METRIC = 0x06
+    HEART_RATE_CONTROL = 0x07
+    FITNESS_TEST = 0x08
+    SPEED_OUT_OF_CONTROL = 0x09
+    COOL_DOWN = 0x0A
+    WATT_CONTROL = 0x0B
+    MANUAL_MODE = 0x0C
+    PRE_WORKOUT = 0x0D
+    POST_WORKOUT = 0x0E
+
+
 @unique
 class FitnessMachineStatusOpcode(IntEnum):
     """Fitness Machine Status (0x2ADA) event opcodes.

{walkingpad_controller-0.4.3 → walkingpad_controller-0.4.4}/src/walkingpad_controller/ftms.py

@@ -466,6 +466,13 @@ class FTMSController:
             "FTMS: Machine status event: 0x%02x (data: %s)", opcode, data.hex()
         )
 
+        # Record the most-recent event so callers can read it via
+        # `controller.status.last_fm_event` and fan out to the status
+        # callbacks (e.g. HA coordinator).
+        self._status.last_fm_event = opcode
+        self._status.timestamp = time.time()
+        self._notify_status()
+
         # Wake any pending command waiter that's expecting this opcode.
         if (
             self._status_ack_expected_opcode is not None
@@ -515,6 +522,13 @@ class FTMSController:
             data.hex(),
         )
 
+        # Push the new status code into TreadmillStatus and fan out so
+        # downstream consumers (HA coordinator) see the change.
+        if self._status.training_status != status_code:
+            self._status.training_status = status_code
+            self._status.timestamp = time.time()
+            self._notify_status()
+
     def _on_control_point_response(self, sender: int, data: bytearray) -> None:
         """Handle FTMS Control Point (2AD9) indication responses.
 

{walkingpad_controller-0.4.3 → walkingpad_controller-0.4.4}/src/walkingpad_controller/models.py

@@ -40,6 +40,19 @@ class TreadmillStatus:
     heart_rate: int = 0
     """Heart rate in bpm (if available, 0 otherwise)."""
 
+    training_status: int = 0
+    """FTMS Training Status (0x2AD3) status code. Standard FTMS enum:
+    0=other, 1=idle, 2=warming up, 3=low-intensity interval,
+    4=high-intensity interval, 5=recovery, 6=isometric, 7=heart-rate control,
+    8=fitness test, 9=speed out of control, 10=cool down, 11=watt control,
+    12=manual mode, 13=pre-workout, 14=post-workout. Stays 0 if the device
+    doesn't expose 0x2AD3."""
+
+    last_fm_event: int = 0
+    """Opcode of the most recent Fitness Machine Status (0x2ADA) event.
+    See `FitnessMachineStatusOpcode` for known values; 0 means no event
+    has been received yet this session."""
+
     timestamp: float = field(default_factory=time.time)
     """Wall-clock time when this status was received."""