Open GPS Tracker

An offline-first, high-accuracy 3D trajectory tracking app for Android.

English | 繁體中文

Open GPS Tracker is an open-source Android application designed for long-term background recording of your 3D movement trajectory (including flight paths, hiking trails, and driving routes). It saves data locally, functions entirely offline, and allows you to easily manage and export standard GPX files containing full altitude and metadata.

---

🚀 Downloads

You can download the latest version of the app directly from our GitHub Releases page.

---

✨ Key Features

• High-Accuracy 3D Tracking: Captures precise latitude, longitude, altitude (<ele> tag in GPX), speed, and bearing.
• Offline-First Architecture: No internet required. Perfect for deep wilderness hikes and flight tracking.
• Smart Background Service: Utilizes Android Foreground Services and WakeLocks to ensure trajectory recording survives Doze Mode and system limits.
• GNSS Constellation Details: View real-time GPS data and see exactly which GNSS satellites (GPS, GLONASS, Galileo, BEIDOU, SBAS, etc.) are currently in use with live green/red visual indicators.
• Intelligent GPS Monitoring: Automatically detects when the system's location provider is disabled and prompts the user, preventing silent data loss.
• Dynamic Frequency Control: Adjust your recording intervals dynamically (e.g., from 1 second to 60 seconds) without needing to interrupt the active session.
• Comprehensive Track Management: A clean, tabbed interface to view all historical recorded sessions, their start times, and durations.
• Easy Export & Deletion: Export any specific tracking session directly to a standard GPX 1.1 XML file or delete it permanently from the local Room database to save space.
• Intelligent Routine Analysis: A sophisticated background engine that monitors user behavior 24/7 to identify daily life patterns. See the Deep Dive section below.
• Google Play Policy Compliant: Meets all strict background location policies (including prominent disclosures) for seamless publishing.

---

🔍 Routine Activity Analysis Deep Dive

The Routine Activity Analysis engine move beyond simple coordinates, providing users with a comprehensive breakdown of how they spend their time across space and time.

🧠 The Intelligent State Machine

The core of the analysis is a robust state machine that categorizes time into four primary states:

• 🏠 HOME: Automatically detected when stationary within a customizable radius of your set home coordinates.
• 💼 WORK: Identified when staying at your pre-defined workplace.
• 🏃 MOVING: Triggered by high-confidence activity recognition (Walking, Running, Cycling, or Driving).
• 🌲 OUTDOOR STAY: Stationary periods detected in locations outside of your primary zones (e.g., parks, shops, or friend's houses).

🛠 Technical Implementation

• Activity Recognition API: Integrates with Google Play Services to perform low-power behavior sensing, significantly reducing battery drain compared to continuous GPS polling.
• Temporal Debouncing: Implements a 5-minute "Stationary Debounce" logic. The engine requires a sustained period of immobility before transitioning from MOVING to a stationary state, effectively filtering out sensor noise during stops at traffic lights or short pauses.
• Coordinate Matching: Uses high-precision distance calculation algorithms to match current coordinates against user-defined profiles, allowing for fine-grained geofencing control (default 100m radius).
• Architecture: Built on a decoupled service architecture using RoutineAnalysisManager and ActivityUpdateReceiver, ensuring analysis continues even if the main UI application is cleared from memory.

📊 Data Insights & Export

• Custom Pie Chart: A high-performance visualization component custom-drawn using Jetpack Compose Canvas for fluid daily summaries.
• Scientific JSON Export: All analysis transitions are exportable as structured JSON data, facilitating advanced external analysis for spatial research or personal productivity audits.

🛠 Tech Stack

The app is built utilizing modern Android development practices and the latest Jetpack libraries:

• Language: Kotlin
• UI Toolkit: Jetpack Compose (Material Design 3)
• Architecture: Clean Architecture + MVVM (Model-View-ViewModel)
• Dependency Injection: Dagger-Hilt
• Local Storage: Room Database
• Preferences: Jetpack DataStore
• Asynchronous Programming: Kotlin Coroutines & Flow
• Location API: Google Play Services FusedLocationProviderClient & GnssStatusCompat
• Target SDK: 35

🚀 Getting Started

Prerequisites

• Android Studio: Ladybug or newer.
• JDK: Version 17+

Installation & Build

1. Clone the repository:

   git clone https://github.com/kuoyaoming/GPSPY.git
   cd GPSPY

2. Open in Android Studio: Import the project into Android Studio. Gradle will automatically sync and download required dependencies.

3. Build via Command Line (Optional):

   # Compile and build the debug APK
   ./gradlew assembleDebug
   
   # Run local unit tests
   ./gradlew testDebugUnitTest

4. Install on your device: Run the app directly via Android Studio, or locate the APK in app/build/outputs/apk/debug/app-debug.apk and install it manually via adb.

⚙️ Automated CI/CD

This project uses GitHub Actions for Continuous Integration and Deployment. It will automatically build the APK and AAB files upon every push to the main branch or when a Pull Request is submitted.

To enable automated signed releases, configure the following GitHub Secrets in your repository settings:

• KEYSTORE_BASE64: Your release keystore, Base64 encoded.
• KEY_ALIAS: The alias of your release key.
• KEY_PASSWORD: The password for your key.
• STORE_PASSWORD: The password for your keystore.

🤝 Contributing

Contributions are always welcome! Whether it's reporting a bug, discussing improvements, or submitting a Pull Request, your input is highly valued.

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

Please read our CONTRIBUTING.md for details on the process for submitting pull requests to us.

📄 License

Distributed under the Apache License 2.0. See LICENSE for more information.