v0.4.3

Improvements from a deep reverse-engineering pass on KS Fit

This release applies findings from decompiling the KingSmith KS Fit app (Flutter/Dart AOT, via blutter). Full analysis lives in docs/ftms-protocol-reference.md and docs/ks-fit-reverse-engineering.md.

Connection setup

• Added KS-MC21-, KS-SMC21C-, ZP-ZEALR1- to the FTMS name allowlist — the MC-21 family is now detected eagerly without a service-UUID probe.
• Stagger CCCD subscriptions with 100/200/300 ms delays — the literal Duration constants used by KS Fit. KingSmith firmware silently drops CCCD writes that arrive in close succession.
• Subscribe to Training Status (0x2AD3); KS Fit subscribes to it and we didn't.

Command acknowledgement

• On the vendor pre-amble path (MC-21), most Control Point opcodes are acknowledged via a Fitness Machine Status (0x2ADA) event rather than a CP indication. _write_control_point now races the indication against the matching status event, returning success on whichever arrives first. Falls back to silent-accept on timeout (existing v0.4.1 behavior).
• _on_machine_status now handles 0x05 (Target Speed Changed) and 0x06 (Target Inclination Changed). Adds FitnessMachineStatusOpcode enum.

Capabilities & metadata

• Read Software Revision String (0x2A28) during connect; expose as FTMSController.firmware_version and WalkingPadController.firmware_version.
• Add KingSmithMode / KingSmithStatus / KingSmithTreadmillStatus enums decoded from KS Fit's AOT snapshot, for callers that want named values instead of raw integers.

Tests

• Fix tests/test_real_device.py to clear the disconnect latch after a successful connect() (BleakClient retries during connect() were leaking the callback, leading to spurious "TEST FAILED" later).

Verified

End-to-end against KS-HD-Z1D: scan → connect → start → set 2 km/h → observe 20s → stop → disconnect, with no regressions on the standard FTMS indication path. Firmware version V0.0.6 read successfully.

v0.4.2

Fixed

• WalkingPadController.connected now defers to the active backend so it reflects the real BLE link state, not a cached bool that drifted when the firmware unilaterally dropped the connection.
• FTMSController.connect() now raises BleakError when the link drops mid-setup (e.g. shortly after a previous abrupt disconnect — Bleak/BlueZ accepts the connect, but the device closes the link before service discovery completes). Previously it silently announced "Connected" and every subsequent command failed with no clear signal.
• FTMSController.start() distinguishes between the device rejecting START_OR_RESUME because the belt is already running (success) and the write itself failing because the connection was lost (real failure). Previously both were treated as "belt already running", masking real disconnects.

Changed

• Connect retries bumped 3 → 5 with 3s gap (was 2s), to ride out the post-disconnect window where Bleak/BlueZ briefly accepts a connect() against a device that's not actually ready to talk.

These changes don't introduce new device support; they make existing failures visible so callers (e.g. the HA integration) can react appropriately instead of seeing phantom "connected" state.

v0.4.1

KingSmith MC-21 support (issue #1)

The MC-21 firmware refuses FTMS REQUEST_CONTROL and rejects SET_TARGET_SPEED unless a fixed 8-byte vendor pre-amble is first written to characteristic d18d2c10-c44c-11e8-a355-529269fb1459 (handle 0x0028, embedded inside the FTMS service). KS Fit replays this pre-amble before every Control Point write — we now mirror that.

Changes

• Detect the vendor pre-amble characteristic during service discovery; gate behavior on DeviceCapabilities.has_vendor_preamble.
• When set, write the magic payload before each Control Point command and treat the indication-timeout as success (MC-21 silently accepts commands instead of indicating).
• Tolerate REQUEST_CONTROL rejection: _has_control is set regardless of the response, so subsequent commands don't keep retrying a call we know will be refused.
• Non-MC-21 devices (no vendor characteristic) take the existing path unchanged.

See docs/issue-1-mc21-investigation.md for the full snoop and APK analysis. Closes #1.

v0.4.0

Initial public release of walkingpad-controller.

Unified Python controller for KingSmith WalkingPad treadmills supporting both FTMS BLE and legacy WiLink protocols via a single API.

Features

• FTMS BLE protocol via bleak — works with modern KingSmith devices (tested on KS-Z1D)
• Legacy WiLink protocol via optional ph4-walkingpad dependency
• Automatic protocol detection
• Cold-start handling — reliable belt startup for FTMS devices
• Reconnect recovery on transient BLE disconnects