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.11.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()34recorder.startRecording()56recorder.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)23picker.pickDirectory(4 null,5 object : SharedStorageDirectoryPicker.DirectoryPickerCallback {6 override fun onDirectoryPicked(directoryUri: Uri) {7 // YOUR CODE GOES HERE8 }910 override fun onCanceled() {11 // YOUR CODE GOES HERE12 }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.fromAssets2import com.tomtom.sdk.location.traceslogger.parser.LocationTracesParserFactory3import com.tomtom.sdk.location.traceslogger.parser.LocationTracesParser45@Suppress("unused")6fun parsingTtpLogsSnippets(7 context: Context,8 fileUri: Uri,9 inputStream: InputStream,10) {11 val parser: LocationTracesParser =12 LocationTracesParserFactory.createTtpTracesParser(context)13 val locationsFromFileUri: List<GeoLocation> = parser.fromFileUri(fileUri)14 val locationsFromLines: List<GeoLocation> = parser.fromInputStream(inputStream)15 val locationsFromAssets: List<GeoLocation> = parser.fromAssets(context, "location_logs.ttp")16}
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)23accessor.pickFile(4 context,5 object : SharedStorageFileAccessor.FilePickedCallback {6 override fun onFilePicked(fileUri: Uri) {7 // YOUR CODE GOES HERE8 }910 override fun onCanceled() {11 // YOUR CODE GOES HERE12 }13 },14)
Next steps
Since you have learned how to record and parse location logs, here are recommendations for the next steps:
Building a navigation app
A tutorial showing how to build a complete application with the TomTom navigation.
Route simulation
Simulate the navigation along the route.
Location tracking
Match the location provided by the LocationProvider to the route.