OpenTracks/README.md

OpenTracks — sensor-first fork

A customized fork of OpenTracks for sport tracking that prioritizes Bluetooth sensor measurements over GPS data.

Upstream: OpenTracksApp/OpenTracks. Fork repository: karol/OpenTracks.

Fork purpose · Changes from upstream · Requirements · Getting started · Configuration · Usage · Development · Upstream maintenance · Documentation · Credits · License

Fork purpose

Use hardware sensors as the primary source of cadence, speed, and distance, with corresponding changes to recording controls and audio behavior.

Changes from upstream

• Bluetooth sensor data takes priority over GPS in the modified recording flow.
• Expanded sensor settings and recording layouts.
• Media controls in the statistics view.
• Voice announcement and audio-focus changes.
• Fork-specific application IDs, including de.dennisguse.opentracks.fork and its build variants.

Requirements

• Android 8.0/API 26 or later for the app, as configured in build.gradle.
• Android SDK with platform 37 for builds.
• The Gradle wrapper; daemon toolchain settings request JetBrains JDK 21 (gradle/gradle-daemon-jvm.properties).

Getting started

Download this fork's APKs from Gitea releases, or build a debug APK from the repository root:

./gradlew assembleIrreproducibleDebug

Build output is under build/outputs/apk/. Store links in the inherited documentation distribute upstream OpenTracks and do not include this fork's changes.

Configuration

Configure Bluetooth sensors and recording options in the app settings. Verify the selected sensors before starting a recording.

The inherited public API examples use upstream package names. When targeting this fork, use the application ID of the installed variant from build.gradle; activity class names retain the de.dennisguse.opentracks namespace.

Usage

Start a recording after pairing the desired sensors. See the inherited feature and usage reference for tracking, export formats, dashboards, backup, and supported sensor types.

The screenshots are inherited documentation assets and may differ from the modified interface.

Development

Run the checks configured by Gitea Actions:

./gradlew lint
./gradlew testNightlyDebugUnitTest --stacktrace

CI configuration defines build and prerelease publication behavior. Check the workflow files for toolchain and runner requirements.

Upstream maintenance

The upstream sync workflow runs daily and on manual dispatch. It merges main from the configured Gitea upstream mirror into this fork's main. Resolve sync failures before retrying.

After an upstream merge, review sensor priority, recording layouts, announcements, and application IDs. Keep fork-specific instructions in this README. Refresh README.upstream.md separately from the merged upstream documentation, retaining upstream attribution and checking relative links.

Documentation

• Inherited upstream README: retained from this checkout, with the local fork notice removed and malformed local links corrected.
• Dashboard API.
• Tested sensors.
• Upstream release instructions: review before applying to this fork.

README style guide.

Credits

Development of the changes maintained in this fork was carried out to a significant extent with assistance from AI coding agents, in collaboration with the repository owner.

OpenTracks is developed by its upstream contributors and derives from Google My Tracks. See the project history and upstream contribution guidelines. Report fork-specific behavior in this fork's issue tracker.

License

See LICENSE for the inherited Apache License 2.0 terms and notices.