Additional learnings¶
TL;DR
Getting to a working Zwift Ride presentation showed me a lot about how Zwift sees network devices. The identity a device claims shapes how Zwift uses it, and Zwift understands several other controller formats too. This page collects those findings so that anyone can pick them up and build on them. Each item ends with ideas for where it could go next.
Identity shapes how Zwift uses a device¶
A device that presents itself like a Wahoo KICKR bike, with a trainer role in its device information, is treated by Zwift as a smart bike that manages its own gears. Zwift then shows gears in "front-rear" form (for example 1-1 to 1-5). The device reports gear changes itself with 0x42 gear report messages:
| Message | Meaning |
|---|---|
42 32 02 08 <front> |
Current front gear |
42 32 02 20 <rear> |
Current rear gear |
This works well when the same device is also the trainer: it shifts, reports the new gear, and Zwift sends resistance updates back. When a separate trainer is the Resistance device, a pure controller identity (the Zwift Ride) is the one that fits, which is why the app uses it.
Where this could go next: a "smart bike" mode for riders whose trainer has no virtual shifting. The app could act as the Power Source and Resistance device, run its own gear table, report gears with 0x42, and pass power and resistance through to the real trainer.
Zwift Click and Zwift Play use simpler frames¶
Zwift supports other controllers with their own button formats:
| Controller | Opcode | Format |
|---|---|---|
| Zwift Click | 0x37 |
A short frame where one byte goes to 0 for "plus" and another for "minus". |
| Zwift Play | 0x07 |
A per-side frame for the left and right Play controllers. |
These are documented by the community projects listed in the credits. The Zwift Ride format covers more inputs (D-pad, four face buttons, analog paddles), so it is the best match for a full game controller.
Where this could go next: a "Click mode" for very simple inputs such as a single foot pedal or a two-button remote, where a smaller identity may be a better fit than a full Ride.
Power data belongs to the trainer¶
The app's GATT tree includes a Fitness Machine service, but a device presenting as a Zwift Ride is used for its controls only. Zwift does not take power or cadence from it, so the rider's trainer stays the Power Source. That is exactly the split riders want.
Where this could go next: if a future mode needs to relay power (for example the smart bike idea above), it would use a trainer-style identity rather than the Ride identity.
Zwift also browses _zwift-protocol._tcp¶
Besides _wahoo-fitness-tnp._tcp, Zwift sends mDNS queries for a second service type, _zwift-protocol._tcp. I have not seen a public description of what Zwift expects behind it.
Where this could go next: watch for any public documentation of this service. It may be a more direct way for third-party devices to talk to Zwift on the local network.
Different devices describe themselves differently¶
The device information page (data object id 0, see Device information) is where a device says what it is. Comparing replies is very instructive:
| Device | protocolVersion | deviceCapabilities (type, caps) | Follow-up requests from Zwift |
|---|---|---|---|
| KICKR-style smart bike | 514 (0x0202) |
(1, 36), (2, 0): trainer and user input | Controller input config (1024), battery (771), gear index config (528) |
| Smart trainer with Zwift virtual shifting | 515 (0x0203) |
(1, 209), (8, 1), (4, 0): trainer, Wi-Fi, sensor relay | Client/server config (16), sensor relay page (1280), sensor relay configuration (0x44) |
| The app, presenting as a Zwift Ride | 515 (0x0203) |
(2, 1): user input only | Client/server config (16), controller input config (1024), battery (771). Other requests, such as 1280, get no reply. |
Device types from Zwift's protocol: 1 = cycling trainer, 2 = user input device, 3 = treadmill, 4 = sensor relay, 5 = heart rate monitor, 6 = power meter, 7 = cadence sensor, 8 = Wi-Fi.
Two patterns stand out:
- For the smart bike and the trainer,
protocolVersionmatches the two bytes afterRideOnin their handshake reply (514 with02 02, 515 with02 03). The Ride presentation replies with02 00. - Zwift picks its follow-up questions from the capability list, so the list is a good place to look when a new device type behaves unexpectedly.
Where this could go next: the meaning of each capability bit is still open. A small, careful study of these values would help every project that builds Zwift-compatible devices.