From 6eddface6d5b530eb1acf655bf439ce59a429f5e Mon Sep 17 00:00:00 2001 From: Kuro Date: Sun, 29 Jun 2025 02:37:45 +0200 Subject: [PATCH] updated the readme file --- README.md | 73 ++++++++++++++++++++++++++----------------------------- 1 file changed, 34 insertions(+), 39 deletions(-) diff --git a/README.md b/README.md index c57955c..c3dbb4d 100644 --- a/README.md +++ b/README.md @@ -14,63 +14,58 @@ Modern Garmin devices and the Garmin Connect mobile app occasionally suffer from * **Status Notifications:** Provides a persistent notification to show the current connection status (e.g., "Connected," "Disconnected," "Scanning..."). * **Zero-Configuration:** Simply install, grant permissions, and let it run. -## Installation (End-Users) +## Installation (Simple Instructions for Users) -For users who simply want to install the application on their Android device. +These instructions are for users who just want to install and use the app on their phone. You do **not** need Git, Android Studio, or any programming knowledge. -1. **Download the APK:** Navigate to the **Releases** section of this Gitea repository. -2. Download the latest `.apk` file (e.g., `garminreconnector-v1.0.apk`). -3. **Enable Unknown Sources:** On your Android device, you may need to allow installations from unknown sources. This setting is usually found in `Settings > Security` or `Settings > Apps > Special app access`. -4. **Install the App:** Open the downloaded `.apk` file from your file manager or browser downloads. Follow the on-screen prompts to install the application. -5. **Grant Permissions:** After installation, launch the app. It will request necessary permissions for **Location** (required by Android for Bluetooth scanning) and **Notifications**. Please grant these for the app to function correctly. +1. **Go to the Downloads Page:** Click on this direct link to go to the app's download page: + [**https://wiccafe.de/kuro/garminreconnector/releases**](https://wiccafe.de/kuro/garminreconnector/releases) -## Building from Source (Developers) +2. **Download the App File:** On that page, look for the latest release (usually at the top). Under a section called **"Assets,"** you will see a file ending in `.apk` (for example, `garminreconnector-v1.0.apk`). Tap on this file to download it to your phone. -For developers who wish to modify, contribute to, or build the application themselves. +3. **Allow and Install the App:** Your phone will warn you about installing apps from outside the Play Store. This is normal. + * Open the downloaded `.apk` file. You can usually find it by pulling down your phone's notification bar, or by looking in a "Downloads" folder on your phone. + * A security prompt will appear. If it mentions "Install unknown apps" or "Unknown sources," tap "Settings" and enable the permission for your browser (like Chrome) or your file manager. + * Go back to the installation screen and tap **"Install"**. -### 1. Clone the Repository +4. **Grant Permissions:** Once the installation is finished, open the **GarminReconnector** app. It will ask for two permissions: **Location** and **Notifications**. Please **allow** these, as the app needs them to find your watch and run correctly. -First, you need to get a local copy of the source code from our Gitea server. +--- -```bash -git clone [https://wiccafe.de/kuro/garminreconnector](https://wiccafe.de/kuro/garminreconnector) -``` +## Building from Source (For Developers) -### 2. Set Up Android Studio +These instructions are only for developers who want to modify the code or build the app themselves. + +### 1. Set Up Android Studio Ensure you have Android Studio installed and configured on your system. * **Download:** Get the latest version from the official [Android Studio website](https://developer.android.com/studio). +* Follow the installation instructions for your operating system (Windows, macOS, or Linux). -* **Windows:** - 1. Run the downloaded `.exe` installer. - 2. Follow the setup wizard to install Android Studio and the necessary Android SDK components. - 3. Ensure the Android SDK includes an API level appropriate for this project (e.g., API 33 or higher). +### 2. Get the Source Code -* **macOS:** - 1. Open the downloaded `.dmg` file. - 2. Drag and drop Android Studio into the Applications folder. - 3. Launch Android Studio and follow the setup wizard to install the SDK components. +You have two options to get the source code onto your machine. -* **Linux (Debian/Ubuntu):** - 1. Unpack the downloaded `.zip` file into an appropriate location, like `/usr/local/` or `~/`. - 2. Navigate to the `android-studio/bin/` directory in your terminal. - 3. Run `./studio.sh` to launch Android Studio. - 4. Follow the setup wizard to complete the installation. +**Option A: Clone from Command Line** +```bash +git clone [https://wiccafe.de/kuro/garminreconnector](https://wiccafe.de/kuro/garminreconnector) +``` +After cloning, open the project in Android Studio by selecting **"Open an Existing Project"** and navigating to the cloned directory. -### 3. Import and Build the Project +**Option B: Clone from within Android Studio** +1. Open Android Studio. +2. From the welcome screen, select **"Get from VCS"** (Version Control). +3. In the URL field, paste the repository URL: `https://wiccafe.de/kuro/garminreconnector` +4. Choose a local directory where the project will be saved. +5. Click **"Clone"**. Android Studio will download the project and automatically sync it. -1. **Open Android Studio.** -2. From the welcome screen, select **"Open an Existing Project"**. -3. Navigate to the directory where you cloned the `garminreconnector` repository and select it. -4. Android Studio will automatically detect the Gradle project and begin syncing. This may take a few minutes as it downloads the required dependencies. -5. Once the Gradle sync is complete, you can build the project by going to **Build > Make Project**. -6. To run the application, connect an Android device via USB (with Developer Options and USB Debugging enabled) or set up an Android Virtual Device (AVD). -7. Select your target device from the dropdown menu and click the **'Run'** button (the green play icon). +### 3. Build the Project -## Usage - -After installing and granting permissions, the app's service will start automatically. A persistent notification will appear in your status bar, indicating the service is active and showing the current connection state of your Garmin device. There is no further interaction required. +1. Wait for the Gradle sync to complete. This may take a few minutes. +2. Once the sync is complete, you can build the project by going to **Build > Make Project**. +3. To run the application, connect an Android device or use the built-in emulator. +4. Select your target device from the dropdown menu and click the **'Run'** button (the green play icon). ## Known Limitations