Continuous replanning

VERSION 0.2.1455
PUBLIC PREVIEW

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

Introduction

Every trip takes time, and the situation on the road is constantly changing, so routes can become stale as they’re being driven. Continuous replanning provides users with the most up to date route path. This can be a new path, for instance if traffic conditions mean that it will be faster or if a road blockage appears on the original route. It can also be the same path with updated delay information, if a change in the traffic changes the ETA.

The Continuous Replanning component performs the route refresh, checking for better route alternatives in the background and applying them based on its configuration. The component is fully customizable, so you can configure the definition of a better route, the mode for applying a new route, and the interval between replans.

Configuration

Modes and options

Route Replanning Mode

There are three replanning modes:

The default mode is Automatic.

Route Replanning Options

The following options can be used to configure TomTomRouteReplanningEngine:

  • routeReplanInterval - The time interval between replannings.
  • minimalTrafficDelay - The minimum traffic delay time required for an alternative route to be used.
  • minimalTimeDifference - The minimum time difference required for an alternative route to be used.
  • routeReplanningPolicy - How Continuous Replanning will work.

Route Replanning Policy

ContinuousReplanningPolicy specifies how continuous replanning will work.

It has two possible values:

  • Refresh Only - the Continuous Replanning component will only refresh the route along the existing path.
  • Find Better - the Continuous replanning component will search for better routes. It only refreshses if none are found.

The default mode is Refresh Only.

Enabling/Disabling Continuous Replanning

ContinuousReplanningMode is specified using NavigationConfigurationBuilder.with(routeReplanningMode: …​).

1let navigationConfiguration = NavigationConfigurationBuilder(
2 navigationKey: Keys.navigation,
3 locationEngine: locationEngine,
4 routingService: routingService
5)
6.with(routeReplanningMode: .automatic)
7.build()
8
9let navigation = Navigation(configuration: navigationConfiguration)
1let navigationConfiguration = NavigationConfigurationBuilder(
2 navigationKey: Keys.navigation,
3 locationEngine: locationEngine,
4 routingService: routingService
5)
6.with(routeReplanningMode: .manual)
7.build()
8
9let navigation = Navigation(configuration: navigationConfiguration)

Continuous Replanning can be disabled by specifying ContinuousReplanningMode as .none.

1let navigationConfiguration = NavigationConfigurationBuilder(
2 navigationKey: Keys.navigation,
3 locationEngine: locationEngine,
4 routingService: routingService
5)
6.with(routeReplanningMode: .none)
7.build()
8
9let navigation = Navigation(configuration: navigationConfiguration)

Specifying the Route Replanning Policy

To configure the replanning policy, you need to create a TomTomRouteReplanningEngine by passing RouteReplanningEngineOptions with preferred ContinuousReplanningPolicy.

1let routeReplanningEngineOptions = RouteReplanningEngineOptions(
2 routeReplanInterval: .minutes(5),
3 minimalTrafficDelay: .minutes(10),
4 minimalTimeDifference: .minutes(5),
5 routeReplanningPolicy: .findBetter
6)
7let routeReplanningEngine = TomTomRouteReplanningEngine(options: routeReplanningEngineOptions)
8
9let navigationConfiguration = NavigationConfigurationBuilder(
10 navigationKey: Keys.navigation,
11 locationEngine: locationEngine,
12 routingService: routingService
13)
14.with(routeReplanningEngine: routeReplanningEngine)
15.build()
16
17let navigation = Navigation(configuration: navigationConfiguration)

Providing a custom Better Route Selector

TomTomRouteReplanningEngine can accept a custom BetterRouteSelector for advanced customization of the better route selection process. To use a custom BetterRouteSelector, pass a class conforming to BetterRouteSelector as an init parameter.

1let betterRouteSelector = CustomBetterRouteSelector()
2
3let routeReplanningEngine = TomTomRouteReplanningEngine(
4 options: routeReplanningEngineOptions,
5 betterRouteSelector: betterRouteSelector
6)
7
8let navigationConfiguration = NavigationConfigurationBuilder(
9 navigationKey: Keys.navigation,
10 locationEngine: locationEngine,
11 routingService: routingService
12)
13.with(routeReplanningEngine: routeReplanningEngine)
14.build()
15
16let navigation = Navigation(configuration: navigationConfiguration)

Working with manual replanning mode

To use manual replanning mode, specify ContinuousReplanningMode as .manual and set up a TomTomNavigationDelegate::tomTomNavigation(_ navigation: Navigation, didProposeRoutePlan routePlan: RoutePlan, reason: RouteReplanningReason) callback.

1let routeReplanningEngineOptions = RouteReplanningEngineOptions(
2 routeReplanInterval: .init(value: 5, unit: .minutes),
3 minimalTrafficDelay: .init(value: 10, unit: .minutes),
4 minimalTimeDifference: .init(value: 5, unit: .minutes),
5 routeReplanningPolicy: .findBetter
6)
7let routeReplanningEngine = TomTomRouteReplanningEngine(options: routeReplanningEngineOptions)
8
9let navigationConfiguration = NavigationConfigurationBuilder(
10 navigationKey: Keys.navigation,
11 locationEngine: locationEngine,
12 routingService: routingService
13)
14.with(routeReplanningEngine: routeReplanningEngine)
15.with(routeReplanningMode: .manual)
16.build()
17
18let navigation = Navigation(configuration: navigationConfiguration)
19navigation.delegate = self
1func tomTomNavigation(
2 _ navigation: Navigation,
3 didProposeRoutePlan routePlan: RoutePlan,
4 reason _: RouteReplanningReason
5) {
6 // Apply the proposed route plan or/and perform other expected functionality
7 navigation.update(routePlan: routePlan, onError: { _ in /* Error handling */ })
8}

Route Deviation

Introduction

The Navigation module detects when the user has diverged from the navigated route. Route Deviation is a specific case of the more general Continuous Replanning feature, but with its own wide range of possibilities for customization. You can configure the definition of a deviation with a custom RouteDeviationEngine or specify how route deviation will work with a separate ReplanningRetryPolicy for deviations. Whenever a deviation is detected, the notification is sent via TomTomNavigationDelegate::func tomTomNavigation(_ navigation: Navigation, didDeviateRoute currentRoute: Route, location: GeoLocation). The location provided by the callback is the location where the deviation from the route was detected. The currentRoute parameter is the Route that the user deviated from.

1func tomTomNavigation(
2 _ navigation: Navigation,
3 didDeviateRoute currentRoute: Route,
4 location: GeoLocation
5) {
6 /* YOUR CODE GOES HERE */
7}

Configuration

Modes and options

Deviation Replanning Mode

There are two replanning modes for deviation:

The default mode is Automatic.

Route Deviation Engine

To configure the route deviation engine, create a custom engine that implements the RouteDeviationEngine protocol and set this engine using NavigationConfigurationBuilder.with(deviationEngine: …​).

1let navigationConfigurationNone = NavigationConfigurationBuilder(
2 navigationKey: Keys.navigation,
3 locationEngine: locationEngine,
4 routingService: routingService
5)
6.with(deviationEngine: customEngine)
7.build()

Enabling/Disabling Route Deviation

DeviationReplanningMode is specified using NavigationConfigurationBuilder.with(deviationReplanningMode: …​).

1let navigationConfiguration = NavigationConfigurationBuilder(
2 navigationKey: Keys.navigation,
3 locationEngine: locationEngine,
4 routingService: routingService
5)
6.with(deviationReplanningMode: .automatic)
7.build()

Route Deviation can be disabled by specifying DeviationReplanningMode as .none.

1let navigationConfigurationNone = NavigationConfigurationBuilder(
2 navigationKey: Keys.navigation,
3 locationEngine: locationEngine,
4 routingService: routingService
5)
6.with(deviationReplanningMode: .none)
7.build()

Specifying the Route Deviation Retry Policy

To configure the replanning retry policy, you need to create a custom class which implements the ReplanningRetryPolicy protocol.

1let navigationConfigurationNone = NavigationConfigurationBuilder(
2 navigationKey: Keys.navigation,
3 locationEngine: locationEngine,
4 routingService: routingService
5)
6.with(routeDeviationReplanningRetryPolicy: customRetryPolicy)
7.build()