Continuous replanning

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

Route update mode

This mode specifies whether or not the system should try to periodically update the active route and look for better route proposals. There are two possible values:

• ENABLED - The system periodically updates the active route and looks for better route proposals, based on replanRouteInterval. The way that better route proposals are handled is defined by BetterProposalAcceptanceMode.
• DISABLED - The system does not update the active route nor search for better route proposals.

By default, RouteUpdateMode is set to ENABLED. It is configured in the following way:

1val options = RouteReplanningEngineOptions(
2    routeUpdateMode = RouteUpdateMode.Enabled
3)
4val engine = RouteReplanningEngineFactory.create(routeReplanner, options)
5val navigationConfiguration = NavigationConfiguration(
6    context = context,
7    apiKey = apiKey,
8    locationProvider = locationProvider,
9    routeReplanner = routeReplanner,
10    routeReplanningEngine = engine
11)

Route refresh

Every trip takes time and the road situation is constantly changing. As a result, route data may become outdated during a trip. 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 amount of traffic)
• Updated legs and sections

Route refresh works only if RouteUpdateMode is set to ENABLED.

Route refresh might fail if the initial route planning was done with densely placed supporting points in comparison to route geometry. The replanning is made based on the geometry of the current route, where the density of coordinates may be lower.

Replanning response

The updated route will always be automatically applied and the reason will be set to RouteUpdateReason.Refresh.

Continuous Replanning - finding better alternatives

If you would like to receive alternative route proposals, RouteUpdateMode must be set to ENABLED. The frequency of searches for better route proposals is defined with replanRouteInterval. The Navigation module will then, based on this interval, periodically attempt to find a better alternative to the current route. This is what continuous replanning refers to. BetterProposalAcceptanceMode defines how a better route proposal is handled.

The RouteReplanningEngine provides a default RouteProposalSelector 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 ten (10) minutes and minTimeDifference to five (5) minutes.

1val options = RouteReplanningEngineOptions(
2    minTrafficDelay = minTrafficDelay,
3    minTimeDifference = minTimeDifference
4)
5val engine = RouteReplanningEngineFactory.create(routeReplanner, options)
6val navigationConfiguration = NavigationConfiguration(
7    context = context,
8    apiKey = apiKey,
9    locationProvider = locationProvider,
10    routeReplanner = routeReplanner,
11    routeReplanningEngine = engine
12)

Providing a custom route proposal selector

If the default implementation of RouteProposalSelector does not do what you need it to do, you can provide your own when creating RouteReplanningEngine. Note that it’s up to the provider of the custom route proposal selector to make sure that a reachable proposal is chosen whenever the current route has a blockage.

1val engine =
2    RouteReplanningEngineFactory.create(routeReplanner, options, customRouteProposalSelector)
3val navigationConfiguration = NavigationConfiguration(
4    context = context,
5    apiKey = apiKey,
6    locationProvider = locationProvider,
7    routeReplanner = routeReplanner,
8    routeReplanningEngine = engine
9)

Replanning response

A better route proposal can be applied automatically or manually and the RouteUpdateReason is set to:

• BETTER_FOUND - A better alternative was found for the current route.
• UNREACHABLE - A better alternative has been found due to blockages on the current route or, if an electric vehicle is used for navigation, due to insufficient battery charge.

Better proposal acceptance mode

There are three ways to handle a better route proposal:

• Automatic - Better route proposals are applied automatically.
• UnreachableOnly - The active route is automatically replaced with a better proposal if it contains a blockage or if the current route is not reachable due to insufficient battery charge. Otherwise, a better route is proposed using ReplannedRouteProposedListener.
• Manual - Obtained routes are proposed using the ReplannedRouteProposedListener.

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

1val navigationConfiguration = NavigationConfiguration(
2    context = context,
3    apiKey = apiKey,
4    locationProvider = locationProvider,
5    routeReplanner = routeReplanner,
6    betterProposalAcceptanceMode = BetterProposalAcceptanceMode.Automatic
7)

The current BetterProposalAcceptanceMode can also be checked and changed during runtime, even if the navigation is already started.

navigation.betterProposalAcceptanceMode
navigation.betterProposalAcceptanceMode = BetterProposalAcceptanceMode.Automatic

Automatic handling

Replan proposals are applied automatically. The user will be notified on RouteUpdatedListener, which will return both a Route and RouteUpdateReason as the reason for the change:

• 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.addRouteUpdatedListener(object : RouteUpdatedListener {
2    override fun onRouteUpdated(route: Route, updateReason: RouteUpdateReason) {
3        if (updateReason == RouteUpdateReason.BetterFound) {
4            /* Your code goes here */
5        }
6    }
7})

Unreachable_only handling

Replan proposals are applied automatically only if there is a blockage on the current route. In that case, the user is notified on RouteUpdatedListener. Otherwise, better route proposals are offered using ReplannedRouteProposedListener.

Manual handling

Obtained routes are proposed using ReplannedRouteProposedListener. You decide whether the proposed route should be applied with acceptProposedRoute or ignored. The navigation will then be updated with the proposed route.

1navigation.addReplannedRouteProposedListener(object : ReplannedRouteProposedListener {
2    override fun onReplannedRouteProposed(replannedRoute: ReplannedRoute) {
3        /* Your code goes here */
4        navigation.acceptProposedRoute()
5    }
6})

Specifying replanning intervals

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

These parameters can be set in RouteReplanningEngineOptions.

1val options = RouteReplanningEngineOptions(
2    replanRouteInterval = replanRouteInterval,
3    validRemainingRouteDuration = validRemainingRouteDuration
4)
5val engine = RouteReplanningEngineFactory.create(routeReplanner, options)
6val navigationConfiguration = NavigationConfiguration(
7    context = context,
8    apiKey = apiKey,
9    locationProvider = locationProvider,
10    routeReplanner = routeReplanner,
11    routeReplanningEngine = engine
12)

Replanning on deviation

If a user has deviated from the current route, the navigation informs 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.

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

Automatic handling

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

1val navigationConfiguration = NavigationConfiguration(
2    context = context,
3    apiKey = apiKey,
4    locationProvider = locationProvider,
5    routeReplanner = routeReplanner,
6    deviationReplanningMode = DeviationReplanningMode.None
7)

This means the user doesn’t need to take any action, because the new route is automatically applied. The user is then be notified on RouteUpdatedListener, which returns 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(NavigationOptions). The NavigationOptions parameter contains RoutePlan. The RoutePlan is built with a Route for the user to follow and the RoutePlanningOptions used for planning that route.

1val routePlan = RoutePlan(route = route, routePlanningOptions = routePlanningOptions)
2val navigationOptions = NavigationOptions(routePlan)
3tomTomNavigation.update(navigationOptions)

To keep navigation guidance consistent, before calling TomTomNavigation.update(NavigationOptions), DepartureInstruction should be filtered out from the proposed route plan. An instruction is just an indicator of starting navigation.

Example of how to remove the DepartureInstruction from the first leg of the route:

1fun Route.removeDepartInstruction(): Route {
2    val firstLeg = legs.first()
3    return firstLeg.instructions
4        .dropWhile { it is DepartureInstruction }
5        .let { newInstructions ->
6            val newFirstLeg = firstLeg.copy(instructions = newInstructions)
7            val oldLegsWithoutFirst = legs.drop(1)
8            val newLegs = listOf(newFirstLeg) + oldLegsWithoutFirst
9            copy(legs = newLegs)
10        }
11}

Replan retry policy

If the replanning is successful, the Navigation module uses the returned route to replace the current one. Otherwise the Navigation module tries 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) periodically retries the operation with increasing delays between calls. The default maximum delay time is ten (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:

1val navigationConfiguration = NavigationConfiguration(
2    context = context,
3    apiKey = apiKey,
4    locationProvider = locationProvider,
5    routeReplanner = routeReplanner,
6    replanningRetryPolicy = replanningRetryPolicy
7)

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.

Next steps

Since you have learned about route replanning, here are recommendations for the next steps:

• Route planning
• Location module quickstart
• Location context