Draft Protocol version 2
Version 2 lets the app control the smart trainer, not just read the controller.
OpenBikeControl 2 adds the other half of the loop. The app tells the trainer which gear to simulate and what to do, the trainer reports back, and one rule decides who is in control. It works over Bluetooth and over the local network, with the same bytes on both.
The closed loop
In version 1 a shift press ends at the app, which then approximates the gear by changing the grade over FTMS. In version 2 the app sends the gear ratio itself, so the trainer can simulate the gear inside its own control loop and report the gear it is actually in.
What changes
Four additions, all optional for controllers except the TCP framing. Button State, Device Status, Haptic Feedback and App Information stay exactly as in version 1.
Trainer Profile
A separate Trainer Service for smart trainers and smart bikes. Trainer Control sets the mode (simulation, target power, target resistance) and its values, Trainer Data streams power, cadence and speed, and Trainer Status announces capabilities and limits.
Control ownership
Exactly one client controls a trainer at a time, across OpenBikeControl and FTMS. The first client that enables a mode owns it until it releases control or disconnects. Every other client still receives the data.
Virtual shifting
The app sends the simulated gear ratio, rider mass and bike mass on every shift. The trainer derives the simulated speed from cadence and reports the gear in use. Smart bikes that own their gearing say so with a flag.
Message framing on TCP
Every TCP message is prefixed with a 2-byte length, so a receiver can split the byte stream even when trainer data is streamed continuously. This part is not backwards compatible: version 2 devices advertise version=2 in their TXT record.
Trainer Service
Trainers expose a second BLE service next to FTMS, separate from the controller service. A smart bike with shifters exposes both. On the network the same messages share the TCP connection and the Trainer Service UUID is listed in the TXT record.
3.1Messages
| Type | Name | Direction | Bytes |
|---|---|---|---|
| 0x05 | Virtual Shifting Control | App → trainer | 11 |
| 0x06 | Virtual Shifting State | Trainer → app | 11 |
| 0x07 | Ride State | App → trainer | 5 |
| 0x08 | Trainer Control | App → trainer | 17 |
| 0x09 | Trainer Data | Trainer → app | 13 |
| 0x0A | Trainer Status | Trainer → app | 15 |
3.2Identifiers
Draft UUIDs. They can still change before release.
d273f690-d548-419d-b9d1-fa0472345229d273f691-d548-419d-b9d1-fa0472345229d273f692-d548-419d-b9d1-fa0472345229d273f693-d548-419d-b9d1-fa0472345229d273f694-d548-419d-b9d1-fa0472345229d273f695-d548-419d-b9d1-fa0472345229d273f696-d548-419d-b9d1-fa04723452293.3Message framing
On TCP every message, in both directions, starts with its length. Receivers buffer until the whole message has arrived.
[0x00, 0x03, 0x01, 0x1B, 0x94]Draft status and feedback
Version 2 is published early so trainer manufacturers and app developers can shape it before anyone ships it.
Message types, field layouts, UUIDs and behaviour can all change while smart trainer manufacturers review the draft. Prototype against it, but don't ship firmware or app releases on it yet. Version 1 stays the current specification until version 2 is released.
- Read the draft. Start with the Trainer Profile, then the Virtual Shifting Extension and message framing.
- Try it. The PR updates the Python examples: a framed mock TCP device, a TCP trainer app, and encoders and parsers for every new message, with tests. Examples on the draft branch.
- Comment. Questions, objections and implementation notes go to pull request #31. This site shows a snapshot of it; the pull request is always the latest version.