Bike2Game
=========

Bike2Game turns your bicycle or exercise bike into a game controller for
Windows. It connects to a Bluetooth Low Energy cadence sensor, reads crank
cadence in RPM, and converts your pedaling into forward movement using a
virtual Xbox-compatible gamepad, VRChat's OSC right-trigger input, or the W
key. Only one output mode is active at a time.


SYSTEM REQUIREMENTS
-------------------

- 64-bit Windows 10 version 2004 (build 19041) or newer, or Windows 11.
- A working Bluetooth Low Energy adapter with Bluetooth enabled.
- A cadence sensor that supports the Bluetooth Cycling Speed and Cadence
  service (CSC UUID 0x1816), CSC Measurement characteristic (UUID 0x2A5B),
  and crank-revolution data.
- Administrator permission. Windows will display an administrator prompt when
  Bike2Game starts because the virtual-controller driver must be installed and
  managed.
- Microsoft .NET 10 Desktop Runtime for x64 when using the framework-dependent
  version of Bike2Game. It is not required when using a self-contained release.

The virtual-controller driver is installed automatically by Bike2Game. A
physical Xbox controller is not required.


HIDMAESTRO INSTALLATION
-----------------------

Bike2Game requires HIDMaestro.Core.dll version 1.3.17 to create the virtual
controller. If this DLL is not included with your copy of Bike2Game, download
the official HIDMaestro release directly from its publisher:

https://github.com/hifihedgehog/HIDMaestro/releases/tag/v1.3.17

Direct ZIP download:

https://github.com/hifihedgehog/HIDMaestro/releases/download/v1.3.17/HIDMaestro-v1.3.17.zip

1. Download and extract HIDMaestro-v1.3.17.zip.
2. Find HIDMaestro.Core.dll inside the extracted folder.
3. Copy HIDMaestro.Core.dll into the same folder as Bike2Game.exe.
4. Start Bike2Game and accept the Windows administrator prompt.

Bike2Game will not start if HIDMaestro.Core.dll is missing. Use version 1.3.17,
which is the version tested with this release of Bike2Game.


SUPPORTED SENSORS
-----------------

Bike2Game is designed for standard Bluetooth LE CSC cadence sensors. It has
been tested with the COOSPO BK9C.

The following are not currently supported:

- ANT+ sensors.
- Sensors using only proprietary Bluetooth services.
- Wheel-speed-only sensors without crank-revolution data.
- Cadence data exposed only through the Cycling Power service.


HOW TO USE
----------

1. Turn on Bluetooth and pedal briefly to wake the cadence sensor.
2. Start Bike2Game and accept the Windows administrator prompt.
3. Open Options and choose Select Bluetooth device.
4. Wait for the sensor to appear, select it, and close the selection window.
5. Click Connect and start.
6. In Options, open the Gamepad side menu to select Left stick forward or
   Right trigger, or select VRChat OSC or W key. Left stick is the default.
7. Begin pedaling. Bike2Game will display the measured RPM and drive only the
   selected output.
8. Use Options > Disconnect before selecting a different sensor.

If a game does not recognize the virtual controller, select Options > W key.
Select either Gamepad option to return to virtual-gamepad output.

For normal forward movement in VRChat:

1. In VRChat, open the Action Menu and enable OSC under OSC > Enabled.
2. In Bike2Game, select Options > VRChat OSC.
3. Connect the cadence sensor normally.

Bike2Game sends the cadence-scaled /input/Vertical value to VRChat on its
default OSC input port (127.0.0.1:9000). At 100 RPM and above it also holds
/input/Run; below 100 RPM it releases Run. All movement is released
automatically when pedaling stops, the sensor disconnects, the option is
disabled, or Bike2Game closes. Individual VRChat worlds may handle vehicles
through their own controls and ignore normal locomotion input.


MOVEMENT SCALING
----------------

- 185 RPM produces full left-stick or right-trigger input.
- Gamepad and VRChat OSC input is proportional through 100 RPM, then receives
  a progressive high-cadence boost while approaching full input at 185 RPM.
- VRChat OSC holds Run at 100 RPM and above when the current world supports it.
- Any positive cadence produces at least 5 percent gamepad or OSC input.
- W key mode presses W at any detected positive cadence; keyboard input is
  binary and cannot represent proportional speed.
- Movement is released automatically when cadence notifications stop.

The cadence sensor controls how frequently it sends measurements. Some sensors
may not report very slow pedaling immediately.


TROUBLESHOOTING
---------------

Sensor does not appear:

- Pedal briefly to wake it.
- Move it closer to the computer.
- Confirm Bluetooth is enabled.
- Close phone apps or other programs that may already be connected to it.
- Reopen the Bluetooth-device window to scan again.

Connected but RPM is not displayed:

- Confirm the sensor supports CSC crank-revolution measurements.
- Continue pedaling for several complete rotations.
- Disconnect and reconnect the sensor.

RPM is displayed but the game does not move:

- Confirm the game supports controller input and that controller input is
  enabled in the game settings.
- Start Bike2Game before starting the game.
- Select W key output to determine whether the problem is specific to the
  game's controller handling.
- Close other controller-emulation software that may create conflicting
  virtual devices.

VRChat OSC forward movement does not respond:

- Confirm OSC is enabled in VRChat's Action Menu under OSC > Enabled.
- Confirm Options > VRChat OSC is selected in Bike2Game.
- Confirm the Bike2Game status changes to "VRChat forward input" while
  pedaling.
- Vehicle controls are world-specific and may ignore normal Vertical input.

Virtual controller unavailable:

- Close Bike2Game and start it again as administrator.
- Restart Windows after the first driver installation if requested.


DISTRIBUTION FILES
------------------

Keep all files from the Bike2Game publish folder together. Do not distribute
or copy only Bike2Game.exe. THIRD-PARTY-NOTICES.txt contains required license
and attribution information for third-party software included in Bike2Game.


TRADEMARKS
----------

Bike2Game is an independent application and is not affiliated with or endorsed
by Microsoft, Xbox, VRChat, COOSPO, or any game developer or publisher.
All product names and trademarks belong to their respective owners.
