|
1 | | -# Roulette Runner App |
| 1 | +# Running Roulette |
2 | 2 |
|
3 | | -The **Roulette Runner** app allows the user to pick a random number of kilometers from a roulette wheel, which can be used to determine distances to run. |
| 3 | +**Running Roulette** is a Garmin watch app that gamifies your running routine by spinning a roulette wheel to randomly select your next running distance. Perfect for runners who want to add spontaneity and fun to their training! |
4 | 4 |
|
5 | 5 | ## Screenshots |
6 | 6 |
|
7 | | -Here are some screenshots of the app in action: |
8 | | - |
9 | | - |
| 7 | + |
10 | 8 |
|
11 | 9 | ## Features |
12 | 10 |
|
13 | | -- **Random Number Picker**: The app displays a random number from the roulette wheel each time a button is pressed. |
14 | | - |
15 | | -## App Workflow |
| 11 | +- **Interactive Roulette Wheel**: Animated spinning wheel with visual feedback and smooth transitions |
| 12 | +- **Multiple Distance Profiles**: Choose from four pre-configured distance ranges: |
| 13 | + - **5K Profile**: Random distances from 0.5K to 5K (10 segments) |
| 14 | + - **10K Profile**: Random distances from 1K to 10K (16 segments) |
| 15 | + - **Half Marathon Profile**: Random distances from 1K to 21K (16 segments) |
| 16 | + - **Marathon Profile**: Random distances from 1K to 42K (16 segments) |
| 17 | +- **Multi-Language Support**: Available in English, Spanish, and Portuguese |
| 18 | +- **Visual Design**: Casino-style roulette with alternating red/black segments and gold accents |
16 | 19 |
|
17 | | -The app have two options inside the app menu: |
18 | | -1. Spin |
19 | | - **Press the start button** and then click the spin option to start the roulette. |
20 | | -2. Exit |
21 | | - **Press the start button** and then click the spin option to start the roulette. |
| 20 | +## How It Works |
22 | 21 |
|
23 | | -After spin the roulette a random **number will be displayed** on the screen. |
| 22 | +1. **Launch the App**: Open Running Roulette on your Garmin watch |
| 23 | +2. **Select Distance Profile** (Optional): Press the menu button and choose "Distances" to select your preferred distance range (5K, 10K, Half Marathon, or Marathon) |
| 24 | +3. **Spin the Wheel**: Press the menu button and select "Spin" to start the roulette animation |
| 25 | +4. **Get Your Distance**: Watch the wheel spin and land on a random distance |
| 26 | +5. **Go Run!**: The selected distance is displayed in the center with a "GO RUN!" prompt |
24 | 27 |
|
25 | 28 | ## Compatibility |
26 | 29 |
|
27 | | -The **Roulette** app has just benn tested on the **Garmin Forerunner 965**. Compatibility with other Garmin devices will be added. |
| 30 | +This app is compatible with a wide range of Garmin devices, including: |
| 31 | + |
| 32 | +- **Forerunner Series**: 165, 165M, 255, 255M, 255S, 255SM, 265, 265S, 570 (42mm/47mm), 955, 965, 970 |
| 33 | +- **Fenix Series**: 7, 7S, 7X, 7 Pro, 8 (43mm/47mm), 8 Pro, 8 Solar, Fenix E |
| 34 | +- **Epix Series**: Epix 2, Epix 2 Pro (42mm/47mm/51mm) |
| 35 | + |
| 36 | +Tested primarily on **Garmin Forerunner 965**. |
| 37 | + |
| 38 | +## Development Setup |
28 | 39 |
|
29 | | -## Setup & Installation |
| 40 | +### Prerequisites |
30 | 41 |
|
31 | | -To use this app on a Garmin device, follow these steps: |
| 42 | +1. **Garmin Connect IQ SDK**: |
| 43 | + - Download and install the [Connect IQ SDK](https://developer.garmin.com/connect-iq/sdk/) from Garmin's developer portal |
| 44 | + - Set up your development environment following Garmin's official documentation |
32 | 45 |
|
33 | | -1. **Install Garmin Connect**: |
34 | | - - Download and install Garmin Connect from [Garmin's official website](https://www.garmin.com/). |
| 46 | +2. **IDE Options**: |
| 47 | + - **Visual Studio Code** with the Monkey C extension (recommended) |
| 48 | + - **Eclipse** with the Connect IQ plugin |
35 | 49 |
|
36 | | -2. **Install MonkeyC SDK**: |
37 | | - - Download the [MonkeyC SDK](https://developer.garmin.com/downloads/) to set up your development environment. |
| 50 | +### Building the App |
38 | 51 |
|
39 | | -3. **Import the project** into your MonkeyC environment. |
| 52 | +1. **Clone the repository**: |
| 53 | + ```bash |
| 54 | + git clone <repository-url> |
| 55 | + cd roulette |
| 56 | + ``` |
40 | 57 |
|
41 | | -4. **Build the app**: |
42 | | - - Run the build command using the MonkeyC SDK to compile the project and deploy it to your Garmin device. |
| 58 | +2. **Build the project**: |
| 59 | + - Using VS Code: Open the project and use the Monkey C build commands |
| 60 | + - Using command line: Use the MonkeyC compiler with the appropriate device target |
43 | 61 |
|
44 | | -5. **Launch the App**: |
45 | | - - Once installed, launch the **Roulette** app on your Garmin device and start pressing buttons to cycle through the numbers. |
| 62 | +3. **Deploy to device**: |
| 63 | + - Connect your Garmin device via USB |
| 64 | + - Use the Connect IQ SDK tools to deploy the compiled `.prg` file to your device |
| 65 | + |
| 66 | +### Project Structure |
| 67 | + |
| 68 | +``` |
| 69 | +roulette/ |
| 70 | +├── source/ # MonkeyC source files |
| 71 | +│ ├── RouletteRunnerApp.mc # Main application entry point |
| 72 | +│ ├── RouletteRunnerAppView.mc # View rendering and animation logic |
| 73 | +│ ├── RouletteRunnerMenuDelegate.mc |
| 74 | +│ ├── RouletteRunnerMenuBehavior.mc |
| 75 | +│ └── RouletteRunnerMenuDistancesDelegate.mc |
| 76 | +├── resources/ # App resources |
| 77 | +│ ├── drawables/ # Icons and images |
| 78 | +│ ├── jsonData/ # Distance profile data |
| 79 | +│ ├── layouts/ # UI layouts |
| 80 | +│ ├── menus/ # Menu definitions |
| 81 | +│ └── strings/ # English strings |
| 82 | +├── resources-spa/ # Spanish translations |
| 83 | +├── resources-por/ # Portuguese translations |
| 84 | +├── manifest.xml # App manifest and device compatibility |
| 85 | +└── monkey.jungle # Build configuration |
| 86 | +``` |
46 | 87 |
|
47 | 88 | ## Customization |
48 | 89 |
|
49 | | -- TBD |
| 90 | +### Adding Custom Distance Profiles |
| 91 | + |
| 92 | +Distance profiles are defined in `resources/jsonData/resources.xml`. Each profile is a JSON array of distance strings: |
| 93 | + |
| 94 | +```xml |
| 95 | +<jsonData id="customProfile">["1K", "2K", "3K", "5K", "8K", "13K"]</jsonData> |
| 96 | +``` |
| 97 | + |
| 98 | +To add a new profile: |
| 99 | +1. Add your JSON data to `resources/jsonData/resources.xml` |
| 100 | +2. Update the menu in `resources/menus/roulette_runner_distances_menu.xml` |
| 101 | +3. Add corresponding string resources for the profile name |
| 102 | +4. Update the menu delegate to handle the new profile selection |
50 | 103 |
|
51 | | -## Dependencies |
| 104 | +### Modifying Colors |
52 | 105 |
|
53 | | -- **MonkeyC SDK**: The app is built using the MonkeyC SDK for Garmin devices. |
54 | | -- **Garmin Device**: This app requires a Garmin device that supports the MonkeyC framework. |
| 106 | +The roulette wheel colors are defined in `RouletteRunnerAppView.mc`: |
| 107 | +- Red segments: `0xCC0000` |
| 108 | +- Black segments: `0x1A1A1A` |
| 109 | +- Gold accents: `0x888800` |
| 110 | +- Selected segment: `0x444400` |
| 111 | + |
| 112 | +### Adding Languages |
| 113 | + |
| 114 | +To add a new language: |
| 115 | +1. Create a new `resources-{lang}/` directory (e.g., `resources-fra/` for French) |
| 116 | +2. Copy `strings.xml` from `resources/strings/` and translate all strings |
| 117 | +3. Add the language code to `manifest.xml` under `<iq:languages>` |
| 118 | + |
| 119 | +## Technical Details |
| 120 | + |
| 121 | +- **Language**: MonkeyC (Garmin's proprietary language) |
| 122 | +- **Min API Level**: 3.2.0 |
| 123 | +- **App Type**: Watch App |
| 124 | +- **Animation**: Custom wheel rotation with physics-based deceleration |
| 125 | +- **Rendering**: Canvas-based drawing with polygon fills for segments |
55 | 126 |
|
56 | 127 | ## Roadmap |
57 | | -- [ ] Add different values customization (ie. Time, reps, etc) |
58 | | -- [ ] Add support for other Garmin Devices |
59 | | -- [ ] Display options based on running distance objetives |
| 128 | + |
| 129 | +- [ ] Add customizable distance values (time-based, rep-based workouts) |
| 130 | +- [ ] Support for additional Garmin device families (Venu, Enduro) |
| 131 | +- [ ] Display workout suggestions based on training objectives |
| 132 | +- [ ] Save spin history and statistics |
| 133 | +- [ ] Integration with Garmin training plans |
| 134 | + |
| 135 | +## Contributing |
| 136 | + |
| 137 | +Contributions are welcome! Please feel free to submit a Pull Request. |
60 | 138 |
|
61 | 139 | ## License |
62 | 140 |
|
63 | 141 | This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. |
| 142 | + |
| 143 | +## Support |
| 144 | + |
| 145 | +For issues, questions, or feature requests, please open an issue on the GitHub repository. |
0 commit comments