Vitruvian Project Phoenix - Android Control App

A native Android application for controlling Vitruvian Trainer workout machines via Bluetooth Low Energy (BLE).

Project Overview

This app enables local control of Vitruvian Trainer machines after the company's bankruptcy. It's a direct port of the proven web application to native Android, providing better stability, user experience, and offline capability.

Features Implemented

Phase 1: Core Functionality ✅

BLE device scanning and connection
Protocol implementation (all commands)
Workout modes (Old School, Pump, TUT, TUT Beast, Eccentric, Echo)
Real-time monitoring (load, position, ticks)
Workout parameter configuration
Color scheme customization
MVVM architecture with Clean Architecture principles
Dependency injection with Hilt
Modern UI with Jetpack Compose

Phase 2: Enhanced Features ✅

Phase 3: Advanced Features ✅

Active workout screen with real-time metrics
Analytics and statistics dashboard
Program builder for custom workout routines
Daily and weekly routine management
Single exercise mode (Just Lift)
Rest timer and countdown features
Haptic feedback
DataStore preferences
Comprehensive unit and integration tests

Planned Features

Technology Stack

Language: Kotlin
UI: Jetpack Compose with Material 3
Architecture: MVVM + Clean Architecture
DI: Hilt/Dagger
BLE: Nordic BLE Library (v2.7.1)
Database: Room with DAO pattern
Preferences: DataStore
Charting: MPAndroidChart
Async: Kotlin Coroutines + Flow
Image Loading: Coil
Logging: Timber
Testing: JUnit, Mockk, Turbine, Truth, Robolectric

Project Structure

app/src/main/java/com/example/vitruvianredux/
├── VitruvianApp.kt                          # Application class
├── MainActivity.kt                          # Main activity
├── data/
│   ├── ble/
│   │   └── VitruvianBleManager.kt           # BLE communication
│   ├── local/
│   │   ├── WorkoutDatabase.kt               # Room database
│   │   ├── WorkoutDao.kt                    # Workout data access
│   │   ├── ExerciseDao.kt                   # Exercise library access
│   │   ├── PersonalRecordDao.kt             # PR tracking
│   │   └── ExerciseImporter.kt              # Exercise library importer
│   ├── preferences/
│   │   └── PreferencesManager.kt            # DataStore preferences
│   └── repository/
│       ├── BleRepositoryImpl.kt             # BLE repository
│       ├── WorkoutRepository.kt             # Workout data repository
│       ├── ExerciseRepository.kt            # Exercise library repository
│       └── PersonalRecordRepository.kt      # Personal records repository
├── domain/
│   ├── model/
│   │   ├── Models.kt                        # Domain models
│   │   ├── Exercise.kt                      # Exercise models
│   │   ├── Routine.kt                       # Routine models
│   │   └── UserPreferences.kt               # Preferences models
│   └── usecase/
│       └── RepCounterFromMachine.kt         # Rep counting logic
├── presentation/
│   ├── screen/
│   │   ├── HomeScreen.kt                    # Home dashboard
│   │   ├── ActiveWorkoutScreen.kt           # Active workout tracking
│   │   ├── AnalyticsScreen.kt               # Statistics and analytics
│   │   ├── JustLiftScreen.kt                # Single exercise mode
│   │   ├── ProgramBuilderScreen.kt          # Custom routine builder
│   │   ├── SingleExerciseScreen.kt          # Individual exercise config
│   │   ├── DailyRoutinesScreen.kt           # Daily workout routines
│   │   └── WeeklyProgramsScreen.kt          # Weekly programs
│   ├── viewmodel/
│   │   ├── MainViewModel.kt                 # Main ViewModel
│   │   ├── ExerciseConfigViewModel.kt       # Exercise configuration
│   │   ├── ExerciseLibraryViewModel.kt      # Exercise library
│   │   └── ThemeViewModel.kt                # Theme management
│   ├── components/
│   │   ├── ConnectionStatusBanner.kt        # Connection status UI
│   │   └── EmptyStateComponent.kt           # Empty state UI
│   └── ui/theme/
│       ├── Theme.kt                         # Theme configuration
│       ├── Color.kt                         # Color definitions
│       ├── Type.kt                          # Typography
│       └── Spacing.kt                       # Spacing system
├── service/
│   └── WorkoutForegroundService.kt          # Foreground workout service
├── util/
│   ├── Constants.kt                         # BLE UUIDs and constants
│   └── ProtocolBuilder.kt                   # Binary protocol frames
└── di/
    └── AppModule.kt                         # Dependency injection

Getting Started

Prerequisites

Android Studio Arctic Fox or newer
Android device with BLE support (API 26+)
Vitruvian Trainer machine for testing

Building the Project

Clone the repository
Open in Android Studio Arctic Fox or newer
Sync Gradle files (will auto-download dependencies)
Build the project: ./gradlew build
Run on a physical device (BLE doesn't work on emulators)

Build Configuration:

Compile SDK: 36
Min SDK: 26 (Android 8.0)
Target SDK: 36
Kotlin: Latest stable
Gradle: 8.x

Permissions Required

BLUETOOTH_SCAN - For scanning BLE devices (Android 12+)
BLUETOOTH_CONNECT - For connecting to BLE devices (Android 12+)
ACCESS_FINE_LOCATION - Required for BLE scanning on older Android versions
BLUETOOTH / BLUETOOTH_ADMIN - For older Android versions

Usage

Launch the app
Tap "Scan for Device" to find your Vitruvian machine (devices starting with "Vee")
Connect to your device
Configure workout parameters (mode, weight, reps)
Tap "Start Workout" to begin
Monitor real-time metrics during workout
Tap "Stop Workout" when complete

BLE Protocol

The app implements the full Vitruvian BLE protocol:

Init Command: 4-byte initialization
Init Preset: 34-byte coefficient table
Program Params: 96-byte workout configuration
Echo Control: 32-byte Echo mode parameters
Color Scheme: 34-byte LED color configuration

All protocol frames are byte-perfect matches to the original web application.

Development Roadmap

Current Progress: Alpha Release (Phase 3 Complete)

Completed:

✅ Project setup and dependencies
✅ BLE infrastructure with Nordic library
✅ Complete protocol implementation
✅ Domain models and Clean Architecture
✅ Enhanced UI with device selection
✅ Connection management
✅ Workout start/stop with foreground service
✅ Rep detection engine
✅ Workout history with Room database
✅ Permission handling with Accompanist
✅ Multi-tab navigation
✅ Exercise library (200+ exercises)
✅ Personal records tracking
✅ Program builder for custom routines
✅ Analytics and statistics dashboard
✅ Daily and weekly routine management
✅ Theme customization
✅ Comprehensive test coverage

Next Steps (Beta Release):

Live charting visualization
CSV export functionality
Unit conversion (kg/lb)
Dark mode toggle
Performance optimization
UI/UX refinements
Beta testing feedback integration

Contributing

This is an open-source community project to rescue Vitruvian machines from becoming e-waste.

Fork the repository
Create a feature branch
Make your changes
Test with real hardware
Submit a pull request

Testing

Running Tests

# Run all unit tests
./gradlew test

# Run specific test class
./gradlew test --tests "com.example.vitruvianredux.protocol.ProtocolBuilderTest"

# Run instrumented tests (requires device/emulator)
./gradlew connectedAndroidTest

Test Coverage

The project includes comprehensive test suites:

Unit Tests:

Protocol builder tests (ProtocolBuilderTest.kt)
ViewModel tests (MainViewModelTest.kt, MainViewModelEnhancedTest.kt)
BLE manager tests (VitruvianBleManagerTest.kt)
Repository tests (WorkoutRepositoryTest.kt)
Domain logic tests (WorkoutModeTest.kt)
Rep counting tests (RepCountingTest.kt, RepTrackingTest.kt)

Integration Tests:

Workout integration tests (WorkoutIntegrationTest.kt)
BLE connection tests (BleConnectionTest.kt)
Offline functionality tests (OfflineFunctionalityTest.kt)

Manual Testing Checklist

Known Issues

Live charting visualization not yet implemented
CSV export feature pending
Unit conversion (kg/lb) not yet available
Dark mode toggle not yet implemented
Some UI elements need polish

Additional Features

Exercise Library

The app includes a comprehensive exercise library with 200+ pre-loaded exercises:

Categorized by muscle group
Detailed instructions
Equipment requirements
Difficulty ratings

Personal Records Tracking

Automatic PR detection during workouts
Historical PR tracking
Performance trends
Progress visualization

Routine Management

Daily Routines: Quick-access workout templates
Weekly Programs: Structured multi-day training plans
Program Builder: Create custom workout routines
Template Library: Pre-built workout templates

Foreground Service

The app uses a foreground service during workouts to ensure:

Persistent BLE connection
Uninterrupted workout tracking
Background operation
System notification for quick access

License

MIT License - See LICENSE file for details

Acknowledgments

Original web app developers for reverse-engineering the BLE protocol
Vitruvian machine owners community for support and testing
Nordic Semiconductor for the excellent BLE library

Support

For issues, questions, or contributions:

Open a GitHub issue
Join the community Discord (link TBD)
Email: vitruvianprojectphoenix@example.com (TBD)

Status: Alpha - Active Development
Version: 0.1.0-alpha
Last Updated: November 4, 2025

🚀 Current Status

The Vitruvian Project Phoenix Android app is under active development with most core functionality complete. The app provides comprehensive control of Vitruvian Trainer machines with advanced features for workout tracking, routine management, and performance analytics.

Build Information

Build Location: app/build/outputs/apk/debug/app-debug.apk
Minimum Android: 8.0 (API 26)
Target Android: API 36
APK Size: ~8-10 MB

What Works

✅ Full BLE device control
✅ All workout modes
✅ Exercise library (200+ exercises)
✅ Workout history and tracking
✅ Personal records
✅ Custom routines and programs
✅ Analytics dashboard
✅ Theme customization

In Development

🚧 Live charting
🚧 CSV export
🚧 Unit conversion
🚧 Dark mode

kwonoj/VitruvianProjectPhoenix