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 Discovery
  4. TCP Protocol
  5. Data Format
  6. Button State Message (Device to App)
  7. Device Status Message (Device to App)
  8. Haptic Feedback Command (App to Device)
  9. App Information (App to Device)
  10. Virtual Shifting Control (App to Trainer)
  11. Virtual Shifting State (Trainer to App)
  12. Ride State (App to Trainer)
  13. Trainer Control (App to Trainer)
  14. Trainer Data (Trainer to App)
  15. Trainer Status (Trainer to App)
  16. Message Framing
  17. Why
  18. Frame Format
  19. Compatibility
  20. Implementation Guidelines
  21. For App Developers
  22. For Device Manufacturers
  23. Comparison with BLE
  24. See Also

mDNS Protocol Specification

Overview

The mDNS (Multicast DNS) implementation provides network-based connectivity for OpenBikeControl devices, similar to the "Direct Connect" protocol. This allows devices to communicate with apps over WiFi/Ethernet networks using TCP sockets.

Example Implementation

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


Service Discovery

Service Type: _openbikecontrol._tcp.local.

Service Name Format: <Device Name>._openbikecontrol._tcp.local.

TXT Record Fields:

The TXT record fields mirror BLE advertisement data:

  • version=2 - Protocol version. Version 2 devices prefix every TCP message with its length, see Message Framing
  • id=<unique-id> - Unique device identifier (MAC address or serial)
  • name=<device-name> - Human-readable device name
  • service-uuids=<uuid-list> - Comma-separated list of service UUIDs, showcasing the hardwares' capabilities. Controllers list d273f680-d548-419d-b9d1-fa0472345229; smart trainers list the Trainer Service d273f690-d548-419d-b9d1-fa0472345229 (see TRAINER.md); smart bikes list both
  • manufacturer=<name> - Device manufacturer
  • model=<model> - Device model

Example:

Service: OpenBikeControl Remote._openbikecontrol._tcp.local.
Port: 8080
TXT:
  version=2
  id=aabbccddeeff
  name=OpenBikeControl Remote
  service-uuids=d273f680-d548-419d-b9d1-fa0472345229
  manufacturer=ExampleCorp
  model=SC-100

TCP Protocol

Once discovered via mDNS/Bonjour, apps connect to the device using TCP sockets for real-time communication.

Connection:

  • Apps initiate TCP connection to <device-ip>:<port> after discovering the device via mDNS
  • Connection should be maintained for the duration of the session
  • Reconnection should be automatic if connection is lost

Data Format

All messages use the same binary format as the BLE protocol for consistency and efficiency.

On TCP, every message is prefixed with its length so receivers can split the byte stream into messages; see Message Framing. The message formats below describe the bytes inside a frame.

Button State Message (Device to App)

Message Type: 0x01

Sent when one or more button states change.

Data Format:

[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)
  • 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)

Example Messages:

// 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]

Device Status Message (Device to App)

Message Type: 0x02

Sent periodically or on status changes.

Data Format:

[Message_Type] [Battery] [Connected]
  • Message_Type (1 byte): Always 0x02 for device status messages
  • Battery (1 byte): Battery level percentage (0-100), or 0xFF if not applicable
  • Connected (1 byte): Device connection state
    • 0x00 = Not connected/ready
    • 0x01 = Connected and ready for input

Example Message:

// Device with 85% battery, connected
[0x02, 0x55, 0x01]

// Device without battery monitoring, connected
[0x02, 0xFF, 0x01]

Haptic Feedback Command (App to Device)

Message Type: 0x03

Sent by the app to trigger haptic feedback on the device.

Data Format:

[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 = Use default intensity for pattern
    • 0x01-0x7F = Low to medium intensity
    • 0x80-0xFF = Medium to maximum intensity

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]

App Information (App to Device)

Message Type: 0x04

Sent by the app to inform the device about the app's identity and capabilities. This allows devices to provide better user feedback, customize button mappings, or enable app-specific features.

Data Format:

[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]

Usage:

  • Apps SHOULD send this message immediately after establishing the TCP connection
  • Apps MAY send updated information if capabilities change during the session
  • Devices SHOULD handle the absence of this message gracefully (assume all buttons supported)
  • The app information is cleared when the TCP connection is closed

Note: This message 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).


Virtual Shifting Control (App to Trainer)

Message Type: 0x05

Optional, for smart trainers and smart bikes. Sent by the app to set the simulated gear ratio, rider mass and bike mass.

Data Format:

[0x05] [Version] [Mode] [Gear_Ratio_L] [Gear_Ratio_H] [Rider_Mass_L] [Rider_Mass_H] [Bike_Mass_L] [Bike_Mass_H] [Gear_Index] [Gear_Count]

Fixed length of 11 bytes. Field definitions, examples and behaviour are specified in VIRTUAL_SHIFTING.md.


Virtual Shifting State (Trainer to App)

Message Type: 0x06

Optional, for smart trainers and smart bikes. Sent by the trainer once right after the TCP connection is accepted (so the app can detect support) and whenever its state changes.

Data Format:

[0x06] [Version] [Flags] [Gear_Ratio_L] [Gear_Ratio_H] [Gear_Index] [Gear_Count] [Front_Index] [Front_Count] [Rear_Index] [Rear_Count]

Fixed length of 11 bytes. Field definitions, examples and behaviour are specified in VIRTUAL_SHIFTING.md.


Ride State (App to Trainer)

Message Type: 0x07

Optional, for smart trainers and smart bikes. Sent by the app at 1–4 Hz with the simulated bike speed so the trainer can align its inertia and gravity simulation with the on-screen speed.

Data Format:

[0x07] [Version] [Speed_L] [Speed_H] [Reserved]

Fixed length of 5 bytes. Field definitions, examples and behaviour are specified in VIRTUAL_SHIFTING.md.


Trainer Control (App to Trainer)

Message Type: 0x08

Optional, for smart trainers and smart bikes. Sets mode (idle, simulation, target power, target resistance) and the simulation or target values.

Data Format:

[0x08] [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]

Fixed length of 17 bytes. Field definitions, examples and behaviour are specified in TRAINER.md.


Trainer Data (Trainer to App)

Message Type: 0x09

Optional, for smart trainers and smart bikes. Power, cadence, speed, applied resistance and grade, sent at 1–4 Hz to every connected client.

Data Format:

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

Fixed length of 13 bytes. Field definitions, examples and behaviour are specified in TRAINER.md.


Trainer Status (Trainer to App)

Message Type: 0x0A

Mandatory for smart trainers and smart bikes. Capabilities, limits, control ownership and active mode. Sent right after the connection is established and whenever any field changes. Because the Control field is per client, the trainer sends it to every connected client when ownership changes.

Data Format:

[0x0A] [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]

Fixed length of 15 bytes. Field definitions, examples and behaviour are specified in TRAINER.md.


Message Framing

Why

TCP is a byte stream, not a message stream. Two messages written separately can arrive in a single read, and one message can be split across two reads. Without a length field a receiver that treats each read as one message will misparse merged messages:

Written:  [0x01, 0x1B, 0x85]  [0x01, 0x1B, 0x86]
Read as:  [0x01, 0x1B, 0x85, 0x01, 0x1B, 0x86]
Parsed:   0x1B = 0x85, 0x01 (Shift Up) = 0x1B, 0x86 = <dangling>

The middle pair is read as a Shift Up press. This rarely happens with occasional button presses, but becomes common with continuously streamed values such as the Steering Angle (0x1B).

Frame Format

Every TCP message in both directions is prefixed with its length:

[Length_Hi] [Length_Lo] [Message_Type] [Payload...]
  • Length (2 bytes, big-endian): number of bytes that follow, i.e. Message_Type + Payload. MUST be at least 1 and at most 512.
  • Message_Type and Payload: the message as defined in Data Format.

Example: a button state message [0x01, 0x1B, 0x94] is sent as [0x00, 0x03, 0x01, 0x1B, 0x94].

Receivers MUST buffer incoming bytes and only process a message once all Length bytes have arrived. Receivers MUST skip (but still consume) messages with an unknown Message_Type. A receiver that reads a Length of 0 or above 512 MUST close the connection.

Framing applies to TCP only. BLE is unchanged: each notification or write is already exactly one message.

Compatibility

Framing is mandatory in protocol version 2 and is not backwards compatible with version 1, which wrote messages to the stream without a length. There is no negotiation: a version 2 app and a version 2 device frame everything from the first byte. Apps that still need to talk to version=1 devices MUST select unframed parsing based on the TXT record, and device firmware SHOULD be updated to version 2.


Implementation Guidelines

For App Developers

  1. Service Discovery:

    • Use Bonjour/Zeroconf libraries to discover _openbikecontrol._tcp.local. services
    • Parse TXT records to get device information
    • Extract IP address and port for TCP connection
  2. TCP Connection:

    • Connect to <device-ip>:<port> using a standard TCP socket
    • Implement automatic reconnection on connection loss
    • Handle binary message parsing and routing
  3. Message Handling:

    • Read the 2-byte length first and buffer until the full message has arrived (see Message Framing)
    • First byte of the message indicates the message type
    • Parse remaining bytes according to message type format
    • Button state messages (0x01) have variable length depending on number of buttons
    • Status messages (0x02) are always 3 bytes
    • Haptic feedback commands (0x03) are always 4 bytes
    • App info messages (0x04) have variable length
    • Virtual shifting messages (0x05, 0x06) are always 11 bytes
    • Ride state messages (0x07) are always 5 bytes
    • Trainer control (0x08), data (0x09) and status (0x0A) are 17, 13 and 15 bytes
  4. Button Handling:

    • Listen for button state messages (type 0x01)
    • Map button IDs to app-specific actions (see Button Mapping)
    • Handle multiple simultaneous button presses
  5. Haptic Feedback:

    • Send haptic feedback messages (type 0x03) to provide tactile feedback
    • Use appropriate patterns for different actions
    • Duration is in 10ms units, intensity from 0-255
  6. Status Monitoring:

    • Monitor device status messages (type 0x02) for battery level
    • Handle disconnection gracefully
    • Display connection status to user

For Device Manufacturers

  1. Network Setup:

    • Implement WiFi connectivity (Station mode or AP mode)
    • Advertise mDNS service on network
    • Implement TCP server
  2. Service Advertisement:

    • Advertise _openbikecontrol._tcp.local. service
    • Include all required TXT record fields
    • Update TXT records if device information changes
  3. TCP Server:

    • Listen on configured port for incoming TCP connections
    • Support multiple simultaneous connections
    • Send button state messages as binary data, each prefixed with its length
    • Handle haptic feedback and app info commands from apps
  4. Message Handling:

    • Send button state messages (type 0x01) only on state changes
    • Send periodic device status updates (type 0x02) every 30-60 seconds
    • Process haptic feedback commands (type 0x03) immediately
    • Process app info messages (type 0x04) for device customization
    • Smart trainers: process Virtual Shifting Control (type 0x05) and send Virtual Shifting State (type 0x06) on connect and on change
    • Smart trainers: optionally use Ride State (type 0x07) as the speed reference for inertia and gravity simulation
    • Smart trainers: send Trainer Status (type 0x0A) on connect and on change, stream Trainer Data (type 0x09), and accept Trainer Control (type 0x08) from the owning client only (see TRAINER.md)
    • Use the same binary format as BLE for consistency
    • Prefix every message with its 2-byte length (see Message Framing)
  5. Power Management:

    • Consider WiFi power consumption
    • Implement sleep modes when inactive
    • Wake on button press or network activity

Comparison with BLE

FeatureBLEmDNS/TCP
Range10-30mWiFi network range
Latency7-15ms20-50ms
SetupPairing requiredNetwork connection required
BatteryLow powerHigher power (WiFi)
CompatibilityDirect device supportWorks through proxies/bridges
Multi-deviceLimitedEasy multiple connections
Data FormatBinary (byte array)Binary (byte array) - same format as BLE

See Also