Logging location traces

Navigation SDK for Android is only available upon request. Contact us to get started.

Navigation functionality depends on the user’s location as it is provided by the LocationProvider. Location updates trigger the navigation pipeline. For testing purposes, it is convenient to use the simulated location updates in the (Route simulation). However, in some cases the locations provided by the system location provider are less accurate, which can cause unwanted navigation behavior.

Therefore, the goal of recording the location traces is to gather the real-life locations from the test drives and use this data to simulate the navigation. This guide explains how to set up the LocationTracesRecorder to record location traces during drive tests and how to parse the traces using the LocationTracesParser.

Setup

This guide uses the Navigation SDK for Android, which is only available upon request. Contact us to get started.

To use the location traces logger add the following dependency to your module’s build.gradle.kts file and synchronize the project.

implementation("com.tomtom.sdk.location:traces-logger:1.1.0")

Recording TTP logs

Location traces are recorded during the navigation session. Therefore, a TomTomNavigation instance must be active for traces to be recorded. To start and stop the recording, use the LocationTracesRecorder. The recorder is initialized by the LocationTracesRecorderFactory. The recorded logs are saved using the LoggerStrategy.

The provided DirectoryLoggerStrategy is used by default. This requires the Uri that points to the existing directory on the device. The helper class is provided for an easier way to choose it. More information is in the section called Picking a directory from the device storage. For each recording, the recorder creates files in the directory with the name provided by the FileNameStrategy. Then, it saves the location traces to the file.

1val recorder: LocationTracesRecorder =
2    LocationTracesRecorderFactory.createTtpRecorder(context, tomTomNavigation, directoryUri).value()
3
4recorder.startRecording()
5
6recorder.stopRecording()

Picking a directory from the device storage

The DirectoryLoggerStrategy uses the directory Uri to create files in the selected folder. On Android, the directory can be chosen using the Storage Access Framework. To make life easier, we provide the helper class SharedStorageDirectoryPicker that is accessing the directory hierarchy. The result of selecting the directory is returned via the SharedStorageDirectoryPicker.DirectoryPickerCallback.

1val picker = SharedStorageDirectoryPicker(activityResultRegistry)
2
3picker.pickDirectory(
4    null,
5    object : SharedStorageDirectoryPicker.DirectoryPickerCallback {
6        override fun onDirectoryPicked(directoryUri: Uri) {
7            /* YOUR CODE GOES HERE */
8        }
9
10        override fun onCanceled() {
11            /* YOUR CODE GOES HERE */
12        }
13    }
14)

If you want to provide the directory without using the SharedStorageDirectoryPicker, you can select a directory on your own and provide a URI to the LocationTracesRecorderFactory.createTtpRecorder(Context, TomTomNavigation, Uri, FileNameStrategy). Using this option, remember that the URI must point to the directory and you should ensure that your app has write access permission.

Parsing TTP logs

To replay the scenario from the recorded location traces, you need to parse the logs to the list of GeoLocation objects. The locations can then be used in the SimulationLocationProvider to simulate the navigation. For more details, see the Route simulation guide.

The LocationTracesParser is used to parse logs from the asset file, InputStream, or the file stored on the device referenced by the Uri. To parse the asset file the additional import is required. The helper class is provided for an easier way to access the file on the device. More detailed information is in the guide called Accessing TTP file on the device storage. Note that the file must store logs in the TTP format. The app will crash if the logs are not stored in TTP format. To initialize the LocationTracesParser for the TTP format, use the LocationTracesParserFactory.createTtpTracesParser(Context) method.

1import com.tomtom.sdk.location.traceslogger.parser.fromAssets
2import com.tomtom.sdk.location.traceslogger.parser.LocationTracesParserFactory
3import com.tomtom.sdk.location.traceslogger.parser.LocationTracesParser
4
5@Suppress("unused")
6fun parsingTtpLogsSnippets(context: Context, fileUri: Uri, inputStream: InputStream) {
7    val parser: LocationTracesParser =
8        LocationTracesParserFactory.createTtpTracesParser(context)
9    val locationsFromFileUri: List<GeoLocation> = parser.fromFileUri(fileUri)
10    val locationsFromLines: List<GeoLocation> = parser.fromInputStream(inputStream)
11    val locationsFromAssets: List<GeoLocation> = parser.fromAssets(context, "location_logs.ttp")
12}

Accessing TTP file on the device storage

To choose the file from device storage, we recommend using the Storage Access Framework. The simplified way of using it is exposed in the helper class called SharedStorageFileAccessor. Note that the default FileExtension for which the compliance check will be done is the TTP extension. If another file type is selected, the IllegalStateException will be thrown. The result of choosing a file is returned via the SharedStorageFileAccessor.FilePickedCallback. The returned Uri can then be used in the LocationTracesParser to retrieve data from the file.

1val accessor = SharedStorageFileAccessor(activityResultRegistry, FileExtension.TtpExtension)
2
3accessor.pickFile(
4    context,
5    object : SharedStorageFileAccessor.FilePickedCallback {
6        override fun onFilePicked(fileUri: Uri) {
7            /* YOUR CODE GOES HERE */
8        }
9
10        override fun onCanceled() {
11            /* YOUR CODE GOES HERE */
12        }
13    }
14)

Next steps

Since you have learned how to record and parse location logs, here are recommendations for the next steps: