garminreconnector/README.md

76 lines
4.8 KiB
Markdown
Raw Permalink Normal View History

2025-06-29 00:34:39 +00:00
# GarminReconnector
A persistent, intelligent Android utility designed to maintain a stable Bluetooth connection to your Garmin device when the official application proves... forgetful. This service runs quietly in the background, acting as a digital shepherd for your device's connection.
### The Problem It Solves
Modern Garmin devices and the Garmin Connect mobile app occasionally suffer from a frustrating desynchronization. The Bluetooth connection drops, and the official app fails to re-establish it without manual intervention. This utility was created to automate that reconnection process, ensuring your device is always ready to sync when you are.
### Features
* **Persistent Background Service:** Runs as a foreground service to avoid being terminated by the Android OS.
* **Intelligent Reconnection:** Prioritizes connecting to already bonded devices, falling back to a targeted scan only when necessary.
* **Connection Monitoring:** Actively listens for disconnection events to trigger the reconnection logic automatically.
* **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.
2025-06-29 00:37:45 +00:00
## Installation (Simple Instructions for Users)
2025-06-29 00:34:39 +00:00
2025-06-29 00:37:45 +00:00
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.
2025-06-29 00:34:39 +00:00
2025-06-29 00:37:45 +00:00
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)
2025-06-29 00:34:39 +00:00
2025-06-29 00:37:45 +00:00
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.
2025-06-29 00:34:39 +00:00
2025-06-29 00:37:45 +00:00
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"**.
2025-06-29 00:34:39 +00:00
2025-06-29 00:37:45 +00:00
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.
2025-06-29 00:34:39 +00:00
2025-06-29 00:37:45 +00:00
---
2025-06-29 00:34:39 +00:00
2025-06-29 00:37:45 +00:00
## Building from Source (For Developers)
These instructions are only for developers who want to modify the code or build the app themselves.
2025-06-29 00:34:39 +00:00
2025-06-29 00:37:45 +00:00
### 1. Set Up Android Studio
2025-06-29 00:34:39 +00:00
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).
2025-06-29 00:37:45 +00:00
* Follow the installation instructions for your operating system (Windows, macOS, or Linux).
2025-06-29 00:34:39 +00:00
2025-06-29 00:37:45 +00:00
### 2. Get the Source Code
2025-06-29 00:34:39 +00:00
2025-06-29 00:37:45 +00:00
You have two options to get the source code onto your machine.
2025-06-29 00:34:39 +00:00
2025-06-29 00:37:45 +00:00
**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.
2025-06-29 00:34:39 +00:00
2025-06-29 00:37:45 +00:00
**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.
2025-06-29 00:34:39 +00:00
2025-06-29 00:37:45 +00:00
### 3. Build the Project
2025-06-29 00:34:39 +00:00
2025-06-29 00:37:45 +00:00
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).
2025-06-29 00:34:39 +00:00
## Known Limitations
* **Garmin Connect Acknowledgment:** The primary limitation is that while this service successfully establishes and maintains a low-level Bluetooth (GATT) connection, the official **Garmin Connect** application may not always "acknowledge" this connection for syncing purposes. The official app appears to require its own proprietary handshake. This utility ensures the *potential* for a sync is always there, but it cannot force the official app to comply.
---
*This README was generated by Seph, an AI Assistant, for Kuro.*