Trainer Profile
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:
- 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.
- 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.
- 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
| Type | Name | Direction | Length | Defined in |
|---|---|---|---|---|
0x05 | Virtual Shifting Control | app → trainer | 11 | VIRTUAL_SHIFTING.md |
0x06 | Virtual Shifting State | trainer → app | 11 | VIRTUAL_SHIFTING.md |
0x07 | Ride State | app → trainer | 5 | VIRTUAL_SHIFTING.md |
0x08 | Trainer Control | app → trainer | 17 | this document |
0x09 | Trainer Data | trainer → app | 13 | this document |
0x0A | Trainer Status | trainer → app | 15 | this document |
0x0B | Calibration Control | app → trainer | — | reserved |
0x0C | Calibration State | trainer → 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
Modebecomes 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 withMode = 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
Controlfield 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 = 0x03in 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 followsGrade,Wind,CRR,CW, the virtual gear ratio if active, and the trainer's speed model.0x02= Target power (ERG). Resistance followsTarget_Power.0x03= Target resistance. Resistance is fixed atTarget_Resistance.0x04-0xFF= Reserved; trainers MUST treat these as0x00
- 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]
- Example: 4.50 % →
- 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]
- Example: 0.0040 →
- CW (2 bytes, uint16): Wind resistance coefficient in 0.01 kg/m.
0xFFFF= Unchanged.- Example: 0.51 kg/m →
51=[0x33, 0x00]
- Example: 0.51 kg/m →
- Wheel_Circ (2 bytes, uint16): Wheel circumference in mm.
0xFFFF= Unchanged.- Example: 2105 mm →
[0x39, 0x08]
- Example: 2105 mm →
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 = 0x00before 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) =Powervalid - Bit 1 (
0x02) =Cadencevalid - Bit 2 (
0x04) =Speedvalid - Bit 3 (
0x08) =Resistancevalid - Bit 4 (
0x10) =Gradevalid - Bit 5 (
0x20) =Speedis 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
- Bit 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 trainer0x01= The receiving client is the owner0x02= Another OpenBikeControl client is the owner0x03= 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
- Bit 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 / unknown0x01= Calibrated0x02= Calibration recommended0x03= Calibration in progress0x04= 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
Controlvalue 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
| Characteristic | UUID | Properties | Message | Required |
|---|---|---|---|---|
| Virtual Shifting Control | d273f691-d548-419d-b9d1-fa0472345229 | Write, Write Without Response | 0x05 | if capability bit 3 |
| Virtual Shifting State | d273f692-d548-419d-b9d1-fa0472345229 | Read, Notify | 0x06 | if capability bit 3 |
| Ride State | d273f693-d548-419d-b9d1-fa0472345229 | Write Without Response | 0x07 | if capability bit 4 |
| Trainer Control | d273f694-d548-419d-b9d1-fa0472345229 | Write, Write Without Response | 0x08 | if capability bits 0–2 |
| Trainer Data | d273f695-d548-419d-b9d1-fa0472345229 | Read, Notify | 0x09 | if capability bits 8–10 |
| Trainer Status | d273f696-d548-419d-b9d1-fa0472345229 | Read, Notify | 0x0A | yes |
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.