Telematics SDK - User Guide  v1.63.7
Location Simulation

This section has details about the simulation for APIs under the telux::loc namespace.


Overview of Location Simulation

The location simulation framework provides the ability to record location data from an actual Telematics device. Applications using ILocationManager APIs will get reports from this recorded data.



Location Simulation Framework


Configuring Location API responses

The framework allows responses to each API to be configured via a JSON file.
Each location manager has its own JSON configuration file. Clients can configure these files for:
Location Manager: configured via simulation/json/api/loc/ILocationManager.json
Example:

API command response for startBasicReports

"startBasicReports": {
    "callbackDelay": 400,
    "error": "SUCCESS",
    "status": "SUCCESS"
},

Location Configurator: configured via simulation/json/api/loc/ILocationConfigurator.json
Example:

API command response for configureRobustLocation

"configureRobustLocation": {
    "callbackDelay": 400,
    "error": "SUCCESS",
    "status": "SUCCESS"
},

Dgnss Manager: configured via simulation/json/api/loc/IDgnssManager.json
Example:

API command response for createSource

"createSource": {
    "callbackDelay": 400,
    "status": "SUCCESS"
},


Support for location reports and notifications

Currently, only the following APIs can be invoked using data from the prerecorded files:

  1. Basic Location Reports
  2. Detailed Location Reports

The remaining APIs only provide canned data in their invocation. Future releases will add support for providing data from the prerecorded file for the following APIs-

  1. NMEA Reports
  2. SV Reports
  3. Measurements Reports
  4. Jammer Reports

Location SystemInfo Reports – Canned response generated from within the LocationManagerStub whenever the client registers for the event for the first time.
Future releases will support periodic triggers dynamically.


Xtra Updates – Canned response generated from within the LocationConfiguratorStub whenever the Xtra feature is enabled or disabled. Future releases will support periodic triggers dynamically.


Format of location reports

The location simulation has the ability to provide PVT data to clients that is prerecorded/captured from the target device in the form of a CSV.

Reports captured via CSV currently:
Basic location and Detailed PVT Location report. Other reports such as NMEA, SV, Measurements, and Jammer provide canned responses.

Data representation:

  1. Each row of the CSV represents a complete iteration of the report at time interval T.
  2. The order in which the fields for every row are represented are as per: simulation/libs/loc/PRE-RECORDED_LOCATION_DATA.csv

Data reporting:

  1. Let us assume the CSV provided to the simulation has 25,000 rows.
  2. Once the client begins a PVT session, each row from the CSV is sent to the client as an iteration after every 100 ms.
  3. SDK provides the automatic replay feature .i.e, if the PVT session is still ongoing and all the rows in the CSV are iterated, the library provides data again from the first row.

Client usage:

  1. By default, CSV based reports are enabled under the tel.conf file. The CSV file is present by default under - ${ROOTFS}/data/telux/csv/PRE-RECORDED_LOCATION_DATA.csv.
  2. Clients can configure the retrieval of reports via tel.conf by modifying the following fields:
    REPORT_SIMULATION_TYPE
    LOCATION_REPORT_FILE_NAME
    Clients are requested to refer to the documentation of these fields under tel.conf for further usage.


Recording utility for Location Reports

The goal of the recording utility is to capture the location reports running on the target device so that the collected data can be used for the off-target SDK simulation.

Reports supported by the recording utility currently:
Basic location and Detailed PVT Location report.

Data representation:

  1. Each iteration of the PVT report is represented by a string containing the PVT fields separated by a comma(,).
  2. The order in which the fields for every row are represented are as per: simulation/libs/loc/PRE-RECORDED_LOCATION_DATA.csv

The tool to capture data is provided under:
simulation/recording_simulation.sh
simulation/recording_simulation.bat

Client usage:

  1. Connect the target to the PC.
  2. Ensure that adb is available and restart adb as root by running "adb root".
  3. Run the recording_simulation script and capture the data in a CSV file.


Limitations

  1. CSV report handling and recording is only supported for Basic and Detailed PVT Location at a fixed interval of 100 ms.
  2. Events like Xtra data updation/Location system info updation are not being triggered asynchronously.
  3. Dgnss report injection is not supported.