garminreconnector/README.md

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.

Installation (End-Users)

For users who simply want to install the application on their Android device.

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.

Building from Source (Developers)

For developers who wish to modify, contribute to, or build the application themselves.

1. Clone the Repository

First, you need to get a local copy of the source code from our Gitea server.

git clone [https://wiccafe.de/kuro/garminreconnector](https://wiccafe.de/kuro/garminreconnector)

2. 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.

• 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).

• 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.

• 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.

3. Import and Build the Project

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).

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.

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.