# OpenTracks

![Bluetooth sensors, recording, and activity export](docs/images/readme-banner.svg)

**A sensor-first fork of OpenTracks.** Record sport activities with Bluetooth sensors taking priority over GPS, alongside customized recording controls and audio behavior.

| Project | Platform | Main change | License |
| --- | --- | --- | --- |
| Personal fork | Android 8.0+ | Bluetooth sensor priority | [Apache 2.0](LICENSE) |

<p align="center">
  <a href="https://gitea.labus.uk/karol/OpenTracks/releases"><strong>Download fork APKs</strong></a> ·
  <a href="#getting-started">Build locally</a> ·
  <a href="#changes-from-upstream">What changed</a> ·
  <a href="README.upstream.md">Upstream documentation</a>
</p>

> **Fork identity** — [This repository](https://gitea.labus.uk/karol/OpenTracks) is based on [OpenTracksApp/OpenTracks](https://codeberg.org/OpenTracksApp/OpenTracks). Upstream store downloads do not include these modifications.

<details>
<summary>Browse all sections</summary>

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

</details>

## 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

| Area | Changes maintained in this fork |
| --- | --- |
| **Recording** | Bluetooth sensor data takes priority over GPS in the modified recording flow. |
| **Interface** | Expanded sensor settings and customized recording layouts. |
| **Audio** | Media controls in the statistics view; voice announcement and audio-focus changes. |
| **App identity** | Fork-specific application IDs, including `de.dennisguse.opentracks.fork` and its variants. |

## Requirements

| Use | Requirements |
| --- | --- |
| **Run the app** | Android 8.0 / API 26 or later, as configured in `build.gradle`. |
| **Build the app** | Android SDK platform 37 and the Gradle wrapper. The daemon toolchain requests JetBrains JDK 21 in `gradle/gradle-daemon-jvm.properties`. |

## Getting started

### Install a build

Download APKs from [this fork's Gitea releases](https://gitea.labus.uk/karol/OpenTracks/releases).

### Build from source

From the repository root:

```bash
./gradlew assembleIrreproducibleDebug
```

**Output:** `build/outputs/apk/`. The debug build is intended for development.

## 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

| Reference | What you will find |
| --- | --- |
| [Inherited upstream README](README.upstream.md) | Original features, screenshots, export formats, and project history. Retained from this checkout; local fork notice removed and malformed links corrected. |
| [Dashboard API](README_API.md) | Integration with external dashboards. |
| [Tested sensors](README_TESTED_SENSORS.md) | Documented sensor compatibility. |
| [Upstream release instructions](README_RELEASE.md) | Inherited release process; review before applying it to this fork. |
| [README style guide](docs/README-STYLE.md) | Shared documentation structure and presentation rules. |

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