Garmin Speed Simulator for Indoor Cycling

A Garmin Connect IQ Data Field app that calculates and records virtual speed based on power and cadence data from an indoor bike trainer. This app is particularly useful for indoor cycling sessions where GPS speed is not available.

Features

• Physics-Based Speed Calculation: Uses power and cadence to simulate realistic cycling speed
• Advanced Physics Model: Includes air resistance, rolling resistance, gradient effects, and bike/rider characteristics
• Automatic Profile Sync: Pulls rider weight and height from Garmin Connect profile
• Multiple Bike Profiles: Road, TT (Time Trial), and MTB (Mountain Bike) with different aerodynamic characteristics
• GPS-Aware: Automatically disables simulation when GPS is active to prevent data conflicts
• Configurable Settings: Bike weight, wheelset type, gradient, and ascent rate
• FIT File Recording: Records speed and distance to your activity file (only when GPS is disabled)
• Optimized Performance: Reduced battery consumption through efficient algorithms and optional debug logging

Requirements

• Compatible Garmin Edge devices (540, 840, 1040, 1050, Edge Explore 2)
• ANT+ power meter or smart trainer providing power and cadence data
• Garmin Connect IQ SDK 4.1.0 or higher

Installation

1. Download the app from the Garmin Connect IQ Store (coming soon)
2. Transfer to your Edge device using Garmin Express or Garmin Connect Mobile
3. Add the data field to one of your indoor cycling activity profiles
4. Configure your bike and rider settings in the data field settings menu

Configuration

The following settings can be configured through the Garmin Connect IQ app or on your device:

• Rider Weight (kg): Auto-populated from Garmin Connect profile, range: 30-150 kg
• Rider Height (cm): Auto-populated from Garmin Connect profile, range: 120-220 cm
• Bike Type: Road (0.7 Cd), TT (0.6 Cd), or MTB (0.9 Cd)
• Bike Weight (kg): Range: 5-20 kg
• Wheelset Type: Light (0.9x), Medium (1.0x), or Heavy (1.1x)
• Gradient (%): Simulated hill gradient, range: -25% to +25%
• Ascent Rate (m/hour): Simulated climbing rate for varied terrain, range: 0-2000 m/hour

How It Works

The app uses physics-based calculations to simulate realistic cycling speed:

1. Force Calculation: Calculates air resistance, rolling resistance, and gravity forces
2. Power Balance: Finds equilibrium speed where power output equals resistance forces
3. Speed Smoothing: Applies exponential smoothing for realistic acceleration/deceleration
4. GPS Detection: Checks if GPS is active and only simulates speed when GPS is disabled
5. FIT Recording: Records simulated speed and distance to native FIT fields (when GPS is off)

Physics Model

• Air Resistance: F = 0.5 × ρ × Cd × A × v²
• Rolling Resistance: F = Crr × m × g × cos(θ)
• Gravity Force: F = m × g × sin(θ)
• Frontal Area: Calculated from rider height and weight using Du Bois formula

Architecture

The app follows a modular, testable architecture:

source/
├── models/          # Data models (BikeProfile, RiderProfile, PhysicsConstants)
├── physics/         # Physics calculations (PhysicsEngine, ForceCalculator, SpeedSmoother)
├── services/        # Business services (SettingsManager, FitRecorder, GpsDetector)
├── utils/           # Utilities (Validators, Logger)
├── ui/              # User interface (SpeedSimulatorView)
└── GarminSpeedSimulatorApp.mc  # Application entry point

test/                # Unit tests for core business logic

Key Design Principles

• Separation of Concerns: UI, business logic, and data models are separate
• Performance Optimization: Cached bike profiles, pre-computed values, reduced iterations
• GPS Safety: Native FIT fields only written when GPS is disabled
• Battery Efficiency: Conditional debug logging, optimized compute cycle

Development Setup

1. Install the Garmin Connect IQ SDK
2. Install Visual Studio Code and the Monkey C extension
3. Clone this repository:

   git clone https://github.com/yourusername/garmin-speed-simulator.git

4. Open the project in VS Code
5. Build and test using the Garmin simulator

Building for Production

Important: Before building for release, disable debug logging:

1. Open source/utils/Logger.mc
2. Change const DEBUG = false; (ensure it's set to false)
3. Build the release version

This will remove all debug logging output, improving battery life and performance.

Running Tests

Unit tests are located in the test/ directory. To run tests:

1. Use the Monkey C: Test command in VS Code
2. Select the test file to run
3. View test results in the output panel

Test coverage includes:

• Physics engine calculations
• Force calculations (air, rolling, gravity)
• Bike profile caching
• Rider profile calculations
• Input validation
• Speed and gradient clamping

Performance Considerations

This app is optimized for Garmin Connect IQ performance best practices:

• Cached Profiles: Bike profiles and wheelset factors are cached at initialization (no dictionary lookups per compute)
• Reduced Iterations: Physics calculations use 3 iterations instead of 5 for faster execution
• Pre-computed Values: Rider profile calculations (frontal area, total mass) are done once at initialization
• Conditional Logging: Debug logging is disabled in production builds to save battery
• Efficient Compute Cycle: The compute() method runs once per second and is optimized to complete quickly

Troubleshooting

Speed seems unrealistic

• Check your rider weight and height in Garmin Connect profile
• Verify bike type matches your actual bike
• Adjust gradient setting if simulating hills

No speed is recorded

• Ensure GPS is disabled in your activity profile
• Check that power meter and cadence sensor are connected
• Verify the data field is added to your activity screen

App shows "GPS active"

• The app automatically disables simulation when GPS is on
• This prevents conflicts with native GPS speed data
• To use the simulator, disable GPS in your activity profile settings

Contributing

Contributions are welcome! Please follow these guidelines:

1. Fork the repository
2. Create a feature branch
3. Write unit tests for new functionality
4. Ensure all tests pass
5. Follow the existing code style and architecture
6. Submit a pull request

Code Style

• Use camelCase for variables and methods
• Use PascalCase for classes
• Add documentation comments to public APIs
• Keep methods focused and under 50 lines
• Follow the single responsibility principle

License

MIT License - see LICENSE file for details

Acknowledgments

• Physics calculations based on standard cycling aerodynamics models
• Thanks to the Garmin Connect IQ developer community
• Built with assistance from Claude.ai

Support

For issues and feature requests, please use the GitHub issues page.

Changelog

Version 2.0.0 (Refactored)

• Complete architecture refactor for maintainability and testability
• Performance optimizations (cached profiles, reduced iterations)
• GPS-aware FIT recording (prevents data conflicts)
• Conditional debug logging for battery efficiency
• Comprehensive unit test suite
• Improved code organization and documentation

Version 1.0.0 (Original)

• Initial release
• Basic speed simulation from power and cadence
• Multiple bike profiles
• FIT file recording