home page

Immersive Smart Training Application

Unity • Wahoo KICKR CORE  • Bluetooth LE

NORRA is an immersive indoor cycling simulator built with Unity 2022.3. It connects to a Wahoo KICKR smart trainer and COROS heart rate monitor via Bluetooth LE — turning a real indoor bike into a virtual road cycling experience. The faster you pedal, the faster you ride.

Key Features

• Bluetooth LE connection to Wahoo KICKR and COROS HRM simultaneously
• Automatic bike route following driven by real cycling speed
• Memory video overlays triggered by location checkpoints
• Dynamic music playlist with GTA-style album art song cards
• Real-time HUD showing power, cadence, speed, heart rate and training zone
• Mini-map with real-time route progress tracking
• Elevation simulation adjusting KICKR resistance on hills
• Zwift-style loading screen with live device connection status
• Full ride summary card with power and HR chart on route completion

Technology Stack

File Structure

Assets/
  Scripts/
    KickrReader.cs
    WorkoutBuilder.cs
    KickrHUD.cs
    BikeRouteFollower.cs
    WaypointRoute.cs
    MemoryFadeSystem.cs
    MemoryCheckpoint.cs
    MiniMap.cs
    ElevationSystem.cs
    MusicPlayer.cs
    LoadingScreen.cs
    RideSummary.cs
    Editor/
      WaypointRouteEditor.cs
  StreamingAssets/
    ride1_h264.mp4
    loading_bg_h264.mp4
  Music/
    *.mp3 / *.wav
  Scenes/
    main_scene.unity

Requirements

• Mac computer with Bluetooth LE support
• Unity 2022.3 LTS or newer
• Wahoo KICKR smart trainer
• COROS heart rate monitor (optional)
• MP4 video files encoded in H.264 baseline profile
• MP3 or WAV audio files for music playlist

Setup Steps

1. Open the Project — Open Unity Hub, click Add, navigate to the NORRA folder. Select Unity 2022.3 as the editor version.
2. Enable Bluetooth Permissions — Go to Edit → Project Settings → Player → Mac → Other Settings and enable Bluetooth. Also open Mac System Settings → Privacy & Security → Bluetooth and add Unity to the allowed apps list.
3. Add Video Files — Place H.264 MP4 files in Assets/StreamingAssets/. If your videos are in HEVC or MOV format, convert them using the command below.
4. Add Music Files — Place MP3 or WAV files in Assets/Music/. Drag them into the MusicPlayer component Songs array in the Inspector.
5. Set Up the Route — Select the Route object in the Hierarchy. Add WaypointRoute component. Use Shift+Click in Scene view to place waypoints along the road.
6. Press Play — The loading screen appears and automatically scans for your KICKR and HRM. Once connected it fades away and the ride begins.

Converting Videos

Unity on Mac requires H.264 MP4 with baseline profile and constant frame rate. Convert any video using Terminal:

ffmpeg -i input.mp4 -c:v libx264 -pix_fmt yuv420p -profile:v baseline -level 3.0 -vf fps=30 -c:a aac output_h264.mp4

To rotate portrait phone videos to landscape:

ffmpeg -i input.mp4 -vf transpose=2 -c:v libx264 -pix_fmt yuv420p -c:a aac output_landscape.mp4

Installing Homebrew and ffmpeg

If you don’t have Homebrew installed, open Terminal and run:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Then install ffmpeg:

brew install ffmpeg

All 12 custom C# scripts are located in Assets/Scripts/. Each script is documented below with its Inspector fields and public methods.

KickrReader.cs

Core Bluetooth LE manager. Scans for and connects to both the Wahoo KICKR trainer and COROS HRM simultaneously using a single Bluetooth LE initialization. Parses incoming BLE data packets and exposes real-time metrics as public properties.

Public Properties:

Inspector Fields:

Public Methods:

• SetTargetPower(int watts) — Sends ERG resistance command to KICKR

BLE UUIDs:

WorkoutBuilder.cs

Controls the workout HUD showing live power, cadence, speed and zone with color coding. Manages structured workout intervals sending target power commands to the KICKR automatically.

Inspector Fields:

Public Methods:

• StartWorkout() — Begins structured workout interval sequence
• StopWorkout() — Stops workout and sets power to 0

KickrHUD.cs

Optional secondary HUD component. Controls individual TMP_Text objects for power, cadence, speed and zone with configurable font sizes set directly from the Inspector without changing code.

Inspector Fields:

BikeRouteFollower.cs

Moves the Bicycle Standard object along WaypointRoute automatically. Speed comes from KickrReader.Speed. Tilts naturally on corners. Triggers MemoryFadeSystem when reaching checkpoint waypoints on the route.

Inspector Fields:

WaypointRoute.cs

Holds all waypoints as child GameObjects. Draws green route lines in Scene view. Used by BikeRouteFollower, MiniMap, and ElevationSystem.

Inspector Fields:

Public Methods:

• GetWaypoints() — Returns all child transforms as waypoint array
• GetWaypoint(int index) — Returns waypoint at index with loop support

MemoryFadeSystem.cs

Plays muted video overlays on a RawImage. Triggered by proximity to MemoryCheckpoints or directly by BikeRouteFollower at waypoints. Supports fade, glitch effect, and PlayOnce mode.

Note: Videos must be H.264 MP4 in Assets/StreamingAssets/. HEVC and MOV formats are not supported on Mac.

Inspector Fields:

Public Methods:

• PlayOnce(string filename) — Plays a video once then fades out. Called by BikeRouteFollower.

MemoryCheckpoint.cs

Attached to scene objects or WaypointRoute child objects. Stores the video filename and trigger radius for the MemoryFadeSystem.

Inspector Fields:

MiniMap.cs

Draws a real-time top-down mini-map onto a RawImage texture every frame. Shows the full route in grey, completed section in orange, memory checkpoint pins in teal, and a pulsing player dot with direction arrow.

Inspector Fields:

ElevationSystem.cs

Reads waypoint Y positions to calculate gradient between current and next waypoint. Adjusts KICKR resistance and bike game speed based on uphill or downhill percentage. Shows gradient and elevation in the HUD.

Inspector Fields:

MusicPlayer.cs

Always-playing playlist that fades volume based on cycling speed. Volume fades to minimum when stopped and fades back to maximum when pedaling. Shows GTA-style song card with album art when tracks change.

Inspector Fields:

Public Methods:

• NextSong() — Skip to next track
• PreviousSong() — Go to previous track
• TogglePlayPause() — Pause or resume playback

LoadingScreen.cs

Full-screen loading screen while Bluetooth devices connect. Supports video background, custom logo and device icons. Auto-dismisses when both devices are ready.

Inspector Fields:

RideSummary.cs

Tracks ride statistics throughout the session and builds a complete summary card in code when the route completes. No manual Unity UI setup needed — all elements created programmatically at runtime.

Inspector Fields:

Public Methods:

• ShowSummary() or EndRide() — Manually trigger the summary screen
• RestartRide() — Reset all stats and hide the summary

Adding a New Route

1. Right-click Hierarchy → Create Empty → name it Route. Add WaypointRoute component.
2. Select Route in the Hierarchy → Inspector → click START Placing Waypoints.
3. Switch to the Scene tab. Hold Shift and click on the road surface to drop waypoints. A green line connects them live.
4. Click STOP when done. Use Undo Last Waypoint to remove mistakes.
5. Add BikeRouteFollower to Bicycle Standard and drag Route into the Route slot.

Adding Memory Video Checkpoints

Proximity Trigger — video fades in as you approach:

• Add MemoryCheckpoint component to any GameObject in the scene
• Set Video File Name to your H.264 MP4 filename
• Set Trigger Radius — how close the bike needs to be
• Add it to the Checkpoints array on MemoryFadeSystem

Waypoint Trigger — video plays once at a specific point:

• Add MemoryCheckpoint component to any WP_XX child of Route
• Set Video File Name to your H.264 MP4 filename
• Make sure BikeRouteFollower has MemoryFadeSystem assigned

Converting Videos for Unity

Unity on Mac requires H.264 MP4 with baseline profile and constant frame rate:

ffmpeg -i input.mp4 -c:v libx264 -pix_fmt yuv420p -profile:v baseline -level 3.0 -vf fps=30 -c:a aac output_h264.mp4

To rotate portrait phone videos to landscape:

ffmpeg -i input.mp4 -vf transpose=2 -c:v libx264 -pix_fmt yuv420p -c:a aac output_landscape.mp4

Setting Up Elevation

The elevation system reads the Y position of each waypoint to calculate gradient:

• Select WP_XX objects on hill sections in Scene view
• Raise their Y position to match the terrain height
• Positive gradient means uphill which gives higher resistance and slower speed
• Negative gradient means downhill which gives lower resistance and faster speed
• Adjust Max Resistance Watts and Min Resistance Watts in ElevationSystem Inspector

Adding Music

1. Place MP3 or WAV files in Assets/Music/. Unity imports them as AudioClips automatically.
2. Click MusicPlayer in Hierarchy. Set Songs array size. For each element drag in the AudioClip, album art PNG, and type the Title and Artist name.
3. For album art: click the PNG in Project → Inspector → change Texture Type to Sprite (2D and UI) → Apply. Then drag into the Album Art slot.

KICKR Not Connecting

Most Bluetooth issues are permissions-related on Mac.

• Go to Mac System Settings → Privacy & Security → Bluetooth → add Unity to allowed apps
• Go to Edit → Project Settings → Player → Mac → Other Settings → enable Bluetooth
• Make sure KICKR is not connected to Zwift, Wahoo App or another device
• Unplug KICKR power for 10 seconds then reconnect
• Check Unity Console for BLE ERROR messages

Video Not Playing

• File must be in Assets/StreamingAssets/ folder
• Must be H.264 encoded — HEVC and QuickTime MOV will not work
• Check the file format in Terminal by running: file yourfile.mp4
• Re-encode with ffmpeg using the command from the Setup Guides page
• Filename in Inspector must match exactly including the extension
• Check Console for AVFoundationVideoMedia error messages

Mini-Map Not Showing

• RawImage must be assigned to Map Display on MiniMap component
• Route and Bike Transform must both be assigned
• Waypoints must exist as children of the Route object
• Make sure the RawImage is visible and not hidden behind other UI elements

Music Not Playing

• AudioClips must be assigned in the Songs array on MusicPlayer
• Music fades to minVolume when not pedaling — this is normal behavior
• Set minVolume to 0.5 in Inspector to hear it clearly at rest
• Check that Unity audio is not muted (speaker icon in Game view toolbar)

Loading Screen Not Dismissing

• Waits for both KICKR and HRM to connect before dismissing
• If HRM is not available, dismisses after 10 seconds with KICKR only
• Set minLoadTime to 0 in Inspector to dismiss immediately for testing
• Check Console for Bluetooth permission error messages

Route Not Moving

• Check BikeRouteFollower has Route and KickrReader assigned in Inspector
• Make sure waypoints exist as children of the Route object
• Check debugKickrSpeed on BikeRouteFollower — should be above 0 when pedaling
• Set minGameSpeed above 0 to test movement without hardware connected

Tools and Engines

Unity Packages and Plugins

Hardware

Bluetooth Standards

Built by Ervin Zhuang • NORRA Cycling Experience • Unity 2022.3 • April 2026