Draft. Version 2 is a proposal under review by smart trainer manufacturers. Expect changes before it is released.Discuss in PR #31

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.

Status
Draft, under review by smart trainer manufacturers
Source
PR #31 at 4a33840
Snapshot
8 October 2026
Adds
Trainer Service · message types 0x05–0x0A
Transports
BLE GATT · mDNS + TCP, length-prefixed
Controllers
Unchanged on BLE; TCP framing is required
Current release
Version 1

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.

The closed loop of OpenBikeControl version 2A controller sends a Shift Up button state message to the trainer app, as in version 1. New in version 2, the app sends the selected gear ratio to the smart trainer with Virtual Shifting Control, and the trainer reports the gear in use with Virtual Shifting State and streams Trainer Data back to the app.Version 1New in version 201 01 0105 … 0x0C06 … 0x0C09 …01 02 0105 … 0x0B06 … 0x0B09 …A · ControllerShiftpaddleB · Trainer appGear1112Ratio2.7503.000of 24 gearsOwns control of the trainerC · Smart trainerLoadSimulates the gear itself0x01Button State0x05 / 0x08Gear ratio · trainer control0x06 / 0x09 / 0x0AGear in use · data · statusSame bytes over BLE GATT and mDNS + TCP · TCP messages are length-prefixed in version 2
Fig. 1 — The closed loop. The controller still talks to the app. The app now also tells the trainer which gear to simulate, and the trainer reports back. Swipe the figure sideways to see all three units.

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.

  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.

  2. 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.

  3. 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.

  4. 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

TypeNameDirectionBytes
0x05Virtual Shifting ControlApp → trainer11
0x06Virtual Shifting StateTrainer → app11
0x07Ride StateApp → trainer5
0x08Trainer ControlApp → trainer17
0x09Trainer DataTrainer → app13
0x0ATrainer StatusTrainer → app15

3.2Identifiers

Draft UUIDs. They can still change before release.

Trainer ServiceBLE · Primary service
d273f690-d548-419d-b9d1-fa0472345229
Virtual Shifting Control0x05 · Write
d273f691-d548-419d-b9d1-fa0472345229
Virtual Shifting State0x06 · Read · Notify
d273f692-d548-419d-b9d1-fa0472345229
Ride State0x07 · Write without response
d273f693-d548-419d-b9d1-fa0472345229
Trainer Control0x08 · Write
d273f694-d548-419d-b9d1-fa0472345229
Trainer Data0x09 · Read · Notify
d273f695-d548-419d-b9d1-fa0472345229
Trainer Status0x0A · Read · Notify · mandatory
d273f696-d548-419d-b9d1-fa0472345229

3.3Message framing

On TCP every message, in both directions, starts with its length. Receivers buffer until the whole message has arrived.

A framed TCP message: two length bytes 0x00 0x03, then the message type 0x01 and its payload 0x1B 0x94.Length · 2 bytes, big-endianMessage · as in version 10x000x030x010x1B0x94Length counts the message type and payload: 3 bytes, at most 512TCP only, both directions
Fig. 2 — Framed TCP message. BLE is unchanged: each notification or write is already one message.[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.

Changes expected

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.

  1. Read the draft. Start with the Trainer Profile, then the Virtual Shifting Extension and message framing.
  2. 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.
  3. 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.