Real-time pedaling efficiency extension for Hammerhead Karoo 2/3. Displays Balance, Torque Effectiveness, and Pedal Smoothness metrics from ANT+ Cycling Dynamics power meter pedals.

kpedal provides cyclists with real-time feedback on pedaling technique during rides. The extension displays data fields on Karoo ride screens and includes a companion app for training drills, ride history, analytics, and achievement tracking.

Key Features:

• Background mode - Collects pedaling data for ALL rides, even without KPedal data fields on screen
• 6 customizable data field layouts for ride screens
• Real-time alerts for pedaling technique issues
• 10 built-in training drills with guided phases
• Custom drill creation
• Automatic ride history with analysis (up to 100 rides)
• 7-day and 30-day trend analytics
• 16 achievements to unlock
• 7 rotating weekly challenges

Balance:

• Pro cyclists: 48-52% (±2%)
• Amateur cyclists: 45-55% is normal
• 2-5% asymmetry is natural and changes with fatigue
• Complete symmetry (50/50) is not required

Torque Effectiveness:

• 80%+ is NOT better - this is a common misconception
• Above 80%, power on the main downstroke phase decreases
• Optimal zone: 70-80% (based on Wattbike research)
• Very high TE means "stealing" power from your strongest phase

Pedal Smoothness:

• Good cyclists: 20-30%
• Elite cyclists: 25-35%
• 100% would be perfectly circular motion (unrealistic)
• Lower values during sprints and high power is normal

6 layouts available for Karoo ride screens:

Create your own drills with configurable parameters:

Target Types:

• MIN: Value must be above threshold (e.g., PS ≥ 25%)
• MAX: Value must be below threshold (e.g., Balance ≤ 48%)
• RANGE: Value must be between min and max (e.g., TE 70-80%)
• EXACT: Value must be within tolerance of target (e.g., Balance 50% ± 2%)

• Score = % of time spent in target zone (0-100%)
• Only phases WITH targets count toward score
• Warm-up/recovery phases (no target) are tracked but don't affect score
• Per-phase scores recorded for detailed feedback

Score Ratings:

7 rotating challenges (based on week number):

Balance (based on threshold setting, default ±5%):

• Optimal: ≤ threshold/2 deviation (±2.5%)
• Attention: ≤ threshold deviation (±5%)
• Problem: > threshold deviation (>5%)

Torque Effectiveness:

• Optimal: within configured range (70-80%)
• Attention: within ±5% of range (65-85%)
• Problem: outside attention zone

Pedal Smoothness:

• Optimal: ≥ minimum threshold (20%)
• Attention: ≥ minimum - 5% (15%)
• Problem: < attention threshold

Configure real-time alerts during rides:

Overall Score (0-100) calculated from:

• Balance Score: 40% weight
• Efficiency Score: 35% weight (TE 50% + PS 50%)
• Consistency Score: 25% weight (time in optimal zone)

• Up to 3 strengths (e.g., "Excellent L/R balance", "Optimal torque effectiveness")
• Up to 3 improvement suggestions (e.g., "Focus on smoother pedal stroke")
• Summary based on overall score

Real-time ride statistics accessible during a ride:

• Duration: Current ride time
• Balance: Current L/R % with trend indicator
• TE/PS: Left and right values with trends
• Time in Zone: Optimal/Attention/Problem percentages
• Overall Score: Real-time ride quality score (0-100)
• Manual Save: Save ride before auto-save on stop

• 7-day trends: Recent performance overview
• 30-day trends: Monthly progress tracking
• Sparkline charts: Visual trend indicators
• Per-metric tracking: Balance, TE, PS progress over time

Requires dual-sided power meter with ANT+ Cycling Dynamics support:

Note: Single-sided power meters do not provide these metrics.

adb install kpedal-1.0.0.apk

Or use Karoo's sideload feature.

Prerequisites:

1. Android Studio with JDK 17
2. GitHub Personal Access Token with read:packages scope

Setup:

Add to ~/.gradle/gradle.properties:

gpr.user=YOUR_GITHUB_USERNAME gpr.key=YOUR_GITHUB_TOKEN

Build Commands:

# Release APK (minified) JAVA_HOME="/Applications/Android Studio.app/Contents/jbr/Contents/Home" ./gradlew assembleRelease # Debug APK JAVA_HOME="/Applications/Android Studio.app/Contents/jbr/Contents/Home" ./gradlew assembleDebug # Quick compile check JAVA_HOME="/Applications/Android Studio.app/Contents/jbr/Contents/Home" ./gradlew compileDebugKotlin # Run unit tests JAVA_HOME="/Applications/Android Studio.app/Contents/jbr/Contents/Home" ./gradlew test # Run lint JAVA_HOME="/Applications/Android Studio.app/Contents/jbr/Contents/Home" ./gradlew lint

Output: app/build/outputs/apk/release/kpedal-1.0.0.apk

1. Profiles → Select your profile → Edit
2. Add or edit a data page
3. Tap on an empty slot → More Data → kpedal
4. Select one of the 6 layouts
5. Save and start riding

4-page onboarding for new users:

1. Welcome - Introduction to KPedal
2. Data Fields - How to add fields to Karoo screens
3. Drills - Overview of training drills
4. Alerts - Alert configuration

Home screen shows:

• Total rides - Lifetime ride count
• Avg balance - All-time average L/R balance
• Streak - Current consecutive days riding
• Last ride - Date, balance, optimal zone %

KPedal runs as a background service to collect pedaling metrics for all rides, even when KPedal data fields are not on your ride screen.

How it works:

1. Service starts automatically when Karoo boots
2. Monitors ride state (recording/paused/stopped)
3. When any ride starts, begins collecting Balance, TE, PS metrics
4. When ride ends, automatically saves analysis to history

Benefits:

• Never miss ride data - all rides are analyzed
• No need to configure data fields to get ride history
• Retroactive analysis even for rides without data fields

Note: A persistent notification "KPedal - Monitoring pedaling metrics" appears in the notification shade. This is required by Android for background services.

• Device: Hammerhead Karoo 2 or Karoo 3
• Display: 480×800 pixels
• OS: Karoo OS 1.524+
• Pedals: ANT+ Cycling Dynamics compatible (dual-sided)
• Android: minSdk 23, targetSdk 34

DataType.Type.PEDAL_POWER_BALANCE → Field.PEDAL_POWER_BALANCE_LEFT DataType.Type.TORQUE_EFFECTIVENESS → Field.TORQUE_EFFECTIVENESS_LEFT/RIGHT DataType.Type.PEDAL_SMOOTHNESS → Field.PEDAL_SMOOTHNESS_LEFT/RIGHT DataType.Type.SMOOTHED_3S_AVERAGE_PEDAL_POWER_BALANCE DataType.Type.SMOOTHED_10S_AVERAGE_PEDAL_POWER_BALANCE 

io.github.kpedal/ ├── KPedalExtension.kt # KarooExtension entry point ├── MainActivity.kt # Compose navigation ├── MainViewModel.kt # State management ├── datatypes/ # 6 RemoteViews DataType layouts │ ├── BaseDataType.kt # Common lifecycle handling │ ├── QuickGlanceDataType.kt │ ├── PowerBalanceDataType.kt │ ├── EfficiencyDataType.kt │ ├── FullOverviewDataType.kt │ ├── BalanceTrendDataType.kt │ └── SingleBalanceDataType.kt ├── drill/ # Drill system │ ├── DrillCatalog.kt # 10 built-in drills │ ├── DrillEngine.kt # Execution engine │ ├── DrillRepository.kt # Results storage │ ├── CustomDrillRepository.kt │ └── model/ # Drill data models ├── engine/ # Core engine │ ├── PedalingEngine.kt # Central data pipeline │ ├── PedalingMetrics.kt # Data model │ ├── StatusCalculator.kt # Threshold evaluation │ ├── AlertManager.kt # In-ride alerts │ ├── LiveDataCollector.kt # Ride statistics │ ├── RideStateMonitor.kt # Ride state tracking │ ├── AchievementChecker.kt # Achievement logic │ └── PedalMonitor.kt # Connection status ├── data/ # Persistence │ ├── PreferencesRepository.kt # Settings (DataStore) │ ├── RideRepository.kt # Ride history │ ├── AchievementRepository.kt # Achievements │ ├── AnalyticsRepository.kt # Trend calculations │ ├── database/ # Room entities & DAOs │ └── models/ # Data models └── ui/ # Compose UI ├── theme/ # Colors, typography ├── components/ # Reusable components └── screens/ # App screens 

• Engine: Room Database v5
• File: kpedal_rides.db
• Tables: rides, drill_results, achievements, custom_drills
• Migration: Fallback to destructive

• AtomicReference for consumer IDs
• AtomicLong for cooldown timestamps
• @Volatile for simple boolean flags
• synchronized lock in SummaryCollector

MIT

kpedal — Real-time pedaling efficiency for Karoo