VirtualRow — Row Anywhere on Real Water Routes

🌐 Website · 📦 GitHub

VirtualRow is a web-based fitness application that lets you row on virtual water routes while connected to your Concept2 PM5 indoor rower via Bluetooth. Experience immersive 3D rowing visualization from your home.

Features

Water Routes

VirtualRow now ships with one bundled demo route:

Route	Location	Distance	Difficulty
Willowbrook River	Willowbrook Valley	5.0 km	Easy

To row real-world courses, search and import them directly from rownative.icu in the route selector.

Immersive 3D Visualization

• Real-time 3D rowing scene with boat, rower, and animated oars
• Dynamic scenery: trees, vegetation, buildings along riverbanks
• Perspective scaling based on distance from rower
• View corridor management - objects become transparent to never obstruct the boat
• Smooth camera following with limited rotation speed
• Cinematic post-processing: ACES tone mapping, chromatic aberration, depth of field, bloom
• Kelvin wake and blade foam particle effects
• CubeCamera environment reflections on water surface

Concept2 PM5 Bluetooth Integration

• Connect directly to your Concept2 PM5 monitor via Web Bluetooth API (Concept2 CSAFE BLE profile)
• Real-time performance metrics: pace, distance, time, power, stroke rate, calories
• Connection persists across route changes and UI navigation
• Built-in PM5 Simulator for testing and demo without physical hardware

Heart Rate Monitoring

• Connect heart rate monitors via Bluetooth (standard HR service)
• Real-time BPM display with chart visualization
• Average and max HR tracking per workout

Getting Started

Requires Node.js 24 (the active LTS line). It is pinned in .nvmrc, so nvm use selects it for you.

See First-Time Setup below under Testing, or for quick start:

git clone <repository-url>
cd virtualrow
nvm use              # → Node 24, per .nvmrc
npm install
npm run dev          # → http://localhost:5173

Browser Compatibility

• Chrome/Chromium 56+ (recommended)
• Edge 79+
• Opera 43+
• Firefox (experimental, requires flag)

Project Structure

src/
 components/
    Rower3D.tsx                    # 3D rowing visualization (~2000 lines)
    RouteMap.tsx                   # 2D route map (Leaflet)
    RowingOverlay.tsx              # In-workout HUD with live metrics
    BluetoothDevice.tsx            # PM5 connection UI
    HeartRateMonitor.tsx           # HR monitor connection
    PM5Simulator.tsx               # PM5 hardware simulator
    MiniMetrics.tsx                # Compact metrics overlay
    PerformanceChart.tsx           # Post-session performance graphs
    HeartRateChart.tsx             # Live HR chart
    Canvas3DErrorBoundary.tsx      # WebGL error fallback
    routeLandmarks/
       LandmarkRenderer.tsx        # Route landmark placement in 3D scene
 hooks/
    usePhysicsEngine.ts            # Physics engine interface
 services/
    bluetoothService.ts            # PM5 BLE communication
    heartRateBluetoothService.ts   # HR monitor BLE service
    pm5SimulatorService.ts         # PM5 simulation
    routeService.ts                # Route data + rownative route import
    workoutService.ts              # Session tracking
 utils/
    geoUtils.ts                    # Geographic calculations
    gpuUtils.ts                    # WebGL/GPU detection
    routeGeometry.ts               # Route spline geometry helpers
 types/
    index.ts                       # Core TypeScript interfaces
    bluetooth.d.ts                 # Web Bluetooth API types
 App.tsx                           # Root component; all application state lives here
 main.tsx                          # React entry point

playwright/
 tests/                            # E2E test specs
 simulators/                       # WebSocket PM5/HR sim server (sim-server.cjs)
 fixtures/                         # Test fixtures
 utils/                            # Test utilities

docs/
 index.html                        # GitHub Pages landing page (no build step)

Testing

# Run unit tests (Vitest)
npm test

# Run unit tests in watch mode
npm test -- --watch

# Run E2E tests (Playwright)
npm run test:e2e

# Start PM5/HR WebSocket simulator (required for E2E)
npm run start:sim

Unit tests are in src/__tests__/. E2E tests are in playwright/tests/ and use a WebSocket simulator at playwright/simulators/sim-server.cjs.

First-Time Setup

git clone <repository-url>
cd virtualrow
npm install

npm run dev
# → http://localhost:5173

3D Environment Asset Kit

Generate the reusable environment GLB kit (riverbed, water surface, riverbanks, trees, buildings, bridge, dock, buoy):

npm run generate:environment-assets

Output file:

• public/models/virtualrow-environment.glb

Troubleshooting

See PM5_TROUBLESHOOTING.md for PM5 connection issues.

Development

See DEVELOPMENT.md for detailed development information.

License

MIT