OpenBikeControl is an open protocol for wireless input devices to control cycling trainer applications. It enables standardized communication between BLE controllers, apps, and the training app itself.
Many cycling trainer apps support various actions that traditionally require:
- On-screen button clicks
- Keyboard input
- Proprietary BLE controllers
OpenBikeControl provides a unified, open protocol that:
- Easy to implement - Simple data format with minimal overhead
- Open standard - No licensing fees or proprietary restrictions
- Dual connectivity - Supports both BLE and network-based connections
- Already partially adopted - Similar technology as the existing "Direct Connect" implementations
- Apple-friendly - Does not rely on manufacturer data fields that cannot be emulated on iOS
OpenBikeControl enables the following trainer app actions:
- Virtual gear shifting - Up/down shifting for smart trainer devices
- Navigation - Menu navigation, route selection, steering controls
- UI controls - Select, back, confirm buttons
- Social features - Emotes (wave, thumbs up, ride on, etc.)
- Training controls - ERG mode adjustments, workout skips
- Custom actions - App-specific features
OpenBikeControl uses two transport mechanisms:
- BLE (Bluetooth Low Energy) - For direct device-to-app connections, or as a fallback for apps if mDNS is not possible
- mDNS (Multicast DNS) - For network-based connections ("Direct Connect")
Both transports use the identical binary message format (including the message type prefix byte), ensuring consistency across connection types.
BLE Protocol:
- Service UUID:
d273f680-d548-419d-b9d1-fa0472345229 - Button State Characteristic (Read/Notify):
d273f681-d548-419d-b9d1-fa0472345229 - Haptic Feedback Characteristic (Write):
d273f682-d548-419d-b9d1-fa0472345229 - App Information Characteristic (Write):
d273f683-d548-419d-b9d1-fa0472345229 - Message types:
0x01(button state),0x03(haptic feedback),0x04(app info) - See BLE.md for complete specification
mDNS Protocol:
- Service Type:
_openbikecontrol._tcp.local. - TCP endpoint:
<device-ip>:<port> - Binary data format (identical to BLE)
- Message types:
0x01(button state),0x02(device status),0x03(haptic feedback),0x04(app info) - See MDNS.md for complete specification
OpenBikeControl defines standard button IDs for common actions. Device manufacturers should map their physical buttons to these standard IDs.
| Button ID | Action | Description |
|---|---|---|
0x01 |
Shift Up | Increase virtual gear |
0x02 |
Shift Down | Decrease virtual gear |
0x03 |
Gear Set | Direct gear selection (use analog value) |
| Button ID | Action | Description |
|---|---|---|
0x10 |
Up | Navigate up in menus |
0x11 |
Down | Navigate down in menus |
0x12 |
Left | Navigate left / Look left |
0x13 |
Right | Navigate right / Look right |
0x14 |
Select/Confirm | Confirm selection |
0x15 |
Back/Cancel | Go back / Cancel |
0x16 |
Menu | Open menu |
0x17 |
Home | Return to home screen |
0x18 |
Steer Left | Steer left in-game |
0x19 |
Steer Right | Steer right in-game |
| Button ID | Action | Description |
|---|---|---|
0x20 |
Emote | Send social emote (use analog value to specify emote type) |
0x21 |
Push to Talk | Activate microphone for voice input |
Emote Analog Values:
0x00= No emote / Released0x01= Pressed (cycle through emotes)0x02-0x1F= Reserved for app-specific emotes
| Button ID | Action | Description |
|---|---|---|
0x30 |
Increase Difficulty | Increase workout intensity / workout difficulty / increase ERG mode power |
0x31 |
Decrease Difficulty | Decrease workout intensity / workout difficulty / decrease ERG mode power |
0x32 |
Skip Interval | Skip to next workout interval |
0x33 |
Pause | Pause workout |
0x34 |
Resume | Resume workout |
0x35 |
Lap | Mark lap |
0x36 |
Previous Internal | Skip to previous workout interval |
0x37 |
U-Turn | Perform U-Turn |
0x38 |
Change Mode | Toggle between modes, e.g. ERG and others |
0x39 |
Take a break | Take a break |
0x3A |
Join another rider | "Teleport" to another rider |
0x3B |
Change route | Show route change selection |
| Button ID | Action | Description |
|---|---|---|
0x40 |
Camera View | Select camera view (use analog value to specify view) |
0x44 |
HUD Toggle | Show/hide HUD |
0x45 |
Map Toggle | Show/hide map |
0x46 |
Spectate rider | Spectate another rider |
Camera View Analog Values:
0x00= No change / Released0x01= Pressed (cycle through camera views)0x02-0x1F= Reserved for app-specific camera views
| Button ID | Action | Description |
|---|---|---|
0x50 |
Power-up 1 | Activate power-up slot 1 |
0x51 |
Power-up 2 | Activate power-up slot 2 |
0x52 |
Power-up 3 | Activate power-up slot 3 |
| Range | Purpose |
|---|---|
0x60-0x7F |
Reserved for future standard actions |
0x80-0x9F |
App-specific custom actions |
0xA0-0xFF |
Manufacturer-specific custom actions |
Apps may implement multi-button combinations by detecting multiple simultaneous button presses. For example:
- Shift Up + Shift Down simultaneously = Reset gear to neutral
- Menu + Select = Quick settings
Hardware or software (such as BikeControl) can send multiple actions per button press to maximize flexibility and compatibility across different trainer apps. This allows a single physical button to trigger multiple related actions simultaneously, with the app deciding which action to respond to based on its capabilities.
Example Use Case:
A "Plus" button on a controller could send three different actions at once:
0x01(Shift Up) - For apps that support virtual gear shifting0x30(ERG Up) - For apps that support ERG mode power adjustment0x14(Select/Confirm) - For apps that use it for menu navigation
Implementation:
When a button is pressed, send a single button state message containing all relevant action IDs:
[0x01, 0x01, 0x01, 0x30, 0x01, 0x14, 0x01]
This means: Shift Up pressed (0x01, 0x01), ERG Up pressed (0x30, 0x01), and Select pressed (0x14, 0x01).
Benefits:
- Compatibility: Works with any app that supports at least one of the actions
- Flexibility: Easy to remap hardware buttons through software configuration
- Discovery: Apps communicate supported actions via the App Information Characteristic, allowing devices to optimize button mappings
- User Experience: Physical buttons can have consistent behavior across different apps
Guidelines for Device Manufacturers:
- Group related actions that make sense together (e.g., shift up, increase resistance, navigate up)
- Allow users to customize which actions are sent per button
- Use the App Information Characteristic to understand which actions the app supports
- Consider providing visual feedback on the device about which actions are active
Guidelines for App Developers:
- Process only the button IDs your app supports, ignoring others
- Send the App Information Characteristic after connecting to inform devices of supported actions
- Handle multiple simultaneous button presses gracefully
-
BLE Implementation:
- Scan for devices advertising service UUID
d273f680-d548-419d-b9d1-fa0472345229 - Connect and discover the Button State characteristic (
d273f681-d548-419d-b9d1-fa0472345229) - Discover the Haptic Feedback characteristic (
d273f682-d548-419d-b9d1-fa0472345229) - Subscribe to notifications for real-time button updates
- Send haptic feedback commands for tactile feedback
- Map button IDs to app-specific actions
- See BLE.md for detailed BLE implementation
- Scan for devices advertising service UUID
-
mDNS Implementation:
- Use Bonjour/Zeroconf libraries to discover
_openbikecontrol._tcp.local.services - Connect via TCP for real-time updates
- Parse TXT records to get device information and service UUIDs
- Use same binary format as BLE for button states and commands
- See MDNS.md for detailed mDNS implementation
- Use Bonjour/Zeroconf libraries to discover
-
Button Mapping:
- Provide user configuration for custom button mappings
- Use standard button IDs as defaults
- Allow users to override mappings for their workflow
-
Multi-Device Support:
- Support connecting multiple OpenBikeControl devices simultaneously
- Allow users to assign devices to specific action categories
-
Hardware:
- Use reliable button switches for digital inputs
- Consider hall-effect sensors for analog inputs
- Include vibration motor for haptic feedback (optional but recommended)
- Include battery monitoring circuitry for battery level reporting
-
Firmware:
- Implement efficient button debouncing (10-50ms)
- Only send notifications on state changes
- Batch multiple button changes in one notification
- Support both BLE and mDNS for maximum compatibility
- Use same binary data format for both BLE and TCP
- Implement haptic feedback if hardware supports it
-
Power Management:
- Implement BLE sleep modes when inactive
- Wake on button press
- Report accurate battery levels
-
Testing:
- Verify range and reliability
- Ensure no interference with other BLE devices (trainers, heart rate monitors)
To ensure quality and compatibility, OpenBikeControl offers a voluntary certification program for device manufacturers. See CERTIFICATION.md for details.
Certified devices receive:
- Official listing in the OpenBikeControl device directory
- Compatibility badge for marketing materials
- Technical support for implementation
- Button mapping presets included in participating apps
- Version 1 (Current)
- Initial protocol specification
- BLE and mDNS transport definitions
- Standard button mappings
- Certification program launch
- Bluetooth SIG - GATT Services
- Apple Core Bluetooth Programming Guide
- mDNS/Bonjour Specification (RFC 6762)
The OpenBikeControl Protocol specification is released under the MIT License, allowing free implementation in both commercial and open-source projects.
For questions, suggestions, or contributions, please refer to the repository documentation.
The protocol is designed to evolve with community feedback while maintaining backward compatibility.