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

Version 2 draft, changes expected

This page documents a proposal that is still under review by smart trainer manufacturers. Message types, field layouts, UUIDs and behaviour can change before release, so don't ship firmware or apps against it yet. Version 1 is the current specification.

Feedback and discussion go to pull request #31. Snapshot of commit 4a33840 from 8 October 2026.

On this page
  1. Overview
  2. Why a trainer profile
  3. Design rules
  4. Relationship to FTMS
  5. Message Summary
  6. Control Ownership
  7. Trainer Control (App to Trainer)
  8. Trainer Data (Trainer to App)
  9. Trainer Status (Trainer to App)
  10. Calibration (Reserved)
  11. Transport Mapping
  12. BLE: Trainer Service
  13. mDNS / TCP
  14. See Also

Trainer Profile

Note

Status: Draft. This document is a proposal and may change before it is final.

Overview

The core OpenBikeControl protocol describes input devices (controllers) talking to apps. The Virtual Shifting Extension adds the first app-to-trainer messages. This document completes that direction: it defines an OpenBikeControl Trainer Service through which an app can control a smart trainer or smart bike and receive its data over BLE and over the network, with a single, explicit rule for who is allowed to control the trainer.

The Trainer Profile is optional. Controllers do not implement it. Trainers and smart bikes implement it next to, not instead of, the Bluetooth SIG Fitness Machine Service (FTMS).

Why a trainer profile

Apps can already control a trainer over BLE with FTMS, and the Virtual Shifting Extension fills FTMS's biggest gap. Three things remain that neither covers:

  1. Network control. FTMS only exists over BLE. Trainers that connect over Wi-Fi today use vendor-specific tunnels. The Trainer Profile uses the same messages over BLE and TCP, so a trainer on the network is controlled exactly like one over BLE.
  2. Control ownership across protocols. FTMS has a control slot, but it only knows about FTMS clients. A trainer that also accepts OpenBikeControl writes needs one rule covering both, otherwise two apps can fight over the trainer.
  3. One place for capability discovery. Apps need to know up front whether a trainer supports simulation, target power, virtual shifting, app-provided speed, and so on. The Trainer Status message carries this for all OpenBikeControl trainer features.

Design rules

The Trainer Profile follows the rest of the protocol:

  • Fixed-length messages with a message type prefix, identical over BLE and TCP
  • Writes are one-way; the trainer never answers a write directly
  • The trainer reports its state whenever it changes, and once after connect
  • Multi-byte fields are little-endian, matching FTMS
  • Everything is optional except Trainer Status, which announces what else is there

Relationship to FTMS

A trainer that implements the Trainer Profile SHOULD still implement FTMS, so apps that have not adopted OpenBikeControl keep working over BLE. The two share one control slot (see Control Ownership). FTMS data characteristics stay readable by every client regardless of who owns control.

Apps on BLE MAY use either FTMS or the Trainer Profile for simulation and target power. They MUST NOT use both on the same connection at the same time.


Message Summary

TypeNameDirectionLengthDefined in
0x05Virtual Shifting Controlapp → trainer11VIRTUAL_SHIFTING.md
0x06Virtual Shifting Statetrainer → app11VIRTUAL_SHIFTING.md
0x07Ride Stateapp → trainer5VIRTUAL_SHIFTING.md
0x08Trainer Controlapp → trainer17this document
0x09Trainer Datatrainer → app13this document
0x0ATrainer Statustrainer → app15this document
0x0BCalibration Controlapp → trainer—reserved
0x0CCalibration Statetrainer → app—reserved

Message types 0x05–0x07 are defined by the Virtual Shifting Extension and are part of the Trainer Service. A trainer MAY implement only those three plus Trainer Status; the Virtual Shifting Extension does not require the rest of this profile.


Control Ownership

Exactly one client controls a trainer at a time. This covers Trainer Control, Virtual Shifting Control and Ride State together, and it covers FTMS too.

Acquiring control:

  • The first client that writes Trainer Control or Virtual Shifting Control with a non-idle Mode becomes the owner. There is no separate request message.
  • While an owner exists, control writes from any other client MUST be ignored. The trainer MUST NOT change its behaviour because of them.
  • Ride State messages from a non-owner MUST be ignored.

Releasing control:

  • The owner writes Trainer Control with Mode = 0x00 (idle) and Virtual Shifting Control with Mode = 0x00, or simply disconnects.
  • The trainer MUST release ownership if no message at all has been received from the owner for 30 seconds. Owners SHOULD send at least one message every 10 seconds; an app that streams Ride State satisfies this automatically.

Reporting:

  • Trainer Status carries a Control field telling each client whether it is the owner, whether another OpenBikeControl client is, or whether an FTMS client is. The trainer sends it to every connected client whenever ownership changes.
  • Apps MUST show the rider when they are not the owner. "Connected, but another app is controlling the trainer" is the message that prevents the most support tickets.

Interaction with FTMS:

  • While an OpenBikeControl owner exists, the trainer MUST reject FTMS Request Control with Control Not Permitted and ignore FTMS control point writes.
  • While an FTMS client holds control, the trainer MUST ignore OpenBikeControl control writes and report Control = 0x03 in Trainer Status.
  • FTMS data (Indoor Bike Data) and OpenBikeControl Trainer Data remain available to all clients at all times.

Transport notes:

  • Over BLE most trainers accept a single central, so ownership is usually implicit. The rule still applies to trainers that accept multiple centrals.
  • Over TCP multiple apps commonly connect at once (for example a trainer app on a PC and a bridge app on a phone). The rule is what makes that safe.

Trainer Control (App to Trainer)

Message Type: 0x08

Sets the trainer's operating mode and the simulation or target values. Replaces the FTMS control point Set Indoor Bike Simulation Parameters, Set Target Power, Set Target Resistance Level and Set Wheel Circumference. Sent on change; apps MAY repeat it.

Data Format:

[Message_Type] [Version] [Mode] [Target_Power_L] [Target_Power_H] [Target_Resistance_L] [Target_Resistance_H] [Grade_L] [Grade_H] [Wind_L] [Wind_H] [CRR_L] [CRR_H] [CW_L] [CW_H] [Wheel_Circ_L] [Wheel_Circ_H]

Total length: 17 bytes.

  • Message_Type (1 byte): Always 0x08
  • Version (1 byte): Format version, currently 0x01
  • Mode (1 byte):
    • 0x00 = Idle. Releases control (see above). The trainer applies no resistance beyond its mechanical minimum.
    • 0x01 = Simulation. Resistance follows Grade, Wind, CRR, CW, the virtual gear ratio if active, and the trainer's speed model.
    • 0x02 = Target power (ERG). Resistance follows Target_Power.
    • 0x03 = Target resistance. Resistance is fixed at Target_Resistance.
    • 0x04-0xFF = Reserved; trainers MUST treat these as 0x00
  • Target_Power (2 bytes, uint16): Watts. 0xFFFF = Unchanged.
  • Target_Resistance (2 bytes, uint16): Resistance level in 0.1 %. 0xFFFF = Unchanged.
  • Grade (2 bytes, int16): Simulated grade in 0.01 %. 0x7FFF = Unchanged.
    • Example: 4.50 % → 450 = [0xC2, 0x01]; −3.00 % → −300 = [0xD4, 0xFE]
  • Wind (2 bytes, int16): Simulated wind speed in 0.001 m/s, positive for a headwind. 0x7FFF = Unchanged.
  • CRR (2 bytes, uint16): Rolling resistance coefficient in 0.0001. 0xFFFF = Unchanged.
    • Example: 0.0040 → 40 = [0x28, 0x00]
  • CW (2 bytes, uint16): Wind resistance coefficient in 0.01 kg/m. 0xFFFF = Unchanged.
    • Example: 0.51 kg/m → 51 = [0x33, 0x00]
  • Wheel_Circ (2 bytes, uint16): Wheel circumference in mm. 0xFFFF = Unchanged.
    • Example: 2105 mm → [0x39, 0x08]

Values the trainer does not support are ignored; the capability bits in Trainer Status tell the app in advance which ones will be honoured. "Unchanged" keeps the trainer's current value, so an app can update a single field without resending the rest.

Example Messages:

// Simulation mode, grade 4.50 %, no wind, CRR 0.0040, CW 0.51, wheel 2105 mm
[0x08, 0x01, 0x01, 0xFF, 0xFF, 0xFF, 0xFF, 0xC2, 0x01, 0x00, 0x00, 0x28, 0x00, 0x33, 0x00, 0x39, 0x08]

// Grade update only, −3.00 %
[0x08, 0x01, 0x01, 0xFF, 0xFF, 0xFF, 0xFF, 0xD4, 0xFE, 0xFF, 0x7F, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF]

// ERG mode, 250 W
[0x08, 0x01, 0x02, 0xFA, 0x00, 0xFF, 0xFF, 0xFF, 0x7F, 0xFF, 0x7F, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF]

// Release control
[0x08, 0x01, 0x00, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0x7F, 0xFF, 0x7F, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF]

App Behaviour:

  • Apps SHOULD send grade updates at 1–2 Hz in simulation mode, as they do with FTMS, and immediately on mode changes.
  • Apps SHOULD send Mode = 0x00 before disconnecting.

Trainer Behaviour:

  • Trainers MUST keep the last values until a new message arrives or ownership is released.
  • On release or disconnect, trainers MUST return to Mode = 0x00.
  • Trainers MUST NOT reply to this message. The applied values show up in Trainer Data and the active mode in Trainer Status.

Trainer Data (Trainer to App)

Message Type: 0x09

Periodic measurements from the trainer. Equivalent to FTMS Indoor Bike Data and sent to every connected client, not only the owner.

Data Format:

[Message_Type] [Version] [Flags] [Power_L] [Power_H] [Cadence_L] [Cadence_H] [Speed_L] [Speed_H] [Resistance_L] [Resistance_H] [Grade_L] [Grade_H]

Total length: 13 bytes.

  • Message_Type (1 byte): Always 0x09
  • Version (1 byte): Format version, currently 0x01
  • Flags (1 byte): Bit field marking which fields are valid
    • Bit 0 (0x01) = Power valid
    • Bit 1 (0x02) = Cadence valid
    • Bit 2 (0x04) = Speed valid
    • Bit 3 (0x08) = Resistance valid
    • Bit 4 (0x10) = Grade valid
    • Bit 5 (0x20) = Speed is the simulated bike speed (virtual gearing or app-provided speed in use) rather than the measured flywheel speed
    • Bits 6–7 = Reserved, MUST be 0
  • Power (2 bytes, uint16): Watts
  • Cadence (2 bytes, uint16): 0.5 rpm, matching FTMS
  • Speed (2 bytes, uint16): 0.01 km/h, matching FTMS
  • Resistance (2 bytes, uint16): Applied resistance level in 0.1 %
  • Grade (2 bytes, int16): Applied grade in 0.01 %

Example Message:

// 220 W, 90 rpm, 32.50 km/h, 12.5 % resistance, 4.50 % grade, all valid
[0x09, 0x01, 0x1F, 0xDC, 0x00, 0xB4, 0x00, 0xB2, 0x0C, 0x7D, 0x00, 0xC2, 0x01]

Trainer Behaviour:

  • Trainers SHOULD send Trainer Data at 1–4 Hz while a client is subscribed (BLE) or connected (TCP).
  • Fields marked invalid MUST be sent as 0.

Trainer Status (Trainer to App)

Message Type: 0x0A

Capabilities, limits, control ownership and current mode. Replaces FTMS Fitness Machine Feature, Supported Power/Resistance Range and the control-related parts of Fitness Machine Status. Mandatory for every trainer implementing the Trainer Service; this is how apps discover everything else.

Data Format:

[Message_Type] [Version] [Control] [Mode] [Capabilities_L] [Capabilities_H] [Max_Power_L] [Max_Power_H] [Max_Resistance_L] [Max_Resistance_H] [Max_Grade_L] [Max_Grade_H] [Min_Grade_L] [Min_Grade_H] [Calibration]

Total length: 15 bytes.

  • Message_Type (1 byte): Always 0x0A
  • Version (1 byte): Format version, currently 0x01
  • Control (1 byte): Ownership as seen by the receiving client
    • 0x00 = Nobody controls the trainer
    • 0x01 = The receiving client is the owner
    • 0x02 = Another OpenBikeControl client is the owner
    • 0x03 = An FTMS client holds control
  • Mode (1 byte): Currently active mode, same values as Trainer Control
  • Capabilities (2 bytes, uint16): Bit field
    • Bit 0 (0x0001) = Simulation mode
    • Bit 1 (0x0002) = Target power mode
    • Bit 2 (0x0004) = Target resistance mode
    • Bit 3 (0x0008) = Virtual shifting (0x05/0x06)
    • Bit 4 (0x0010) = Uses app-provided speed (0x07)
    • Bit 5 (0x0020) = Trainer-owned gearing (has its own gear table)
    • Bit 6 (0x0040) = Wheel circumference
    • Bit 7 (0x0080) = Spin-down calibration
    • Bit 8 (0x0100) = Reports power
    • Bit 9 (0x0200) = Reports cadence
    • Bit 10 (0x0400) = Reports speed
    • Bit 11 (0x0800) = Has incline hardware (physical tilt)
    • Bits 12–15 = Reserved, MUST be 0
  • Max_Power (2 bytes, uint16): Highest target power accepted, in W. 0 = Not applicable.
  • Max_Resistance (2 bytes, uint16): Highest resistance level, in 0.1 %. 0 = Not applicable.
  • Max_Grade (2 bytes, int16): Steepest positive grade simulated, in 0.01 %.
  • Min_Grade (2 bytes, int16): Steepest negative grade simulated, in 0.01 %. Trainers that cannot simulate descents report 0.
  • Calibration (1 byte):
    • 0x00 = Not supported / unknown
    • 0x01 = Calibrated
    • 0x02 = Calibration recommended
    • 0x03 = Calibration in progress
    • 0x04 = Last calibration failed

Example Messages:

// Direct-drive trainer: sim, ERG, resistance, virtual shifting, app speed, wheel
// circumference, spin-down, power/cadence/speed; 2000 W, 100 %, +20 % / -10 %;
// this client owns control, simulation active, calibrated
[0x0A, 0x01, 0x01, 0x01, 0xDF, 0x07, 0xD0, 0x07, 0xE8, 0x03, 0xD0, 0x07, 0x18, 0xFC, 0x01]

// Same trainer, but another OpenBikeControl client owns it and runs ERG
[0x0A, 0x01, 0x02, 0x02, 0xDF, 0x07, 0xD0, 0x07, 0xE8, 0x03, 0xD0, 0x07, 0x18, 0xFC, 0x01]

// Smart bike with its own gear table, no app speed, no wheel circumference;
// nobody in control, idle
[0x0A, 0x01, 0x00, 0x00, 0x2F, 0x07, 0xD0, 0x07, 0xE8, 0x03, 0xD0, 0x07, 0x18, 0xFC, 0x01]

Trainer Behaviour:

  • Trainers MUST send Trainer Status once when a client subscribes (BLE) or right after the connection is established (TCP), and again whenever any field changes.
  • When ownership changes, Trainer Status MUST be sent to every connected client, because the Control value differs per client.

Calibration (Reserved)

Message types 0x0B (Calibration Control, app to trainer) and 0x0C (Calibration State, trainer to app) are reserved for a spin-down procedure and will be specified separately. Until then, trainers report calibration state in Trainer Status and perform calibration through FTMS or their vendor app.


Transport Mapping

BLE: Trainer Service

Service UUID: d273f690-d548-419d-b9d1-fa0472345229

CharacteristicUUIDPropertiesMessageRequired
Virtual Shifting Controld273f691-d548-419d-b9d1-fa0472345229Write, Write Without Response0x05if capability bit 3
Virtual Shifting Stated273f692-d548-419d-b9d1-fa0472345229Read, Notify0x06if capability bit 3
Ride Stated273f693-d548-419d-b9d1-fa0472345229Write Without Response0x07if capability bit 4
Trainer Controld273f694-d548-419d-b9d1-fa0472345229Write, Write Without Response0x08if capability bits 0–2
Trainer Datad273f695-d548-419d-b9d1-fa0472345229Read, Notify0x09if capability bits 8–10
Trainer Statusd273f696-d548-419d-b9d1-fa0472345229Read, Notify0x0Ayes

The Trainer Service is separate from the controller service (d273f680-…). A smart bike with shifters and buttons exposes both; a direct-drive trainer exposes only the Trainer Service; a handlebar remote only the controller service. The Button State characteristic on the controller service is unchanged by this profile.

Advertisement: Trainers advertise the Trainer Service UUID. A device that offers both services cannot fit two 128-bit UUIDs into one advertising packet; such devices SHOULD put the controller service UUID in the advertising packet and the Trainer Service UUID in the scan response. Apps MUST discover services after connecting rather than relying on the advertisement alone.

mDNS / TCP

The Trainer Service UUID is listed in the service-uuids TXT record field, which is how apps discover trainers on the network. All trainer messages share the TCP connection with the controller messages, each prefixed with its length as described in Message Framing. This matters here more than for controllers, since Trainer Data and Ride State are continuous streams.


See Also