Table of Contents
This is a programming interface based on Android Intents to communicate with OpenTracks - a FLOSS sports tracking app. OpenTracks can record GPS based activity/workouts and while doing that, provide live update of current status, for example speed, duration of the activity and so on.
Smart device developers of Gadgetbridge can use this programming interface to utilize GPS tracking for a smart band/watch device without GPS. Gadgetbridge has an internal implementation which smart devices can take use, currently the best implementation in Gadgetbridge is for the Fossil smart watch where it is used for it's workout app. Gadgetbridge also allows Mibands/Amazfit bands/watches to use this API as a remote trigger via Button and Device actions. The Button actions allow you can to start activity recording in OpenTracks by using the button on the smart band/watch. In the Debug menu in Gadgetbridge, there are Start/Stop/Status buttons to do the same without any involvement of a on wrist device.
What does it do for the user:
This can remotely start (and i the future also stop) OpenTracks fitness activity recording. OpenTracks can provide feedback about current status (duration of activity, speed and so on) of the activity. This is very similar to the "Workout recording" in MiFit does (with the selection of type of workout and so on...). See short step by step manual below for how to use this.
To use this practically:
- Install OpenTracks Nightly release or official release on F-Droid.
- Enable the API in OpenTracks
- In Gadgetbridge settings, select "OpenTracks package name" based on which OpenTracks version you installed. (official, playstore, debug, nightly...)
- Use this function either in:
The activity type (walking, running, biking...) is set in OpenTracks settings. This means that you cannot specify upfront via the API call the type of activity to be recorded, but activity type can of course be changed by the user later via editing the recorded activity in OpenTracks later.
For Miband/Amazfit devices, we currently do not utilize the "Record activity/Workout" on the band (triggered either from the phone companion app or from the band/watch on newer devices).
API Implementation in Gadgetbridge
A short explanation of how this integration with OpenTracks works:
Starting the recording from a device requires calling
this class. For a simple example, check out the implementation in
WorkoutRequestHandler, used by the Fossil HR series. The OpenTracks class
can be set in the Gadgetbridge settings and depends on the installation source
used for OpenTracks. Details can be found in their documentation here:
startRecording() sends an
explicit Intent to OpenTracks signalling it to start recording. It passes along
the package name and class name of our
OpenTracksController which OpenTracks
will use to send the statistics URIs to. After starting the recording service,
OpenTracks uses a new explicit Intent to start our
passes along the URIs and the read permissions for those URIs (using
Intent.FLAG_GRANT_READ_URI_PERMISSION). So at that point
OpenTracksController is started as a new
Context) which has
the read permissions for the statistics URIs. The controller saves its
Context into the
OpenTracksContentObserver in the GB main process, so it
can keep running and read the statistics with the correct
whatever class, device or activity calls the methods on the
OpenTracksContentObserver from, it will always work.
Testing the OpenTracks API from adb
adb shell am start -n de.dennisguse.opentracks.debug/de.dennisguse.opentracks.publicapi.StartRecording
adb shell am start -n de.dennisguse.opentracks.debug/de.dennisguse.opentracks.publicapi.StopRecording