Prototype native Zwift and ROUVY gear display

[sbroenne]

Goal

Investigate whether Virtual Gears can expose trainer-side Zwift virtual-shifting support so Zwift or ROUVY owns and natively displays the selected gear while Virtual Gears applies that gear to an otherwise unsupported KICKR.

Proposed data flow

Zwift Click / on-screen controls
        -> Zwift or ROUVY
        -> proprietary selected gear ratio
        -> Virtual Gears trainer proxy
        -> confirmed wheel-circumference command
        -> physical KICKR

This differs from the current mode: today Virtual Gears consumes the Click, chooses the drivetrain and gear, applies it through the Wahoo wheel-circumference command, and displays the confirmed gear on the iPhone. In native mode, the riding app would own its fixed virtual-gear sequence and HUD.

Research prototype

• Add the trainer-side Zwift custom service and required characteristics to the emulated trainer behind a developer-only flag.
• Independently document and implement the handshake and message framing; do not copy GPLv3 SHIFTR source into this project.
• Decode the selected Zwift gear ratio and map it onto the existing confirmed wheel-circumference pipeline.
• Keep power, cadence and FTMS control forwarding unchanged.
• Let the riding app connect directly to Zwift Click/Play hardware in native mode.
• Detect unsupported or incomplete negotiation and fail explicitly rather than silently falling back to a misleading gear state.
• First test BLE recognition. If Zwift requires the topology demonstrated by SHIFTR, evaluate a Wahoo Direct Connect-compatible server over Wi-Fi.

Product constraints

• Treat this as experimental because the trainer-side protocol is undocumented and may change without notice.
• Native mode cannot preserve arbitrary Virtual Gears drivetrains: Zwift/ROUVY owns the available gear sequence.
• Keep the current vendor-independent FTMS mode as the safe default.
• Do not claim compatibility until physically validated for each riding-app version, transport, controller and trainer combination.
• Review App Store metadata, README, GitHub Pages, safety/privacy documentation and hardware evidence before exposing the feature publicly.

Acceptance criteria

• A protocol note records the independently observed service, characteristics, handshake, framing and selected-ratio messages.
• A developer flag cleanly separates native-protocol mode from current Virtual Gears-controlled shifting.
• Zwift or ROUVY shows its native current-gear indicator during a real ride.
• A gear command is not shown as applied by Virtual Gears until the KICKR confirms the corresponding wheel circumference.
• Terrain/SIM commands continue to pass through without fighting the gear adjustment.
• Disconnects, malformed messages and protocol-version changes produce explicit safe behavior.
• The trainer wheel circumference is restored after normal stop, interruption and protocol failure.
• Hardware evidence records the exact iPhone, iOS, KICKR firmware, riding-app version, controller and observed shift latency.
• Licensing and legal implications of implementing the undocumented protocol have been reviewed.

References

• SHIFTR demonstrates the general Direct Connect bridge architecture and reports Zwift ratios from 0.75 through 5.49. Its GPLv3 implementation is reference evidence, not reusable source for this project.
• Wahoo virtual shifting compatibility
• ROUVY virtual shifting
• Apple Core Bluetooth