# OpenTracks — sensor-first fork

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

**Upstream:** [OpenTracksApp/OpenTracks](https://codeberg.org/OpenTracksApp/OpenTracks).
**Fork repository:** [karol/OpenTracks](https://gitea.labus.uk/karol/OpenTracks).

[Fork purpose](#fork-purpose) · [Changes from upstream](#changes-from-upstream) · [Requirements](#requirements) · [Getting started](#getting-started) · [Configuration](#configuration) · [Usage](#usage) · [Development](#development) · [Upstream maintenance](#upstream-maintenance) · [Documentation](#documentation) · [Credits](#credits) · [License](#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](https://gitea.labus.uk/karol/OpenTracks/releases), or build a debug APK from the repository root:

```bash
./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](README.upstream.md#features) for tracking, export formats, dashboards, backup, and supported sensor types.

The [screenshots](README.upstream.md#screenshots) are inherited documentation assets and may differ from the modified interface.

## Development

Run the checks configured by Gitea Actions:

```bash
./gradlew lint
./gradlew testNightlyDebugUnitTest --stacktrace
```

[CI configuration](.gitea/workflows/ci.yaml) defines build and prerelease publication behavior. Check the workflow files for toolchain and runner requirements.

## Upstream maintenance

The [upstream sync workflow](.gitea/workflows/auto-update.yaml) 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](README.upstream.md): retained from this checkout, with the local fork notice removed and malformed local links corrected.
- [Dashboard API](README_API.md).
- [Tested sensors](README_TESTED_SENSORS.md).
- [Upstream release instructions](README_RELEASE.md): review before applying to this fork.

[README style guide](docs/README-STYLE.md).

## 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](README.upstream.md#project-history) and [upstream contribution guidelines](CONTRIBUTING.md). Report fork-specific behavior in this fork's issue tracker.

## License

See [LICENSE](LICENSE) for the inherited Apache License 2.0 terms and notices.