Continuous replanning

VERSION 0.3.34
PUBLIC PREVIEW

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

In order to improve the driver’s driving experience, the Navigation module periodically tries to replan the current route in the following situations:

  • To refresh route data such as the estimated time of arrival (ETA).
  • To find a better alternative.
  • On deviation from the planned route.

This is what continuous replanning stands for.

A route is planned by using the route optimization type defined in the RoutePlan.

Route Replanning Policy

The RouteReplanningPolicy specifies how continuous replanning will work:

The default policy is REFRESH_ONLY.

Route refresh

Every trip takes time and the road situation is constantly changing, so route data may become out of date while driving. Route refresh provides users the most up-to-date route information such as:

  • Travel time and ETA (Estimated Time of Arrival)
  • Traffic information (delay and length of traffic)
  • Updated legs and sections

In order for continuous replanning to work in refreshing mode, user needs to set the RouteReplanningPolicy.REFRESH_ONLY policy during the RouteReplanningEngine configuration.

1val options = RouteReplanningEngineOptions(
2 routeReplanningPolicy = RouteReplanningPolicy.REFRESH_ONLY
3)
4val engine = RouteReplanningEngineFactory.create(options)
5navigationConfigurationBuilder.routeReplanningEngine(engine)

Replanning response

The updated route can be applied automatically or manually and the reason will be set to RouteUpdateReason.REFRESH.

Finding better alternatives

If you would like to receive alternative route proposals you need to set RouteReplanningPolicy.FIND_BETTER policy during the RouteReplanningEngine configuration. Continuous replanning will then try to find a better alternative to the current route. Only none are found will the current one be refreshed.

1val options = RouteReplanningEngineOptions(
2 routeReplanningPolicy = RouteReplanningPolicy.FIND_BETTER
3)
4val engine = RouteReplanningEngineFactory.create(options)
5navigationConfigurationBuilder.routeReplanningEngine(engine)

Configuring the BetterRouteSelector

The RouteReplanningEngine provides a default BetterRouteSelector implementation for selecting the best route. This can be configured by setting the following fields in RouteReplanningEngineOptions:

  • minTrafficDelay - Minimum traffic delay on the current route to trigger a search for a better alternative.
  • minTimeDifference - How much the alternative route has to be faster to be used as a replan proposal.

By default, minTrafficDelay is set to 10 minutes and minTimeDifference to 5 minutes.

1val options = RouteReplanningEngineOptions(
2 minTrafficDelay = minTrafficDelay,
3 minTimeDifference = minTimeDifference
4)
5val engine = RouteReplanningEngineFactory.create(options)
6navigationConfigurationBuilder.routeReplanningEngine(engine)

Providing a custom better router selector

If the default implementation of BetterRouteSelector does not do what you need it to do, you can provide your own when creating RouteReplanningEngine.

val engine = RouteReplanningEngineFactory.create(options, customBetterRouteSelector)
navigationConfigurationBuilder.routeReplanningEngine(engine)

Replanning response

The updated route can be applied automatically or manually and the RouteUpdateReason will be set to:

  • BETTER_FOUND - A better alternative has been found for the current route.
  • UNREACHABLE - A better alternative has been found due to blockages on the current route.

Applying a route proposal

There are three ways to handle a route proposal:

Automatic mode is set by default and can be changed by passing ContinuousReplanningMode to the NavigationConfiguration during the TomTomNavigation initialization.

navigationConfigurationBuilder.continuousReplanningMode(ContinuousReplanningMode.MANUAL)

The current ContinuousReplanningMode can also be checked and changed during runtime, even if the navigation has been started.

navigation.continuousReplanningMode()
navigation.changeContinuousReplanningMode(ContinuousReplanningMode.MANUAL)

Automatic handling

Continuous replanning is enabled and replan proposals are applied automatically. The user will be notified on OnRouteUpdatedListener, which will return both a Route and RouteUpdateReason as the reason for the change:

  • REFRESH - The current route has been refreshed with data from the replanned route.
  • BETTER_FOUND - A better alternative has been found for the current route.
  • UNREACHABLE - A better alternative has been found due to blockages on the current route.
1navigation.addOnRouteUpdatedListener(object : OnRouteUpdatedListener {
2 override fun onRouteUpdated(route: Route, updateReason: RouteUpdateReason) {
3 if (updateReason == RouteUpdateReason.REFRESH) {
4 /* Your code goes here */
5 }
6 }
7})

Manual handling

Continuous replanning is enabled and obtained routes are proposed using OnReplannedRouteProposedListener. You decide whether the proposed route should be applied with update() or ignored.

1navigation.addOnReplannedRouteProposedListener(object : OnReplannedRouteProposedListener {
2 override fun onReplannedRouteProposed(replannedRoute: ReplannedRoute) {
3 /* Your code goes here */
4 navigation.update(RoutePlan(replannedRoute.route, routingOptions))
5 }
6})

Specifying replanning intervals

By default, the intervals between route updates in continuous replanning are set to 3 minutes. The minimum remaining travel time is set to 10 minutes. After this point, continuous replanning is automatically disabled.

These parameters can be set in RouteReplanningEngineOptions.

1val options = RouteReplanningEngineOptions(
2 replanRouteInterval = replanRouteInterval,
3 validRemainingRouteDuration = validRemainingRouteDuration
4)
5val engine = RouteReplanningEngineFactory.create(options)
6navigationConfigurationBuilder.routeReplanningEngine(engine)

Replanning on deviation

If a user has deviated from the current route, the navigation will inform them of it. The navigation module may do one of the following things:

  • Automatically plan a new route.
  • Wait for the user to manually provide a new route.

Automatic handling

The default is to automatically plan a new route. To turn off automatic route planning, configure TomTomNavigation:

navigationConfigurationBuilder.deviationReplanningMode(DeviationReplanningMode.NONE)

This means the user doesn’t have to take any action, because the new route will be automatically applied. The user will then be notified on OnRouteUpdatedListener, which will return RouteUpdateReason.DEVIATION as the reason for the change as well as the Route itself.

Manual handling

This is the default route deviation handling strategy. Manual handling means that once a user is informed about a deviation from the route, navigation is stopped. Navigation only starts again once a new route has been planned and started.

A manual route update is made by calling TomTomNavigation.update(RoutePlan, RouteUpdatedCallback?). The RoutePlan parameter is built with a Route for the user to follow and the RoutingOptions used for planning that route.

val routePlan = RoutePlan(route = route, routingOptions = routingOptions)
tomTomNavigation.update(routePlan)

Replan retry policy

If the replanning is successful, the Navigation module will use the returned route to replace the current one. Otherwise the Navigation module will try to replan the route again. The number of replan attempts and the delay between retries are defined by the ReplanningRetryPolicy interface.

Policy configuration

The default implementation of ReplanningRetryPolicy (see TomTomReplanningRetryPolicy) will periodically retry the operation with increasing delays between calls. The default maximum delay time is 10 seconds.

The default parameters can also be overridden as follows:

1val replanningRetryPolicy = TomTomReplanningRetryPolicy(
2 maxRetryDelay = maxRetryDelay
3)

Once the policy is configured, it must be provided during initialization of the Navigation module:

navigationConfigurationBuilder.replanningRetryPolicy(replanningRetryPolicy)

Providing a custom replan retry policy

You can also provide your own implementation instead of using the default policy. To do this, implement the ReplanningRetryPolicy interface and pass it during the Navigation module initialization.