walkingpad-controller 0.4.10__tar.gz → 0.5.0__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.
- {walkingpad_controller-0.4.10 → walkingpad_controller-0.5.0}/PKG-INFO +3 -2
- walkingpad_controller-0.5.0/docs/sperax-p3max-protocol.md +371 -0
- {walkingpad_controller-0.4.10 → walkingpad_controller-0.5.0}/pyproject.toml +15 -1
- {walkingpad_controller-0.4.10 → walkingpad_controller-0.5.0}/src/walkingpad_controller/__init__.py +10 -3
- {walkingpad_controller-0.4.10 → walkingpad_controller-0.5.0}/src/walkingpad_controller/const.py +12 -0
- {walkingpad_controller-0.4.10 → walkingpad_controller-0.5.0}/src/walkingpad_controller/controller.py +141 -6
- {walkingpad_controller-0.4.10 → walkingpad_controller-0.5.0}/src/walkingpad_controller/ftms.py +12 -3
- {walkingpad_controller-0.4.10 → walkingpad_controller-0.5.0}/src/walkingpad_controller/models.py +8 -0
- walkingpad_controller-0.5.0/src/walkingpad_controller/sperax.py +549 -0
- walkingpad_controller-0.5.0/tests/commands/__init__.py +0 -0
- walkingpad_controller-0.5.0/tests/commands/_common.py +224 -0
- walkingpad_controller-0.5.0/tests/commands/test_connect.py +22 -0
- walkingpad_controller-0.5.0/tests/commands/test_disconnect.py +15 -0
- walkingpad_controller-0.5.0/tests/commands/test_observe.py +69 -0
- walkingpad_controller-0.5.0/tests/commands/test_pause.py +77 -0
- walkingpad_controller-0.5.0/tests/commands/test_reset.py +17 -0
- walkingpad_controller-0.5.0/tests/commands/test_resume.py +74 -0
- walkingpad_controller-0.5.0/tests/commands/test_set_inclination.py +24 -0
- walkingpad_controller-0.5.0/tests/commands/test_set_speed.py +48 -0
- walkingpad_controller-0.5.0/tests/commands/test_start.py +27 -0
- walkingpad_controller-0.5.0/tests/commands/test_stop.py +31 -0
- walkingpad_controller-0.5.0/tests/commands/test_switch_mode.py +28 -0
- walkingpad_controller-0.5.0/tests/commands/test_update_state.py +26 -0
- walkingpad_controller-0.5.0/tests/probe_disconnect.py +274 -0
- walkingpad_controller-0.5.0/tests/probe_keepalive.py +217 -0
- walkingpad_controller-0.5.0/tests/probe_lib_stability.py +75 -0
- walkingpad_controller-0.5.0/tests/probe_preworkout.py +329 -0
- walkingpad_controller-0.5.0/tests/probe_preworkout2.py +243 -0
- walkingpad_controller-0.5.0/tests/probe_setup_killer.py +210 -0
- walkingpad_controller-0.5.0/tests/probe_setup_step.py +167 -0
- walkingpad_controller-0.5.0/tests/stress_dynamic.py +398 -0
- walkingpad_controller-0.5.0/tests/stress_real_device.py +207 -0
- walkingpad_controller-0.5.0/tests/stress_start_stop.py +269 -0
- walkingpad_controller-0.5.0/tests/stress_traced.py +260 -0
- walkingpad_controller-0.5.0/tests/test_sperax_codec.py +177 -0
- walkingpad_controller-0.5.0/tests/watch_ble.py +221 -0
- walkingpad_controller-0.4.10/.github/workflows/publish.yml +0 -51
- {walkingpad_controller-0.4.10 → walkingpad_controller-0.5.0}/.gitignore +0 -0
- {walkingpad_controller-0.4.10 → walkingpad_controller-0.5.0}/LICENSE +0 -0
- {walkingpad_controller-0.4.10 → walkingpad_controller-0.5.0}/README.md +0 -0
- {walkingpad_controller-0.4.10 → walkingpad_controller-0.5.0}/docs/ftms-protocol-reference.md +0 -0
- {walkingpad_controller-0.4.10 → walkingpad_controller-0.5.0}/docs/ks-fit-reverse-engineering.md +0 -0
- {walkingpad_controller-0.4.10 → walkingpad_controller-0.5.0}/src/walkingpad_controller/wilink.py +0 -0
- {walkingpad_controller-0.4.10 → walkingpad_controller-0.5.0}/tests/test_real_device.py +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
|
-
Metadata-Version: 2.
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
2
|
Name: walkingpad-controller
|
|
3
|
-
Version: 0.
|
|
3
|
+
Version: 0.5.0
|
|
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
|
|
@@ -19,6 +19,7 @@ Classifier: Programming Language :: Python :: 3.12
|
|
|
19
19
|
Classifier: Topic :: Home Automation
|
|
20
20
|
Classifier: Topic :: Software Development :: Libraries
|
|
21
21
|
Requires-Python: >=3.10
|
|
22
|
+
Requires-Dist: bleak-retry-connector>=3.0.0
|
|
22
23
|
Requires-Dist: bleak>=0.20.0
|
|
23
24
|
Provides-Extra: all
|
|
24
25
|
Requires-Dist: ph4-walkingpad>=1.0.0; extra == 'all'
|
|
@@ -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.
|
|
7
|
+
version = "0.5.0"
|
|
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"
|
|
@@ -26,6 +26,7 @@ classifiers = [
|
|
|
26
26
|
]
|
|
27
27
|
dependencies = [
|
|
28
28
|
"bleak>=0.20.0",
|
|
29
|
+
"bleak-retry-connector>=3.0.0",
|
|
29
30
|
]
|
|
30
31
|
|
|
31
32
|
[project.optional-dependencies]
|
|
@@ -43,3 +44,16 @@ Issues = "https://github.com/mcdax/walkingpad-controller/issues"
|
|
|
43
44
|
|
|
44
45
|
[tool.hatch.build.targets.wheel]
|
|
45
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
|
+
]
|
{walkingpad_controller-0.4.10 → walkingpad_controller-0.5.0}/src/walkingpad_controller/__init__.py
RENAMED
|
@@ -1,7 +1,8 @@
|
|
|
1
1
|
"""walkingpad-controller — Python library for controlling WalkingPad treadmills over BLE.
|
|
2
2
|
|
|
3
|
-
Supports
|
|
4
|
-
Protocol is auto-detected based on the BLE
|
|
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.
|
|
39
|
+
__version__ = "0.5.0"
|
|
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
|
]
|
{walkingpad_controller-0.4.10 → walkingpad_controller-0.5.0}/src/walkingpad_controller/const.py
RENAMED
|
@@ -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,10 @@ 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".
|
|
270
|
+
SPERAX_NAME_PREFIXES = ("SPERAX_",)
|
|
271
|
+
|
|
260
272
|
# Default connection parameters.
|
|
261
273
|
# KingSmith FTMS firmware can be left in a bad state for several seconds
|
|
262
274
|
# after a previous abrupt disconnect — Bleak/BlueZ then accepts the next
|