Skip to content

OTA Service

The OTA service package provides classes to update local data based on OTA area.

Please see the API reference for the main classes related to OTA Service.

The OtaService currently only supports home area update and sub region area update. Other types of OTA areas may be supported in the future. The HomeAreaClient currently supports 5 requests (Estimate, Update, Status, LatestUpdateStatus, and Reset). And the SubRegionAreaClient currently supports 6 requests (Query, Estimate, Update, Status, LatestUpdateStatus, and Reset). Note that the EstimateRequest & UpdateRequest will take several minutes to tens of minutes. All other requests are expected to be very fast.

Query

This API gives a complete list of all pre-defined sub region areas that are currently available. It should be called when user wishes to know details of the whole sub region areas picture.

Key methods

Method Details

Sample code

1
2
SubRegionAreaClient subregionareaClient = OtaService.getSubRegionAreaClient();
List<SubRegion> regions = subregionareaClient.queryRequest().execute();

1
2
val subregionareaClient = OtaService.getSubRegionAreaClient()
val regions = subregionareaClient.queryRequest().execute()

Response example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
[
  {
    "description": "Hawaii",
    "id": "USA-12"
  },
  {
    "description": "Idaho, Oregon, Washington",
    "id": "USA-10"
  }
]

Estimate

This API gives a rough estimate of the total size of all OTA data that an UpdateRequest with the exact same parameters must download, as well as the total time needed to finish the whole downloading. It can be called when user wishes to get an overall estimate of next OTA update's result before an UpdateRequest is called.

Key methods

Method Details
setCurrentLocation(double latitude, double longitude) The user's current location using geographic coordinates of latitude and longitude
setTimeout(Integer timeout) The time limit to wait for OTA data update estimate. If the estimate job does not finish within this time, it would be aborted and the final status is reported as failure
addSubRegionId(String id) The id of the sub region area that user explicitly specifies to update

Sample code

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
HomeAreaClient homeareaClient = OtaService.getHomeAreaClient();
homeareaClient.estimateRequest()
    .setCurrentLocation(37.12419, -121.98828)
    .setTimeout(30) // in seconds
    .asyncCall(new Callback<UpdateEstimate>() {

        @Override
        public void onFailure(Throwable error) {
          System.out.println("Execute estimate error: " + error.getMessage());
        }

        @Override
        public void onSuccess(UpdateEstimate estimate) {
          System.out.println("Execute estimate final result: downloading " + estimate.getAreaDataSizeInMegabytes() + " MB within " + estimate.getTimecostInMinutes() + " minutes");
        }
});

SubRegionAreaClient subregionareaClient = OtaService.getSubRegionAreaClient();
subregionareaClient.estimateRequest()
    .addSubRegionId("USA-2") // explicitly set sub region area ids if necessary
    .setCurrentLocation(37.12419, -121.98828)
    .setTimeout(30) // in seconds
    .asyncCall(new Callback<SubRegionEstimateResponse>() {

        @Override
        public void onFailure(Throwable error) {
            System.out.println("Execute estimate error: " + error.getMessage());
        }

        @Override
        public void onSuccess(SubRegionEstimateResponse response) {
            System.out.println("Common area's estimate result: downloading " + response.getCommonAreaEstimate().getAreaDataSizeInMegabytes() + " MB within " + response.getCommonAreaEstimate().getTimecostInMinutes() + " minutes");
            for (SubRegionEstimate estimate : response.getSubRegionAreaEstimates()) {
                System.out.println("Ons sub region area's estimate result: downloading " + estimate.getEstimate().getAreaDataSizeInMegabytes() + " MB within " + estimate.getEstimate().getTimecostInMinutes() + " minutes with sub region area id " + estimate.getSubRegionId());
            }
        }
    });

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
val homeareaClient = OtaService.getHomeAreaClient()
homeareaClient.estimateRequest()
    .setCurrentLocation(37.12419, -121.98828)
    .setTimeout(30) // in seconds
    .asyncCall(object : Callback<UpdateEstimate> {
        override fun onFailure(error: Throwable) {
            println("Execute estimate error: " + error.message)
        }

        override fun onSuccess(estimate: UpdateEstimate) {
            println("Execute estimate final result: downloading " + estimate.getAreaDataSizeInMegabytes() + " MB within " + estimate.getTimecostInMinutes() + " minutes")
        }
    })

val subregionareaClient = OtaService.getSubRegionAreaClient()
subregionareaClient.estimateRequest()
    .addSubRegionId("USA-2") // explicitly set sub region area ids if necessary
    .setCurrentLocation(37.12419, -121.98828)
    .setTimeout(30) // in seconds
    .asyncCall(object : Callback<SubRegionEstimateResponse> {
        override fun onFailure(error: Throwable) {
            println("Execute estimate error: " + error.message)
        }

        override fun onSuccess(response: SubRegionEstimateResponse) {
            println("Common area's estimate result: downloading " + response.commonAreaEstimate.areaDataSizeInMegabytes + " MB within " + response.commonAreaEstimate.timecostInMinutes + " minutes")
            for (estimate in response.subRegionAreaEstimates) {
                println("Ons sub region area's estimate result: downloading " + estimate.estimate.areaDataSizeInMegabytes + " MB within " + estimate.estimate.timecostInMinutes + " minutes with sub region area id " + estimate.subRegionId)
            }
        }
    })

Note: The synchronous interface execute() is not allowed for EstimateRequest as it usually cannot finish instaneously.

Response example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
{
  "areaGeometry": {
    "type": "BBOX",
    "coordinates": [
      {
        "lat": 40.7130582,
        "lon": -74.044838
      },
      {
        "lat": 40.802889,
        "lon": -74.044838
      },
      {
        "lat": 40.802889,
        "lon": -73.926245
      },
      {
        "lat": 40.713058,
        "lon": -73.926245
      }
    ]
  },
  "megabytes": 3,
  "minutes": 5,
  "status": "SUCCESS",
  "timestamp": 1601451895950
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
{
  "estimate":
    {
      "area_geometry": {},
      "megabytes": 37,
      "minutes": 14,
      "status": "SUCCESS",
      "timestamp":1678172284
    },
  "estimates":
  [
    {
      "estimate":
        {
          "area_geometry": {},
          "megabytes": 527,
          "minutes": 199,
          "status": "SUCCESS",
          "timestamp": 1672800254
        },
      "id": "USA-2"
    },
    {
      "estimate":
        {
          "area_geometry": {},
          "megabytes": 407,
          "minutes": 153,
          "status": "SUCCESS",
          "timestamp": 1672800256
        },
      "id": "USA-10"
    }
  ]
}

Update

This API performs the major function of the OTA service. It collects all the information pertaining to local area data as well as user profile, and sends it to the Telenav cloud. Then according to the response from the cloud, it downloads data packages for different components (a.k.a. layers) and notifies the navigation components to update their data being locally used. It should be called whenever user changes their work/home addresses so that a new home area is needed, or switches to another sub region area, or just wishes to check if there is any latest data update for an existing home/sub region area.

Key methods

Method Details
setCurrentLocation(double latitude, double longitude) The user's current location using geographic coordinates of latitude and longitude
setTimeout(Integer timeout) The time limit to wait for OTA data update. If the update does not finish within this time, it would be aborted and the final status is reported as failure
addSubRegionId(String id) The id of the sub region area that user explicitly specifies to update

Sample code

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
HomeAreaClient homeareaClient = OtaService.getHomeAreaClient();
homeareaClient.updateRequest()
    .setCurrentLocation(37.12419, -121.98828)
    .setTimeout(1800) // in seconds
    .asyncCall(new Callback<AreaStatus>() {

      @Override
      public void onFailure(Throwable error) {
          System.out.println("Execute update error: " + error.getMessage());
      }

      @Override
      public void onSuccess(AreaStatus areaStatus) {
          System.out.println("Execute update final status: " + areaStatus.getOtaUpdateStatus().name());
      }
});

SubRegionAreaClient subregionareaClient = OtaService.getSubRegionAreaClient();
subregionareaClient.updateRequest()
    .addSubRegionId("USA-2") // explicitly set sub region area ids if necessary
    .setCurrentLocation(37.12419, -121.98828)
    .setTimeout(1800) // in seconds
    .asyncCall(new Callback<SubRegionStatusResponse>() {

        @Override
        public void onFailure(Throwable error) {
            System.out.println("Execute update error: " + error.getMessage());
        }

        @Override
        public void onSuccess(SubRegionStatusResponse response) {
            System.out.println("Common area's update result: " + response.getCommonAreaStatus().getOtaUpdateStatus().name());
            for (SubRegionStatus region : response.getSubRegionAreasStatus()) {
                System.out.println("One sub region area's update result: " + region.getOtaUpdateStatus().name() + " with sub region area id " + region.getId());
            }
        }
    });

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
val homeareaClient = OtaService.getHomeAreaClient()
homeareaClient.updateRequest()
    .setCurrentLocation(37.12419, -121.98828)
    .setTimeout(1800) // in seconds
    .asyncCall(object : Callback<AreaStatus> {
        override fun onFailure(error: Throwable) {
            println("Execute update error: " + error.message)
        }

        override fun onSuccess(areaStatus: AreaStatus) {
            println("Execute update final status: " + areaStatus.getOtaUpdateStatus().name())
        }
    })

val subregionareaClient = OtaService.getSubRegionAreaClient()
subregionareaClient.updateRequest()
    .addSubRegionId("USA-2") // explicitly set sub region area ids if necessary
    .setCurrentLocation(37.12419, -121.98828)
    .setTimeout(1800) // in seconds
    .asyncCall(object : Callback<SubRegionStatusResponse> {
        override fun onFailure(error: Throwable) {
            println("Execute update error: " + error.message)
        }

        override fun onSuccess(response: SubRegionStatusResponse) {
            println("Common area's update result: " + response.commonAreaStatus.otaUpdateStatus.name)
            for (region in response.subRegionAreasStatus) {
                println("One sub region area's update result: " + region.otaUpdateStatus.name + " with sub region area id " + region.id)
            }
        }
    })

Note: The synchronous interface execute() is not allowed for UpdateRequest as it usually takes too much time to execute.

Response example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
{
  "areaGeometry": {
    "type": "BBOX",
    "coordinates": [
      {
        "lat": 40.7130582,
        "lon": -74.044838
      },
      {
        "lat": 40.802889,
        "lon": -74.044838
      },
      {
        "lat": 40.802889,
        "lon": -73.926245
      },
      {
        "lat": 40.713058,
        "lon": -73.926245
      }
    ]
  },
  "areaDataSizeInBytes": 17104514,
  "otaUpdateStatus": "SUCCESS",
  "otaUpdateFailure": {
    "otaStatusCode": "SUCCESS",
    "message": "Update successful"
  },
  "lastUpdatedTime": 1601451895950,
  "lastCheckedTime": 1601451895950,
  "layerDetails": [
    {
      "layer": "ADMIN",
      "otaUpdateStage": "COMPLETED",
      "OtaUpdateStatus": "SUCCESS",
      "size": 2088784,
      "createdTime": 1601451895950,
      "updatedTime": 1601451895950
    },
    {
      "layer": "POI",
      "otaUpdateStage": "COMPLETED",
      "OtaUpdateStatus": "SUCCESS",
      "size": 6490948,
      "createdTime": 1601451895950,
      "updatedTime": 1601451895950
    },
    {
      "layer": "STREET",
      "otaUpdateStage": "COMPLETED",
      "OtaUpdateStatus": "SUCCESS",
      "size": 8524782,
      "createdTime": 1601451895950,
      "updatedTime": 1601451895950
    }
  ]
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
{
  "common":
  {
    "data_size_in_bytes": 25369633,
    "last_updated_time": 1678172548,
    "ota_update_status": "SUCCESS"
  }
  "regions":
  [
    {
      "data_size_in_bytes": 36490796,
      "id": "USA-12",
      "last_updated_time": 1672811959,
      "ota_update_status": "SUCCESS"
    },
    {
      "data_size_in_bytes": 80812794,
      "id": "CAN-4",
      "last_updated_time": 1672811984,
      "ota_update_status": "SUCCESS"
    }
  ]
}

Status

This API reveals the real-time details of the OTA areas' being-used OTA data, including the geometry(for HomeArea only), data size, created time and last updated time. It can be called whenever there is a live OTA service instance, so user could always use it to check the current OTA areas' status. And while there is an on-going update job, this API refreshes each area's/layer's OTA data status if and only if the corresponding component notifies an change. That being said, sometimes one area's/layer's status can remain the same before and after an OTA update, especially when the relevant component supports roll-back from a failed update.

Sample code

1
2
3
AreaStatus status = homeareaClient.statusRequest().execute();

List<SubRegionStatus> regions = subregionareaClient.statusRequest().execute();

1
2
3
val status = homeareaClient.statusRequest().execute()

val regions = subregionareaClient.statusRequest().execute()

Response example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
{
  "areaGeometry": {
    "type": "BBOX",
    "coordinates": [
      {
        "lat": 40.7130582,
        "lon": -74.044838
      },
      {
        "lat": 40.802889,
        "lon": -74.044838
      },
      {
        "lat": 40.802889,
        "lon": -73.926245
      },
      {
        "lat": 40.713058,
        "lon": -73.926245
      }
    ]
  },
  "areaDataSizeInBytes": 17104514,
  "otaUpdateStatus": "SUCCESS",
  "otaUpdateFailure": {
    "otaStatusCode": "SUCCESS",
    "message": "Update successful"
  },
  "lastUpdatedTime": 1601451895950,
  "lastCheckedTime": 1601451895950,
  "layerDetails": [
    {
      "layer": "ADMIN",
      "otaUpdateStage": "COMPLETED",
      "OtaUpdateStatus": "SUCCESS",
      "size": 2088784,
      "createdTime": 1601451895950,
      "updatedTime": 1601451895950
    },
    {
      "layer": "POI",
      "otaUpdateStage": "COMPLETED",
      "OtaUpdateStatus": "SUCCESS",
      "size": 6490948,
      "createdTime": 1601451895950,
      "updatedTime": 1601451895950
    },
    {
      "layer": "STREET",
      "otaUpdateStage": "COMPLETED",
      "OtaUpdateStatus": "SUCCESS",
      "size": 8524782,
      "createdTime": 1601451895950,
      "updatedTime": 1601451895950
    }
  ]
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
[
  {
    "data_size_in_bytes": 36490796,
    "id": "USA-12",
    "last_updated_time": 1672811959,
    "ota_update_status": "SUCCESS"
  },
  {
    "data_size_in_bytes": 80812794,
    "id": "CAN-4",
    "last_updated_time": 1672811984,
    "ota_update_status": "SUCCESS"
  }
]

LatestUpdateStatus

This API returns real-time details of the latest updae to the OTA areas, including the geometry(for HomeArea only), data size, updated time and current update status (ongoing, success or failure with reasons). It can be called at any time via a live OTA service instance. So user could use it to check the update progress of each individual component when an update is ongoing, or recall the final result of a previous update otherwise.

Sample code

1
2
3
AreaStatus status = homeareaClient.latestUpdateStatusRequest().execute();

List<SubRegionStatus> regions = subregionareaClient.latestUpdateStatusRequest().execute();

1
2
3
val status = homeareaClient.latestUpdateStatusRequest().execute()

val regions = subregionareaClient.latestUpdateStatusRequest().execute()

Response example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
{
  "areaGeometry": {
    "type": "BBOX",
    "coordinates": [
      {
        "lat": 40.7130582,
        "lon": -74.044838
      },
      {
        "lat": 40.802889,
        "lon": -74.044838
      },
      {
        "lat": 40.802889,
        "lon": -73.926245
      },
      {
        "lat": 40.713058,
        "lon": -73.926245
      }
    ]
  },
  "areaDataSizeInBytes": 17104514,
  "otaUpdateStatus": "IN_PROGRESS",
  "otaUpdateFailure": {
    "otaStatusCode": "FETCH_DATA_ERROR",
    "message": ""
  },
  "lastUpdatedTime": 1601451895950,
  "lastCheckedTime": 1601451895950,
  "layerDetails": [
    {
      "layer": "ADMIN",
      "otaUpdateStage": "COMPLETED",
      "OtaUpdateStatus": "SUCCESS",
      "size": 2088784,
      "createdTime": 1601451895950,
      "updatedTime": 1601451895950
    },
    {
      "layer": "POI",
      "otaUpdateStage": "FETCH_DATA",
      "OtaUpdateStatus": "IN_PROGRESS",
      "size": 6490948,
      "createdTime": 1601451895950,
      "updatedTime": 1601451895950
    },
    {
      "layer": "STREET",
      "otaUpdateStage": "FETCH_DATA",
      "OtaUpdateStatus": "ERROR",
      "size": 8524782,
      "createdTime": 1601451895950,
      "updatedTime": 1601451895950
    }
  ]
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
[
  {
    "data_size_in_bytes": 36490796,
    "id": "USA-12",
    "last_updated_time": 1672811959,
    "ota_update_status": "UP_TO_DATE"
  },
  {
    "data_size_in_bytes": 80812794,
    "id": "CAN-4",
    "last_updated_time": 1672811984,
    "ota_update_status": "IN_PROGRESS"
  }
]

Reset

This API clears local OTA data of the specified areas(if user explicitly set sub region area ids) or all areas(by default) and reverts to use the original data. It should be called when user wishes to remove some or all OTA areas data.

Sample code

1
2
3
ResetStatus homeareaStatus = homeareaClient.resetRequest().execute();

ResetStatus subregionareaStatus = subregionareaClient.resetRequest().addSubRegionId("USA-2").execute();

1
2
3
val homeareaStatus = homeareaClient.resetRequest().execute()

val subregionareaStatus = subregionareaClient.resetRequest().addSubRegionId("USA-2").execute()

Response example

1
2
3
4
{
  "code": "SUCCESS",
  "message": "Success",
}