walkingpad-controller 0.4.11__tar.gz → 0.5.1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (45) hide show
  1. {walkingpad_controller-0.4.11 → walkingpad_controller-0.5.1}/PKG-INFO +2 -2
  2. walkingpad_controller-0.5.1/docs/sperax-p3max-protocol.md +371 -0
  3. {walkingpad_controller-0.4.11 → walkingpad_controller-0.5.1}/pyproject.toml +14 -1
  4. {walkingpad_controller-0.4.11 → walkingpad_controller-0.5.1}/src/walkingpad_controller/__init__.py +10 -3
  5. {walkingpad_controller-0.4.11 → walkingpad_controller-0.5.1}/src/walkingpad_controller/const.py +16 -0
  6. {walkingpad_controller-0.4.11 → walkingpad_controller-0.5.1}/src/walkingpad_controller/controller.py +126 -3
  7. {walkingpad_controller-0.4.11 → walkingpad_controller-0.5.1}/src/walkingpad_controller/models.py +8 -0
  8. walkingpad_controller-0.5.1/src/walkingpad_controller/sperax.py +549 -0
  9. walkingpad_controller-0.5.1/tests/commands/__init__.py +0 -0
  10. walkingpad_controller-0.5.1/tests/commands/_common.py +224 -0
  11. walkingpad_controller-0.5.1/tests/commands/test_connect.py +22 -0
  12. walkingpad_controller-0.5.1/tests/commands/test_disconnect.py +15 -0
  13. walkingpad_controller-0.5.1/tests/commands/test_observe.py +69 -0
  14. walkingpad_controller-0.5.1/tests/commands/test_pause.py +77 -0
  15. walkingpad_controller-0.5.1/tests/commands/test_reset.py +17 -0
  16. walkingpad_controller-0.5.1/tests/commands/test_resume.py +74 -0
  17. walkingpad_controller-0.5.1/tests/commands/test_set_inclination.py +24 -0
  18. walkingpad_controller-0.5.1/tests/commands/test_set_speed.py +48 -0
  19. walkingpad_controller-0.5.1/tests/commands/test_start.py +27 -0
  20. walkingpad_controller-0.5.1/tests/commands/test_stop.py +31 -0
  21. walkingpad_controller-0.5.1/tests/commands/test_switch_mode.py +28 -0
  22. walkingpad_controller-0.5.1/tests/commands/test_update_state.py +26 -0
  23. walkingpad_controller-0.5.1/tests/probe_disconnect.py +274 -0
  24. walkingpad_controller-0.5.1/tests/probe_keepalive.py +217 -0
  25. walkingpad_controller-0.5.1/tests/probe_lib_stability.py +75 -0
  26. walkingpad_controller-0.5.1/tests/probe_preworkout.py +329 -0
  27. walkingpad_controller-0.5.1/tests/probe_preworkout2.py +243 -0
  28. walkingpad_controller-0.5.1/tests/probe_setup_killer.py +210 -0
  29. walkingpad_controller-0.5.1/tests/probe_setup_step.py +167 -0
  30. walkingpad_controller-0.5.1/tests/stress_dynamic.py +398 -0
  31. walkingpad_controller-0.5.1/tests/stress_real_device.py +207 -0
  32. walkingpad_controller-0.5.1/tests/stress_start_stop.py +269 -0
  33. walkingpad_controller-0.5.1/tests/stress_traced.py +260 -0
  34. walkingpad_controller-0.5.1/tests/test_protocol_detection.py +40 -0
  35. walkingpad_controller-0.5.1/tests/test_sperax_codec.py +177 -0
  36. walkingpad_controller-0.5.1/tests/watch_ble.py +221 -0
  37. walkingpad_controller-0.4.11/.github/workflows/publish.yml +0 -51
  38. {walkingpad_controller-0.4.11 → walkingpad_controller-0.5.1}/.gitignore +0 -0
  39. {walkingpad_controller-0.4.11 → walkingpad_controller-0.5.1}/LICENSE +0 -0
  40. {walkingpad_controller-0.4.11 → walkingpad_controller-0.5.1}/README.md +0 -0
  41. {walkingpad_controller-0.4.11 → walkingpad_controller-0.5.1}/docs/ftms-protocol-reference.md +0 -0
  42. {walkingpad_controller-0.4.11 → walkingpad_controller-0.5.1}/docs/ks-fit-reverse-engineering.md +0 -0
  43. {walkingpad_controller-0.4.11 → walkingpad_controller-0.5.1}/src/walkingpad_controller/ftms.py +0 -0
  44. {walkingpad_controller-0.4.11 → walkingpad_controller-0.5.1}/src/walkingpad_controller/wilink.py +0 -0
  45. {walkingpad_controller-0.4.11 → walkingpad_controller-0.5.1}/tests/test_real_device.py +0 -0
@@ -1,6 +1,6 @@
1
- Metadata-Version: 2.4
1
+ Metadata-Version: 2.5
2
2
  Name: walkingpad-controller
3
- Version: 0.4.11
3
+ Version: 0.5.1
4
4
  Summary: Python library for controlling KingSmith WalkingPad treadmills over BLE (FTMS and legacy WiLink protocols)
5
5
  Project-URL: Homepage, https://github.com/mcdax/walkingpad-controller
6
6
  Project-URL: Repository, https://github.com/mcdax/walkingpad-controller
@@ -0,0 +1,371 @@
1
+ # Sperax P3 Max — BLE Protocol
2
+
3
+ Reverse-engineered protocol for the **Sperax P3 Max** walking pad / vibration treadmill
4
+ (advertised BLE name `SPERAX_P3MAX`). Tracking: [issue #3](https://github.com/mcdax/hass-walkingpad/issues/3).
5
+
6
+ The device is built around a **wi-linktech WLT6200** BLE module
7
+ (GATT *Manufacturer Name* = `wi-linktech`, *Model Number* = `WLT6200`).
8
+ It does **not** use FTMS (`0x1826`) and it is **not** the legacy KingSmith WiLink
9
+ protocol (`0xFE00` / `0xFE01` / `0xFE02`). It uses a custom framed protocol on a
10
+ vendor service, documented below.
11
+
12
+ All command and status frames in this document were validated against a full,
13
+ unfiltered HCI snoop capture: **146/146 distinct frames pass CRC**, and a from-scratch
14
+ encoder reproduces every captured frame byte-for-byte.
15
+
16
+ ---
17
+
18
+ ## 1. GATT layout
19
+
20
+ | Role | Service | Characteristic | Handle | Properties |
21
+ |------|---------|----------------|--------|------------|
22
+ | **Command (write)** | `0000fff0-0000-1000-8000-00805f9b34fb` | `0000fff2-…` | `0x002c` | Write **No Response** |
23
+ | **Status (notify)** | `0000fff0-0000-1000-8000-00805f9b34fb` | `0000fff1-…` | `0x0029` | Notify |
24
+
25
+ To talk to the device:
26
+
27
+ 1. Connect.
28
+ 2. Enable notifications on `0xFFF1` (write `0x0001` to its CCCD, handle `0x002a`).
29
+ 3. Send the **hello** command (§4.1) once.
30
+ 4. Send a **status-poll** command (§4.4) periodically (the app does ~3×/s) to keep
31
+ the status stream flowing, and send control commands as needed.
32
+
33
+ > A second vendor service `0x0000ff10-…` (`0xFF11` notify / `0xFF12` write) is present
34
+ > on the device but is **not** used by the official app for control. Ignore it.
35
+
36
+ The device also exposes a standard **Device Information** service (`0x180A`):
37
+ `Manufacturer = wi-linktech`, `Model = WLT6200`, `SW Rev = R22_V227.04.03`,
38
+ `HW Rev = V1.0.0`.
39
+
40
+ ---
41
+
42
+ ## 2. Frame format
43
+
44
+ Every frame — in both directions — has the same envelope:
45
+
46
+ ```
47
+ F5 | LEN | 00 | CMD | [ ARGS… ] | CRC_lo | CRC_hi | FA
48
+ ```
49
+
50
+ | Field | Size | Description |
51
+ |-------|------|-------------|
52
+ | `F5` | 1 | Start-of-frame delimiter |
53
+ | `LEN` | 1 | **Transmitted** (post-stuffing) total frame length, in bytes |
54
+ | `00` | 1 | Constant channel/address byte (always `0x00`) |
55
+ | `CMD` | 1 | Command / message type (see §4, §5) |
56
+ | `ARGS` | n | Command arguments (may be empty) |
57
+ | `CRC` | 2 | CRC-16, little-endian (see §3) |
58
+ | `FA` | 1 | End-of-frame delimiter |
59
+
60
+ ### 2.1 Byte stuffing
61
+
62
+ `0xF5`, `0xFA` and `0xF0` are reserved. Any **logical** byte in the range
63
+ `0xF0`–`0xFF` that would otherwise appear in the body (i.e. in `00 | CMD | ARGS | CRC`,
64
+ **not** the `F5`/`LEN`/`FA` framing) is escaped:
65
+
66
+ ```
67
+ encode: 0xFn -> F0 0n (emit 0xF0, then the low nibble)
68
+ decode: F0 0n -> 0xF0 | 0n (= 0xFn)
69
+ ```
70
+
71
+ Examples: `0xFA → F0 0A`, `0xF5 → F0 05`, `0xF4 → F0 04`, `0xFF → F0 0F`.
72
+
73
+ Because stuffing changes the byte count, `LEN` is the **stuffed** length as it appears
74
+ on the wire, while the CRC is computed over the **de-stuffed** bytes (see §3).
75
+
76
+ ---
77
+
78
+ ## 3. Checksum (CRC-16)
79
+
80
+ | Parameter | Value |
81
+ |-----------|-------|
82
+ | Width | 16 bits |
83
+ | Polynomial | `0xA327` (reflected form, as used directly below) |
84
+ | Init | `0xFFFF` |
85
+ | Reflected | yes (input and output) |
86
+ | XOR out | `0x0000` |
87
+ | Byte order in frame | **little-endian** (`CRC_lo` first) |
88
+
89
+ The CRC is computed over the **de-stuffed** byte sequence
90
+ `[ 0xF5, LOGICAL_LEN, 0x00, CMD, ARGS… ]`, where `LOGICAL_LEN` is the de-stuffed frame
91
+ length (which equals `LEN` when no stuffing occurred).
92
+
93
+ Reference implementation:
94
+
95
+ ```python
96
+ def crc16(data: bytes) -> int:
97
+ c = 0xFFFF
98
+ for b in data:
99
+ c ^= b
100
+ for _ in range(8):
101
+ c = (c >> 1) ^ 0xA327 if (c & 1) else (c >> 1)
102
+ return c & 0xFFFF
103
+ ```
104
+
105
+ ### 3.1 Full encoder / decoder
106
+
107
+ ```python
108
+ def stuff(b: bytes) -> bytes:
109
+ out = bytearray()
110
+ for x in b:
111
+ if 0xF0 <= x <= 0xFF:
112
+ out += bytes([0xF0, x & 0x0F])
113
+ else:
114
+ out.append(x)
115
+ return bytes(out)
116
+
117
+ def destuff(b: bytes) -> bytes:
118
+ out = bytearray(); i = 0
119
+ while i < len(b):
120
+ if b[i] == 0xF0 and i + 1 < len(b):
121
+ out.append(0xF0 | b[i + 1]); i += 2
122
+ else:
123
+ out.append(b[i]); i += 1
124
+ return bytes(out)
125
+
126
+ def encode(inner: bytes) -> bytes:
127
+ # inner = the logical body WITHOUT framing/CRC, i.e. [0x00, CMD, ARGS...]
128
+ logical_len = 1 + 1 + len(inner) + 2 + 1 # F5 + LEN + inner + CRC(2) + FA
129
+ c = crc16(bytes([0xF5, logical_len]) + inner)
130
+ body = stuff(inner + bytes([c & 0xFF, (c >> 8) & 0xFF]))
131
+ tx_len = 1 + 1 + len(body) + 1 # actual on-wire length
132
+ return bytes([0xF5, tx_len]) + body + bytes([0xFA])
133
+
134
+ def decode(frame: bytes) -> bytes:
135
+ # returns the logical inner body [0x00, CMD, ARGS...] (CRC verified)
136
+ full = bytes([0xF5]) + destuff(frame[1:-1]) + bytes([0xFA])
137
+ data = bytearray(full[:-3]); data[1] = len(full) # LOGICAL_LEN for CRC
138
+ lo, hi = full[-3], full[-2]
139
+ assert crc16(bytes(data)) == (hi << 8 | lo), "CRC mismatch"
140
+ return full[2:-3]
141
+ ```
142
+
143
+ ---
144
+
145
+ ## 4. Commands (app → device, characteristic `0xFFF2`)
146
+
147
+ All commands share the `F5 | LEN | 00 | CMD | … | CRC | FA` envelope. The
148
+ **inner body** column below is `00 | CMD | ARGS` (i.e. what `encode()` takes / `decode()`
149
+ returns).
150
+
151
+ | CMD | Meaning | Inner body | Args |
152
+ |-----|---------|-----------|------|
153
+ | `0x01` | Hello / handshake | `00 01` | none |
154
+ | `0x15` | Belt / run control | `00 15 <state> <speed> <incline>` | see §4.2 |
155
+ | `0x16` | Vibration control | `00 16 <state> <level>` | see §4.3 |
156
+ | `0x19` | Status poll (keep-alive) | `00 19` | none |
157
+
158
+ ### 4.1 Hello — `0x01`
159
+
160
+ Sent once, right after connecting and enabling notifications.
161
+
162
+ ```
163
+ 00 01 (inner)
164
+ F5 07 00 01 26 D8 FA (on wire)
165
+ ```
166
+
167
+ The device replies with a **hello response** (§5.1) carrying capability/info bytes.
168
+
169
+ ### 4.2 Belt / run control — `0x15`
170
+
171
+ Inner body: `00 15 <state> <speed> <incline>`
172
+
173
+ | Arg | Values | Meaning |
174
+ |-----|--------|---------|
175
+ | `state` | `0x01` = run, `0x02` = pause, `0x00` = stop | Belt state (see below) |
176
+ | `speed` | `0x00`–… | **Target speed in km/h × 10** (e.g. `0x1E` = 3.0 km/h). `0x00` when stopping. |
177
+ | `incline` | `0x00`–`0x0A` | Incline step (0 = flat, 10 = max; no decline) |
178
+
179
+ The three `state` values behave differently (confirmed in hass-walkingpad#3):
180
+
181
+ - **`0x01` run** — start / keep the belt moving at `speed`.
182
+ - **`0x02` pause** — belt decelerates to 0 but the device **keeps** its session
183
+ counters (steps / distance / time); a later `run` resumes the session.
184
+ - **`0x00` stop** — belt stops **and** the device **resets** the session counters
185
+ to 0 (the next status frame reports all-zero counters).
186
+
187
+ To **start** the belt and set a speed, send `state=0x01` with the desired `speed`.
188
+ The official app ramps the speed up by sending successive `0x15` frames with an
189
+ increasing `speed` byte, but a single frame with the final target also works.
190
+
191
+ To **pause** (keep totals): `00 15 02 00 00`. To **stop** (reset totals): `00 15 00 00 00`.
192
+
193
+ **Run-control reference frames** (incline `0x00`; generated by the verified encoder,
194
+ those overlapping the capture match byte-for-byte):
195
+
196
+ | km/h | `speed` | On-wire frame |
197
+ |------|---------|---------------|
198
+ | 0.5 | `0x05` | `F5 0A 00 15 01 05 00 CB 88 FA` |
199
+ | 1.0 | `0x0A` | `F5 0A 00 15 01 0A 00 B4 41 FA` |
200
+ | 1.5 | `0x0F` | `F5 0A 00 15 01 0F 00 A4 C4 FA` |
201
+ | 2.0 | `0x14` | `F5 0A 00 15 01 14 00 05 95 FA` |
202
+ | 2.5 | `0x19` | `F5 0A 00 15 01 19 00 1F C9 FA` |
203
+ | 3.0 | `0x1E` | `F5 0A 00 15 01 1E 00 6A D9 FA` |
204
+ | 3.5 | `0x23` | `F5 0A 00 15 01 23 00 D2 DF FA` |
205
+ | 4.0 | `0x28` | `F5 0A 00 15 01 28 00 28 7A FA` |
206
+ | 4.5 | `0x2D` | `F5 0B 00 15 01 2D 00 38 F0 0F FA` ¹ |
207
+ | 5.0 | `0x32` | `F5 0A 00 15 01 32 00 1C C2 FA` |
208
+ | 5.5 | `0x37` | `F5 0A 00 15 01 37 00 0C 47 FA` |
209
+ | 6.0 | `0x3C` | `F5 0B 00 15 01 3C 00 F0 06 E2 FA` ¹ |
210
+
211
+ ¹ CRC contains a byte ≥ `0xF0`, so byte-stuffing applies and `LEN` becomes `0x0B`.
212
+
213
+ **Incline** (at 3.0 km/h), captured:
214
+
215
+ | Incline | Frame |
216
+ |---------|-------|
217
+ | 0 | `F5 0A 00 15 01 1E 00 6A D9 FA` |
218
+ | 1 | `F5 0A 00 15 01 1E 01 9E B7 FA` |
219
+ | 2 | `F5 0A 00 15 01 1E 02 82 04 FA` |
220
+
221
+ ### 4.3 Vibration control — `0x16`
222
+
223
+ Inner body: `00 16 <state> <level>`
224
+
225
+ | Arg | Values | Meaning |
226
+ |-----|--------|---------|
227
+ | `state` | `0x01` = on, `0x00` = off | Vibration state |
228
+ | `level` | `0x01`–`0x04` (`0x00` when off) | Vibration intensity |
229
+
230
+ > The belt and the vibration motor are **mutually exclusive**: enabling vibration
231
+ > stops the belt.
232
+
233
+ Captured frames:
234
+
235
+ | Action | Frame |
236
+ |--------|-------|
237
+ | Vibration level 1 | `F5 09 00 16 01 01 55 EA FA` |
238
+ | Vibration level 2 | `F5 09 00 16 01 02 49 59 FA` |
239
+ | Vibration level 3 | `F5 09 00 16 01 03 BD 37 FA` |
240
+ | Vibration level 4 | `F5 09 00 16 01 04 3E 79 FA` |
241
+ | Vibration off | `F5 09 00 16 00 00 34 6D FA` |
242
+
243
+ ### 4.4 Status poll — `0x19`
244
+
245
+ Inner body: `00 19`. On wire: `F5 08 00 19 F0 0A 59 FA`
246
+ (note the CRC low byte `0xFA` is stuffed to `F0 0A`, so `LEN = 0x08`).
247
+
248
+ Sent repeatedly (~3×/s in the app) to keep the device streaming status
249
+ notifications (§5.2).
250
+
251
+ ---
252
+
253
+ ## 5. Notifications (device → app, characteristic `0xFFF1`)
254
+
255
+ Same envelope. Three message types were observed: `0x01` (hello response),
256
+ `0xD0` (command ACK) and `0x19` (status).
257
+
258
+ ### 5.1 Hello response — `0x01`
259
+
260
+ Sent once after the hello command. Inner body (example):
261
+
262
+ ```
263
+ 00 01 00 06 00 A8 27 11 01 00 05 78 03 4B 00 0A 01 04 00
264
+ ```
265
+
266
+ Carries device capability/config data (units, limits, etc.). Exact field layout is
267
+ not yet decoded — not required for control; useful later for exposing device limits.
268
+
269
+ ### 5.2 Status — `0x19`
270
+
271
+ The core telemetry frame, streamed while polling. Inner body is fixed-layout
272
+ (19 bytes). Offsets below are within the **inner body** (`byte[0] = 0x00`,
273
+ `byte[1] = 0x19`):
274
+
275
+ | Offset | Field | Notes |
276
+ |-------:|-------|-------|
277
+ | 0 | `0x00` | constant channel byte |
278
+ | 1 | `0x19` | message type |
279
+ | 2–3 | — | constant `00 00` in all samples |
280
+ | **4** | **state** | `0x10` = running, `0x0F` = decelerating/stopping, `0x01` = stopped, `0x50` = vibration mode, `0x00` = idle/off |
281
+ | 5–7 | — | constant `00 00 00` |
282
+ | **8–9** | **duration** | uint16 LE — elapsed seconds |
283
+ | **10–11** | **distance** | uint16 LE in **10 m units** → metres = value × 10 |
284
+ | **12–13** | calorie-like counter | uint16 LE; slow-moving. Left unmapped — the app's kcal is computed app-side and this field is only a coarse broadcast |
285
+ | **14** | **steps** | uint8 (device-confirmed) |
286
+ | **15** | **speed** | **current speed in km/h × 10** (`0x1E` = 3.0; ramps down during stop) |
287
+ | **16** | **incline** | `0x00`–`0x0A` (0 = flat, 10 = max) |
288
+ | 17 | `0x00` | |
289
+ | **18** | **vibration level** | `0x00`–`0x04`; retains last level, only meaningful while state (4) is `0x50` |
290
+
291
+ Field units for duration and distance were derived from a real walk: integrating
292
+ speed over the session gives ~30 m and offset 10 reads `3` (× 10 = 30 m), while
293
+ offset 8 tracks the elapsed-second count. Steps (offset 14) were confirmed on the
294
+ physical console by the device owner (hass-walkingpad#3). The offset 12–13 counter
295
+ moves too slowly to be distance and is most likely a coarse calorie estimate; it is
296
+ left unmapped pending confirmation.
297
+
298
+ > Note: steps (offset 14) is a single byte, so it wraps at 255 on this capture's
299
+ > layout. Not yet observed on a longer walk — flagged for confirmation.
300
+
301
+ **Worked examples** (inner body, spaces added):
302
+
303
+ ```
304
+ running 3.0 km/h, incline 0: 00 19 00 00 10 00 00 00 10 00 01 00 01 00 0F 1E 00 00 00
305
+ running 3.0 km/h, incline 1: 00 19 00 00 10 00 00 00 18 00 01 00 01 00 1C 1E 01 00 00
306
+ running 3.0 km/h, incline 2: 00 19 00 00 10 00 00 00 22 00 02 00 02 00 2D 1E 02 00 00
307
+ decelerating (speed 2.8): 00 19 00 00 0F 00 00 00 2B 00 03 00 02 00 3D 1C 00 00 00
308
+ stopped: 00 19 00 00 01 00 00 00 2F 00 03 00 02 00 44 00 00 00 00
309
+ vibration mode, level 1: 00 19 00 00 50 00 00 00 2F 00 03 00 02 00 44 00 00 00 01
310
+ idle / off: 00 19 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 04
311
+ ```
312
+
313
+ ### 5.3 Command ACK — `0xD0`
314
+
315
+ Immediately after each control command, the device sends a `0xD0` acknowledgement
316
+ echoing the command type and its primary argument. Inner body: `00 D0 <CMD> <state> <arg>`.
317
+
318
+ | After command | ACK inner body |
319
+ |---------------|----------------|
320
+ | Run (`0x15`, running) | `00 D0 15 01 00` |
321
+ | Stop (`0x15`, stop) | `00 D0 15 02 00` |
322
+ | Vibration on (`0x16`) | `00 D0 16 01 00` |
323
+ | Vibration off (`0x16`)| `00 D0 16 00 00` |
324
+
325
+ ---
326
+
327
+ ## 6. Example session
328
+
329
+ Reproduced from the reference capture (times in seconds from start):
330
+
331
+ | Time | Direction | Meaning | Frame |
332
+ |------|-----------|---------|-------|
333
+ | 138.6 | → | Hello | `F5 07 00 01 26 D8 FA` |
334
+ | 138.8 | ← | Hello response | `F5 19 00 01 …` |
335
+ | 146.9 | → | Run, speed 0.2, incline 0 | `F5 0A 00 15 01 02 00 BE 98 FA` |
336
+ | … | → | Speed ramps 0.2 → 3.0 km/h | successive `0x15` frames |
337
+ | 167.2 | → | Run, speed 3.0, incline 0 | `F5 0A 00 15 01 1E 00 6A D9 FA` |
338
+ | 175.3 | → | Incline 1 | `F5 0A 00 15 01 1E 01 9E B7 FA` |
339
+ | 184.8 | → | Incline 2 | `F5 0A 00 15 01 1E 02 82 04 FA` |
340
+ | 194.1 | → | Stop belt | `F5 0A 00 15 02 00 00 C3 19 FA` |
341
+ | 210.2 | → | Vibration level 1 | `F5 09 00 16 01 01 55 EA FA` |
342
+ | 217.7 | → | Vibration level 2 | `F5 09 00 16 01 02 49 59 FA` |
343
+ | 225.2 | → | Vibration level 3 | `F5 09 00 16 01 03 BD 37 FA` |
344
+ | 231.5 | → | Vibration level 4 | `F5 09 00 16 01 04 3E 79 FA` |
345
+ | 238.3 | → | Vibration off | `F5 09 00 16 00 00 34 6D FA` |
346
+
347
+ Throughout, the app sends the status poll (`F5 08 00 19 F0 0A 59 FA`) ~3×/s and the
348
+ device streams `0x19` status notifications.
349
+
350
+ ---
351
+
352
+ ## 7. Open items
353
+
354
+ - Decode the hello-response (`0x01`) fields → device limits / units.
355
+ - Status counters mostly resolved: offset 8–9 = duration (s), 10–11 = distance
356
+ (×10 m), 14 = steps. Offset 12–13 is an unmapped calorie-like counter — confirm
357
+ its unit (or that kcal is purely app-side) with a longer instrumented capture.
358
+ - Confirm whether steps (offset 14) is really a single byte (wraps at 255) or has a
359
+ high byte elsewhere — needs a >255-step walk to observe.
360
+ - **Max speed is 12.0 km/h** (confirmed by the device owner in hass-walkingpad#3;
361
+ the reference capture only reached 3.0 km/h). The `<speed>` byte still follows
362
+ km/h × 10, so 12.0 km/h = `0x78`.
363
+ - **Incline is 0–10, no decline** (confirmed by a full incline-sweep capture in
364
+ hass-walkingpad#3). The `<incline>` byte in the run command and the incline field
365
+ in the status frame both range `0x00` (flat) .. `0x0A` (max); values never go
366
+ negative. The device does not expose a separate decline in the protocol.
367
+
368
+ ---
369
+
370
+ *Derived from an unfiltered Android HCI snoop capture of a real P3 Max session.
371
+ CRC/framing verified against 146/146 distinct captured frames.*
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
6
  name = "walkingpad-controller"
7
- version = "0.4.11"
7
+ version = "0.5.1"
8
8
  description = "Python library for controlling KingSmith WalkingPad treadmills over BLE (FTMS and legacy WiLink protocols)"
9
9
  readme = "README.md"
10
10
  license = "MIT"
@@ -44,3 +44,16 @@ Issues = "https://github.com/mcdax/walkingpad-controller/issues"
44
44
 
45
45
  [tool.hatch.build.targets.wheel]
46
46
  packages = ["src/walkingpad_controller"]
47
+
48
+ [tool.hatch.build.targets.sdist]
49
+ # Whitelist what goes into the source distribution. Without this hatchling
50
+ # sweeps in whatever sits in the working tree (captured APKs, tooling logs,
51
+ # etc.), which bloated the sdist to hundreds of MB and would break the PyPI
52
+ # upload. Keep it to the actual package plus docs/tests.
53
+ include = [
54
+ "src/walkingpad_controller",
55
+ "tests",
56
+ "docs",
57
+ "README.md",
58
+ "LICENSE",
59
+ ]
@@ -1,7 +1,8 @@
1
1
  """walkingpad-controller — Python library for controlling WalkingPad treadmills over BLE.
2
2
 
3
- Supports both FTMS (Fitness Machine Service) and legacy WiLink protocols.
4
- Protocol is auto-detected based on the BLE device name and services.
3
+ Supports FTMS (Fitness Machine Service), legacy WiLink, and the Sperax /
4
+ wi-linktech (WLT6200) protocols. Protocol is auto-detected based on the BLE
5
+ device name and services.
5
6
 
6
7
  Quick start:
7
8
 
@@ -20,6 +21,8 @@ Quick start:
20
21
  from .const import (
21
22
  FTMS_NAME_PREFIXES,
22
23
  FTMS_SERVICE_UUID,
24
+ SPERAX_NAME_PREFIXES,
25
+ SPERAX_SERVICE_UUID,
23
26
  WILINK_SERVICE_UUID,
24
27
  BeltState,
25
28
  FTMSOpcode,
@@ -30,9 +33,10 @@ from .const import (
30
33
  from .controller import WalkingPadController
31
34
  from .ftms import FTMSController
32
35
  from .models import DeviceCapabilities, SpeedRange, TreadmillStatus
36
+ from .sperax import SperaxController
33
37
  from .wilink import WiLinkController
34
38
 
35
- __version__ = "0.4.0"
39
+ __version__ = "0.5.1"
36
40
 
37
41
  __all__ = [
38
42
  # Main controller
@@ -40,6 +44,7 @@ __all__ = [
40
44
  # Protocol-specific controllers
41
45
  "FTMSController",
42
46
  "WiLinkController",
47
+ "SperaxController",
43
48
  # Data models
44
49
  "TreadmillStatus",
45
50
  "SpeedRange",
@@ -53,5 +58,7 @@ __all__ = [
53
58
  # Constants
54
59
  "FTMS_SERVICE_UUID",
55
60
  "WILINK_SERVICE_UUID",
61
+ "SPERAX_SERVICE_UUID",
56
62
  "FTMS_NAME_PREFIXES",
63
+ "SPERAX_NAME_PREFIXES",
57
64
  ]
@@ -33,6 +33,13 @@ KINGSMITH_VENDOR_PREAMBLE_PAYLOAD = bytes.fromhex("01000d00060b0f0d")
33
33
  # Legacy WiLink Service (for older devices)
34
34
  WILINK_SERVICE_UUID = "0000fe00-0000-1000-8000-00805f9b34fb"
35
35
 
36
+ # Sperax / wi-linktech (WLT6200) vendor service — Sperax P3 Max walking pad.
37
+ # Custom framed protocol (F5 .. FA, CRC-16/0xA327). Not FTMS, not WiLink.
38
+ # See docs/sperax-p3max-protocol.md.
39
+ SPERAX_SERVICE_UUID = "0000fff0-0000-1000-8000-00805f9b34fb"
40
+ SPERAX_WRITE_UUID = "0000fff2-0000-1000-8000-00805f9b34fb" # write-no-response
41
+ SPERAX_NOTIFY_UUID = "0000fff1-0000-1000-8000-00805f9b34fb" # notify
42
+
36
43
 
37
44
  # --- Enums ---
38
45
 
@@ -43,6 +50,7 @@ class ProtocolType(Enum):
43
50
 
44
51
  WILINK = "wilink" # Legacy protocol (service 0xFE00, ph4-walkingpad)
45
52
  FTMS = "ftms" # Standard FTMS (service 0x1826)
53
+ SPERAX = "sperax" # Sperax P3 Max / wi-linktech WLT6200 (service 0xFFF0)
46
54
  UNKNOWN = "unknown"
47
55
 
48
56
 
@@ -257,6 +265,14 @@ class TreadmillDataFlags:
257
265
  # getter matches all three).
258
266
  FTMS_NAME_PREFIXES = ("KS-HD-", "KS-MC21-", "KS-SMC21C-", "ZP-ZEALR1-")
259
267
 
268
+ # BLE name prefixes for the Sperax / wi-linktech (WLT6200) vendor protocol.
269
+ # The P3 Max advertises as "SPERAX_P3MAX". Keep this specific rather than a
270
+ # bare "SPERAX_" prefix: other Sperax-branded pads (e.g. the RM-01, which
271
+ # advertises as "SPERAX_RM-01_...") speak FTMS, not the WLT6200 vendor
272
+ # protocol. A too-broad prefix would misroute them to Sperax and break them;
273
+ # names that don't match here fall through to service-probe detection.
274
+ SPERAX_NAME_PREFIXES = ("SPERAX_P3MAX",)
275
+
260
276
  # Default connection parameters.
261
277
  # KingSmith FTMS firmware can be left in a bad state for several seconds
262
278
  # after a previous abrupt disconnect — Bleak/BlueZ then accepts the next