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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: walkingpad-controller
-Version: 0.4.2
+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
@@ -35,11 +35,12 @@ Supports both **FTMS** (Fitness Machine Service) and legacy **WiLink** protocols
 ## Features
 
 - **Unified API** — single `WalkingPadController` class for all device types
-- **Auto protocol detection** — FTMS for newer KS-HD-* devices, WiLink for older models
+- **Auto protocol detection** — FTMS for newer KS-HD-* / KS-MC21-* / KS-SMC21C-* / ZP-ZEALR1-* devices, WiLink for older models
 - **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)
+- **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
 
@@ -120,6 +121,7 @@ The main entry point. Auto-detects protocol and delegates to the appropriate bac
 | `status` | Current `TreadmillStatus` |
 | `min_speed` / `max_speed` | Speed range in km/h (read from device for FTMS) |
 | `speed_increment` | Speed step size in km/h |
+| `firmware_version` | Firmware version string (FTMS only; empty otherwise) |
 | `connect()` | Connect and auto-detect protocol |
 | `disconnect()` | Disconnect from the device |
 | `start()` | Start the belt (runs at minimum speed) |
@@ -158,8 +160,9 @@ For advanced use, you can use the protocol controllers directly:
 ## Supported Devices
 
 ### FTMS Protocol (tested)
-- KingSmith KS-Z1D (BLE name: `KS-HD-Z1D`)
-- Other KingSmith devices with BLE names starting with `KS-HD-`
+- KingSmith KS-Z1D (BLE name: `KS-HD-Z1D`) — confirmed working
+- KingSmith MC-21 (BLE names: `KS-MC21-*`, `KS-SMC21C-*`, `ZP-ZEALR1-*`) — confirmed working as of v0.4.1, requires the vendor pre-amble described below
+- Other KingSmith devices with BLE names starting with `KS-HD-` are expected to work via the same FTMS / supplement-service code path
 
 ### WiLink Protocol (via ph4-walkingpad)
 - WalkingPad A1, A1 Pro
@@ -172,10 +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 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.2 → walkingpad_controller-0.4.4}/README.md

@@ -7,11 +7,12 @@ Supports both **FTMS** (Fitness Machine Service) and legacy **WiLink** protocols
 ## Features
 
 - **Unified API** — single `WalkingPadController` class for all device types
-- **Auto protocol detection** — FTMS for newer KS-HD-* devices, WiLink for older models
+- **Auto protocol detection** — FTMS for newer KS-HD-* / KS-MC21-* / KS-SMC21C-* / ZP-ZEALR1-* devices, WiLink for older models
 - **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)
+- **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
 
@@ -92,6 +93,7 @@ The main entry point. Auto-detects protocol and delegates to the appropriate bac
 | `status` | Current `TreadmillStatus` |
 | `min_speed` / `max_speed` | Speed range in km/h (read from device for FTMS) |
 | `speed_increment` | Speed step size in km/h |
+| `firmware_version` | Firmware version string (FTMS only; empty otherwise) |
 | `connect()` | Connect and auto-detect protocol |
 | `disconnect()` | Disconnect from the device |
 | `start()` | Start the belt (runs at minimum speed) |
@@ -130,8 +132,9 @@ For advanced use, you can use the protocol controllers directly:
 ## Supported Devices
 
 ### FTMS Protocol (tested)
-- KingSmith KS-Z1D (BLE name: `KS-HD-Z1D`)
-- Other KingSmith devices with BLE names starting with `KS-HD-`
+- KingSmith KS-Z1D (BLE name: `KS-HD-Z1D`) — confirmed working
+- KingSmith MC-21 (BLE names: `KS-MC21-*`, `KS-SMC21C-*`, `ZP-ZEALR1-*`) — confirmed working as of v0.4.1, requires the vendor pre-amble described below
+- Other KingSmith devices with BLE names starting with `KS-HD-` are expected to work via the same FTMS / supplement-service code path
 
 ### WiLink Protocol (via ph4-walkingpad)
 - WalkingPad A1, A1 Pro
@@ -144,10 +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 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