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. Example Implementation
  3. Service UUID
  4. Characteristics
  5. 1. Button State Characteristic (READ/NOTIFY)
  6. 2. Haptic Feedback Characteristic (WRITE)
  7. 3. App Information Characteristic (WRITE)
  8. Trainer Service (Optional)
  9. Standard BLE Services
  10. Device Information Service (0x180A)
  11. Battery Service (0x180F)
  12. Advertisement Requirements
  13. Connection Parameters
  14. Implementation Guidelines
  15. For App Developers
  16. For Device Manufacturers
  17. See Also

BLE Protocol Specification

Overview

The Bluetooth Low Energy (BLE) implementation provides direct device-to-app connections for OpenBikeControl devices.


Example Implementation

Sometimes it's easier to understand the protocol by looking at a concrete example:

Service UUID

Primary Service UUID: d273f680-d548-419d-b9d1-fa0472345229

This service UUID is used for OpenBikeControl device advertisement and discovery.


Characteristics

1. Button State Characteristic (READ/NOTIFY)

UUID: d273f681-d548-419d-b9d1-fa0472345229

Properties: Read, Notify

Description: Reports the state of all buttons on the controller.

Data Format:

The characteristic value uses the same binary format as the mDNS protocol for consistency:

[Message_Type] [Button_ID_1] [State_1] [Button_ID_2] [State_2] ... [Button_ID_N] [State_N]
  • Message_Type (1 byte): Always 0x01 for button state messages
  • Button_ID (1 byte): Identifier for the button (see Button Mapping section)
  • State (1 byte): Current state of the button
    • 0x00 = Released/Off
    • 0x01 = Pressed/On
    • 0x02-0xFF = Analog value (for analog inputs like triggers or joysticks, where 0x02 = minimum, 0xFF = maximum)

Notification Behavior:

  • Notifications MUST be sent only when a button state changes
  • Include all changed buttons in a single notification to minimize BLE traffic
  • If multiple buttons change simultaneously, combine them in one notification
  • Maximum recommended payload: 20 bytes (1 message type + 9 button state pairs)

Example Notifications:

// Single button press (button 0x01 pressed)
[0x01, 0x01, 0x01]

// Multiple buttons (button 0x01 pressed, button 0x02 released)
[0x01, 0x01, 0x01, 0x02, 0x00]

// Analog input (button 0x10 at 50% = 0x80)
[0x01, 0x10, 0x80]

2. Haptic Feedback Characteristic (WRITE)

UUID: d273f682-d548-419d-b9d1-fa0472345229

Properties: Write, Write Without Response

Description: Receives haptic feedback commands from the app to provide tactile feedback on the device.

Data Format:

The characteristic value uses the same binary format as the mDNS protocol for consistency:

[Message_Type] [Pattern] [Duration] [Intensity]
  • Message_Type (1 byte): Always 0x03 for haptic feedback commands

  • Pattern (1 byte): Type of haptic feedback pattern

    • 0x00 = No haptic (stop)
    • 0x01 = Single short vibration
    • 0x02 = Double pulse
    • 0x03 = Triple pulse
    • 0x04 = Long vibration
    • 0x05 = Success pattern (crescendo)
    • 0x06 = Warning pattern (two short pulses)
    • 0x07 = Error pattern (three short pulses)
    • 0x08-0xFF = Reserved for future patterns
  • Duration (1 byte): Duration of the haptic feedback in units of 10ms

    • 0x00 = Use default duration for pattern
    • 0x01-0xFF = Duration in 10ms units (e.g., 0x0A = 100ms, 0x64 = 1000ms)
    • Maximum recommended duration: 0x64 (1000ms)
  • Intensity (1 byte): Vibration intensity level

    • 0x00 = No vibration (off)
    • 0x01-0x7F = Low to medium intensity
    • 0x80-0xFF = Medium to maximum intensity
    • 0x00 = Use default intensity for pattern

Example Commands:

// Single short vibration with default settings
[0x03, 0x01, 0x00, 0x00]

// Double pulse, 200ms duration, medium intensity (128)
[0x03, 0x02, 0x14, 0x80]

// Success pattern with maximum intensity
[0x03, 0x05, 0x00, 0xFF]

// Stop all haptic feedback
[0x03, 0x00, 0x00, 0x00]

Write Behavior:

  • Apps can send haptic feedback commands at any time
  • Commands are executed immediately upon receipt
  • If a new command is received while haptic feedback is active, the current pattern is interrupted and the new pattern starts immediately
  • Devices should acknowledge commands if "Write" property is used, but may use "Write Without Response" for lower latency
  • If the device does not support haptic feedback, it should accept the writes but perform no action

Use Cases:

  • Confirmation feedback when button press is registered
  • Success/error feedback for virtual gear changes
  • Navigation feedback (e.g., reaching menu boundaries)
  • Power-up activation confirmation
  • Training milestone celebrations

3. App Information Characteristic (WRITE)

UUID: d273f683-d548-419d-b9d1-fa0472345229

Properties: Write, Write Without Response

Description: Receives information from the app about its identity and capabilities. This allows devices to provide better user feedback, customize button mappings, or enable app-specific features.

Data Format:

The characteristic value uses the same binary format as the mDNS protocol for consistency:

[Message_Type] [Version] [App_ID_Length] [App_ID...] [App_Version_Length] [App_Version...] [Button_Count] [Button_IDs...]
  • Message_Type (1 byte): Always 0x04 for app information messages
  • Version (1 byte): Format version, currently 0x01
  • App_ID_Length (1 byte): Length of the App ID string (0-32 characters)
  • App_ID (variable): UTF-8 encoded app identifier string
    • Should be lowercase, alphanumeric with optional hyphens/underscores
    • Examples: "zwift", "trainerroad", "rouvy", "my-custom-app"
  • App_Version_Length (1 byte): Length of the App Version string (0-32 characters)
  • App_Version (variable): UTF-8 encoded app version string
    • Recommended to follow semantic versioning format
    • Examples: "1.52.0", "2.0.1-beta"
  • Button_Count (1 byte): Number of supported button IDs (0-255)
    • 0 indicates the app supports all button types
  • Button_IDs (variable): Array of button ID bytes
    • Each byte represents a supported button ID from Button Mapping
    • Devices can use this to provide visual feedback or customize layouts

Example Data:

// App: "zwift", Version: "1.52.0", Buttons: [0x01, 0x02, 0x10, 0x14]
[0x04, 0x01, 0x05, 'z', 'w', 'i', 'f', 't', 0x06, '1', '.', '5', '2', '.', '0', 0x04, 0x01, 0x02, 0x10, 0x14]

Write Behavior:

  • Apps SHOULD send this information immediately after connecting to the device
  • Apps MAY send updated information if capabilities change during the session
  • Commands are processed immediately upon receipt
  • Devices SHOULD handle the absence of this message gracefully (assume all buttons supported)
  • If a new message is received, it replaces the previous app information
  • Devices should acknowledge commands if "Write" property is used, but may use "Write Without Response" for simplicity
  • The written value will be emptied on every disconnect

Note: This characteristic is optional for apps to implement, but the information is important for devices to provide the best user experience (e.g., highlighting supported buttons, customizing layouts for specific apps).

Use Cases:

  • Device displays app name/version on screen or LEDs
  • Device highlights or enables only supported buttons
  • Device customizes button layouts for popular apps
  • Device logs connection history for diagnostics
  • Device provides app-specific haptic patterns or feedback

Maximum Payload Size:

The maximum size of this characteristic depends on MTU, but should aim to fit within standard MTU (23 bytes data):

  • Message Type (1) + Version (1) + Max App ID (1+32) + Max Version (1+32) + Button Count (1) = 69 bytes minimum
  • Recommended to keep App ID + Version under 40 characters combined for compatibility
  • For longer values, increase MTU negotiation or truncate gracefully

Trainer Service (Optional)

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

Smart trainers and smart bikes expose a second service for trainer control and data. It is separate from the controller service above, so the Button State characteristic stays unchanged for devices that are both a controller and a trainer. Controllers that are not trainers do not implement it.

CharacteristicUUIDPropertiesMessage typeSpec
Virtual Shifting Controld273f691-d548-419d-b9d1-fa0472345229Write, Write Without Response0x05VIRTUAL_SHIFTING.md
Virtual Shifting Stated273f692-d548-419d-b9d1-fa0472345229Read, Notify0x06VIRTUAL_SHIFTING.md
Ride Stated273f693-d548-419d-b9d1-fa0472345229Write Without Response0x07VIRTUAL_SHIFTING.md
Trainer Controld273f694-d548-419d-b9d1-fa0472345229Write, Write Without Response0x08TRAINER.md
Trainer Datad273f695-d548-419d-b9d1-fa0472345229Read, Notify0x09TRAINER.md
Trainer Statusd273f696-d548-419d-b9d1-fa0472345229Read, Notify0x0ATRAINER.md

Each message type maps to its own characteristic. The message type byte is still the first byte of every value, so the same bytes can be sent over TCP, where all messages share one stream.

Trainer Status is mandatory; everything else is announced by its capability bits. The trainer never answers a write directly: it notifies the matching state characteristic whenever something changes. Only one client controls a trainer at a time, see Control Ownership.

Advertisement: Trainers advertise the Trainer Service UUID. Devices offering both services SHOULD advertise the controller service UUID in the advertising packet and the Trainer Service UUID in the scan response, since two 128-bit UUIDs do not fit in one packet. Apps MUST discover services after connecting.


Standard BLE Services

OpenBikeControl devices MUST implement the following standard BLE services:

Device Information Service (0x180A)

Required characteristics:

  • Manufacturer Name String (0x2A29) - Device manufacturer
  • Model Number String (0x2A24) - Device model
  • Serial Number String (0x2A25) - Unique device serial
  • Hardware Revision String (0x2A27) - Hardware version
  • Firmware Revision String (0x2A26) - Firmware version
  • Software Revision String (0x2A28) - Optional software version

Battery Service (0x180F)

Required for battery-powered devices:

  • Battery Level (0x2A19) - Current battery percentage (0-100)

CRITICAL: OpenBikeControl devices MUST NOT rely on manufacturer-specific data in BLE advertisements. This restriction ensures compatibility with Apple iOS devices, which do not allow apps to emulate manufacturer data.

Advertisement Data:

  • Service UUIDs: Must advertise the primary service UUID d273f680-d548-419d-b9d1-fa0472345229
  • Flags: General discoverable mode, BR/EDR not supported

Example Advertisement:

Flags: 0x06 (LE General Discoverable, BR/EDR not supported)
Complete List of 128-bit Service UUIDs: d273f680-d548-419d-b9d1-fa0472345229

Connection Parameters

Recommended BLE connection parameters for optimal performance:

  • Connection Interval: 7.5-15ms (for low latency)
  • Slave Latency: 0 (for immediate response)
  • Supervision Timeout: 4 seconds
  • MTU Size: 23 bytes minimum, 247 bytes preferred

Implementation Guidelines

For App Developers

  1. Device Discovery:

    • Scan for devices advertising service UUID d273f680-d548-419d-b9d1-fa0472345229
    • Filter by device name if needed
  2. Connection:

    • Connect and discover the OpenBikeControl service
    • Discover Button State characteristic (d273f681-d548-419d-b9d1-fa0472345229)
    • Discover Haptic Feedback characteristic (d273f682-d548-419d-b9d1-fa0472345229)
    • Subscribe to Button State notifications for real-time button updates
    • Optional: discover the Trainer Service (d273f690-d548-419d-b9d1-fa0472345229) and subscribe to Trainer Status to detect smart trainers and their capabilities (see TRAINER.md)
  3. Button Handling:

    • Map button IDs to app-specific actions (see Button Mapping)
    • Parse notification data to extract button state changes
    • Handle multiple simultaneous button presses
  4. Haptic Feedback:

    • Send haptic commands to provide tactile feedback
    • Use appropriate patterns for different actions (success, error, confirmation)
    • Consider user preferences for haptic intensity

For Device Manufacturers

  1. Hardware:

    • Use reliable button switches for digital inputs
    • Optional: Consider hall-effect sensors for analog inputs
    • Optional: Include vibration motor for haptic feedback
    • Include battery monitoring circuitry for battery level reporting
  2. Firmware:

    • Implement efficient button debouncing (10-50ms)
    • Only send notifications on state changes
    • Batch multiple button changes in one notification
    • Implement haptic feedback patterns if hardware supports it
    • Handle gracefully if haptic commands are received but hardware doesn't support it
  3. Power Management:

    • Implement BLE sleep modes when inactive
    • Wake on button press
    • Report accurate battery levels
    • Consider power consumption of haptic motor
  4. Testing:

    • Verify range and reliability
    • Test haptic feedback patterns and intensities
    • Ensure no interference with other BLE devices (trainers, heart rate monitors)
    • Validate notification timing and latency

See Also